From 5cbe0a9f3308c5d0dabee5c858046fe9be72fc34 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jan=20Posp=C3=AD=C5=A1il?= Date: Sat, 15 Dec 2007 22:43:35 +0000 Subject: [PATCH] GGUS#19469 - updated some of the issues - the reply to this ticket prepared in the document GGUS19469-reply.txt - still a lot has to be done :( --- org.glite.lb.doc/GGUS19469-reply.txt | 145 ++++++++++++++++++++++++++ org.glite.lb.doc/src/LBAG-Configuration.tex | 5 + org.glite.lb.doc/src/LBAG-Installation.tex | 7 ++ org.glite.lb.doc/src/LBAG-Introduction.tex | 9 +- org.glite.lb.doc/src/LBAG-Running.tex | 5 + org.glite.lb.doc/src/LBAG-Troubleshooting.tex | 6 ++ org.glite.lb.doc/src/LBAG.tex | 21 +++- org.glite.lb.doc/src/LBDG-Common.tex | 2 + org.glite.lb.doc/src/LBDG-Introduction.tex | 3 +- org.glite.lb.doc/src/LBDG.tex | 7 +- org.glite.lb.doc/src/LBUG-Appendix.tex | 1 + org.glite.lb.doc/src/LBUG-Introduction.tex | 1 + org.glite.lb.doc/src/LBUG-Tools.tex | 6 ++ org.glite.lb.doc/src/LBUG-UseCases.tex | 3 +- org.glite.lb.doc/src/change_acl.tex | 18 ++-- org.glite.lb.doc/src/consumer_api.tex | 9 +- org.glite.lb.doc/src/log_usertag.tex | 48 ++++++--- org.glite.lb.doc/src/logevent.tex | 28 +++-- org.glite.lb.doc/src/producer_api.tex | 3 +- org.glite.lb.doc/src/web_services.tex | 7 +- 20 files changed, 283 insertions(+), 51 deletions(-) create mode 100644 org.glite.lb.doc/GGUS19469-reply.txt create mode 100644 org.glite.lb.doc/src/LBAG-Configuration.tex create mode 100644 org.glite.lb.doc/src/LBAG-Installation.tex create mode 100644 org.glite.lb.doc/src/LBAG-Running.tex create mode 100644 org.glite.lb.doc/src/LBAG-Troubleshooting.tex create mode 100644 org.glite.lb.doc/src/LBDG-Common.tex diff --git a/org.glite.lb.doc/GGUS19469-reply.txt b/org.glite.lb.doc/GGUS19469-reply.txt new file mode 100644 index 0000000..f56e8cf --- /dev/null +++ b/org.glite.lb.doc/GGUS19469-reply.txt @@ -0,0 +1,145 @@ +We are really sorry that it took us so long to reply to this GGUS +ticket, however we took all the comments and suggestions really +seriously and during the gLite restructuring we made all the required +changes and among others we now have a completely new documentation both +for Logging and Bookkeeping (LB) and Job Provenance (JP). + +We attach our comments inline to your initial review/request: + +> The available 'Logging and Bookkeeping User and Reference Guide' has +> several problems: +> +> General remarks : the link from the general glite doc page +> (http://glite.web.cern.ch/glite/documentation/default.asp) links to +> https://edms.cern.ch/file/571273/1/LB-guide.pdf while EDMS proposes +> https://edms.cern.ch/file/571273/2/LB-guide.pdf However both documents +> seem to be the same (even so says diff on the pdf files). Now the most +> surprising thing is that the proposed document is still a DRAFT dating +> almost 1.5 years now. Isn't that more than enough time to publish a +> final document? + +The LB documentation has been changed completely. It is now part of the +org.glite.lb.doc module and it contains three major documents: +- LB User's Guide (LBUG) +- LB Adminstrator's Guide (LBAG) +- LB Developer's Guide (LBDG) + +TODO: the official web location for these documents is now... and links +to these documents were updated on all the following webs: +http://egee.cesnet.cz/en/JRA1 +http://glite.web.cern.ch/glite/documentation/default.asp +https://edms.cern.ch/document/571273/2 +http://egee-jra1-wm.mi.infn.it/egee-jra1-wm + +TODO: The same holds also for the JP documentation that is now part of +the org.glite.jp.doc module. + +> At last, the guide mentions example code (quote from p. 14 : "You can +> found this example in client module, file job_status.c."). I found an +> 'examples' dir in the glite-lb-client package, however it does not +> contain C source code but rather useless executable files!! + +The source code of all the examples is now also included in the +glite-lb-client (RPM) together with a simple Makefile so that users +can make the examples on their machines. + +> I skip the "Introduction" section. +> +> 2/ Quickstart Guide +> 2.1/ Command Line Tools +> quite OK but is missing the (C) type of the values that can be given +> to a user tag: only a string or is an integer value possible? This has +> it's importance in the following. + +TODO: log_usertag.tex + +> I think the documentation misses a description of the equivalent API. +> At least some part of the code of the CLI interface should be +> available, as in a job this duty is probably better done by the code +> itself than by some external command. + +TODO: glite-lb-logevent is now in details described in LBUG, section +2.1, and the use-case of using this tool to log the user-tag is +described in the LBUG 3.1. The logging API is in details described in +LBDG together with the programming examples. + + +> 2.2/ L&B querying API +> General remarks: +> when compiling, of course header files and libraries are required. Why +> not indicate them ? what flavor of libglite_lb_client shall be used ? +> And to have some code querying an edg/lcg LB ? although stuff in this +> API is prefixed by edg_, it's not possible to query an edg/lcg LB with +> this API when linking against glite libs : error msg is 'Operation not +> supported (Protocol versions incompatible)'. I'm glad to know now but +> I would have preferred reading it in the docs. + +TODO: consumer_api.tex + +> Section 2.2.2, +> example 1 ("Job status", p. 13) +> It would be quite interesting to give some details about the +> edg_wll_JobStat data type and more generally about every data type +> used for returning results. Also I do not agree with "The code also +> shows a complete handling of returned errors": although it is claimed +> it uses errno values, errno variable is not used and the return codes +> do not always match the defined errno values. Hence the question : how +> to interpret these return codes, can't some details be given in the +> docs ? + +TODO: consumer_api.tex, see \label{JS} + +> example 2 ("All user's jobs" p. 14) does not work: it misses the +> calling of +> edg_wll_SetParam(ctx, EDG_WLL_PARAM_QUERY_SERVER, my_lb_srv); +> edg_wll_SetParam(ctx, EDG_WLL_PARAM_QUERY_SERVER_PORT, srv_port); +> for the soft to know which LB host to query. This is needed in also +> every following example where no explicit jobid is used. If there is a +> general/convenient way to set it through config files or environment +> vars, it is not mentioned. + +TODO: consumer_api.c, see \label{JQ-auj} + +> One more thing about this example : output can be HUGE! Better mention +> it... + +Mentioned :). + +> example "querying user tags", p. 17 +> I haven't managed to get it working and after quite a few tries I'm +> still unable to query user tags I did set myself (proved by the output +> of the 'glite-lb-logevent' command, which also shows that the tag +> could be capitalized by the m/w) from some successfully +> executing/executed job. +> +> Is this code really working ? Could it be a problem linked with the LB +> or VO I'm using (I tried under 'esr' and 'dteam' VOs)? + +TODO: consumer_api.c, see \label{JQ_ut} + +> I had no more chance with example "All jobs marked as red" p. 19 and +> the event query. Is there some available code somewhere that does +> successfully query some user tag? + +TODO: consumer_api.c, see \label{ASQ_allred} + + +> 3/ The reference +> Hey, is it really supposed to turn out as a reference? For now, it +> looks more like an index, except that an index helps locating +> occurrences. Has the function 'edg_wll_GetServerLimit' (mentioned on +> p. 97) disappeared from the library? No libglite_lb_whatever seems to +> contain it. + +The automatically generated documentation was really unreadeble, so we +removed it almost completely from the LBDG. + +TODO: Only a list of header files and important API functions can be +found there. + +> I can provide the full source code I used if requested. + +We would really appreciate if you could look at the documentation now +and tell us if you find it suitable and if all examples are working for +you without problems. + diff --git a/org.glite.lb.doc/src/LBAG-Configuration.tex b/org.glite.lb.doc/src/LBAG-Configuration.tex new file mode 100644 index 0000000..e08ce37 --- /dev/null +++ b/org.glite.lb.doc/src/LBAG-Configuration.tex @@ -0,0 +1,5 @@ +\section{Configuration} +\TODO{} + +\subsection{Setting up the MySQL database} + diff --git a/org.glite.lb.doc/src/LBAG-Installation.tex b/org.glite.lb.doc/src/LBAG-Installation.tex new file mode 100644 index 0000000..3480f50 --- /dev/null +++ b/org.glite.lb.doc/src/LBAG-Installation.tex @@ -0,0 +1,7 @@ +\section{Installation} +\TODO{} + +\subsection{Complete RPMs description} +\subsection{Daemons description} +\subsection{CLI tools description: purge/dump/load} + diff --git a/org.glite.lb.doc/src/LBAG-Introduction.tex b/org.glite.lb.doc/src/LBAG-Introduction.tex index 55d7858..7843699 100644 --- a/org.glite.lb.doc/src/LBAG-Introduction.tex +++ b/org.glite.lb.doc/src/LBAG-Introduction.tex @@ -1,10 +1,5 @@ \section{Introduction} +\TODO{This document should contain:} -This document should contain +\subsection{Deployment scenarios} -\subsection{deployment scenarios} -\subsection{instalation} -\subsection{configuration} -\subsection{complete RMPs description} -\subsection{daemons description} -\subsection{CLI tools description: purge/dump/load} diff --git a/org.glite.lb.doc/src/LBAG-Running.tex b/org.glite.lb.doc/src/LBAG-Running.tex new file mode 100644 index 0000000..fdb6ae8 --- /dev/null +++ b/org.glite.lb.doc/src/LBAG-Running.tex @@ -0,0 +1,5 @@ +\section{Running and stopping the services} +\TODO{} + +\subsection{Tests if everything works properly} + diff --git a/org.glite.lb.doc/src/LBAG-Troubleshooting.tex b/org.glite.lb.doc/src/LBAG-Troubleshooting.tex new file mode 100644 index 0000000..c4397a4 --- /dev/null +++ b/org.glite.lb.doc/src/LBAG-Troubleshooting.tex @@ -0,0 +1,6 @@ +\section{Troubleshooting} +\TODO{} + +\subsection{Debugging} +\subsection{Fine tuning the performance} + diff --git a/org.glite.lb.doc/src/LBAG.tex b/org.glite.lb.doc/src/LBAG.tex index 91bd37f..e777ce5f 100644 --- a/org.glite.lb.doc/src/LBAG.tex +++ b/org.glite.lb.doc/src/LBAG.tex @@ -4,7 +4,7 @@ \input{definitions} \title{Logging and Bookkeeping} -\Subtitle{Admin's Guide} +\Subtitle{Administrator's Guide} \author{CESNET EGEE II JRA1 team} \DocIdentifier{EGEE-II....} \Date{\today} @@ -13,9 +13,10 @@ \Dissemination{PUBLIC} \DocumentLink{http://...} -\Abstract{ -This admin's guide explains how to administer the Logging and Bookkeeping (\LB) service. -} +\Abstract{ This administrator's guide explains how to administer the Logging +and Bookkeeping (\LB) service. Several deployment scenarios are described +together with the installation, configuration, running and troubleshooting +steps. } \begin{document} @@ -26,6 +27,18 @@ This admin's guide explains how to administer the Logging and Bookkeeping (\LB) \newpage \input{LBAG-Introduction} +\newpage +\input{LBAG-Installation} + +\newpage +\input{LBAG-Configuration} + +\newpage +\input{LBAG-Running} + +\newpage +\input{LBAG-Troubleshooting} + \nocite{jgc} \bibliographystyle{unsrt} \bibliography{lbjp} diff --git a/org.glite.lb.doc/src/LBDG-Common.tex b/org.glite.lb.doc/src/LBDG-Common.tex new file mode 100644 index 0000000..dff668c --- /dev/null +++ b/org.glite.lb.doc/src/LBDG-Common.tex @@ -0,0 +1,2 @@ +\section{\LB\ Common} +\TODO{Add the information about LB common - list of header files, important functions and data types and their description, etc.} diff --git a/org.glite.lb.doc/src/LBDG-Introduction.tex b/org.glite.lb.doc/src/LBDG-Introduction.tex index 78c04d7..1ac1ed9 100644 --- a/org.glite.lb.doc/src/LBDG-Introduction.tex +++ b/org.glite.lb.doc/src/LBDG-Introduction.tex @@ -1,3 +1,2 @@ \section{Introduction} - -\endinput +\TODO{Add the information from the "Best practices" workshop, i.e. information how the whole LB is coded, why C, what were the general techniques - context, connection pool, .T templates description, etc.} diff --git a/org.glite.lb.doc/src/LBDG.tex b/org.glite.lb.doc/src/LBDG.tex index ebdccc0..6f0973d 100644 --- a/org.glite.lb.doc/src/LBDG.tex +++ b/org.glite.lb.doc/src/LBDG.tex @@ -13,8 +13,8 @@ \DocumentLink{http://...} \Abstract{This developer's guide explains how to use the Logging and Bookkeeping -(\LB) service API. Logging, querying and notification API as well as the Web Services -Interface is described in details together with programming examples. } +(\LB) service API. Logging (producer), querying (consumer) and notification API as well as the Web Services +Interface is described in details together with programing examples. } \begin{document} @@ -25,6 +25,9 @@ Interface is described in details together with programming examples. } \input{LBDG-Introduction} \newpage +\input{LBDG-Common} + +\newpage \input{producer_api} \newpage diff --git a/org.glite.lb.doc/src/LBUG-Appendix.tex b/org.glite.lb.doc/src/LBUG-Appendix.tex index e1e575c..42405da 100644 --- a/org.glite.lb.doc/src/LBUG-Appendix.tex +++ b/org.glite.lb.doc/src/LBUG-Appendix.tex @@ -4,6 +4,7 @@ \label{a:events} Complete list of all events' names together with their description follows. % see events.tex.T +\TODO{Enable page break in the following table:} \input{events} \newpage diff --git a/org.glite.lb.doc/src/LBUG-Introduction.tex b/org.glite.lb.doc/src/LBUG-Introduction.tex index 68e1bad..41efc97 100644 --- a/org.glite.lb.doc/src/LBUG-Introduction.tex +++ b/org.glite.lb.doc/src/LBUG-Introduction.tex @@ -580,6 +580,7 @@ pending events belonging to this handle accordingly. % asi nepotrebujeme \subsubsection{Clients} \subsubsection{Proxy} +\TODO{Proxy is now "integrated" into the server executable, update the text:} \emph{\LB proxy} is the implementation of the local view concept (Sect.~\ref{local}). When deployed (on the Resource Broker node in the current gLite middleware) diff --git a/org.glite.lb.doc/src/LBUG-Tools.tex b/org.glite.lb.doc/src/LBUG-Tools.tex index 53dc8ca..52b2c3a 100644 --- a/org.glite.lb.doc/src/LBUG-Tools.tex +++ b/org.glite.lb.doc/src/LBUG-Tools.tex @@ -1,3 +1,9 @@ \section{Tools description} +In this section we give a description of the tools that are installed +together with the \verb'glite-lb-client'. These are the only \LB\ tools that a +regular grid user may need to use. + \input{logevent} + +\TODO{Maybe add other tools: glite-lb-notify, glite-lb-job-log, glite-lb-job-status, ...?} diff --git a/org.glite.lb.doc/src/LBUG-UseCases.tex b/org.glite.lb.doc/src/LBUG-UseCases.tex index 6926c08..82ce831 100644 --- a/org.glite.lb.doc/src/LBUG-UseCases.tex +++ b/org.glite.lb.doc/src/LBUG-UseCases.tex @@ -1,9 +1,10 @@ \section{Use Cases} 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) +cases which are meant for the end-user: adding a~user description (tag) to a~job, and changing a~job access control list. \input{log_usertag} \input{change_acl} +\TODO{Add User Query Use Cases and Notifications Use Cases} diff --git a/org.glite.lb.doc/src/change_acl.tex b/org.glite.lb.doc/src/change_acl.tex index 0543347..760b80b 100644 --- a/org.glite.lb.doc/src/change_acl.tex +++ b/org.glite.lb.doc/src/change_acl.tex @@ -1,9 +1,12 @@ \subsection{Changing Job Access Control List} \label{change_acl} +\TODO{Review if it is still correct - Dan?} + +In order to change ACL for a job a special event \verb'ChangeACL' is used. This +event can be logged by the job owner using the \verb'glite-lb-logevent' command +(see also Sect.~\ref{glite-lb-logevent}). General template for changing the ACL +is as follows: -In order to change ACL for a job a special event \verb+ChangeACL+ is used. This -event can be logged by the job owner using the glite-lb-logevent command (see also -Sect.~\ref{glite-lb-logevent}). General template for changing the ACL is as follows: \begin{verbatim} glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ -j \ @@ -30,8 +33,9 @@ where Adding a user specified by her subject name to the ACL (\verb'user_id' = subject name, \verb'user_id_type' = 0, \verb'permission_type' = 0, \verb'operation' = 0): + \begin{verbatim} -glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ +glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ -j https://scientific.civ.zcu.cz:9000/PC8Y6jBitHt_fKMTEKFnVw \ --user_id '/O=CESNET/O=Masaryk University/CN=Daniel Kouril' \ --user_id_type 0 --permission_type 0 --operation 0 @@ -42,7 +46,7 @@ subject name, \verb'user_id_type' = 0, \verb'permission_type' = 0, \verb'operation' = 1): \begin{verbatim} -glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ +glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ -j https://scientific.civ.zcu.cz:9000/PC8Y6jBitHt_fKMTEKFnVw \ --user_id '/O=CESNET/O=Masaryk University/CN=Daniel Kouril' \ --user_id_type 0 --permission_type 0 --operation 1 @@ -52,7 +56,7 @@ Adding a VOMS group to the ACL (\verb'user_id' = VOMS group, \verb'user_id_type' = 1, \verb'permission_type' = 0, \verb'operation' = 0): \begin{verbatim} -glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ +glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ -j https://scientific.civ.zcu.cz:9000/PC8Y6jBitHt_fKMTEKFnVw \ --user_id 'VOCE:/VOCE' \ --user_id_type 1 --permission_type 0 --operation 0 @@ -63,7 +67,7 @@ combined e.g. with VOMS groups (\verb'user_id' = subject name, \verb'user_id_type' = 0, \verb'permission_type' = 1, \verb'operation' = 0): \begin{verbatim} -glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ +glite-lb-logevent -e ChangeACL -s UserInterface -p --permission 1 \ -j https://scientific.civ.zcu.cz:9000/PC8Y6jBitHt_fKMTEKFnVw \ --user_id '/O=CESNET/O=Masaryk University/CN=Daniel Kouril' \ --user_id_type 0 --permission_type 1 --operation 0 diff --git a/org.glite.lb.doc/src/consumer_api.tex b/org.glite.lb.doc/src/consumer_api.tex index 4a760ba..9e1ea91 100644 --- a/org.glite.lb.doc/src/consumer_api.tex +++ b/org.glite.lb.doc/src/consumer_api.tex @@ -1,4 +1,5 @@ -\section{\LB\ Querying API} +\section{\LB\ Querying (Consumer) API} +\TODO{Complete review; create really functional (buildable) examples and use verbatiminput of relevant part of the code; add list of header files, important functions and data types and their description, etc.} \def\partitle#1{\par{\textbf{#1}}\par} @@ -66,6 +67,8 @@ Default value is EDG\_WLL\_QUERYRES\_NONE. \partitle{Job status} \label{JS} +\TODO{Add edg\_wll\_JobStat description and error codes handling} + 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{djra1.4}. @@ -130,6 +133,8 @@ in the rest of this document.} \partitle{All user's jobs} \label{JQ-auj} +\TODO{Update the example so that it is really working} + The simple query example is a request for all user's jobs. Another condition type, \\ \texttt{EDG\_WLL\_QUERY\_ATTR\_OWNER}, is used in this case, with the @@ -162,6 +167,7 @@ The query may return either a~list of job ID's or a~list of job states or both, depending on the parameters \texttt{jobsOut} and \texttt{statesOut}. If either is NULL the corresponding list is not retrieved. +Developers should keep in mind that the output of such a query could be really huge. \par The following examples demonstrates how \texttt{edg\_wll\_QueryJobs()} combines @@ -319,6 +325,7 @@ This query equals to the formula \partitle{User tags} \label{JQ_ut} +\TODO{Is it really working?} User tags can be used for marking (labelling) jobs. A user tag is a pair of user defined \texttt{name} and \texttt{value}. diff --git a/org.glite.lb.doc/src/log_usertag.tex b/org.glite.lb.doc/src/log_usertag.tex index d9d6abb..588cf60 100644 --- a/org.glite.lb.doc/src/log_usertag.tex +++ b/org.glite.lb.doc/src/log_usertag.tex @@ -1,16 +1,15 @@ \subsection{Logging a UserTag event} \label{log_usertag} -User tag is an arbitrary ``name=value'' pair with which the user can -assign additional information to a job. Further on, LB can be queried -based also on values of user tags. -% (see Sect.~\ref{tag-query}). +User tag is an arbitrary ``name=value'' pair with which the user can assign +additional information to a job. Further on, LB can be queried based also on +values of user tags. % (see Sect.~\ref{tag-query}). -In order to add user tag for a job a special event \verb+UserTag+ is used. This -event can be logged by the job owner using the glite-lb-logevent command (see also -sec.\ref{glite-lb-logevent}). Here we suppose the command is used from user's running - application because a correct setting of environment variables needed by -the command is assured. +In order to add user tag for a job a special event \verb'UserTag' is used. This +event can be logged by the job owner using the glite-lb-logevent command (see +also sec.\ref{glite-lb-logevent}). Here we suppose the command is used from +user's running application because a correct setting of environment variables +needed by the command is assured. General template for adding user tag is as follows: @@ -26,17 +25,32 @@ where \begin{tabularx}{\textwidth}{lX} \verb'' & specifies the job to change \\ -\verb'' & specifies the sequence code returned by previous call - of verb 'glite-lb-logevent'\\ -\verb'' & specifies the name of user tag\\ -\verb'' & specifies the value of user tag\\ +\verb'' & specifies the sequence code returned by previous call + of verb 'glite-lb-logevent' \\ +\verb'' & specifies the name of user tag \\ +\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{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'. +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 \verb'-j' option of \verb'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. +If the user application calls \verb'glite-lb-logevent' just once, it is +sufficient to pass this value to the \verb'-c' option. However, if there are +more subsequent calls, the user is responsible for capturing an updated +sequence code from the stdout of \verb'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. -The example bellow is a job consisting of 100 phases. A user tag phase is used to log the phase currently being executed. Subsequently, the user may monitor execution of the job phases as a part of the job status returned by \LB. +\TODO{What are the possible values/types of the tag? String/Integer/Float/Double?} + +The example bellow is a job consisting of 100 phases. A user tag phase is used +to log the phase currently being executed. Subsequently, the user may monitor +execution of the job phases as a part of the job status returned by \LB. \begin{verbatim} #!/bin/sh @@ -53,3 +67,5 @@ The example bellow is a job consisting of 100 phases. A user tag phase is used done \end{verbatim} +\TODO{Add more examples.} + diff --git a/org.glite.lb.doc/src/logevent.tex b/org.glite.lb.doc/src/logevent.tex index 6c427f5..28d3dcc 100644 --- a/org.glite.lb.doc/src/logevent.tex +++ b/org.glite.lb.doc/src/logevent.tex @@ -2,12 +2,16 @@ \label{glite-lb-logevent} Besides the API's \LB\ offers its users a simple command-line interface for -logging events. The command glite-lb-logevent is used for this purpose. However, it -is intended for internal WMS debugging tests in the first place and should not -be used for common event logging because of possibility of confusing \LB\ -server job state automaton. +logging events. The command \verb'glite-lb-logevent' is used for this purpose. +However, it is intended for internal WMS debugging tests in the first place and +should not be used for common event logging because of possibility of confusing +\LB\ server job state automaton. -The only legal user usage is for logging \verb'UserTag' and \verb'ChangeACL' events. The following description is therefore concentrating only on options dealing with these two events. +The command \verb'glite-lb-logevent' is a complex logging tool and the complete +list of parameters can be obtained using the \verb'-h' option. However, +the only legal user usage is for logging \verb'UserTag' and \verb'ChangeACL' +events. The following description is therefore concentrating only on options +dealing with these two events. Command usage is: @@ -28,7 +32,8 @@ where \medskip -Each event specified after \verb'-e' option has different sub-options enabling to set event specific values. +Each event specified after \verb'-e' option has different sub-options enabling +to set event specific values. Sub-options usable with \verb'UserTag' event are: @@ -52,6 +57,13 @@ Sub-options usable with \verb'ChangeACL' event are: \bigskip -To be able to use this command several environmental variables must be set properly. User must specify where the event should be sent. This is address and port of glite-lb-logd daemon. It is done using environmental variable \verb'EDG_WL_LOG_DESTINATION' in a form \verb'address:port'. +To be able to use this command several environmental variables must be set +properly. User must specify where the event should be sent. This is address and +port of glite-lb-logd daemon. It is done using environmental variable +\verb'EDG_WL_LOG_DESTINATION' in a form \verb'address:port'. + +Because user is allowed to change ACL or add user tags only for her jobs, paths +to valid X509 user credentials has to be set to authorise her. This is done +using two environmental variables \verb'EDG_WL_X509_KEY' and +\verb'EDG_WL_X509_CERT' in a form \verb'path_to_cred'. -Because user is allowed to change ACL or add user tags only for her jobs, paths to valid X509 user credentials has to be set to authorise her. This is done using two environmental variables \verb'EDG_WL_X509_KEY' and \verb'EDG_WL_X509_CERT' in a form \verb'path_to_cred'. diff --git a/org.glite.lb.doc/src/producer_api.tex b/org.glite.lb.doc/src/producer_api.tex index 71f4fe9..6e21829 100644 --- a/org.glite.lb.doc/src/producer_api.tex +++ b/org.glite.lb.doc/src/producer_api.tex @@ -1,2 +1,3 @@ -\section{\LB\ Logging API} +\section{\LB\ Logging (Producer) API} +\TODO{Add the list of header files, important functions and data types and their description; add fully working (buildable) programing examples and use verbatiminput to include the important parts of the code.} diff --git a/org.glite.lb.doc/src/web_services.tex b/org.glite.lb.doc/src/web_services.tex index 983cc5f..b322e96 100644 --- a/org.glite.lb.doc/src/web_services.tex +++ b/org.glite.lb.doc/src/web_services.tex @@ -1,4 +1,6 @@ -\subsection{Using \LB\ Web Service} +\section{Using \LB\ Web Service} + +\TODO{Complete review, list of all relevant (WSDL) files, their location, etc.} The \LB\ web service interface currently reflects the functionality of legacy \LB\ query API (Sect.~\ref{query-C}). @@ -9,7 +11,7 @@ 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 +Consequently, 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 @@ -17,3 +19,4 @@ encoding. For exact definition of the operations and types see the WSDL file. +\TODO{Add fully functional WS examples - in Java, Python, C?} -- 1.8.2.3