Best Practices for Diagnostic Provider Extensible Markup Language

 

Some conventions to follow for Diagnostic Provider (DP) Extensible Markup Language (XML) declarations. These guidelines are to help keep your use of Diagnostic Providers (DP) consistent.

• Include the Document type definition (DTD) for your Diagnostic Provider at the top 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 you 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 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

Creating a Diagnostic Provider
Work with Diagnostic Providers

 

Reference topic