Collecting Custom Metrics with Database Monitoring

Use custom_queries to collect metrics from any table the Agent’s database user can read. This extends the data available in Datadog beyond the query performance metrics that Database Monitoring collects natively, such as application state tables, business counters, or queue depths.

Before you begin

The Datadog Agent must be installed and the database integration configured. The Agent’s database user needs SELECT on any tables you query.

Configuration

Add custom_queries to your integration’s conf.yaml file. Each entry in the list runs one SQL query and maps its output columns to metrics or tags.

OptionRequiredDescription
metric_prefixYesAll metrics emitted by this query begin with this prefix.
queryYesThe SQL to execute. All returned rows are evaluated. Use the pipe character (|) for multi-line queries.
columnsYesA list of columns in the same order as your SELECT. Each column requires a name and a type. Set type to gauge, count, rate, or another metric type to emit a metric, or tag to apply the column value as a tag on every metric from this query.
tagsNoA list of static tags applied to every metric from this query.

Notes:

  • The number of columns entries must equal the number of columns returned by the query.
  • The order of columns entries must match the order of columns returned by the query.
  • At least one entry in columns must be a metric type (not tag).

Examples

    Add custom_queries to your postgres.d/conf.yaml file.

    If the query reads from a table the datadog user cannot already access, grant the permission first:

    GRANT SELECT ON <TABLE_NAME> TO datadog;

    Example: The following company table contains employee records:

    id | name  | age | address    | salary
---------------------------------------
1  | Paul  | 32  | California | 20000
2  | Allen | 25  | Texas      | 30000
3  | Teddy | 23  | Norway     | 45000

    To collect age and salary as metrics with name and address as tags:

    custom_queries:
  - metric_prefix: postgresql.employee
    query: SELECT age, salary, name, address FROM company
    columns:
      - name: employee_age
        type: gauge
      - name: employee_salary
        type: gauge
      - name: name
        type: tag
      - name: address
        type: tag
    tags:
      - source:hr_db

    After you update the file, restart the Agent.

    For the full configuration reference, see Postgres Custom Metric Collection.

    Add custom_queries to your mysql.d/conf.yaml file.

    Important: All table references must include the database name (database_name.table_name). If you omit the database name, the Agent fails with the error: No database selected.

    Example: The following company table in the testdb database contains employee records:

    id | name  | age | address    | salary
---------------------------------------
1  | Paul  | 32  | California | 20000
2  | Allen | 25  | Texas      | 30000
3  | Teddy | 23  | Norway     | 45000

    To collect age and salary as metrics with name and address as tags:

    custom_queries:
  - metric_prefix: mysql.employee
    query: SELECT age, salary, name, address FROM testdb.company
    columns:
      - name: employee_age
        type: gauge
      - name: employee_salary
        type: gauge
      - name: name
        type: tag
      - name: address
        type: tag
    tags:
      - source:hr_db

    After you update the file, restart the Agent.

    For the full configuration reference, see MySQL Custom Queries.

    SQL Server supports two approaches for collecting custom metrics: custom queries or performance counters.

    Custom queries

    Add custom_queries to your sqlserver.d/conf.yaml file to collect metrics from any table.

    Example: The following company table in testdb contains employee records:

    id | name  | age | address    | salary
---------------------------------------
1  | Paul  | 32  | California | 20000
2  | Allen | 25  | Texas      | 30000
3  | Teddy | 23  | Norway     | 45000

    To collect age and salary as metrics with name and address as tags:

    custom_queries:
  - metric_prefix: sqlserver.employee
    query: SELECT age, salary, name, address FROM testdb.dbo.company
    columns:
      - name: employee_age
        type: gauge
      - name: employee_salary
        type: gauge
      - name: name
        type: tag
      - name: address
        type: tag
    tags:
      - source:hr_db

    Performance counters

    Use custom_metrics to collect metrics from sys.dm_os_performance_counters and other system DMVs.

    custom_metrics:
  - name: sqlserver.clr.execution
    counter_name: CLR Execution
    OptionRequiredDescription
    nameYesThe metric name in Datadog.
    counter_nameYesThe counter name from sys.dm_os_performance_counters.
    instance_nameNoA specific counter instance. Use ALL to collect all instances (requires tag_by).
    tag_byNoTag name used to differentiate instances when instance_name: ALL.

    After you update the file, restart the Agent.

    For the full configuration reference, including performance counter details and the legacy stored procedure method, see Collect SQL Server Custom Metrics.

    Validation

    After the Agent runs, search for your metrics in the Metrics Explorer.

    To check for configuration errors, run the Agent’s status subcommand and look for your integration under the Checks section:

    postgres
--------
  - instance #0 [ERROR]: 'Missing metric_prefix parameter in custom_queries'
  - Collected 0 metrics, 0 events & 0 service checks

    Further Reading

    Additional helpful documentation, links, and articles:

    Database MonitoringDOCUMENTATION more more Metric TypesDOCUMENTATION more more