GlassFish - World's first Java EE 7 Application Server


Logging Documentation Plan for GlassFish Server Open Source Edition 3.1

People and Roles

Name Role Location Time Zone Email
Scott Fordin Documentation Feature Owner Burlington, MA, USA US/Eastern sfordin@dev.java.net
Paul Davies Peer Reviewer Santa Clara, CA, USA US/Pacific pauldavies@dev.java.net
Naman Mehta Feature Lead Santa Clara, CA, USA US/Pacific namanmehta@dev.java.net
Anissa Lam Software Engineer Santa Clara, CA, USA US/Pacific anilam@dev.java.net
Vince Kraemer Software Engineer Santa Clara, CA, USA US/Pacific VinceKraemer@dev.java.net
Jerome Dochez Software Engineer Santa Clara, CA, USA US/pacific dochez@dev.java.net

Audience

This feature is aimed at system administrators, application developers, and product support engineers.

Summary of the Feature From a User's Perspective

The Logging & Diagnostic components provide GUI and command-line tools for configuring, searching, viewing, and archiving server logs. These features will be available for standalone instances, DAS, and cluster nodes.

Availability

This feature is available in all GlassFish Server distributions.

Statement of Work

This section describes in detail for each document the work that is required by the introduction of the feature, such as changes, addition of new material, relocation of existing material, and removal of existing material.

Documentation Impact:

  • None
  • Minor
  • Moderate
  • Major
  • New

Note - If a document is task based (as opposed to reference), the changes should be determined from the user task analysis for the feature.

Changes to Books

Error Message Reference Changes

Section Documentation Impact Writer Reviewers Description of Change
Message IDs and Diagnostic Information New Scott All reviewers Entire book will be regenerated from properties files.

Administration Guide Changes

Section Documentation Impact Writer Reviewers Description of Change
Chapter 7, Administering the Logging Service        
   About Logging, Logging Targets New Scott All reviewers New subsection to introduce concept of targets, logging.properties per instance/node target.
   Setting Log Levels Moderate Scott Naman, Anissa Explain setting levels per instance/node target.
   Viewing Log Records New Scott Naman, Anissa New search filters, ZIP file compilation.
   Viewing Log Records New Scott Naman, Anissa Explanations corresponding to 2.1.1 features: display-log-records, display-error-distributions, display-error-statistics.
   Compiling Log Records Into a ZIP File New Scott Naman, Anissa Explain how to use new ZIP compilation feature.
Appendix A., Subcommands for the asadmin Utility        
   set-log-levels Minor Scott Naman, Anissa Rename; add --target option.
   list-log-levels Minor Scott Naman, Anissa Rename; add --target option.
   display-log-records Moderate Scott Naman, Anissa Pull in from 2.1.1; rework for 3.0.1, add --target option.
   display-error-distributions Moderate Scott Naman, Anissa Pull in from 2.1.1; rework for 3.0.1, add --target option.
   display-error-statistics Moderate Scott Naman, Anissa Pull in from 2.1.1; rework for 3.0.1, add --target option.
   collect-log-files New Scott Naman, Anissa New subcommand for compiling logs into ZIP file.

Troubleshooting Guide Changes

Section Documentation Impact Writer Reviewers Description of Change
Examining Log Files, in Chapter 1 Moderate Scott Anissa Add description of node options, ZIP file compilation.

Changes to man Pages

asadmin man Page Changes

Topic Title Documentation Impact Writer Reviewers Description of Change
set-log-levels Minor Scott Naman, Anissa Rename; add --target option.
list-log-levels Minor Scott Naman, Anissa Rename; add --target option.
display-log-records Moderate Scott Naman, Anissa Pull in from 2.1.1; rework for 3.0.1, add --target option.
display-error-distributions Moderate Scott Naman, Anissa Pull in from 2.1.1; rework for 3.0.1, add --target option.
display-error-statistics Moderate Scott Naman, Anissa Pull in from 2.1.1; rework for 3.0.1, add --target option.
collect-log-files New Scott Naman, Anissa New subcommand for compiling logs into ZIP file.

Changes to Online Help

Admin Console Online Help Changes

See the GlassFish 3.1 Admin Console Doc Plan for a list of Admin Console online help changes.

Review Schedule

The review schedule for the documentation items that are affected by this feature is provided in the following table.

Item Review Start Date Review End Date
Error Message Reference changes    
Administration Guide changes    
Troubleshooting Guide_ Changes    
asadmin man Page changes    
Admin Console online help changes    

Reviewers are listed in the Statement of Work.

Please use the Logging Documentation Review page to provide your review comments on the Logging documentation deliverables.

Related Information

Email aliases:

Comments:
Comment ID
Section Comment
PMD-001 Error Message Reference Changes As you'll have to regenerate the entire book from the properties files, change columns in this table as follows:
  • Change the Documentation Impact to New.
  • Change the Description of Change to state that the entire book will be regenerated from the properties files.
PMD-002 Administration Guide Changes:
Chapter 7, Administering the Logging Service
Appendix A., Subcommands for the asadmin Utility 		If the sections that follow are listed in later rows are subsections of the chapter or appendix, delete the content of the other cells in the chapter or appendix row and and indent the content of the first column in each subsection row. That way, it'll be clearer that you are itemizing the individual changes in each chapter and appendix. This would be so much easier if wiki tables supported cell spans.
PMD-003 Administration Guide Changes, Viewing Log Records Delete the references to the wiki feature. Log messages will be published in the Error Message Reference. The references in the 1-pager and the project page to publication of log messages in a wiki are erroneous. I have asked Naman to correct these errors.
PMD-004 Administration Guide Changes: set-log-level, list-logger-levels, display-log-records, display-error-distributions, and display-error-statistics Ensure that the target option is preceded by 2 dashes.
PMD-005
Reference Manual Changes Delete this section. The changes to man pages are propagated automatically to the Reference Manual without further intervention from the writer, so they do not need to be listed twice.
PMD-006
Troubleshooting Guide Changes You can probably just delete the 1st row in this table and change the 1st column of the 2nd row to read "Examining Log Files in Chapter".
PMD-007
Troubleshooting Guide Changes Delete the references to the wiki feature. See PMD-003
PMD-008 Changes to Man Pages
Ensure that the target option is preceded by 2 dashes.
PMD-009
Changes to Online Help
Move the content of this section to the Administration Console Documentation Plan and add a cross-reference to that plan.

Determine the online help set to which the topics listed in Log Viewer Online Help Changes belong (probably common). There is no separate online help set for the log viewer.
Posted by pauldavies at Jul 28, 2010 17:00
Comment ID Response
PMD-001 Made requested changes to Impact and Description.
PMD-002 Made requested formatting changes.
PMD-003 Deleted all references to wiki feature.
PMD-004 Globally changed all target references to --target.
PMD-005 Deleted section.
PMD-006 Made requested formatting change.
PMD-007 See response to PMD-003.
PMD-008 See response to PMD-004.
PMD-009 Moved content to GlassFish 3.1 Admin Console Doc Plan; fleshed out topics some more.
Posted by sfordin at Aug 18, 2010 14:27

Added link to the new Logging Documentation Review page. Please use this page to provide comments on the Logging documentation deliverables.
Posted by sfordin at Sep 28, 2010 12:43