Configure Custom Metrics

Database Visibility extends monitoring by specifying SQL queries to run on the monitored database and the queries run during normal database activity. You can schedule these custom queries to run on regular intervals and collect the results in a custom metric. See Database Custom Metrics Window.

To specify custom queries to run:

Navigate to Configuration > Custom Metrics > New.

Complete the following fields:

Name: The name you want to name your custom metric. Once you create a custom metric/event, you cannot change its name.
Custom Query Metric Type: The type of result that you want from the query.
1. Select the Metric type to generate metrics for which health rules can be defined. Metrics of this type are displayed in the Metric Browser or in the Custom Metrics tab of each collector.
2. Select the Event Data type to generate custom events whenever the custom query output is non-empty. If you want to be notified when a custom event occurs, you can create a policy that is triggered by that custom event. Custom events are displayed in the Events tab. If the custom query outputs multiple rows, the first 40 rows will be included in the event details. Each row displays a maximum of 5000 characters, including the column separators (|).
Database Type: The database platform that you want to run the metric on.
Databases: The database instances that you want to run the metric on. You can run the metric on all database instances of the specified database type or specific database instances you specify. However, in the case of a cluster, you cannot run the metric on a specific database instance.

Schedule: The time interval at which you want to run the query. For metric type custom queries, the metric value reported in between the specified intervals is the value observed in the previous query execution. The timeout for configured custom metric depends on the frequency of running the query. The following table provides the timeout details based on the time interval, and the properties that you can use to configure the custom timeout value:


Interval (minutes)	Default Timeout (seconds)	Maximum Allowed Timeout (seconds)	Properties
1	10	50	`dbagent.custommetric.query.timeout.for.1.min.interval`
5	15	180	`dbagent.custommetric.query.timeout.for.5.min.interval`
10	30	300	`dbagent.custommetric.query.timeout.for.10.min.interval`
30	60	300	`dbagent.custommetric.query.timeout.for.30.min.interval`
60	120	300	`dbagent.custommetric.query.timeout.for.60.min.interval`
360	180	300	`dbagent.custommetric.query.timeout.for.360.min.interval`
720	300	300	`dbagent.custommetric.query.timeout.for.720.min.interval`
1440	300	300	`dbagent.custommetric.query.timeout.for.1440.min.interval`

Note: If you specify a value greater than the maximum allowed timeout value, then the maximum allowed timeout value is considered.

Warning:

When you increase the query timeout value, it may affect the query executions. If there are multiple high frequency queries with high timeout values, it may result in missed executions of those queries and other queries as well.

You can manage this behaviour to some degree by:

Enabling the dbagent.custom.metric.high.frequency.multithreading.enabled property: This property enables an additional thread for high-frequency queries, a total of two high-frequency threads. This makes the high-frequency queries execution faster and thus reduce missed queries. However, it may also result in low or medium frequency queries being stalled or missed due to unavailability of connections.
Increasing the number of database connections:
By default, Database Monitoring uses two database connections for custom queries. If you have enabled the dbagent.custom.metric.high.frequency.multithreading.enabled property for high-frequency dual-threading, Database Monitoring utilizes both connections. You can then increase the number of connections so that low and medium frequency threads have connections available to run their queries. However,more connections result in higher session consumption on the database. Because sessions in a database instance are a limited resource, this may impact database performance and session availability for other database clients.

Query Text: The query that you want to execute. If you are creating a custom metric of Metric type, its query must have one of the following return types:

Positive integer. For example, the query below returns a positive integer.
```
SELECT COUNT(*) FROM employees
```
String and positive integer. For example, the query below returns a string and a positive integer.
```
SELECT name, salary FROM employees
```

Custom queries appear for all collectors, but the data only reflects the collector that you created it for. You can test the semantics of the query and also validate the results by clicking the Test Query button.

Note: Custom query results are validated if the Database Agent >= 4.5.5.

The following points provide information about using limits when configuring custom metrics:

Up to 150 custom metrics can be reported per collector per minute.You can increase the custom metrics limit from the agent configuration properties by using the key, dbagent.custom.metric.reportable.per.server and the Max value 150. See Database Agent Configuration Properties for information about the key value.
The maximum limit configured in the agent takes precedence and overrides the maximum limit configured at the account level and Controller level. Therefore, the priority order is as following:
- Agent-level configuration
- Account-level configuration
- Controller-level configuration

Custom metrics are supported for all relational databases: MySQL, Microsoft SQL Server, Microsoft Azure SQL, Oracle, PostgreSQL, DB2, SAP HANA, and Sybase.