How to use Bean Regexes to filter your JMX metrics and supply additional tags

How to use Bean Regexes to filter your JMX metrics and supply additional tags

Datadog supports regexes to match JMX Mbean names and domain names to configure your include and exclude filters. The regexes must conform to Java’s regular expression format. Note that these filters were added in version 5.5.0.

Capture groups from the provided regex can be used to supply additional tag values for your metrics.

This article provides one example of how to use the bean_regex from the Java integration, and how to reference such capture groups to set additional tags.

Suppose you have the following Mbean name: There is some information we could use as tags once the Agent has collected the metric. For instance, we could export such metric with the following tags:

  • env: dev
  • region: eu-central-1
  • method: GET
  • status: 200

Bean regexes can be supplied as a single regex or a list of regex expressions. For the latter, only the first entry of the list that matches will be taken into account. See an example of a configuration file to export your custom metrics with some additional tags:

  is_jmx: true

  - host: "<JMX_ENDPOINT>"
    port: "<JMX_PORT>"

      - include:
            - "*(?:\\.env\\.)([a-z]+)(?:.*\\.region\\.)([a-z-]+[0-9])(?:.*\\.method\\.)([A-Z]+)(?:.*\\.status\\.)([0-9]+)(?:.*)"
              metric_type: gauge
              alias: "my.jmx.metric"
              env: $1
              region: $2
              method: $3
              status_code: $4
              optional: tag

Each capture group is stored in a Java Map. The first capture group starts at position 0. Once you determined which capture group you want to export as a tag, you just have to reference them in the tags section of your include or exclude filter, plus to the number of the group (e.g. the position inside the Map).

For the provided example in bean_regex, the capture groups are:

  • $0:
  • $1: dev
  • $2: eu-central-1
  • $3: GET
  • $4: 200

Using the Metrics Explorer, you will be able to query your metrics and filter them by the tags you have just created.

Further Reading