Enabling Metrics and Storage Types

Given below are the configurations that should be in place for your WSO2 product to use the metrics feature. You need to first enable metrics for your server and then enable the required storage types (reporters) that will be used for storing the metrics data. See the following topics for instructions:

Enabling metrics

To enable metrics for your product, set the Enabled parameter under the Metrics element to true in the <PRODUCT_HOME>/repository/conf/metrics.xml file. Alternatively, you can enable metrics at the time of starting the server by using the following command:

-Dmetrics.enabled=true

Once metrics are enabled, the metrics dashboard will be updated for your product.

Configuring the storage of metrics

WSO2 products (based on Carbon 4.4.x Kernel versions) are configured by default to store the information from metrics in the following reporters: JMX, CSV and JDBC. These reporters are configured in the metrics.xml file (stored in the <PRODUCT_HOME>/repository/conf directory). You can disable metrics for individual reporters by setting the Enabled parameter to false.

If you set the the Enabled parameter under the Metrics element to false in the metrics.xml file, metrics will be disabled for all the reporters and it is not possible to enable metrics for individual reporters.

See the following topics for information on configuring each of the available storage types.

JMX

The following parameters in the metrics.xml file can be used to configure a JMX storage for metrics data.

Element Name	Description	Type	Default Value	Mandatory/Optional
Enabled	This parameter specifies whether ot noy metics monitoring is enabled for JMX.	Boolean	true	Mandatory

CSV

The following parameters in the metrics.xml file can be used to configure a CSV storage for metrics data.

Element Name	Description	Type	Default Value	Mandatory/Optional
Enabled	This parameter specifies whether or not metrics monitoring is enabled for CSV.	Boolean	false	Mandatory
Location	The location where the CSV files are stored.	String	${carbon.home}/repository/logs/metrics/
PollingPeriod	The time interval between polling activities that are carried out to update the metrics dashboard based on latest information. For example, if the polling period is 60, polling would be carried out every 60 milliseconds.	Integer	60

JDBC

H2 is not recommended in production

The H2 database is NOT recommended in enterprise testing and production environments. It has lower performance, clustering limitations, and can cause file corruption failures. Please use an industry-standard RDBMS such as Oracle, PostgreSQL, MySQL, or MS SQL instead. See the instructions on setting up an RDBMS.

The following parameters in the metrics.xml file can be used to configure a JDBC storage for metrics data.

Element Name	Description	Type	Default Value	Mandatory/Optional	Notes
Enabled	This parameter specifies whether or not metrics monitoring is enabled for JDBC.	Boolean	true	Mandatory
DataSourceName	The name of the datasource used.	String	`jdbc/WSO2MetricsDB`
PollingPeriod	The time interval between polling activities that are carried out to update the metrics dashboard based on latest information. For example, if the polling period is 60, polling would be carried out every 60 milliseconds.	Integer	60		This value is specified in milliseconds.
ScheduledCleanup	This element contains parameters relating to scheduled cleanup. The possible values are `Enabled`, `ScheduledCleanupPeriod` and `DaysToKeep`. Scheduled cleanup involves scheduling a task to clear metric data in the database after a specified time interval. This is done to avoid excessive memory usage.
ScheduledCleanup/Enabled	This parameter specifies whether or not scheduled cleanup is enabled.	Boolean	true
ScheduledCleanup/ScheduledCleanupPeriod	The number of milliseconds that should elapse after a clean-up task before the next clean-up task is carried out.	Integer	86400
ScheduledCleanup/DaysToKeep	The number of days during which the scheduled clean-up task should be carried out.	Integer	7

If you have enabled JDBC, then you also need to specify a datasource configuration, which will be used to create the connection between the WSO2 product and the JDBC data storage system. The metrics-datasources.xml file is used for configuring this datasource for metrics.

Parameters that can be configured for a datasource are as follows:

XML element	Attribute	Description	Data type	Default value	Mandatory/Optional
`<datasources-configuration>`	`xmlns`	The root element. The namespace is specified as: `xmlns:svns="http://org.wso2.securevault/configuration"`			Mandatory
`<providers>`		The container element for the datasource providers.			Mandatory
`<provider>`		The datasource provider, which should implement `org.wso2.carbon.ndatasource.common .spi.DataSourceReader`. The datasources follow a pluggable model in providing datasource type implementations using this approach.	Fully qualified Java class		Optional
`<datasources>`		The container element for the datasources.			Mandatory
`<datasource>`		The root element of a datasource.			Mandatory
`<name>`		Name of the datasource.	String		Mandatory
`<description>`		Description of the datasource.	String		Optional
`<jndiConfig>`		The container element that allows you to expose this datasource as a JNDI datasource.			Optional
`<name>`		The JNDI resource name to which this datasource will be bound.	String		Mandatory if specifying JNDI configuration
`<environment>`		The container element in which you specify the following JNDI properties: `java.naming.factory.initial`: Selects the registry service provider as the initial context. `java.naming.provider.url`: Specifies the location of the registry when the registry is being used as the initial context.	Fully qualified Java class		Optional
`<definition>`	`type`	The container element for the data source definition. Set the `type` attribute to "RDBMS", or to "custom" if you're creating a custom type. The "RDBMS" datasource reader expects a `configuration` element with the sub elements listed below.	String		Mandatory
`<configuration>`		The container element for the RDBMS properties.			Mandatory if definition type is RDBMS
`<url>`		The connection URL that passes the JDBC driver to establish the connection.	URL		Mandatory
`<username>`		The connection user name that passes the JDBC driver to establish the connection.	String		Optional
`<password>`		The connection password that passes the JDBC driver to establish the connection.	String		Optional
`<driverClassName>`		The class name of the JDBC driver.	Fully qualified Java class		Mandatory
`<maxActive>`		The maximum number of active connections that can be allocated from this pool at the same time.	Integer	100	Optional
`<maxWait>`		Maximum number of milliseconds that the pool waits (when there are no available connections) for a connection to be returned before throwing an exception.	Integer	30000 (30 seconds)	Optional
`<testOnBorrow>`		Specifies whether objects will be validated before being borrowed from the pool. If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another. When set to `true`, the `validationQuery` parameter must be set to a non-null string.	Boolean	false	Optional
`<validationQuery>`		The SQL query that is used for validating connections from this pool before returning them to the caller. If specified, this query does not have to return any data, as it cannot throw an SQLException. The default value is "null". Example values are `SELECT 1`(mysql), `select 1 from dual`(oracle), `SELECT 1`(MS Sql Server).	String	null	Mandatory when `testOnBorrow` is set to true
`<validationInterval>`		To avoid excess validation, a connection will be validated at this frequency, at most (interval time in milliseconds). If a connection is due for validation, but has been validated previously within this interval, it will not be validated again. The default value is 30000 (30 seconds).	Long	30000 (30 seconds)	Optional

Sample configuration

Shown below is a sample metrics.xml file with the default configurations specifying the types of storages enabled for metrics data. See the above topics for instructions.

The default configurations in the metrics.xml file

-->

<!--
    This is the main configuration file for metrics
-->

<Metrics xmlns="http://wso2.org/projects/carbon/metrics.xml">

    <!--
        Enable Metrics
    -->
    <Enabled>false</Enabled>
    <!--
        Metrics reporting configurations
    -->

    <Reporting>
        <JMX>
            <Enabled>true</Enabled>
        </JMX>
        <CSV>
            <Enabled>false</Enabled>
            <Location>${carbon.home}/repository/logs/metrics/</Location>
            <!-- Polling Period in seconds -->
            <PollingPeriod>60</PollingPeriod>
        </CSV>
        <JDBC>
            <Enabled>true</Enabled>
            <!-- Source of Metrics, which will be used to
                identify each metric in database -->
            <!-- Commented to use the hostname
                <Source>Carbon</Source>
            -->
            <!--
                JNDI name of the data source to be used by the JDBC Reporter.
                This data source should be defined in a *-datasources.xml
                file in conf/datasources directory.
            -->
            <DataSourceName>jdbc/WSO2MetricsDB</DataSourceName>
            <!-- Polling Period in seconds -->
            <PollingPeriod>60</PollingPeriod>
            <ScheduledCleanup>
                <!--
                    Schedule regular deletion of metrics data older than a set number of days.
                    It is strongly recommended that you enable this job to ensure your metrics tables do not get extremely
                    large. Deleting data older than seven days should be sufficient.
                -->
                <Enabled>true</Enabled>
                <!-- This is the period for each cleanup operation in seconds -->
                <ScheduledCleanupPeriod>86400</ScheduledCleanupPeriod>
                <!-- The scheduled job will cleanup all data older than the specified days -->
                <DaysToKeep>7</DaysToKeep>
            </ScheduledCleanup>
        </JDBC>
    </Reporting>
</Metrics>

Once you have enabled Metrics as explained above, proceed to the section on configuring metric properties for information on how to configure the gauges on the metrics dashboard.