Etiquetado unificado de DogStatsD: env, service y version en las métricas

Etiquetado unificado de DogStatsD: envía métricas por UDP al puerto 8125 y añade env, service y version con DD_ENV, DD_SERVICE y DD_VERSION.
DogStatsD tags unifiés : env, service, version dans les métriques

El etiquetado unificado de DogStatsD vincula tus métricas personalizadas con las trazas y los logs de un mismo servicio mediante tres etiquetas: env, service y version. Sin ellas, una métrica enviada por UDP al puerto 8125 queda huérfana: no se puede filtrar por despliegue ni comparar con la versión anterior.

Este tutorial sigue la documentación de Datadog: enviar una métrica a DogStatsD, poner las etiquetas en Kubernetes y comprobar después que llegan correctamente. Para un equipo SRE, lo que está en juego es concreto: durante un incidente, filtrar por version:1.4.2 te dice enseguida si la regresión sigue al último despliegue.

Nuestro blog también trata la cardinalidad de las métricas personalizadas y el modelo de facturación de APM. Aquí nos quedamos en el etiquetado.

En resumen

  • DogStatsD escucha en UDP en el puerto 8125 (Agent v6 y posteriores). La aplicación no espera ninguna respuesta.
  • Datadog recomienda las etiquetas reservadas env, service y version para vincular métricas, trazas y logs.
  • Si el servicio ve DD_ENV, DD_SERVICE y DD_VERSION, el cliente DogStatsD añade esas etiquetas a las métricas personalizadas. Según la documentación, los clientes .NET y PHP no lo hacen.
  • En Kubernetes, el Admission Controller del Cluster Agent puede inyectar esas variables a partir de las etiquetas (labels) de los pods.

Etiquetado unificado de DogStatsD: el problema que hay que resolver

Una métrica checkout.latency emitida por veinte pods solo tiene valor si sabes de qué entorno y de qué versión procede. Podrías escribir esas etiquetas a mano en cada llamada. Es frágil: una errata crea una etiqueta nueva y, por tanto, una serie nueva.

El etiquetado unificado saca la decisión del código. El despliegue lleva los valores, la aplicación los lee de su entorno y el cliente los añade. El objetivo de este artículo: conseguir ese comportamiento en un servicio de Kubernetes y comprobarlo de extremo a extremo.

Requisitos previos, según la documentación de Datadog: Agent 6.19.x o 7.19.x como mínimo, un SDK o cliente compatible y, para la inyección automática, un Cluster Agent v7.40 o más reciente. Este artículo trata de Datadog; no dice nada sobre Dynatrace Managed ni SaaS.

Paso 1: enviar una métrica a DogStatsD en el puerto 8125

Antes de hablar de etiquetas, valida la ruta de red. El formato de un datagrama es: nombre, valor, tipo, tasa de muestreo opcional y, después, las etiquetas precedidas de #. El nombre admite letras ASCII, cifras, guiones bajos y puntos. Los tipos son c (contador), g (gauge), ms (timer), h (histograma), s (set) y d (distribución).

Formato de un datagrama DogStatsD y tres comandos de shell que envían una métrica por UDP al puerto 8125 de localhost
echo -n "custom_metric:60|g|#shell" >/dev/udp/localhost/8125
echo -n "custom_metric:60|g|#shell" | nc -4u -w0 127.0.0.1 8125

La opción -n de echo suprime el salto de línea final. Las opciones -4u de nc imponen UDP sobre IPv4. Estos comandos proceden de la página de la documentación sobre el formato de los datagramas.

Dónde escucha el Agent

En un host, el puerto se ajusta con dogstatsd_port en datadog.yaml, con 8125 como valor por defecto. En un contenedor, publica 8125/udp y define DD_DOGSTATSD_NON_LOCAL_TRAFFIC="true" si llegan métricas de un origen distinto de localhost. Con Helm, el bloque dogstatsd acepta port, useHostPort y nonLocalTraffic.

En Kubernetes, la documentación propone pasar la IP del nodo al pod con DD_AGENT_HOST, leída desde status.hostIP. El pod envía entonces al puerto 8125 de esa dirección.

Paso 2: inicializar el cliente DogStatsD

En la aplicación, un cliente DogStatsD encapsula el envío UDP. Ejemplo en Python extraído de la documentación (pip install datadog):

Inicialización del cliente DogStatsD de Python con statsd_host 127.0.0.1 y statsd_port 8125
from datadog import initialize, statsd

options = {
    'statsd_host':'127.0.0.1',
    'statsd_port':8125
}

initialize(**options)

El cliente de Python también ofrece statsd_constant_tags (etiquetas aplicadas a todas las métricas, eventos y checks de servicio) y statsd_namespace (prefijo del nombre). La documentación precisa que los clientes de Python son seguros entre hilos, pero no se comparten entre procesos: cada proceso hijo crea su propio cliente o activa disable_buffering.

Las constantes statsd_constant_tags siguen siendo útiles para una etiqueta que no depende del despliegue. Para env, service y version, prefiere el mecanismo unificado que se describe a continuación.

Paso 3: poner env, service y version en Kubernetes

La documentación sobre el etiquetado unificado describe la configuración completa: tres etiquetas (labels) tags.datadoghq.com/env, /service y /version, colocadas a la vez en el recurso padre (Deployment) y en la plantilla del pod. Para APM se añaden las variables DD_ENV, DD_SERVICE y DD_VERSION, leídas mediante la API descendente (fieldRef) desde esas etiquetas.

Extracto YAML de un Deployment con las etiquetas tags.datadoghq.com env, service y version, y la variable DD_SERVICE leída mediante fieldRef
metadata:
  labels:
    tags.datadoghq.com/env: "prod"
    tags.datadoghq.com/service: "checkout"
    tags.datadoghq.com/version: "1.4.2"
env:
  - name: DD_SERVICE
    valueFrom:
      fieldRef:
        fieldPath: metadata.labels['tags.datadoghq.com/service']

Para las métricas y los logs, la documentación indica que bastan las etiquetas a nivel de pod: las variables DD_* solo son necesarias para APM. Pero para que el cliente DogStatsD del proceso de la aplicación añada él mismo las etiquetas, el servicio debe ver las tres variables. Es lo que dice la página: si DD_ENV, DD_SERVICE y DD_VERSION son visibles, las etiquetas correspondientes se añaden a las métricas personalizadas.

Varios contenedores y Docker

Para un pod con varios contenedores, usa tags.datadoghq.com/<NOM_CONTENEUR>.env (y .service, .version). En Docker, las etiquetas equivalentes son com.datadoghq.tags.env, .service y .version.

Paso 4: dejar que el Admission Controller inyecte las variables

Escribir las variables en cada manifiesto es repetitivo. El Admission Controller del Cluster Agent lo hace por ti. Según la documentación de Datadog, inyecta DD_AGENT_HOST, DD_TRACE_AGENT_URL, DD_ENTITY_ID y DD_EXTERNAL_ENV, así como env, service y version tomados de las etiquetas. Las etiquetas del pod prevalecen sobre las del recurso propietario, y una variable DD_ENV, DD_SERVICE o DD_VERSION ya presente nunca se sobrescribe.

Las opciones de activación:

  • Datadog Operator: features.admissionController.enabled y features.admissionController.mutateUnlabelled;
  • Helm: clusterAgent.admissionController.enabled y clusterAgent.admissionController.mutateUnlabelled (activado por defecto desde la versión 2.35.0 del chart, según la página);
  • DaemonSet: variables DD_ADMISSION_CONTROLLER_ENABLED y DD_ADMISSION_CONTROLLER_MUTATE_UNLABELLED en el Cluster Agent.

Los límites que conviene conocer

  • Es un MutatingAdmissionWebhook: solo modifica los pods en su creación. Un pod que ya está en marcha no recibe nada; hay que recrearlo.
  • Solo cubre las variables de APM y DogStatsD y las etiquetas estándar.
  • Con mutateUnlabelled: false (valor por defecto), un pod sin etiqueta no se inyecta. Un pod con admission.datadoghq.com/enabled: "false" nunca se inyecta, aunque mutateUnlabelled valga true.

El modo de comunicación (hostip por defecto, service, socket, csi) determina cómo se rellena DD_AGENT_HOST o el socket. El modo service requiere Kubernetes 1.22 o superior.

Cómo comprobar que funciona

  1. En el pod: kubectl exec <pod> -- env | grep DD_ debe listar DD_ENV, DD_SERVICE y DD_VERSION con tus valores.
  2. En Datadog, abre el Metrics Explorer y filtra tu métrica personalizada: las etiquetas env, service y version deben aparecer como facetas.
  3. Despliega una versión nueva: el valor de version debe cambiar. La documentación insiste en este punto: version debe evolucionar con cada despliegue.

No he ejecutado estos comandos en un clúster para este artículo; se deducen de la documentación citada. Revísalos en tu contexto.

Buenas prácticas

  • No definas env con dos valores distintos: las etiquetas de StatsD se suman y una métrica puede llevar ambos. Ocurre también con un env global (Helm datadog.tags) combinado con una etiqueta de pod diferente.
  • Evita añadir version a las métricas de sistema de un host sin contenedores: no cambia en cada invocación.
  • Mantén valores de etiquetas de baja cardinalidad; version es aceptable, un identificador de petición no.
  • El tráfico UDP no tiene acuse de recibo: una métrica perdida no genera ningún error en la aplicación. Vigila el Agent, no solo el código.

¿Y OpenTelemetry?

Según la misma página, las variables DD_* no se admiten de entrada con OpenTelemetry. Se usa OTEL_RESOURCE_ATTRIBUTES con service.name, service.version y deployment.environment.name, y OTEL_SERVICE_NAME prevalece sobre service.name. Si dudas entre los dos mundos, lee nuestra comparativa OpenTelemetry y Prometheus y nuestra comparativa Dynatrace y Datadog. Dynatrace tiene su propia lógica de etiquetado; aquí no describo ninguna equivalencia que no esté documentada.

Para desplegar un collector en el mismo clúster, consulta el Collector de OpenTelemetry en Kubernetes.

Preguntas frecuentes

¿Qué puerto usa DogStatsD?

UDP 8125 por defecto en el Agent v6 y posteriores. Se cambia con dogstatsd_port en datadog.yaml o con DD_DOGSTATSD_PORT en un contenedor.

¿Por qué mis métricas de DogStatsD no tienen la etiqueta version?

Comprueba primero que el proceso ve DD_VERSION y que tu cliente la gestiona: según la documentación, los clientes .NET y PHP no recogen estas variables. Comprueba después que el pod se creó después de activar el Admission Controller.

¿Hacen falta las variables DD_* para las métricas?

Para las métricas y los logs que ve el Agent, bastan las etiquetas del pod. Para que el cliente DogStatsD añada las etiquetas dentro del proceso, las variables deben estar presentes.

Conclusión

Tres etiquetas, tres variables y un Admission Controller bien configurado bastan para que cada métrica personalizada lleve su entorno, su servicio y su versión. Es una inversión pequeña que acelera el diagnóstico. Para profundizar en el método, lee observabilidad y monitorización.

Fuentes

span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a Datadog Inc. Dynatrace es una marca de Dynatrace LLC. Los nombres de productos pertenecen a sus respectivos propietarios. Los extractos de código reproducen ejemplos de la documentación oficial; los valores son ejemplos. Comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Snapshot Elasticsearch : sauvegarde et snapshot consultable ne sont pas la même chose

Snapshot Elasticsearch: una copia de seguridad y un snapshot buscable no son lo mismo

Next Post
Jan alternative ChatGPT open source : IA locale hors ligne

Jan alternativa a ChatGPT de código abierto: IA local sin conexión

Related Posts