The Coherence reporting feature provides a capable query definition that allows for any information residing in the coherence JMX data source to be logged to a text file. After a custom report has been created, the custom report can be included in a report batch and executed on a specified time interval by the ReportControl MBean. For a complete description of the report configuration XML file see report-config.dtd.

This section provides the following information:

Configuring an Output File

The output file several items to be configured to correctly generate the file.

Specifying Data Columns

Data columns can be sourced from JMX Attributes, ObjectName key part, JMX composite attributes, JMX joined attributes, Report macros and Report Constants.

How to Include an Attribute

To include from MBeans returned from the query-pattern, the report must have a column with an attribute source. This is the most common item that will be included in the report.

To include the RoleName attribute from the query pattern "Coherence:type=Node,*".

<column id = "RoleName">
  <type>attribute</type>
  <name>RoleName</name>
  <header>Role Name</header>
</column>

How to Include Part of the Key

The ObjectName key part is including a value from the ObjectName key into the report from ObjectNames returned from the query-pattern.

To include the nodeId key part from the query pattern "Coherence:type=Node,*"

<column id ="NodeId">
  <type>key</type>
  <name>nodeId</name>
  <header>Node Id</header>
</column>

How to Include Information from Composite Attributes

JMX composite values are used to include part of a composite data attribute in a report.

To include the startTime of the LastGCInfo Attribute from the query pattern "java.lang:type=GarbageCollector,*".

<column id="LastGCStart">
   <type>attribute</type>
   <name>LastGcInfo/startTime</name>
   <header>Last GC Start Time</header>
</column>

How to Include Information from Multiple MBeans

A JMX join attribute is required when a report requires information from multiple MBeans. The major considerations when creating a join is to determine both the primary query, the join query and the foreign key. The primary query should be the query that returns the appropriate number of rows for the report. The join query pattern must reference a single MBEan and can not contain a wild card (*). The foreign key is determined by what attributes from the primary query that are required to complete the join query string.

The reporter feature that enables joins between MBeans is a column substitution macro. The column substitution allows for the resulting value from a column to be included as part of a string. A column substitution macro is a column id attribute surrounded by curly braces "{{}}". The reporter does not check for cyclical references and will fail during execution if a cycle is configured.

Including Multiple MBean Information Example

If a report requires TotalGets from the Cache MBean (Coherence:type=cache,*) and RoleName from the Node MBean (Coherence:type=Node,*), a join attribute must be used.

Since the larger number of MBeans will come from the Cache MBean, Coherence:type=Cache,* would be the primary query and the RoleName would be the join attribute. The foreign key for this join is the nodeId key part from the Cache MBean and it must be included in the report.

<column id="RoleName">
   <type>attribute</type>
   <name>RoleName</name>
   <header>Role Name</header>
    <query>
       <pattern>Coherence:type=Node,nodeId={NodeFK}</pattern>
    </query>
</column>

<column id ="NodeFK">
  <type>key</type>
  <name>nodeId</name>
  <header>Node Id</header>
</column>

Limitations on Join Attributes The major limitation of join attributes is that the result of the join must have only one value.

Report Macros

There are three report macros that can be included in a report:

• Report Time (report-time) is the time and date that the report was executed. This information is useful for time series analysis.
   
• Report Batch/Count (report-count) is a long identifier that can be used to correlate information from different reports executed at the same time.
   
• Reporting Node (report-node) is used when integrating information from the same report executed on different nodes or excluding the executing node information from the report.

To include the execution time into the report.

<column id ="ReportTime">
   <type>global</type>
   <name>{report-time}</name>
   <header>Report Time</header>
</column>

To include the Report Batch/Count

<column id="ReportBatch">
  <type>global</type>
  <name>{report-count}</name>
  <header>batch</header>
</column>

To include the execution node

<column id="ReportNode">
  <type>global</type>
  <name>{report-node}</name>
  <header>ExecNode</header>
  <hidden>true</hidden>
</column>

How to Include Constant Values

Report constants can be used to either static values or report parameters. These constants can be either double or string values. Often these are used in filters to limit the results to a particular data set or in calculations.

To include a constant double of 1.0

<column id ="One">
  <type>constant</type>
  <header>Constant1</header>
  <data-type>double</data-type>
  <value>1.0</value>
  <hidden>true</hidden>
</column>

To include a constant string of "dist-Employee"

<column id ="EmployeeCacheName">
  <type>constant</type>
  <header>Employee Cache Name</header>
  <data-type>string</data-type>
  <value>dist-Employee</value>
  <hidden>true</hidden>
</column>

Including Queries in a Report

The query is the foundation of the information included in a report. Each query includes a query pattern, column references, and an optional filter reference. The query pattern is a string that is a JMX ObjectName query string. This string can return 1 or more MBeans. The column references must be defined in the <columns> section of the report definition file. The filter reference must be defined in the <filters> section of the report section.

The following example illustrates how to include the list all the Node Ids and RoleNames in the cluster where the RoleName equals CoherenceServer.

<filters>
   <filter id="equalsRef">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>
</filters> 

<query>
   <pattern>Coherence:type=Node,*</pattern>
   <filter-ref>equalsRef</filter-ref>
</query>

<row>
  <column id ="NodeRef">
    <type>key</type>
    <name>nodeId</name>
    <header>Node Id</header>
  </column>

  <column id ="RoleRef">
    <name>RoleName</name>
    <header>Role</header>
  </column>

  <column id = "StringRef">
    <type>constant</type>
    <name>ConstString</name>
    <data-type>string</data-type>
    <value>CoherenceServer</value>
    <hidden>true</hidden>
  </column>
  
</row>

Using Filters to Construct Reports

Filters limit the data returned in the Report. Filters are either Comparison filters or Composite filters. Comparison Filters evaluate the results of 2 columns while Composite filters evaluate the boolean results from 1 or 2 filters. Comparison filters are "equals", "greater" and "less".

Composite Filter types are "and", "or", "not". Each composite filter evaluates the filter parameters first to last and standard boolean logic applies. Composite filter evaluation uses standard short circuit logic. Cyclic references checks are not done during execution and will create a runtime error.

Defining an equals filter where RoleRef and StringRef are defined columns.

<filters>
   <filter id="equals">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>
</filters>

Defining a filter where PacketsResent are Greater than PacketsSent (assuming PacketsResent and PacketsSent are valid column references).

<filters>
   <filter id="greaterRef">
     <type>greater</type>
     <params>
        <column-ref>PacketsResent</column-ref>
        <column-ref>PacketsSent</column-ref>
     </params>
   </filter>
</filters>

Defining an filter where PacketsResent are Less than PacketsSent (assuming PacketsResent and PacketsSent are valid column references).

<filters>
   <filter id="greaterRef">
     <type>less</type>
     <params>
        <column-ref>PacketsResent</column-ref>
        <column-ref>PacketsSent</column-ref>
     </params>
   </filter>
</filters>

Defining an "and" filter (assuming all column-ref values are valid).

<filters>
   <filter id="equalsRef">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>

   <filter id="greaterRef">
     <type>greater</type>
     <params>
        <column-ref>PacketsResent</column-ref>
        <column-ref>PacketsSent</column-ref>
     </params>
   </filter>

   <filter>
     <type>and</type>
     <params>
        <filter-ref>greaterRef</filter-ref>
        <filter-ref>equalsRef</filter-ref>
     <params>
   </filter>
</filters>

Defining an "or" filter (assuming all column-ref values are valid).

<filters>
   <filter id="equalsRef">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>

   <filter id="greaterRef">
     <type>greater</type>
     <params>
        <column-ref>PacketsResent</column-ref>
        <column-ref>PacketsSent</column-ref>
     </params>
   </filter>

   <filter>
     <type>or</type>
     <params>
        <filter-ref>greaterRef</filter-ref>
        <filter-ref>equalsRef</filter-ref>
     <params>
   </filter>
</filters>

Defining a not equals filter where RoleRef and StringRef are defined columns.

<filters>
   <filter id="equals">
     <type>equals</type>
     <params>
        <column-ref>RoleRef</column-ref>
        <column-ref>StringRef</column-ref>
     </params>
   </filter>

   <filter id = "Not">
     <type>not</type>
     <params>
        <filter-ref>equals</filter-ref>
     </params>  
   </filter>
</filters>

Using Functions to Construct a Report

Reporter Functions allow for mathematical calculations on data elements within the same row of the report. The supported functions are Add, Subtract, Multiply, and Divide. Function columns can then be included as parameters into other Function columns.

Function Examples

To add columns (Attribute1 and Attribute2) into a third column (Addition)

<column id="AttributeID1">
  <name>Attribute1</name>
</column>

<column id="AttributeID2">
  <name>Attribute2</name>
</column>

<column id="Addition">
  <type>function</type>
  <name>Add2Columns</name>
  <header>Adding Columns</header>
  <function-name>add</function-name>
  <params>
    <column-ref>AttributeID1</column-ref>
    <column-ref>AttributeID2</column-ref>
  </params>
</column>

To subtract one column (Attribute2) from another (Attribute1) into a third column (Subtraction)

<column id="AttributeID1">
  <name>Attribute1</name>
</column>

<column id="AttributeID2">
  <name>Attribute2</name>
</column>

<column id="Subtraction">
  <type>function</type>
  <name>Subtract2Columns</name>
  <header>Difference</header>
  <function-name>subtract</function-name>
  <params>


    <column-ref>AttributeID1</column-ref>
    <column-ref>AttributeID2</column-ref>
  </params>
</column>

To multiply columns (Attribute1 and Attribute2) into a third column (Multiplication).

<column id="AttributeID1">
  <name>Attribute1</name>
</column>

<column id="AttributeID2">
  <name>Attribute2</name>
</column>

<column id="Multiplication">
  <type>function</type>
  <name>Multiply2Columns</name>
  <header>Multiply Columns</header>
  <function-name>multiply</function-name>
  <params>
    <column-ref>AttributeID1</column-ref>
    <column-ref>AttributeID2</column-ref>
  </params>
</column>

To divide one column (Attribute1) by another (Attribute2) into a third column (Division). The result of all division is a Double data type.

<column id="AttributeID1">
  <name>Attribute1</name>
</column>

<column id="AttributeID2">
  <name>Attribute2</name>
</column>

<column id="Division">
  <type>function</type>
  <name>Dividing2Columns</name>
  <header>Division</header>
  <function-name>Divide</function-name>
  <params>
    <column-ref>AttributeID1</column-ref>
    <column-ref>AttributeID2</column-ref>
  </params>
</column>

Using Aggregates to Construct a Report

Reporter Aggregates allow for multiple rows to be aggregated into as single value/row.

Aggregate Examples

Sum the values in the "size" column

<column id ="SumRef">
   <type>function</type>
   <function-name>sum</function-name>
   <column-ref>size</column-ref>>
   <header>Sum</header>
</column>

Average the values in the "size" column

<column id ="AverageRef">
   <type>function</type>
   <header>Average</header>
   <function-name>avg</function-name>
   <column-ref>size</column-ref>>
</column>

Find the Maximum the value in the "size" column

<column id ="MaximumRef">
   <type>function</type>
   <header>Maximum</header>
   <function-name>max</function-name>
   <column-ref>size</column-ref>>
</column>

Find the Minimum the value in the "size" column

<column id ="MinimumRef">
   <type>function</type>
   <header>Minimum</header>
   <function-name>min</function-name>
   <column-ref>size</column-ref>>
</column>

Constructing Delta Functions

Many numeric attributes in the Coherence are cumulative. These values are reset only when the resetStatistics operation is executed on the MBean. To determine the state of the system without resetting the statistics the Reporter users a delta function. The Delta function subtracts the prior value of a column from the current value of a column and returns the difference.

The prior values for a report are stored in a map on the Reporter client. This map is keyed by the "delta key". The delta key by default is the MBean name for the attribute. However, when there is not a one-to-one relationship between MBean and rows in the report or the MBean name is subject to change between executions of the report, the delta key will be calculated using the columns provided in the <params> section.

Accuracy of Delta Functions Delta functions are only correct when the report is running as part of a report batch.

Delta Function Examples

How include a delta calculation of an Attribute. (Assume "PacketsSent" is a defined column)

<column id="DeltaPacketsSent">
  <type>function</type>
  <name>PacketsSent</name>
  <header>Delta Sent</header>
  <function-name>delta</function-name>
  <column-ref>PacketsSent</column-ref>
</column>

How include a delta calculation of an Attribute with an alternate "delta key". (Assume "PacketsSent", "NodeID" and "TimeStamp" are a defined columns)

<column id="DeltaPacketsSent">
  <type>function</type>
  <name>PacketsSent</name>
  <header>Delta Sent</header>
  <function-name>delta</function-name>
  <column-ref>PacketsSent</column-ref>
  <params>
     <column-ref>NodeID</column-ref>
     <column-ref>TimeStamp</column-ref>
  </params>
</column>