Collect Mongo Custom Metrics

Collect Mongo Custom Metrics

To collect custom metrics with the Datadog-Mongo integration, use the custom_queries option in the conf.d/mongo.d/conf.yaml file at the root of your Agent’s configuration directory. See the sample mongo.d/conf.yaml for more details.

Configuration

custom_queries has the following options:

  • metric_prefix: Each metric starts with the chosen prefix.
  • query: This is the Mongo runCommand query to execute as a JSON object. Note that The Agent only supports count, find, and aggregates queries.
  • fields: Ignored for count queries. This is a list representing each field with no specific order. Ignores unspecified and missing fields. There are three required pieces of data for each fields:
    • field_name: This is the name of the field from which to fetch the data.
    • name: This is the suffix to append to the metric_prefix to form the full metric name. If type is tag, this column is treated as a tag and applied to every metric collected by this particular query.
    • type: This is the submission method (gauge, count, rate, etc..). This can also be set to tag to tag each metric in the row with the name and value of the item in this column. You can use the count type to perform aggregation for queries that return multiple rows with the same or no tags.
  • tags: A list of tags to apply to each metric (as specified above).
  • count_type: For count queries only, this is the submission method (gauge, count, rate, etc…) of the count result. Ignored for non-count queries.

Examples

For the examples below, the following mongo collection user_collection is used:

{ name: "foo", id: 12345, active: true, age:45, is_admin: true}
{ name: "bar", id: 67890, active: false, age:25, is_admin: true}
{ name: "foobar", id: 16273, active: true, age:35, is_admin: false}

Choose the type of query you would like to see an example for:

To monitor how many users are active at a given time, your Mongo count command would be:

db.runCommand( {count: user_collection, query: {active:true}})

Which would correspond to the following custom_queries YAML configuration inside your mongo.d/conf.yaml file:

custom_queries:
  - metric_prefix: mongo.users
    query: {"count": "user_collection", "query": {"active":"true"}}
    count_type: gauge
    tags:
      - user:active

This would emit one gauge metric mongo.users with one tag: user:active.

Note: The metric type defined is gauge. See the metric type documentation to learn more.

To monitor the age per user, your Mongo find command would be:

db.runCommand( {find: user_colleciton, filter: {active:true} )

Which would correspond to the following custom_queries YAML configuration inside your mongo.d/conf.yaml file:

custom_queries:
  - metric_prefix: mongo.example2
    query: {"find": "user_colleciton", "filter": {"active":"true"}}
    fields:
      - field_name: name
        name: name
        type: tag
      - field_name: age
        name: user.age
        type: gauge

This would emit one gauge metric mongo.example2.user.age with two tags: name:foo and name:foobar

Note: The metric type defined is gauge. See the metric type documentation to learn more.

To monitor the average age for an admin and a non-admin user, your Mongo aggregate command would be:

db.runCommand(
              {
                'aggregate': "user_collection",
                'pipeline': [
                  {"$match": {"active": "true"}},
                  {"$group": {"_id": "$is_admin", "age_avg": {"$avg": "$age"}}}
                ],
                'cursor': {}
              }
            )

Which would correspond to the following custom_queries YAML configuration inside your mongo.d/conf.yaml file:

custom_queries:
  - metric_prefix: mongo.example3
    query: {"aggregate": "user_collection","pipeline": [{"$match": {"active": "true"}},{"$group": {"_id": "$is_admin", "age_avg": {"$avg": "$age"}}}],"cursor": {}}
    fields:
      - field_name: age_avg
        name: user.age
        type: gauge
      - field_name: _id
        name: is_admin
        type: tag
    tags:
      - test:mongodb

This would emit one gauge metric mongo.example3.user.age with two tags: is_admin:true and is_admin:false representing the average age of users for each tags.

Note: After updating the Mongo YAML file, restart the Datadog Agent.

Validation

To verify the result, search for the metrics using the Metrics Explorer:

Debugging

Run the Agent’s status subcommand and look for mongo under the Checks section. Additionally, the Agent’s logs may provide useful information.

Further Reading

Additional helpful documentation, links, and articles: