Operating Systems: i5/OS
             Personalize the table of contents and search results

 

Diagnostic Provider registered attributes and registered tests

 

Each Diagnostic Provider (DP) provides a list of state dump attributes, configuration dump attributes, self tests, and self test attributes. The tests are operations that the DP can perform. The attributes are pieces of information that are available for collection from a Configuration dump, a State dump, or a specific Self Diagnostic test.

Each attribute can be seen as a piece of information with a label on it. Each attribute is also considered to be either registered or not registered. A registered attribute is one that should be available from one release of WebSphere Application Server to the next. A nonregistered attribute might not be available in its current form in future releases of the product (no commitment has been made).

When performing a Configuration dump, a State dump, or a Self Diagnostic test, an administrator or automatic tooling can request only registered values, or all values, depending on the needs of the administrator or tool. Note that the option of filtering results is only available through the Diagnostic Provider's Java Management Extension (JMX) MBean interface, which you can access programmatically or through the wsadmin tool.

 

The DiagnosticProviderRegistration XML file

The DiagnosticProviderRegistration Extensible Markup Language (XML) file is used in conjunction with the method signatures to filter the results of calling the various methods. This XML file defines the configuration information, state information, and self diagnostic tests exposed by the component. In the configuration and state information, the key working unit is referred to as the attribute. Specification of an attribute is as follows: 

<attribute>
        <id><Regular Expression representing the attribute name></id>
        <descriptionKey><MsgKey into a ResourceBundle for localization of the label></descriptionKey>
        <registered>true</registered>
   </attribute>
The parts are as follows:

ID:

The attribute's name. This name can be expressed with wildcard characters conforming to regular expression syntax. The registered attribute ID is used in the following places:

As an example, if a configuration dump returns an attribute with ID cachedServlet-MyServlet-servletPath to the administration console, the administration console could use the descriptionKey corresponding to the attribute registered as <id>cachedServlet-.*-servletPath</id> when selecting what description text to put next to this attribute's name and return values.

descriptionKey:

This is a key into a resourceBundle for localization.

registered:

This is a boolean qualifying whether this attribute will be available from one release of the software to the next. If registered is true, then this attribute should be available in the next release. If registered is false, then there is no guarantee that this attribute will continue to exist. Automation should use some caution when handling non-registered attributes.
Specification of a selfDiagnosticTest is as follows: 

<test>
       <id><Regular Expression for the name of the test></id>
       <descriptionKey><MsgKey into a ResourceBundle for localization of the label></descriptionKey>
       <attribute><One or more attributes which will be output from this test></attribute>
</test>
The parts are as follows:

ID:

Similar to the ID for the attribute, but in this case, describing the test to be performed instead of the attribute to be returned.

descriptionKey:

This is a key into a resourceBundle for localization.

 

Method interfaces 

public DiagnosticEvent [] configDump(String aAttributeId, boolean aRegisteredOnly);
public DiagnosticEvent [] stateDump(String aAttributeId, boolean aRegisteredOnly);

These methods invoke the configuration or state dump on the component, and specify a regular expression filter for the attributes to return as well as filtering the output to include all matching attributes, or only those attributes which are registered. This enables the administrator or automated software driving the method to specify a subset of the overall fields (especially important if many attributes are exposed or if the State Collection Specification increases the amount of data available). The following helper methods are available to assist with filtering the output. To take a list of Attributes that are available to return, and filter them: 

    public static AttributeInfo [] queryMatchingDPInfoAttributes(String aAttributeId,
        AttributeInfo [] inAttrs, String [] namesToCheck, boolean aRegisteredOnly) {
To take a single Attribute that is available to return, and filter it: 

    public static AttributeInfo queryMatchingDPInfoAttributes(String aAttributeId,
        AttributeInfo [] inAttrs, String nameToCheck, boolean aRegisteredOnly) {
To go through a populated set of Attribute Information and remove unneeded parts: 

    public static void filterEventPayload(String aAttributeId, HashMap payLoad) {

For details on these messages, please review the API documentation for the DiagnosticProviderHelper class. The basic concept is that, once the component knows what attributes are able to be returned, the helper method will determine which of them should be returned based on the regular expression logic and registration boolean. The selfDiagnostic Method interface here is similar to that of Configdump and Statedump: 

public DiagnosticEvent[] selfDiagnostic(String aTestId, boolean aRegisteredOnly)
The difference is that the first parameter is a regular expression filter for which test to run.

 

Related tasks


Working with Diagnostic Providers