Diagnostic Provider Extensible Markup Language

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

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

• Include the Document type definition (DTD) for our Diagnostic Provider at the beginning of every DP declaration 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 two 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 following startup, only show it in the startup section (for example, a configuration attribute containing a file name from which startup data is read).

Create a Diagnostic Provider

Work with Diagnostic Providers