B Report File Configuration Elements

The report file configuration reference provides a detailed description of the report file deployment descriptor elements.

This appendix includes the following sections:

Report File Deployment Descriptor

The report file deployment descriptor specifies a report for displaying management information that is based on MBeans. The coherence.jar/reports directory contains many predefined report files. See Analyzing Report Contents. Modify the reports or create new reports as required.

The report file deployment descriptor schema is defined in the coherence-report-config.xsd file, which is located in the root of the coherence.jar library and at the following Web URL:

http://xmlns.oracle.com/coherence/coherence-report-config/1.1/coherence-report-config.xsd

The <report-config> element is the root element of the deployment descriptor and includes the XSD and namespace declarations. For example:

<?xml version='1.0'?>

<report-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://xmlns.oracle.com/coherence/coherence-report-config"
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-report-config
   coherence-report-config.xsd">

Note:

  • The schema that is located in the coherence.jar library is always used at run time even if the xsi:schemaLocation attribute references the Web URL.

  • Omit the xsi:schemaLocation attribute to disable schema validation.

  • When deploying Oracle Coherence into environments where the default character set is EBCDIC rather than ASCII, ensure that the deployment descriptor file is in ASCII format and is deployed into its run-time environment in the binary format.

Report File Element Reference

The report file element reference includes all non-terminal report file configuration elements. Each section includes instructions on how to use the element and also includes descriptions for all valid subelements.

column

Used in: row

Description

The column element contains information to generate a report column. The column element supports the use of an id attribute to uniquely identify the column. The ID is used within the column-ref subelement.

Elements

Table B-1 describes the subelements of the column element.

Table B-1 column Subelements

Element Required/ Optional Description

type

Optional

Specifies an XmlColumn implementation. The type element defines the type of the column in the report. The following values are valid:

  • attribute – (default) A column that contains the data from an MBean attribute.

  • key – A column that contains the value from an MBean key attribute.

  • method – A column that contains the result of an MBean method invocation.

  • function – A column that contains the result of a function or aggregation. See the function-name element in this table.

  • global – A column that contains a value not related to any specific MBean. Global column names are {report-time}, {report-count}, and {node-id}.

  • constant – A column that contains a constant string of numeric value.

  • property – A column that contains a value of a Java system property.

name

Optional

Specifies an attribute or method name on the MBean. For composite data types, the name element can contain a slash (/) delimited name sequence.

header

Optional

Specifies the column header. The value of the name element is used if this item is omitted.

delim

Optional

Specifies a character that separates column or array values. Valid values are {tab}, {space}, or any non-whitespace character.

query

Optional

Specifies information necessary to construct a JMX query to find all MBeans contributing to the report or column.

hidden

Optional

Specifies whether the column value is hidden in the report. Valid values are true and false.

column-ref

Optional

Specifies a reference to a column identifier. The reference passes a column value as an argument to a filter or another column.

function-name

Optional

Specifies the name of the calculation to apply to the associated MBean attribute values. This element is only valid when the type element is function. The following values are valid:

  • sum – The sum of all retrieved attribute values

  • avg – The average value for all retrieved attribute values

  • min – The minimum numeric value for all retrieved attribute values

  • max – The maximum numeric value for all retrieved attribute values

  • add – The sum of values for two column references

  • subtract – The difference between values for two column references

  • multiply – The product of values for two column references

  • divide – The ratio between values for two column references

params

Optional

Specifies an argument column or a filter reference

data-type

Optional

Specifies the data type of a constant column. Valid values are double and string.

value

Optional

Specifies the value of a constant column

group-by

Optional

specifies whether the column is included in the group by clause of the query. Valid values are true and false. The default values is false.

subquery

Optional

Specifies whether the column is included as part of a subquery. Valid values are true and false. The default values is false.

return-neg

Optional

Specifies if a negative value is returned to the query. Negative values are considered error or not available codes on Oracle Coherence MBeans. By default, these codes return zero to not affect column calculations. Valid values are true and false. The default values is false.

filter

Used in: filters

Description

The filter element defines a filter to use in the report. The filter element supports the use of an id attribute to uniquely identify the filter. Use the ID when referring to a filter with the filter-ref element. Filters can be referenced from within a params element and a query element.

Elements

Table B-2 describes the subelements of the filter element.

Table B-2 filter Subelements

Element Required/ Optional Description

type

Optional

Specifies an XmlFilter implementation. The type element defines the type of the filter in the report. The following values are valid:

  • equals – A filter that compares the result of two or more column references for a value equality.

  • greater – A filter that compares the results of two column references for the greater than condition. If any of the values is resolved to null, the evaluation yields false. (This approach is equivalent to the way the NULL values are handled by SQL.)

  • less – A filter that compares the results of two column references for the less than condition. If any of the values is resolved to null, the evaluation yields false.

  • not – A filter that returns the logical not of a filter reference.

  • and – A filter that returns the logical and of two filter references.

  • or – A filter that returns the logical or of two filter references.

params

Optional

Specifies an argument column or a filter reference

filters

Used in: report

Description

The filters element contains any number of filter elements.

Elements

Table B-3 describes the subelements of the filters element.

Table B-3 filters Subelements

Element Required/ Optional Description

filter

Optional

Defines a filter to use in the report

params

Used in: column, filter, query

Description

The params element identifies an argument column or a filter reference.

Elements

Table B-4 describes the subelements of the params element.

Table B-4 params Subelements

Element Required/ Optional Description

filter-ref

Required

Specifies a reference to a filter ID. The reference passes a filter as an argument to a query or another filter.

column-ref

Required

Specifies a reference to a column identifier. The reference passes a column value as an argument to a filter or another column.

query

Used in: column, report

Description

The query element contains information necessary to construct a JMX query to find all MBeans contributing to the report or column. Enter queries within a <pattern> element.

Examples

The following example includes all node MBeans in the report or column:

<query>
   <pattern>Coherence:type=Node,*</pattern>
</query>

The following example that includes only the Cluster MBean in the report or column:

<query>
   <pattern>Coherence:type=Cluster</pattern>
</query>

The pattern string allows macro substitutions with run-time values that come from report columns. For example, to provide a cache name in the query pattern, define a reporter.cacheName system property and use the following construct:

<report>
   ...
   <query>
      <pattern>Coherence:type=Cache,name={CacheName},*</pattern>
   </query>
   <row>
      <column id="CacheName">
         <type>property</type>
         <name>reporter.cacheName</name>
      </column>
   </row>
</report>

Sometimes a query pattern is known to result in a list of MBean names that have a well-known key attribute. Use the key attribute to retrieve an attribute from a related (joined) MBean. For example, because the Coherence:type=Service,* pattern is known to result in MBeans in the Coherence:type=Service,nodeId=NNN format, the following configuration below prints the MemberName attribute from a corresponding NodeMBean along with the ServiceName attribute for the ServiceMBean.

<report>
   ...
   <query>
      <pattern>Coherence:type=Service,*</pattern>
      <params>
         <column-ref>MemberName</column-ref>
         <column-ref>NodeId</column-ref>
         <column-ref>ServiceName</column-ref>
      </params>
   </query>
   <row>
      <column id="MemberName">
         <type>attribute</type>
         <name>MemberName</name>
         <query>
            <pattern>Coherence:type=Node,nodeId={NodeId}</pattern>
         </query>
      </column>
      <column id="NodeId">
         <type>key</type>
         <name>nodeId</name>
      </column>
      <column id="ServiceName">
         <type>key</type>
         <name>name</name>
      </column>
   </row>
</report>

Elements

Table B-5 describes the subelements of the query element.

Table B-5 query Subelements

Element Required/ Optional Description

pattern

Required

Specifies a JMX query or object name to include in the report

filter-ref

Optional

Specifies a reference to a filter ID. The reference passes a filter as an argument to a query or another filter.

params

Optional

Specifies an argument column or a filter reference

report

Used in: report-config

Description

The report element contains information necessary to generate a JMX-based report. A report can include any number of report elements; however, a report file typically contains a single report definition.

Elements

Table B-6 describes the subelements of the report element.

Table B-6 report Subelements

Element Required/ Optional Description

description

Optional

Specifies a descriptive heading for the associated report or column.

file-name

Required

Specifies the file name for the generated report. The file name is either absolute or relative to a directory that is specified in the corresponding report group deployment descriptor. If the specified file exists, then the new report lines are appended to the file; otherwise, a new report file is created.

The file name may contain three macros:

  • {batch} – This macro is replaced with a counter (a sequential number).

  • {node} – This macro is replaced with the cluster member ID. Use this macro to differentiate reports on different cluster members.

  • {date} – This macro is replaced with the current date (YYYYMMDD).

Note: A process running the reporter requires read, write, and create access to the report output directory.

delim

Optional

Specifies a character that separates column or array values. Valid values are {tab}, {space}, or any non-whitespace character.

hide-headers

Optional

Specifies whether the report includes description and column headers. Valid values are true and false.

filters

Optional

Specifies a group of filters for the report

query

Required

Specifies information necessary to construct a JMX query to find all MBeans contributing to the report or column

row

Required

Specifies information to generate a report row

report-config

Root Element

Description

The report-config element is the root element of the report configuration deployment descriptor and contains the report definition.

Elements

Table B-7 describes the subelements of the report-config element.

Table B-7 report-config Subelements

Element Required/ Optional Description

report

required

Specifies the information necessary to generate a JMX-based report

row

Used in: report-config

Description

The row element contains a list of columns to include in the report.

Elements

Table B-8 describes the subelements of the row element.

Table B-8 row Subelements

Element Required/ Optional Description

column

Required

Specifies the information that generates a report column