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 beginning of every DP declaration Extensible Markup Language (XML) file.
  • Start all names and name segments with lowercase. 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 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 that contains a file name from which startup data is read).