Documentation for the use_canonical_bean_name JMX agent param

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/<CONTAINER_NAME>.checks: |
                "FreePhysicalMemorySize": {
                  "metric_type": "gauge",
                  "alias": "jvm.free_physical_memory"
-               } 
+               }
             }
           }
         }]
@@ -197,7 +197,7 @@ ad.datadoghq.com/<CONTAINER_NAME>.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:
     <METRICS_TO_COLLECT>
 
@@ -329,8 +330,8 @@ spec:
           -Dcom.sun.management.jmxremote.local.only=false
           -Dcom.sun.management.jmxremote.port=<JMX_PORT>
           -Dcom.sun.management.jmxremote.rmi.port=<JMX_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.

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 or per include/exclude filter.
 
 instances:
   - host: <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`:
 

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; setting `use_canonical_bean_name: true` (in `init_config`, on an instance, or on an individual `include`/`exclude` filter) 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/

content/en/integrations/guide/use-bean-regexes-to-filter-your-jmx-metrics-and-supply-additional-tags.md

@@ -64,6 +64,76 @@ 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`. 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.
+
+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:
+  is_jmx: true
+  use_canonical_bean_name: true
+
+instances:
+  - host: "<JMX_ENDPOINT>"
+    port: "<JMX_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
+```
+
+Example with per-filter override — useful when migrating incrementally:
+
+```yaml
+init_config:
+  is_jmx: true
+
+instances:
+  - host: "<JMX_ENDPOINT>"
+    port: "<JMX_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" >}}