Opened 9 years ago

Closed 9 years ago

#1012 closed task (complete)

Document BIND-10 message codes

Reported by: stephen Owned by: stephen
Priority: medium Milestone: Sprint-20110628
Component: documentation Version:
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: DNS Feature Depending on Ticket:
Estimated Difficulty: 3.0 Add Hours to Ticket: 0
Total Hours: 0 Internal?: no

Description

Collect the various message codes and explanations in one place.

Subtickets

Change History (15)

comment:1 Changed 9 years ago by stephen

  • Owner set to stephen
  • Status changed from new to assigned

comment:2 Changed 9 years ago by jreed

Please make sure this can output in DocBook XML too so I can include in the guide --- or even as multiple XML outputs per module/daemon so I can include into manual pages.

comment:3 Changed 9 years ago by stephen

  • Owner changed from stephen to jreed

Done - it creates DocBook XML output. I've also extended the bind10-guide a bit to include the start of a section on the logging.

comment:4 Changed 9 years ago by stephen

  • Status changed from assigned to reviewing

comment:5 Changed 9 years ago by jreed

It should probably indicate the debug level also. Admins reading the documentation for the log messages will want to know what debug level to set too to possibly see some messages.

Maybe output should be formatted to clearly say what type of log message an item is: DEBUG, INFORMATIONAL, WARNING, etc...

The output of the brief value with string replacements maybe should be in a fixed face or italics or other so can recognize this is the exact message (default language).

I will provide more comments later.

I hope to try to reuse the XML to include into the guide itself. Doing that will provide more feedback for this.

comment:6 Changed 9 years ago by jreed

system_messages.py is in the tools directory but these are not included in the tarball. If a user wants to regenerate it should be included. Even if included in the tarball, I do not think this requires any type of test, but if it did, it could be very simple.

Should the tarball include the XML? The HTML? I think yes for HTML, maybe XML does not matter. Since they can regenerate (if they have system_messages.py).

Maybe the XML should have different sections for each PREFIX (module type).

I'd like an option to not include the abstract, XML headers, chapters so I can embed this XML easily into the guide itself. (That option would be useful for test if that was desired too.)

Maybe system_messages.py should have a sh-bang #! line at top. But then it would need to know path or correct name of the python to use. See bindctl_main.py.in (and configure.ac) for example.

comment:7 follow-up: Changed 9 years ago by stephen

system_messages.py is in the tools directory but these are not included in the tarball. If a user wants to regenerate it should be included. Even if included in the tarball, I do not think this requires any type of test, but if it did, it could be very simple.

Is it something we want to distribute? I was thinking that this is just a short-cut to produce part of the documentation and that we would distribute it in the same way.

Should the tarball include the XML? The HTML? I think yes for HTML, maybe XML does not matter. Since they can regenerate (if they have system_messages.py).

If we distribute the XML for the manual then yes, we should distribute the XML for this.

Maybe the XML should have different sections for each PREFIX (module type).

We can do this - the problem is getting some sort of introductory section for each prefix. Where do we put that? (Especially as at some time in the future we may have several different prefixes in the same message file.)

I'd like an option to not include the abstract, XML headers, chapters so I can embed this XML easily into the guide itself. (That option would be useful for test if that was desired too.)

At the moment everything is hard-coded into code. I can modify it so that all the section information is in some form of template file. We could then set up different templates for different circumstances.

Maybe system_messages.py should have a sh-bang #! line at top. But then it would need to know path or correct name of the python to use. See bindctl_main.py.in (and configure.ac) for example.

I'll do this.

This ticket is still assigned to you - are you finished reviewing?

comment:8 in reply to: ↑ 7 Changed 9 years ago by jreed

Replying to stephen:

system_messages.py is in the tools directory but these are not included in the tarball. If a user wants to regenerate it should be included. Even if included in the tarball, I do not think this requires any type of test, but if it did, it could be very simple.

Is it something we want to distribute? I was thinking that this is just a short-cut to produce part of the documentation and that we would distribute it in the same way.

We should allow others to regenerate. I think we should ship it. Especially if we ship the XML (see below).


Should the tarball include the XML? The HTML? I think yes for HTML, maybe XML does not matter. Since they can regenerate (if they have system_messages.py).

If we distribute the XML for the manual then yes, we should distribute the XML for this.

Ok.

Maybe the XML should have different sections for each PREFIX (module type).

We can do this - the problem is getting some sort of introductory section for each prefix. Where do we put that? (Especially as at some time in the future we may have several different prefixes in the same message file.)

We can ignore this for now.

I'd like an option to not include the abstract, XML headers, chapters so I can embed this XML easily into the guide itself. (That option would be useful for test if that was desired too.)

At the moment everything is hard-coded into code. I can modify it so that all the section information is in some form of template file. We could then set up different templates for different circumstances.

We can ignore this for now also. We won't embed into the guide. But link to it.

Maybe system_messages.py should have a sh-bang #! line at top. But then it would need to know path or correct name of the python to use. See bindctl_main.py.in (and configure.ac) for example.

I'll do this.

This ticket is still assigned to you - are you finished reviewing?

Since same ticket also included the guide additions, I will do some minor edits on that also.
And add a link to the messages file.

I'd also like to mention the possible severity levels here and the proposed debug rules (above 20 is for developer). We can fine tune it later.

comment:9 Changed 9 years ago by jreed

I made minor changes to documentation. commit 4a88c75d4d1decc3b3d5518bd12d592c118a7fd5

comment:10 Changed 9 years ago by jreed

commit 77e3f8cf3f3fe79c7dd5f92f30d70c47b515f4cd adds anchor, for example:

http://bind10.isc.org/docs/bind10-messages.html#DATASRC_QUERY_REF_FAIL

comment:11 Changed 9 years ago by jreed

commit 77e3f8cf3f3fe79c7dd5f92f30d70c47b515f4cd links to guide, minor grammar fix, and remove comma from the ID message.

comment:12 Changed 9 years ago by jreed

  • Owner changed from jreed to UnAssigned

The python script looks good to me. I don't think it needs a thorough code review if not shipped.

You may merge this into the master now. We can reconsider if we want the system_messages.py script in tarball later.

For changes entry, something like:

Add some initial documentation about the logging framework. Provide BIND 10 Messages Manual in HTML and DocBook? XML formats. This provides all the log message descriptions in a single document. A developer tool, tools/system_messages.py (available in git repo), was written to generate this.

I have added to my release checklist a step to make sure the bind10-messages.html is up-to-date.

comment:13 Changed 9 years ago by jreed

Three other commits to branch include:

52adf933c0bed4753a06632b25a46055d23eb655

4fe29ae03d1ff8f6d721b42f4bb356702110c4e0

e3fa282a59eea69c50dcb9354e568a8503510511

I am done for now. Please merge to master.

comment:14 Changed 9 years ago by jreed

  • Owner changed from UnAssigned to stephen

comment:15 Changed 9 years ago by stephen

  • Estimated Difficulty changed from 0.0 to 3
  • Resolution set to complete
  • Status changed from reviewing to closed

Merged to master in commit 502100d7b9cd9d2300e78826a3bddd024ef38a74

Note: See TracTickets for help on using tickets.