From 20ef62db28a0f8075059452a8856ed2be047ce1e Mon Sep 17 00:00:00 2001 From: LMnet Date: Thu, 19 Mar 2026 14:33:17 +1300 Subject: [PATCH 1/2] Documentation for the use_canonical_bean_name JMX agent param --- .../guide/autodiscovery-with-jmx.md | 17 +++++----- .../guide/creating-a-jmx-integration.md | 3 +- .../faq/troubleshooting-jmx-integrations.md | 3 +- ...-jmx-metrics-and-supply-additional-tags.md | 31 +++++++++++++++++++ 4 files changed, 44 insertions(+), 10 deletions(-) diff --git a/content/en/containers/guide/autodiscovery-with-jmx.md b/content/en/containers/guide/autodiscovery-with-jmx.md index 5037df80e40..bf9d2f30f38 100644 --- a/content/en/containers/guide/autodiscovery-with-jmx.md +++ b/content/en/containers/guide/autodiscovery-with-jmx.md @@ -21,7 +21,7 @@ further_reading: --- -In containerized environments there are a few differences in how the Agent connects to the JMX server. Autodiscovery features make it possible to dynamically setup these integrations. Use Datadog's JMX based integrations to collect JMX applications metrics from your pods in Kubernetes. +In containerized environments there are a few differences in how the Agent connects to the JMX server. Autodiscovery features make it possible to dynamically setup these integrations. Use Datadog's JMX based integrations to collect JMX applications metrics from your pods in Kubernetes. If you are using the Java tracer for your applications, you can alternatively take advantage of the [Java runtime metrics][2] feature to send these metrics to the Agent. @@ -67,7 +67,7 @@ Use one of the following methods: ### Autodiscovery annotations -In this method, a JMX check configuration is applied using annotations on your Java-based Pods. This allows the Agent to automatically configure the JMX check when a new container starts. Ensure these annotations are on the created Pod, and not on the object (Deployment, DaemonSet, etc.) creating the Pod. +In this method, a JMX check configuration is applied using annotations on your Java-based Pods. This allows the Agent to automatically configure the JMX check when a new container starts. Ensure these annotations are on the created Pod, and not on the object (Deployment, DaemonSet, etc.) creating the Pod. Use the following template for Autodiscovery annotations: @@ -186,7 +186,7 @@ ad.datadoghq.com/.checks: | "FreePhysicalMemorySize": { "metric_type": "gauge", "alias": "jvm.free_physical_memory" - } + } } } }] @@ -197,7 +197,7 @@ ad.datadoghq.com/.checks: | }] } } -``` +``` See the [JMX integration][6] documentation for more information about the formatting for these metrics. @@ -207,9 +207,9 @@ If you need to pass a more complex custom configuration for your Datadog-JMX int #### 1. Compose configuration file -When using this method, the Agent needs a configuration file and an optional `metrics.yaml` file for the metrics to collect. These files can either be mounted into the Agent pod or built into the container image. +When using this method, the Agent needs a configuration file and an optional `metrics.yaml` file for the metrics to collect. These files can either be mounted into the Agent pod or built into the container image. -The configuration file naming convention is to first identify your desired integration name from the [prerequisite steps of available integrations](#available-jmx-integrations). Once this is determined, the Agent needs a configuration file named relative to that integration—_or_ within that integration's config directory. +The configuration file naming convention is to first identify your desired integration name from the [prerequisite steps of available integrations](#available-jmx-integrations). Once this is determined, the Agent needs a configuration file named relative to that integration—_or_ within that integration's config directory. For example, for the [Tomcat][81] integration, create _either_: - `/etc/datadog-agent/conf.d/tomcat.yaml`, or @@ -225,6 +225,7 @@ ad_identifiers: init_config: is_jmx: true + use_canonical_bean_name: true conf: @@ -329,8 +330,8 @@ spec: -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.port= -Dcom.sun.management.jmxremote.rmi.port= - -Djava.rmi.server.hostname=$(POD_IP) -``` + -Djava.rmi.server.hostname=$(POD_IP) +``` ## Available JMX integrations The Datadog Agent comes with several JMX integrations pre-configured. diff --git a/content/en/extend/guide/creating-a-jmx-integration.md b/content/en/extend/guide/creating-a-jmx-integration.md index 24086fa2cc3..979adde8acd 100644 --- a/content/en/extend/guide/creating-a-jmx-integration.md +++ b/content/en/extend/guide/creating-a-jmx-integration.md @@ -20,6 +20,7 @@ The JMX integration contains specific init and instance configs: init_config: is_jmx: true # Identifies the integration type as JMX. collect_default_metrics: true # Collect metrics declared in `metrics.yaml`. + use_canonical_bean_name: true # Optional. When true, match bean_regex against canonical (alphabetically ordered) MBean names. Recommended true for new setups; default false for backward compatibility. Can be overridden per instance. instances: - host: # JMX hostname @@ -42,7 +43,7 @@ Edit the `metrics.yaml` to define the filters for collecting metrics. See the [JMX integration][5] for details on the metrics filters format. -[JMXFetch test cases][6] provide examples of how metrics filters work. +[JMXFetch test cases][6] provide examples of how metrics filters work. Example of `metrics.yaml`: diff --git a/content/en/integrations/faq/troubleshooting-jmx-integrations.md b/content/en/integrations/faq/troubleshooting-jmx-integrations.md index 947be8594da..b450cc9a854 100644 --- a/content/en/integrations/faq/troubleshooting-jmx-integrations.md +++ b/content/en/integrations/faq/troubleshooting-jmx-integrations.md @@ -49,7 +49,7 @@ If you're able to connect using the command above, run: `beans` and send to the {{% /tab %}} {{< /tabs >}} -**Note**: If you're able to see some metrics (`jvm.heap_memory`, `jvm.non_heap_memory`, etc.) it is a sign that JMXFetch is properly running. If you're targeting another application and not seeing related metrics, the likely issue is a misconfiguration in your YAML. +**Note**: If you're able to see some metrics (`jvm.heap_memory`, `jvm.non_heap_memory`, etc.) it is a sign that JMXFetch is properly running. If you're targeting another application and not seeing related metrics, the likely issue is a misconfiguration in your YAML. If your `bean_regex` does not match beans that appear in JConsole or `list everything`, see [Use Bean regexes to filter your JMX metrics and supply additional tags][8]—MBean property order is not guaranteed; using `use_canonical_bean_name: true` can help. ## Agent troubleshooting @@ -280,3 +280,4 @@ instances: [5]: https://tomcat.apache.org/tomcat-7.0-doc/config/listeners.html#JMX_Remote_Lifecycle_Listener_-_org.apache.catalina.mbeans.JmxRemoteLifecycleListener [6]: https://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html#SSL_and_Tomcat [7]: http://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html +[8]: /integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags/ diff --git a/content/en/integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags.md b/content/en/integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags.md index e8698f7b686..0e12b542c88 100644 --- a/content/en/integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags.md +++ b/content/en/integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags.md @@ -64,6 +64,37 @@ For the provided example in `bean_regex`, the capture groups are: Using the [Metrics Explorer][3], you are able to query your metrics and filter them by the tags you have just created. +## Bean name property ordering + +JMX MBean names have the form `domain:key1=value1,key2=value2,...`. The JMX specification does not guarantee the order of key properties in the bean name string. By default, `bean_regex` matches against the string returned by `ObjectName.toString()`, which preserves registration order. The same MBean may therefore appear as `my.app:type=MyType,name=MyName,scope=MyScope` or `my.app:name=MyName,scope=MyScope,type=MyType` depending on the application. + +To make `bean_regex` matching deterministic, set `use_canonical_bean_name` to `true` in `init_config` (applies to all instances) or on an individual instance (overrides `init_config`). The Agent then matches against the canonical form of the MBean name (`ObjectName.getCanonicalName()`), where key properties are sorted alphabetically. For new setups, setting `use_canonical_bean_name: true` is recommended. The default is `false` for backward compatibility. + +Example with canonical bean names (write your `bean_regex` so that key properties are in alphabetical order): + +```yaml +init_config: + is_jmx: true + use_canonical_bean_name: true + +instances: + - host: "" + port: "" + + conf: + - include: + domain: my.app + bean_regex: + - "my.app:name=(.*),scope=(.*),type=MyType" + attribute: + SomeAttribute: + metric_type: gauge + alias: "my.app.some_metric" + tags: + name: $1 + scope: $2 +``` + ## Further Reading {{< partial name="whats-next/whats-next.html" >}} From 87d5a89a4528da0f0f817ec83fd49905be0a0a0a Mon Sep 17 00:00:00 2001 From: LMnet Date: Thu, 26 Mar 2026 14:36:15 +1300 Subject: [PATCH 2/2] Support filter-level use_canonical_bean_name flag --- .../guide/creating-a-jmx-integration.md | 2 +- .../faq/troubleshooting-jmx-integrations.md | 2 +- ...-jmx-metrics-and-supply-additional-tags.md | 43 ++++++++++++++++++- 3 files changed, 43 insertions(+), 4 deletions(-) diff --git a/content/en/extend/guide/creating-a-jmx-integration.md b/content/en/extend/guide/creating-a-jmx-integration.md index 979adde8acd..9c75ecf1418 100644 --- a/content/en/extend/guide/creating-a-jmx-integration.md +++ b/content/en/extend/guide/creating-a-jmx-integration.md @@ -20,7 +20,7 @@ The JMX integration contains specific init and instance configs: init_config: is_jmx: true # Identifies the integration type as JMX. collect_default_metrics: true # Collect metrics declared in `metrics.yaml`. - use_canonical_bean_name: true # Optional. When true, match bean_regex against canonical (alphabetically ordered) MBean names. Recommended true for new setups; default false for backward compatibility. Can be overridden per instance. + use_canonical_bean_name: true # Optional. When true, match bean_regex against canonical (alphabetically ordered) MBean names. Recommended true for new setups; default false for backward compatibility. Can be overridden per instance or per include/exclude filter. instances: - host: # JMX hostname diff --git a/content/en/integrations/faq/troubleshooting-jmx-integrations.md b/content/en/integrations/faq/troubleshooting-jmx-integrations.md index b450cc9a854..7054c54080f 100644 --- a/content/en/integrations/faq/troubleshooting-jmx-integrations.md +++ b/content/en/integrations/faq/troubleshooting-jmx-integrations.md @@ -49,7 +49,7 @@ If you're able to connect using the command above, run: `beans` and send to the {{% /tab %}} {{< /tabs >}} -**Note**: If you're able to see some metrics (`jvm.heap_memory`, `jvm.non_heap_memory`, etc.) it is a sign that JMXFetch is properly running. If you're targeting another application and not seeing related metrics, the likely issue is a misconfiguration in your YAML. If your `bean_regex` does not match beans that appear in JConsole or `list everything`, see [Use Bean regexes to filter your JMX metrics and supply additional tags][8]—MBean property order is not guaranteed; using `use_canonical_bean_name: true` can help. +**Note**: If you're able to see some metrics (`jvm.heap_memory`, `jvm.non_heap_memory`, etc.) it is a sign that JMXFetch is properly running. If you're targeting another application and not seeing related metrics, the likely issue is a misconfiguration in your YAML. If your `bean_regex` does not match beans that appear in JConsole or `list everything`, see [Use Bean regexes to filter your JMX metrics and supply additional tags][8]—MBean property order is not guaranteed; setting `use_canonical_bean_name: true` (in `init_config`, on an instance, or on an individual `include`/`exclude` filter) can help. ## Agent troubleshooting diff --git a/content/en/integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags.md b/content/en/integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags.md index 0e12b542c88..cf1bc97f4c4 100644 --- a/content/en/integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags.md +++ b/content/en/integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags.md @@ -68,9 +68,15 @@ Using the [Metrics Explorer][3], you are able to query your metrics and filter t JMX MBean names have the form `domain:key1=value1,key2=value2,...`. The JMX specification does not guarantee the order of key properties in the bean name string. By default, `bean_regex` matches against the string returned by `ObjectName.toString()`, which preserves registration order. The same MBean may therefore appear as `my.app:type=MyType,name=MyName,scope=MyScope` or `my.app:name=MyName,scope=MyScope,type=MyType` depending on the application. -To make `bean_regex` matching deterministic, set `use_canonical_bean_name` to `true` in `init_config` (applies to all instances) or on an individual instance (overrides `init_config`). The Agent then matches against the canonical form of the MBean name (`ObjectName.getCanonicalName()`), where key properties are sorted alphabetically. For new setups, setting `use_canonical_bean_name: true` is recommended. The default is `false` for backward compatibility. +To make `bean_regex` matching deterministic, set `use_canonical_bean_name` to `true`. The Agent then matches against the canonical form of the MBean name (`ObjectName.getCanonicalName()`), where key properties are sorted alphabetically. For new setups, setting `use_canonical_bean_name: true` is recommended. The default is `false` for backward compatibility. -Example with canonical bean names (write your `bean_regex` so that key properties are in alphabetical order): +The parameter can be set at three levels (highest precedence first): + +1. **`include`/`exclude` filter** — applies only to that filter's `bean_regex` and `bean_name` matching. Useful for gradual migration when some filters depend on the old property order. +2. **Instance** — applies to all filters in the instance. +3. **`init_config`** — applies to all instances. + +Example with canonical bean names globally (write your `bean_regex` so that key properties are in alphabetical order): ```yaml init_config: @@ -95,6 +101,39 @@ instances: scope: $2 ``` +Example with per-filter override — useful when migrating incrementally: + +```yaml +init_config: + is_jmx: true + +instances: + - host: "" + port: "" + + conf: + # This filter uses canonical order + - include: + use_canonical_bean_name: true + bean_regex: + - "my.app:name=(.*),scope=(.*),type=MyType" + attribute: + SomeAttribute: + metric_type: gauge + alias: "my.app.some_metric" + tags: + name: $1 + scope: $2 + # This filter keeps the old toString() order + - include: + bean_regex: + - "my.app:type=Legacy,name=(.*)" + attribute: + LegacyAttribute: + metric_type: gauge + alias: "my.app.legacy_metric" +``` + ## Further Reading {{< partial name="whats-next/whats-next.html" >}}