We are really sorry that it took us so long to reply to this GGUS
ticket, we thought that there must be a prize for the longest ticket one day.

Seriously, 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 four major
documents:

- LB User's Guide (LBUG)
- LB Adminstrator's Guide (LBAG)
- LB Developer's Guide (LBDG)
- LB Test Plan (LBTP)

The official web location for these documents is now
http://egee.cesnet.cz/en/JRA1/LB
and links to these documents were updated hopefully on all the following webs:

http://glite.web.cern.ch/glite/documentation/default.asp
http://glite.web.cern.ch/glite/packages/R3.1/deployment/glite-LB/glite-LB.asp
http://egee-jra1-wm.mi.infn.it/egee-jra1-wm
https://twiki.cern.ch/twiki/bin/view/EGEE/Glite-LB
https://twiki.cern.ch/twiki/bin/view/EGEE/Egee3Jra1

The old LB User's Guide was removed from
https://edms.cern.ch/document/571273/2

The JP documentation is going to have a similar structure, it is now kept
in the org.glite.jp.doc module and it will be published soon.


> 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.

LB keeps user tags only as strings, it is left on the
application level to give the values some semantics. It is now
mentioned in LBUG Section 2.3.1.

> 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.

glite-lb-logevent is now in details described in LBUG, Section
2.3, and the use-case of using this tool to log the user-tag is
described in the LBUG 2.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.

All this is now mentioned in LBDG Section 4.

> 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 ?

See LBDG Section 4.3.4 and above mentioned examples.

> 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.

Please try the new examples provided.


> 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)?

Please try the new examples provided.


> 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?

Please try the new examples provided.


> 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 unreadable, so we removed
it almost completely from the LBDG. 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.
