Diagnostic Provider Extensible Markup Language

Some conventions to follow for Diagnostic Provider (DP) XML declarations.

These guidelines are to help keep the use of Diagnostic Providers (DP) consistent.

• Include the Document type definition (DTD) for the Diagnostic Provider at the top of every DP declaration Extensible Markup Language (XML) file.

• Start all names and name segments with lower case. Use camel case for attribute names. That is, capitalize every initial letter in the name, except the first. For example, traceCollectionSpec.

• Indicate hierarchy with dashes. Dashes work better than dots because attribute names are regular expressions. For example, traceService-traceCollectionSpec.

• Indicate string dynamic parts to attribute names using an asterisk (*). For example,

  vhosts-.*-webgroups-.*-webapps-.*-listeners-filterInvocationListeners 
  

  which would match vhosts-someHost-webgroups-someGroup-webapps-someApp-listeners-filterInvocationListeners

• Indicate numeric dynamic parts to attribute names using [0-9]*. For example,

  vhosts-index-[0-9]* 
  

  which would match webcontainer-vhosts-index-123

• If we have a general purpose self diagnostic test that can be run without significant performance cost, name it general.

 

Some tips for configDump implementation

• configDump should contain information used to define the component's environment. Some examples are:

  • configuration data set by Java Management Extensions (JMX)

  • configuration from system properties, xml files, and property files

  • configuration information hard-wired and unchanging in code (such as, if a resource adapter implements interface X, or has some static final field Y, then those could indicate aspects of configuration and be included in the configDump).

• configDump should not contain dynamically registered attributes, such as:

  • a list of registered loggers (this belongs in stateDump)

  • a list of servlets in an application (this belongs in stateDump).

• configDump should be separated into 2 sections -- startup and current.

  • All configDump attributes must start with either startup- or current-.

  • The startup section details the component's environment at startup time. Startup configDump attributes start with startup- .

  • The current section details the component's environment at the moment the configDump is requested. Current configDump attributes start with current-.

 

Best practices for configDump

• Group related attributes using an attribute hierarchy (such as, for two attributes about the traceLog: startup-traceLog-rolloverSize=20, startup-traceLog-maxNumberOfBackupFiles=1)

• For information in the current attribute list that refers to the same thing as a startup attribute, the names of both current and startup attributes should match.

• If an attribute has no use after startup, only show it in the startup section (for example, a configuration attribute that contains a file name from which startup data is read).

---

 

Related tasks

Create a Diagnostic Provider
Working with Diagnostic Providers