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,serviceyversionpara vincular métricas, trazas y logs. - Si el servicio ve
DD_ENV,DD_SERVICEyDD_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).

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):

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.

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.enabledyfeatures.admissionController.mutateUnlabelled; - Helm:
clusterAgent.admissionController.enabledyclusterAgent.admissionController.mutateUnlabelled(activado por defecto desde la versión 2.35.0 del chart, según la página); - DaemonSet: variables
DD_ADMISSION_CONTROLLER_ENABLEDyDD_ADMISSION_CONTROLLER_MUTATE_UNLABELLEDen 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 conadmission.datadoghq.com/enabled: "false"nunca se inyecta, aunquemutateUnlabelledvalgatrue.
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
- En el pod:
kubectl exec <pod> -- env | grep DD_debe listarDD_ENV,DD_SERVICEyDD_VERSIONcon tus valores. - En Datadog, abre el Metrics Explorer y filtra tu métrica personalizada: las etiquetas
env,serviceyversiondeben aparecer como facetas. - Despliega una versión nueva: el valor de
versiondebe cambiar. La documentación insiste en este punto:versiondebe 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.
- No definas
envcon dos valores distintos: las etiquetas de StatsD se suman y una métrica puede llevar ambos. Ocurre también con unenvglobal (Helmdatadog.tags) combinado con una etiqueta de pod diferente. - Evita añadir
versiona las métricas de sistema de un host sin contenedores: no cambia en cada invocación. - Mantén valores de etiquetas de baja cardinalidad;
versiones 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
- DogStatsD, documentación de Datadog
- Formato de los datagramas de DogStatsD, documentación de Datadog
- Unified Service Tagging, documentación de Datadog
- Admission Controller, documentación de Datadog
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.