From b6f9d7976d38334a5809d10e688b0999c50ecc5e Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jan=20Posp=C3=AD=C5=A1il?= Date: Sun, 9 Dec 2007 17:50:20 +0000 Subject: [PATCH] files reshufle, main file for Admin's Guide --- org.glite.lb.doc/Makefile | 27 ++-- org.glite.lb.doc/src/LBAG-Introduction.tex | 3 + org.glite.lb.doc/src/LBAG.tex | 33 +++++ .../src/{arch.tex => LBUG-Architecture.tex} | 3 + .../src/{caveats.tex => LBUG-Caveats.tex} | 4 + .../src/{interaction.tex => LBUG-Interaction.tex} | 15 ++ org.glite.lb.doc/src/LBUG-Introduction.tex | 21 +++ org.glite.lb.doc/src/LBUG-QuickStartGuide.tex | 37 +++++ org.glite.lb.doc/src/LBUG-ReferenceGuide.tex | 31 ++++ .../src/{security.tex => LBUG-Security.tex} | 3 + org.glite.lb.doc/src/LBUG.tex | 162 ++------------------- org.glite.lb.doc/src/consumer_api.tex | 2 +- org.glite.lb.doc/src/copyright.tex | 2 +- org.glite.lb.doc/src/definitions.tex | 6 + org.glite.lb.doc/src/log_usertag.tex | 2 +- 15 files changed, 184 insertions(+), 167 deletions(-) create mode 100644 org.glite.lb.doc/src/LBAG-Introduction.tex create mode 100644 org.glite.lb.doc/src/LBAG.tex rename org.glite.lb.doc/src/{arch.tex => LBUG-Architecture.tex} (99%) rename org.glite.lb.doc/src/{caveats.tex => LBUG-Caveats.tex} (98%) rename org.glite.lb.doc/src/{interaction.tex => LBUG-Interaction.tex} (81%) create mode 100644 org.glite.lb.doc/src/LBUG-Introduction.tex create mode 100644 org.glite.lb.doc/src/LBUG-QuickStartGuide.tex create mode 100644 org.glite.lb.doc/src/LBUG-ReferenceGuide.tex rename org.glite.lb.doc/src/{security.tex => LBUG-Security.tex} (98%) create mode 100644 org.glite.lb.doc/src/definitions.tex diff --git a/org.glite.lb.doc/Makefile b/org.glite.lb.doc/Makefile index 2ba0f99..3141d77 100644 --- a/org.glite.lb.doc/Makefile +++ b/org.glite.lb.doc/Makefile @@ -11,29 +11,30 @@ PREFIX=/opt/glite 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 diff --git a/org.glite.lb.doc/src/LBAG-Introduction.tex b/org.glite.lb.doc/src/LBAG-Introduction.tex new file mode 100644 index 0000000..78c04d7 --- /dev/null +++ b/org.glite.lb.doc/src/LBAG-Introduction.tex @@ -0,0 +1,3 @@ +\section{Introduction} + +\endinput diff --git a/org.glite.lb.doc/src/LBAG.tex b/org.glite.lb.doc/src/LBAG.tex new file mode 100644 index 0000000..91bd37f --- /dev/null +++ b/org.glite.lb.doc/src/LBAG.tex @@ -0,0 +1,33 @@ +\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} diff --git a/org.glite.lb.doc/src/arch.tex b/org.glite.lb.doc/src/LBUG-Architecture.tex similarity index 99% rename from org.glite.lb.doc/src/arch.tex rename to org.glite.lb.doc/src/LBUG-Architecture.tex index afd752d..69cfc09 100644 --- a/org.glite.lb.doc/src/arch.tex +++ b/org.glite.lb.doc/src/LBUG-Architecture.tex @@ -1,3 +1,5 @@ +\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. @@ -112,3 +114,4 @@ for them are kept by the notification interlogger. Once a~new listening address is announced to the server, the pending notifications are delivered. +\endinput diff --git a/org.glite.lb.doc/src/caveats.tex b/org.glite.lb.doc/src/LBUG-Caveats.tex similarity index 98% rename from org.glite.lb.doc/src/caveats.tex rename to org.glite.lb.doc/src/LBUG-Caveats.tex index 2c2c0e0..ac04a14 100644 --- a/org.glite.lb.doc/src/caveats.tex +++ b/org.glite.lb.doc/src/LBUG-Caveats.tex @@ -1,3 +1,5 @@ +\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. @@ -82,3 +84,5 @@ of external dependencies (MySQL, Globus Toolkit) 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 diff --git a/org.glite.lb.doc/src/interaction.tex b/org.glite.lb.doc/src/LBUG-Interaction.tex similarity index 81% rename from org.glite.lb.doc/src/interaction.tex rename to org.glite.lb.doc/src/LBUG-Interaction.tex index 376d962..85aabde 100644 --- a/org.glite.lb.doc/src/interaction.tex +++ b/org.glite.lb.doc/src/LBUG-Interaction.tex @@ -1,3 +1,5 @@ +\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. @@ -41,4 +43,17 @@ information on job status which is relevant for their processing. 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 diff --git a/org.glite.lb.doc/src/LBUG-Introduction.tex b/org.glite.lb.doc/src/LBUG-Introduction.tex new file mode 100644 index 0000000..70fbb7d --- /dev/null +++ b/org.glite.lb.doc/src/LBUG-Introduction.tex @@ -0,0 +1,21 @@ +\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 diff --git a/org.glite.lb.doc/src/LBUG-QuickStartGuide.tex b/org.glite.lb.doc/src/LBUG-QuickStartGuide.tex new file mode 100644 index 0000000..59251b3 --- /dev/null +++ b/org.glite.lb.doc/src/LBUG-QuickStartGuide.tex @@ -0,0 +1,37 @@ +\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 diff --git a/org.glite.lb.doc/src/LBUG-ReferenceGuide.tex b/org.glite.lb.doc/src/LBUG-ReferenceGuide.tex new file mode 100644 index 0000000..c32962b --- /dev/null +++ b/org.glite.lb.doc/src/LBUG-ReferenceGuide.tex @@ -0,0 +1,31 @@ +\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 diff --git a/org.glite.lb.doc/src/security.tex b/org.glite.lb.doc/src/LBUG-Security.tex similarity index 98% rename from org.glite.lb.doc/src/security.tex rename to org.glite.lb.doc/src/LBUG-Security.tex index 4178f7a..87f19bf 100644 --- a/org.glite.lb.doc/src/security.tex +++ b/org.glite.lb.doc/src/LBUG-Security.tex @@ -1,3 +1,5 @@ +\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 @@ -54,3 +56,4 @@ program, see section~\ref{change_acl}. %can be specified using by either the -V option to glite_lb_bkserverd or setting %the VOMS_CERT_DIR environment variable. +\endinput diff --git a/org.glite.lb.doc/src/LBUG.tex b/org.glite.lb.doc/src/LBUG.tex index 7f87bcf..3f80078 100644 --- a/org.glite.lb.doc/src/LBUG.tex +++ b/org.glite.lb.doc/src/LBUG.tex @@ -1,12 +1,7 @@ \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} @@ -31,158 +26,23 @@ as well as \LB\ query and notification API use cases. \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} diff --git a/org.glite.lb.doc/src/consumer_api.tex b/org.glite.lb.doc/src/consumer_api.tex index e1d7034..a779acc 100644 --- a/org.glite.lb.doc/src/consumer_api.tex +++ b/org.glite.lb.doc/src/consumer_api.tex @@ -66,7 +66,7 @@ Default value is EDG\_WLL\_QUERYRES\_NONE. 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\\ diff --git a/org.glite.lb.doc/src/copyright.tex b/org.glite.lb.doc/src/copyright.tex index 3c17886..981ab62 100644 --- a/org.glite.lb.doc/src/copyright.tex +++ b/org.glite.lb.doc/src/copyright.tex @@ -4,7 +4,7 @@ \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. diff --git a/org.glite.lb.doc/src/definitions.tex b/org.glite.lb.doc/src/definitions.tex new file mode 100644 index 0000000..1be4fb7 --- /dev/null +++ b/org.glite.lb.doc/src/definitions.tex @@ -0,0 +1,6 @@ +\def\LB{L\&B} +\def\eg{e.\,g.} +\def\ie{i.\,e.} +\def\Dash{\,---\,\penalty-1000} +\def\todo#1{\par\textbf{TODO:} #1\par} + diff --git a/org.glite.lb.doc/src/log_usertag.tex b/org.glite.lb.doc/src/log_usertag.tex index 629b34e..9f01701 100644 --- a/org.glite.lb.doc/src/log_usertag.tex +++ b/org.glite.lb.doc/src/log_usertag.tex @@ -31,7 +31,7 @@ where \verb'' & 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. -- 1.8.2.3