JMX

Información general

La integración de Java te permite recopilar métricas, trazas (traces) y logs desde tu aplicación de Java.

Configuración

Recopilación de métricas

Los checks de JMX tiene un límite de 350 métricas por instancia. Consulta las opciones de configuración. Si necesitas más métricas, ponte en contacto con el soporte de Datadog.

Si tu aplicación expone métricas de JMX, un complemento ligero de Java llamado JMXFetch (sólo compatible con Java >= 1.7.) es llamado por el Datadog Agent para conectar con el servidor MBean y recopilar tus métricas de aplicación. También envía checks de servicio que informan sobre el estado de tus instancias monitorizadas. Este complemento envía métricas al Datadog Agent utilizando el servidor DogStatsD que se ejecuta dentro de Agent. Estas integraciones también utilizan las métricas de JMX:

ActiveMQ
Cassandra
Solr
Tomcat
Kafka

Nota: Al enviar un tipo de métrica RATE (TASA) a través de DogStatsD, la métrica aparece como GAUGE en la aplicación para garantizar una comparación pertinente entre diferentes Agents. Para obtener más información, consulta la documentación de envío de métricas: DogStatsD.

Instalación

Asegúrate de que puedes abrir una conexión remota de JMX. Se necesita una conexión remota para que Datadog Agent se conecte a la JVM, incluso cuando las dos están en el mismo host. Por razones de seguridad, es recomendado no utilizar 0.0.0.0 para la dirección de escucha, y utilizar com.sun.management.jmxremote.host=127.0.0.1 para una JVM y Agent colocados.

Configuración

Si ejecutas el Agent como un binario en un host, configura tu check de JMX como cualquier otra integración del Agent. Si ejecutas el Agent como DaemonSet en Kubernetes, configura tu check de JMX utilizando auto-discovery.

Configurar el Agent para conectarte a JMX. Edita jmx.d/conf.yaml en la carpeta conf.d/ en la raíz de tu directorio de configuración del Agent. Consulta las opciones de configuración más abajo o ve las plantillas init_config e instance para todas las opciones disponibles de configuración.

  init_config:
    is_jmx: true
    collect_default_metrics: true
    # custom_jar_paths:
    #  - <CUSTOM_JAR_FILE_PATH>.jar

  instances:
    - host: localhost
      port: port
      user: username
      password: password
      name: jmx_instance_name

Reiniciar el Agent

Nota: Para ejecutar más de un check de JMX, crea archivos de configuración con el formato jmx_<INDEX>.d/conf.yaml, por ejemplo: jmx_1.d/conf.yaml, jmx_2.d/conf.yaml, etc. Cada carpeta debe almacenarse en el directorio conf.d, con la opción is_jmx establecida en true en el archivo de configuración.

La imagen estándar gcr.io/datadoghq/agent:latest para ejecutar el contenedor del Datadog Agent no tiene JMX instalado. Utiliza la imagen gcr.io/datadoghq/agent:latest-jmx, esta imagen está basada en gcr.io/datadoghq/agent:latest, pero incluye una JVM, que el Agent necesita para ejecutar jmxfetch.

Para ejecutar un check de JMX en uno de tus contenedores:

Crea un archivo de configuración del check de JMX haciendo referencia al host, o utilizando un archivo de configuración del check de JMX para una de las integraciones de Datadog compatibles oficialmente:
Integra este archivo dentro de la carpeta conf.d/ de tu Datadog Agent: -v <HOST_FOLDER_PATH>:/conf.d. Consulta la documentación de Configuración de plantillas de check para obtener más información.

Nota: El uso de %%port%% ha demostrado generar problemas en la práctica. Si experimentas algún problema, la mejor solución es sustituir %%port%% por un puerto de JMX codificado.

Opciones de configuración

Opción	Obligatorio	Descripción
`custom_jar_paths`	No	Permite especificar jars personalizados que se añaden a la ruta de clase de la JVM del Agent.
`jmx_url`	No	Si el Agent necesita conectarse a una URL de JMX no predeterminada, especifícala aquí en lugar de un host y el puerto. Si utilizas esto, deberás especificar un `name` para la instancia.
`is_jmx`	No	Permite crear archivos de configuración diferentes para cada aplicación en lugar de utilizar un único archivo de JMX largo. Incluye la opción en cada archivo de configuración como se explica en la nota de la sección Configuración.
`collect_default_jvm_metrics`	No	Indica la integración que recopila las métricas de JVM por defecto (`jvm.`). Por defecto es true. Nota*: Si estás utilizando una integración que no necesita métricas de JMX específicas, establece `collect_default_jvm_metrics: false`
`collect_default_metrics`	No	Cada integración contiene un archivo `metrics.yaml` que incluye un lista de beans por defecto a recopilar. Configurando esto en `True` automáticamente recopila esas métricas sin agregarlas de forma explícita al archivo yaml. Esto se utiliza en general para la configuración con Autodiscovery a fin de reducir el tamaño del objeto de configuración. Esto no es aplicable para recopilar métricas de JMX con el Java Tracing Agent.
`java_bin_path`	No	Especifica la ruta a tu archivo ejecutable o binario de Java si el Agent no puede encontrarlo, por ejemplo: `C:/path/to/java.exe` o `/etc/alternatives/java`
`java_options`	No	Opciones de JVM de Java
`name`	No	Se utiliza junto con `jmx_url`.
`new_gc_metrics`	No	Establécelo en true para utilizar mejores nombres de métrica para las métricas de recopilación de elementos no usados. Por defecto es `false`.
`process_name_regex`	No	En lugar de especificar un host y un puerto o `jmx_url`, el Agent puede conectarse utilizando la API adjunta. Para ello es necesario tener instalado el JDK y establecer la ruta a `tools.jar`.
`refresh_beans`	No	Periodo de actualización para actualizar la lista de MBeans coincidentes. Por defecto es 600 segundos. La disminución de este valor puede resultar en un mayor uso de la CPU.
`refresh_beans_initial`	No	Periodo de actualización para actualizar la lista de MBeans coincidentes inmediatamente después de la inicialización. Por defecto es el valor de `refresh_beans`.
`rmi_connection_timeout`	No	El tiempo de espera de la conexión, en milisegundos, cuando se conecta a una JVM utilizando `host` y `port` o una `jmx_url`.
`rmi_client_timeout`	No	Especifica la duración sin respuesta de la JVM conectada, en milisegundos, tras la cual el Agent abandona una conexión existente y vuelve a intentarlo.
`service`	No	Adjunta una etiqueta `service:<SERVICE>` a cada métrica, evento y check de servicio emitidos por esta integración.
`service_check_prefix`	No	Prefijo personalizado del check de servicio, por ejemplo `my_prefix`, para obtener un check de servicio llamado `my_prefix.can_connect`. El nombre de la integración se utiliza por defecto si no se establece.
`tools_jar_path`	No	Debe establecerse cuando se configura `process_name_regex`.
`trust_store_path` y `trust_store_password`	No	Debe establecerse si SSL está activado.

El parámetro conf es un lista de diccionarios. Sólo se permiten 2 claves en este diccionario:

Clave	Obligatorio	Descripción
`include`	Sí	Un diccionario de filtros: se recopila cualquier atributo que coincida con estos filtros, a menos que también coincida con los filtros de “exclusión” (véase más abajo).
`exclude`	No	Un diccionario de filtros: los atributos que coincidan con estos filtros no se recopilarán.

Las etiquetas se añaden automáticamente a métricas basándose en el nombre real del MBean. Puedes especificar explícitamente etiquetas suplementarias. Por ejemplo, asumiendo que el siguiente MBean es expuesto por tu aplicación monitorizada:

mydomain:attr0=val0,attr1=val1

Crearía una métrica llamada mydomain (o alguna variación según el atributo dentro del bean) con etiquetas: attr0:val0, attr1:val1, domain:mydomain, simple:val0, raw_value:my_chosen_value, multiple:val0-val1.

Si especifica un alias en una clave include con formato camel case, se convierte a snake case. Por ejemplo, MyMetricName aparece en Datadog como my_metric_name.

Descripción de los filtros

Cada diccionario include o exclude admite las siguientes claves:

Clave	Descripción
`domain`	Un nombre de dominio o lista de nombres de dominio, por ejemplo: `java.lang`.
`domain_regex`	Un patrón de expresión regular o lista de patrones que coincidan con el nombre de dominio, por ejemplo: `java\.lang.*`.
`bean` o `bean_name`	Un nombre de bean o lista de nombres completos de bean, por ejemplo: `java.lang:type=Compilation`.
`bean_regex`	Un patrón de expresión regular o lista de patrones que coincidan con los nombres completos de los beans, por ejemplo: `java\.lang.[,:]type=Compilation.`. Puedes utilizar grupos de captura en tu expresión regular para suministrar como valores de etiqueta. Consulta el ejemplo de configuración anterior.
`class`	Una clase de lista de nombres de clase, por ejemplo: `org.datadog.jmxfetch.SimpleTestJavaApp`.
`class_regex`	Un patrón de expresión regular o lista de patrones que coincidan con los nombres de las clases, por ejemplo: `org\.datadog\.jmxfetch\.SimpleTestJavaApp`.
`exclude_tags`	Un lista de claves de etiqueta para eliminar las métricas finales. Esto puede utilizarse para mejorar la cardinalidad de la etiqueta de métrica, por ejemplo: `["attr1", "id", "partition-id"]`.
`attribute`	Una lista o un diccionario de nombres de atributos (consulta más abajo para más detalles).

Notas:

Las expresiones regulares definidas en domain_regex y bean_regex deben ajustarse al formato de expresión regular de Java. Estos filtros se añadieron en la versión 5.5.0.
Excepto los patrones de expresión regular, todos los valores distinguen entre mayúsculas y minúsculas.

Además de estos parámetros, los filtros admiten claves “personalizadas” que permiten filtrar por parámetros de bean. Por ejemplo, si deseas recopilar métricas en relación con la caché de Cassandra, podrías utilizar el filtro type: - Caches:

conf:
    - include:
          domain: org.apache.cassandra.db
          type:
              - Caches

Filtro de atributos

El filtro attribute puede aceptar dos tipos de valores:

Un diccionario cuyas claves coinciden con los nombres de los atributos de destino:

conf:
    - include:
          attribute:
              maxThreads:
                  alias: tomcat.threads.max
                  metric_type: gauge
              currentThreadCount:
                  alias: tomcat.threads.count
                  metric_type: gauge
              bytesReceived:
                  alias: tomcat.bytes_rcvd
                  metric_type: counter

Puedes especificar un alias para el atributo que se convierte en el nombre de métrica en Datadog.
También puedes especificar el tipo de métrica: gauge, histogram, counter/rate o monotonic_count. Si eliges counter, se calcula una rate por segundo para la métrica y se envía como gauge.

Una lista de nombres de atributos de destino:

conf:
    - include:
          domain: org.apache.cassandra.db
          attribute:
              - BloomFilterDiskSpaceUsed
              - BloomFilterFalsePositives
              - BloomFilterFalseRatio
              - Capacity
              - CompressionRatio
              - CompletedTasks
              - ExceptionCount
              - Hits
              - RecentHitRate

El tipo de métrica es por defecto gauge.
El nombre de métrica es jmx.<DOMAIN_NAME>.<ATTRIBUTE_NAME>.

He aquí otro ejemplo de filtrado:

instances:
    - host: 127.0.0.1
      name: jmx_instance
      port: 9999

init_config:
    conf:
        - include:
              bean: org.apache.cassandra.metrics:type=ClientRequest,scope=Write,name=Latency
              attribute:
                  - OneMinuteRate
                  - 75thPercentile
                  - 95thPercentile
                  - 99thPercentile

Validación

Ejecuta el subcomando de estado del Agent y busca tu check de JMX en la sección JMXFetch.

Además, los checks de JMX tienen una configuración predeterminada que recopila métricas de tu aplicación de JMX. Consulta el Metric Explorer para: jvm.heap_memory, jvm.non_heap_memory, o jvm.gc.cms.count.

APM

Disponible para el Agent v6.0+_

Consulta la documentación específica sobre cómo configurar la recopilación de logs de Java para reenviar tus logs a Datadog.

Recopilación de trazas

Después de habilitar la recopilación de trazas con tu Agent, consulta la documentación dedicada a instrumentar tu aplicación Java para enviar tus trazas a Datadog.

Datos recopilados

Métricas

jvm.heap_memory (gauge)	The total Java heap memory used. Shown as byte
jvm.heap_memory_committed (gauge)	The total Java heap memory committed to be used. Shown as byte
jvm.heap_memory_init (gauge)	The initial Java heap memory allocated. Shown as byte
jvm.heap_memory_max (gauge)	The maximum Java heap memory available. Shown as byte
jvm.non_heap_memory (gauge)	The total Java non-heap memory used. Non-heap memory is calculated as follows: `Metaspace + CompressedClassSpace + CodeCache` Shown as byte
jvm.non_heap_memory_committed (gauge)	The total Java non-heap memory committed to be used. Shown as byte
jvm.non_heap_memory_init (gauge)	The initial Java non-heap memory allocated. Shown as byte
jvm.non_heap_memory_max (gauge)	The maximum Java non-heap memory available. Shown as byte
jvm.thread_count (count)	The number of live threads. Shown as thread
jvm.gc.cms.count (count)	The total number of garbage collections that have occurred.
jvm.gc.major_collection_count (gauge)	The rate of major garbage collections. Set `new_gc_metrics: true` to receive this metric.
jvm.gc.minor_collection_count (gauge)	The rate of minor garbage collections. Set `new_gc_metrics: true` to receive this metric.
jvm.gc.parnew.time (gauge)	The approximate accumulated garbage collection time elapsed. Shown as millisecond
jvm.gc.major_collection_time (gauge)	The fraction of time spent in major garbage collection. Set `new_gc_metrics: true` to receive this metric. Shown as permille
jvm.gc.minor_collection_time (gauge)	The fraction of time spent in minor garbage collection. Set `new_gc_metrics: true` to receive this metric. Shown as permille

Nota: Establece new_gc_metrics: true en tu jmx.d/conf.yaml para reemplazar las siguientes métricas:

jvm.gc.cms.count   => jvm.gc.minor_collection_count
                      jvm.gc.major_collection_count
jvm.gc.parnew.time => jvm.gc.minor_collection_time
                      jvm.gc.major_collection_time

Checks de servicio

jmx.can_connect
Returns CRITICAL if the Agent is unable to connect to and collect metrics from the monitored JVM instance, WARNING if no metrics are collected, and OK otherwise.
Statuses: ok, critical, warning