VPATH = ${top_srcdir}/src
KPATH = TEXINPUTS=".:$(VPATH)//:"
+KPATHBIB = BIBINPUTS=".:$(VPATH)//:"
LATEX = $(KPATH) latex
PDFLATEX = $(KPATH) pdflatex
-BIBTEX = $(KPATH) bibtex
+BIBTEX = $(KPATHBIB) bibtex
DVIPS = $(KPATH) dvips
-default: LBUG.pdf
+default: LBUG.pdf LBAG.pdf
-%.dvi: %.tex
- $(LATEX) $<
-# $(BIBTEX) `basename $< .tex`
-# $(LATEX) $<
- $(LATEX) $<
-
-%.ps: %.dvi
- $(DVIPS) -ta4 -o $@ $<
+# %.dvi: %.tex
+# $(LATEX) $<
+# $(BIBTEX) `basename $< .tex`
+# $(LATEX) $<
+# $(LATEX) $<
+#
+# %.ps: %.dvi
+# $(DVIPS) -ta4 -o $@ $<
%.pdf: %.tex
$(PDFLATEX) $<
-# $(BIBTEX) `basename $< .tex`
-# $(PDFLATEX) $<
+ $(BIBTEX) `basename $< .tex`
+ $(PDFLATEX) $<
$(PDFLATEX) $<
clean:
- rm -rvf LBUG*
+ rm -rvf LBUG* LBAG*
.PHONY: all clean purge ps pdf
--- /dev/null
+\section{Introduction}
+
+\endinput
--- /dev/null
+\documentclass{egee}
+%\usepackage{doxygen}
+
+\input{definitions}
+
+\title{Logging and Bookkeeping}
+\Subtitle{Admin's Guide}
+\author{CESNET EGEE II JRA1 team}
+\DocIdentifier{EGEE-II....}
+\Date{\today}
+\Activity{JRA1: Middleware Engineering and Integration}
+\DocStatus{DRAFT}
+\Dissemination{PUBLIC}
+\DocumentLink{http://...}
+
+\Abstract{
+This admin's guide explains how to administer the Logging and Bookkeeping (\LB) service.
+}
+
+\begin{document}
+
+\input{frontmatter}
+\newpage
+\tableofcontents
+
+\newpage
+\input{LBAG-Introduction}
+
+\nocite{jgc}
+\bibliographystyle{unsrt}
+\bibliography{lbjp}
+
+\end{document}
+\subsection{Service Architecture}
+
Within the gLite WMS, upon creation
each job is assigned a~unique, virtually non-recyclable
\emph{job identifier} (JobId) in an~URL form.
Once a~new listening address is announced to the
server, the pending notifications are delivered.
+\endinput
+\section{Known Problems and Caveats}
+
\subsection{Indexed attributes}\label{ConsIndx}
\LB\ queries can be fairly complicated and they can potentially return large
amounts of data. In such cases, there is a~risk of server overload.
than those described in the release documentation. While the \LB\ has been designed to achieve
reasonable backward and forward compatibility, some disruptive changes in minor revisions
of external software have been observed before.
+
+\endinput
+\subsection{Interactions with other Services}
+
The main \LB\ functionality is keeping track of jobs managed by
the Workload Management System otherwise.
Therefore its basic usage is done internally by the WMS components.
Notifications on job state change are used by WMS GUI
to monitor the state of jobs periodically.
+\subsubsection{Component and Interaction Diagrams}
+% \todo{nekdy priste}
+% To help understanding the service a set of component and interaction
+% diagrams might help. This section is not mandatory.
+
+\begin{figure}[h]
+\centering
+\includegraphics[width=.8\hsize]{logging-arch-notif}
+\caption{Overview of the \LB\ architecture}
+\label{fig-arch}
+\end{figure}
+
+\endinput
--- /dev/null
+\section{Introduction}
+%This Section should give a brief summary of what the service described
+%is supposed to achieve and how it fits into the overall
+%architecture. It should contain subsections on the service internal
+%architecture and its relations to other services.
+
+The Logging and Bookkeeping (\LB) service tracks jobs managed by
+the gLite WMS (workload management system).
+It gathers events from various WMS components in a~reliable way
+and processes them in order to give a~higher level view, the
+\emph{status of job}.
+
+Virtually all the important
+data are fed to \LB\ internally from various gLite middleware
+components, transparently from the user's point of view.
+On the contrary, \LB\ provides public interfaces for querying the job
+information synchronously as well as registering for asynchronous
+notifications.
+API's for this functionality are described in this document in detail.
+
+\endinput
--- /dev/null
+\section{Quickstart Guide}
+% The quickstart guide should explain in simple terms and with examples
+% how a user is supposed to achieve the most common usecases. E.g. how
+% to submit and cancel a job, how to receive a job's output. How to
+% create a grid file, move it around, locate it, and delete it. How to
+% monitor the progress on an application etc.
+
+\subsection{Command-Line Tools}
+This section describes usage of event-logging \LB\ command in the two
+cases which are ment for the end-user: adding a~user description (tag)
+to a~job, and changing a~job access control list.
+
+\subsubsection{Logging a UserTag event}
+\label{log_usertag}
+\input{log_usertag}
+
+\subsubsection{Changing Job Access Control List}
+\label{change_acl}
+\input{change_acl}
+
+
+%% \subsection{\LB Producer API}
+%% \todo{honik}
+%% This API is not public at the moment, it may change later.
+%% \input{producer_api}
+
+
+\subsection{\LB\ Querying API}
+%\todo{valtri}
+\input{consumer_api}
+
+
+\subsection{\LB\ Notification API}
+\input{notification_api}
+
+
+\endinput
--- /dev/null
+\section{Reference Guide}
+
+%The reference guide should contain detailed descriptions of all
+%provided CLIs and APIs. There should be two subsections for those.
+
+\subsection{Command-Line Interfaces}
+\label{cmdln_interface}
+\input{cmdln_interface}
+
+\newpage
+
+\subsection{\LB\ Web Service Interface}
+
+The \LB\ web service interface currently reflects the functionality of legacy
+\LB\ query API (Sect.~\ref{query-C}).
+
+The following sections describe the operations defined in the \LB\ WSDL
+file as well as its custom types.
+
+For the sake of readability this documentation does not follow the structure
+of WSDL strictly, avoiding to duplicate information which is already present
+here.
+Conseqently, the SOAP messages are not documented, for example, as they
+are derived from operation inputs and outputs mechanically.
+The same holds for types: \eg\ we do not document defined elements
+which correspond 1:1 to types but are required due to the literal SOAP
+encoding.
+
+For exact definition of the operations and types see the WSDL file.
+
+\endinput
+\subsection{Security and Access Control}
+
The \LB\ infrastructure ensures high level of security for information it
processes. All the \LB\ components communicate solely over authenticated
connections and users who query the \LB\ server also must authenticate properly
%can be specified using by either the -V option to glite_lb_bkserverd or setting
%the VOMS_CERT_DIR environment variable.
+\endinput
\documentclass{egee}
-\usepackage{doxygen}
-\usepackage{tabularx}
+%\usepackage{doxygen}
-\def\LB{L\&B}
-\def\eg{e.\,g.}
-\def\ie{i.\,e.}
-\def\Dash{\,---\,\penalty-1000}
-\def\todo#1{\par\textbf{TODO:} #1\par}
+\input{definitions}
\title{Logging and Bookkeeping}
\Subtitle{User's Guide}
\input{frontmatter}
\newpage
\tableofcontents
-\newpage
-
-\section{Introduction}
-%This Section should give a brief summary of what the service described
-%is supposed to achieve and how it fits into the overall
-%architecture. It should contain subsections on the service internal
-%architecture and its relations to other services.
-
-The Logging and Bookkeeping (\LB) service tracks jobs managed by
-the gLite WMS (workload management system).
-It gathers events from various WMS components in a~reliable way
-and processes them in order to give a~higher level view, the
-\emph{status of job}.
-
-Virtually all the important
-data are fed to \LB\ internally from various gLite middleware
-components, transparently from the user's point of view.
-On the contrary, \LB\ provides public interfaces for querying the job
-information synchronously as well as registering for asynchronous
-notifications.
-API's for this functionality are described in this document in detail.
-
-
-\subsection{Service Architecture}
-\input{arch}
-
-
-\subsection{Security and Access Control}
-\input{security}
-
-
-\subsection{Interactions with other Services}
-\input{interaction}
-
\newpage
-\section{Quickstart Guide}
-% The quickstart guide should explain in simple terms and with examples
-% how a user is supposed to achieve the most common usecases. E.g. how
-% to submit and cancel a job, how to receive a job's output. How to
-% create a grid file, move it around, locate it, and delete it. How to
-% monitor the progress on an application etc.
-
-\subsection{Command-Line Tools}
-This section describes usage of event-logging \LB\ command in the two
-cases which are ment for the end-user: adding a~user description (tag)
-to a~job, and changing a~job access control list.
-
-\subsubsection{Logging a UserTag event}
-\label{log_usertag}
-\input{log_usertag}
-
-\subsubsection{Changing Job Access Control List}
-\label{change_acl}
-\input{change_acl}
-
-
-%% \subsection{\LB Producer API}
-%% \todo{honik}
-%% This API is not public at the moment, it may change later.
-%% \input{producer_api}
-
-
-\subsection{\LB\ Querying API}
-%\todo{valtri}
-\input{consumer_api}
-
-
-\subsection{\LB\ Notification API}
-\input{notification_api}
-
+\input{LBUG-Introduction}
+\input{LBUG-Architecture}
+\input{LBUG-Security}
+\input{LBUG-Interaction}
\newpage
-\section{Reference Guide}
-
-%The reference guide should contain detailed descriptions of all
-%provided CLIs and APIs. There should be two subsections for those.
-
-\subsection{Command-Line Interfaces}
-\label{cmdln_interface}
-\input{cmdln_interface}
-
+\input{LBUG-QuickStartGuide}
\newpage
-
-\subsection{\LB\ Web Service Interface}
-
-The \LB\ web service interface currently reflects the functionality of legacy
-\LB\ query API (Sect.~\ref{query-C}).
-
-The following sections describe the operations defined in the \LB\ WSDL
-file as well as its custom types.
-
-For the sake of readability this documentation does not follow the structure
-of WSDL strictly, avoiding to duplicate information which is already present
-here.
-Conseqently, the SOAP messages are not documented, for example, as they
-are derived from operation inputs and outputs mechanically.
-The same holds for types: \eg\ we do not document defined elements
-which correspond 1:1 to types but are required due to the literal SOAP
-encoding.
-
-For exact definition of the operations and types see the WSDL file.
-
-
-{
-\def\chapter#1{}
-\def\section#1{\subsubsection{#1}}
-\def\subsection#1{\par\textbf{#1}\par}
-
-\let\odesc=\description
-\let\oedesc=\enddescription
-\renewenvironment{description}{\odesc\itemindent=1em
-\listparindent=2em
-}{\oedesc}
-%\renewenvironment{description}{\list{}{\labelwidth 5cm\leftmargin 5cm}}
-%{\endlist}
-
-\let\null=\relax
-%\input LB-ug
-}
-
+\input{LBUG-ReferenceGuide}
\newpage
-\section{Known Problems and Caveats}
-\input{caveats}
-
-
-\begin{thebibliography}1
-\bibitem[R1]{lbapi}\emph{\LB\ API Reference}, DataGrid-01-TED-0139.
-\bibitem[R2]{lbarch}\emph{\LB\ Architecture release 2}, DataGrid-01-TED-0141.
-\bibitem[R3]{WMS} G.Avellino at al., \emph{The DataGrid Workload Management System: Challenges and Results}, Journal of Grid Computing, ISSN: 1570-7873, 2005, accepted.
-\end{thebibliography}
-
-\clearpage
-
-\appendix
-
-\section{Component and Interaction Diagrams}
-% \todo{nekdy priste}
-% To help understanding the service a set of component and interaction
-% diagrams might help. This section is not mandatory.
-
-
-\begin{figure}[h]
-\centering
-\includegraphics[width=.8\hsize]{logging-arch-notif}
-\caption{Overview of the \LB\ architecture}
-\label{fig-arch}
-\end{figure}
-
-
+\input{LBUG-Caveats}
+\bibliographystyle{unsrt}
+\bibliography{lbjp}
\end{document}
The simplest case corresponds to the situation when an exact job ID
is known and the only information requested is the job status. The job ID
-format is described in~\cite{lbapi}.
+format is described in~\cite{djra1.4}.
The following example shows
all the relevant structures and API calls to retrieve status information
about a job with the ID\\
\vfill{}
{\bf
-Copyright \copyright Members of the EGEE Collaboration. 2004. See
+Copyright} \copyright\ {\bf Members of the EGEE Collaboration. 2004. See
\href{http://www.eu-egee.org/partners/}{http://www.eu-egee.org/partners/} for
details on the copyright holders.
--- /dev/null
+\def\LB{L\&B}
+\def\eg{e.\,g.}
+\def\ie{i.\,e.}
+\def\Dash{\,---\,\penalty-1000}
+\def\todo#1{\par\textbf{TODO:} #1\par}
+
\verb'<tag_value>' & specifies the value of user tag\\
\end{tabularx}
-The user application is always executed from within a JobWrapper script (part of Workload Management System \cite{WMS}). The wrapper sets the appropriate \verb'JobId' in the environment variable \verb'GLITE_WMS_JOBID'. The user should pass this value to the -j option of glite-lb-logevent. Similarly, the wrapper sets an initial value of the event sequence code in the environment variable \verb'GLITE_WMS_SEQUENCE_CODE'.
+The user application is always executed from within a JobWrapper script (part of Workload Management System \cite{jgc}). The wrapper sets the appropriate \verb'JobId' in the environment variable \verb'GLITE_WMS_JOBID'. The user should pass this value to the -j option of glite-lb-logevent. Similarly, the wrapper sets an initial value of the event sequence code in the environment variable \verb'GLITE_WMS_SEQUENCE_CODE'.
If the user application calls glite-lb-logevent just once, it is sufficient to pass this value to the -c option. However, if there are more subsequent calls, the user is responsible for capturing an updated sequence code from the stdout of glite-lb-logevent and using it in subsequent calls. The \LB\ design requires the sequence codes in order to be able to sort events correctly while not relying on strictly synchronized clocks.
git://scientific.zcu.cz / jra1mw.git / commitdiff