Formato de datagramas y uso de shells

Documentos > Desarrolladores > DogStatsD > Formato de datagramas y uso de shells

Esta sección especifica el formato de datagramas sin procesar para métricas, eventos y checks de servicios compatibles con DogStatsD. Los datagramas sin procesar están codificados en UTF-8. Esta sección no es de lectura obligatoria, si estás utilizando cualquiera de las bibliotecas de clientes DogStatsD. Pero si quieres escribir tu propia biblioteca o utilizar el shell para enviar métricas, entonces sigue leyendo.

Protocolo de DogStatsD

<METRIC_NAME>:<VALUE>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

Parámetro	Obligatorio	Descripción
`<METRIC_NAME>`	Sí	Cadena que sólo contiene caracteres alfanuméricos ASCII, guiones bajos y puntos. Consulta la política relativa a los nombres de métricas.
`<VALUE>`	Sí	Número entero o flotante.
`<TYPE>`	Sí	`c` para COUNT (Recuento), `g` para GAUGE (Indicador), `ms` para TIMER (Temporizador), `h` para HISTOGRAM (Histograma), `s` para SET (Conjunto), `d` para DISTRIBUTION (Distribución). Para ver más detalles, consulta Tipos de métricas.
`<SAMPLE_RATE>`	No	Un valor flotante entre `0` y `1`, inclusive. Sólo funciona con las métricas COUNT, HISTOGRAM, DISTRIBUTION, y TIMER. El valor por defecto es `1`, que muestrea el 100% del tiempo.
`<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>`	No	Lista de cadenas separadas por comas. Utiliza dos puntos para etiquetas (tags) (`env:prod`) de clave/valor. Para más información sobre la definición de etiquetas, consulta Empezando con las etiquetas.

Los siguientes son algunos ejemplos de datagramas:

page.views:1|c: incrementa la métrica COUNT page.views.
fuel.level:0.5|g: registra que el depósito de combustible está medio vacío.
song.length:240|h|@0.5: muestra el histograma song.length como si se enviara la mitad del tiempo.
users.uniques:1234|s: realiza un seguimiento de los visitantes únicos del sitio.
users.online:1|c|#country:china: incrementa la métrica y la etiqueta COUNT de los usuarios activos por país de origen.
users.online:1|c|@0.5|#country:china: realiza un seguimiento de los usuarios activos de China y utiliza una frecuencia de muestreo.

Protocolo de DogStatsD v1.1

A partir del Agent >=v6.25.0 y <v7.0.0 o >=v7.25.0, es posible empaquetar valores. Esta opción es compatible con todos los tipos de métricas, excepto SET. Los valores se separan mediante un :, por ejemplo:

<METRIC_NAME>:<VALUE1>:<VALUE2>:<VALUE3>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

TYPE, SAMPLE_RATE y TAGS se comparten entre todos los valores. Esto genera las mismas métricas que el envío de múltiples mensajes con un valor en cada uno. Esto es útil para las métricas HISTOGRAM, TIMING y DISTRIBUTION.

Ejemplo de datagramas

page.views:1:2:32|d: realiza un muestreo de la métrica DISTRIBUTION page.views tres veces con los valores 1, 2 y 32.
song.length:240:234|h|@0.5: realiza un muestreo del histograma song.length como si se enviara la mitad del tiempo, dos veces. A cada valor se le aplica la frecuencia de muestreo de 0.5.

Protocolo de DogStatsD v1.2

A partir del Agent >=v6.35.0 y <v7.0.0 o >=v7.35.0, se admite un nuevo campo de ID de contenedor. El Datadog Agent utiliza el valor del ID de contenedor para enriquecer las métricas de DogStatsD con etiquetas de contenedor adicionales.

El ID de contenedor lleva el prefijo c:, por ejemplo:

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|c:<CONTAINER_ID>

Nota: Configura dogstatsd_origin_detection_client como true en tu archivo datadog.yaml o la variable de entorno DD_DOGSTATSD_ORIGIN_DETECTION_CLIENT=true para indicar al Datadog Agent que extraiga el campo del ID de contenedor y adjunte las etiquetas de contenedor correspondientes.

Ejemplo de datagramas

page.views:1|g|#env:dev|c:83c0a99c0a54c0c187f461c7980e9b57f3f6a8b0c918c8d93df19a9de6f3fe1d: el Datadog Agent añade etiquetas de contenedor como image_name y image_tag a la métrica page.views.

Para obtener más información sobre las etiquetas de contenedor, consulta la documentación sobre el etiquetado en Kubernetes y Docker.

Protocolo de DogStatsD v1.3

Los Agents v6.40.0+ y v7.40.0+ admiten un campo de marca temporal Unix opcional.

Cuando se proporciona este campo, el Datadog Agent no procesa ninguna métrica (sin agregación) y sólo se limita a enriquecer los métricas con etiquetas. Esto puede ser útil si ya estabas agregando tus métricas en tu aplicación y quieres enviarlas a Datadog sin ningún procesamiento adicional.

La marca de tiempo Unix debe ser un número positivo válido en el pasado. Sólo se admiten métricas GAUGE y COUNT.

El valor es una marca de tiempo Unix (UTC) y debe llevar el prefijo T, por ejemplo:

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|T<METRIC_TIMESTAMP>

Ejemplo de datagramas

page.views:15|c|#env:dev|T1656581400: una métrica COUNT que indica que 15 vistas de páginas ocurrieron el 30 de junio de 2022 a las 9:30 UTC

DogStatsD protocolo v1.4

A partir del Agent >=v7.51.0, se admite un nuevo valor de inode para el campo ID del contenedor. El campo ID del contenedor ahora puede contener dos valores para enriquecer métricas de DogStatsD con etiquetas de contenedor adicionales:

El ID del contenedor, si está disponible.
El inode de nodo cgroup, si el ID del contenedor no está disponible.

El campo ID del contenedor sigue llevando el prefijo c:, y el valor puede ser uno de los siguientes:

c:ci-<CONTAINER_ID>
c:in-<CGROUP_INODE>

Por compatibilidad con versiones anteriores, seguimos admitiendo el siguiente formato, aunque se considera obsoleto:

c:<CONTAINER_ID>

DogStatsD protocolo v1.5

A partir del Agent >=v7.57.0, se admite un nuevo campo de datos externos. El Datadog Agent utiliza el valor de datos externos para enriquecer métricas de DogStatsD con etiquetas de contenedor adicionales, cuando el ID del contenedor no está disponible.

El ID del contenedor lleva el prefijo e:, por ejemplo:

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|e:<EXTERNAL_DATA>

Estos datos son proporcionados por el controlador de admisión del Datadog Agent y contendrán:

Un booleano que representa si el contenedor es un contenedor init o no.
El nombre del contenedor.
El UID del pod.

El formato es el siguiente:

it-INIT_CONTAINER,cn-CONTAINER_NAME,pu-POD_UID

Se vería así:

it-false,cn-nginx-webserver,pu-75a2b6d5-3949-4afb-ad0d-92ff0674e759

DogStatsD protocolo v1.6

A partir del Agent >=v7.64.0, se admite un nuevo campo de cardinalidad. El Datadog Agent utiliza el valor de cardinalidad para enriquecer métricas de DogStatsD con etiquetas de contenedor adicionales que corresponden a su cardinalidad.

El campo de cardinalidad lleva el prefijo card:, por ejemplo:

<METRIC_NAME>:<VALUE>|<TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>|card:<CARDINALITY>

La cardinalidad afectará al enriquecimiento de etiquetas de:

Los valores disponibles para la cardinalidad son:

none
low
orchestrator
high

_e{<TITLE_UTF8_LENGTH>,<TEXT_UTF8_LENGTH>}:<TITLE>|<TEXT>|d:<TIMESTAMP>|h:<HOSTNAME>|p:<PRIORITY>|t:<ALERT_TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

Parámetro	Obligatorio	Descripción
`_e`	Sí	El datagrama debe comenzar por `_e`.
`<TITLE>`	Sí	Título del evento.
`<TEXT>`	Sí	Texto del evento. Inserta saltos de línea con: `\\n`.
`<TITLE_UTF8_LENGTH>`	Sí	Longitud (en bytes) del `<TITLE>` del archivo codificado en UTF-8
`<TEXT_UTF8_LENGTH>`	Sí	Longitud (en bytes) del `<TEXT>` del archivo codificado en UTF-8
`d:<TIMESTAMP>`	No	Añade una marca de tiempo al evento. El valor predeterminado es la marca temporal Unix actual.
`h:<HOSTNAME>`	No	Añade un nombre de host al evento. Por defecto es la instancia del Datadog Agent.
`k:<AGGREGATION_KEY>`	No	Añade una clave de agregación para agrupar el evento con otros que tengan la misma clave. No existen valores por defecto.
`p:<PRIORITY>`	No	Configura como `normal` o `low`. El valor por defecto es `normal`.
`s:<SOURCE_TYPE_NAME>`	No	Añade un tipo de origen al evento. No existen valores por defecto.
`t:<ALERT_TYPE>`	No	Configura como `error`, `warning`, `info` o `success`. El valor por defecto es `info`.
`#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>`	No	Los dos puntos en las etiquetas forman parte de la cadena de la lista de etiquetas y no tienen ningún propósito de análisis, lo que sí sucede en los otros parámetros. No existen valores por defecto.

Los siguientes son algunos ejemplos de datagramas:

## Send an exception
_e{21,36}:An exception occurred|Cannot parse CSV file from 10.0.0.17|t:warning|#err_type:bad_file

## Send an event with a newline in the text
_e{21,42}:An exception occurred|Cannot parse JSON request:\\n{"foo: "bar"}|p:low|#err_type:bad_request

Parámetro	Obligatorio	Descripción
`_sc`	Sí	El datagrama debe comenzar por `_sc`.
`<NAME>`	Sí	Nombre del check de servicio.
`<STATUS>`	Sí	Número entero correspondiente al estado del check (OK = `0`, WARNING (Advertencia) = `1`, CRITICAL (Crítico) = `2`, UNKNOWN (Desconocido) = `3`).
`d:<TIMESTAMP>`	No	Añade una marca de tiempo al check. El valor predeterminado es la marca de tiempo Unix actual.
`h:<HOSTNAME>`	No	Añade un nombre de host al evento (no existen valores por defecto).
`#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>`	No	Configura las etiquetas del evento. Una lista de cadenas separadas por comas (no existen valores por defecto).
`m:<SERVICE_CHECK_MESSAGE>`	No	Mensaje que describe el estado actual del check de servicio. Este campo debe situarse en último lugar entre los campos de metadatos (no existen valores por defecto).

El siguiente es un ejemplo de datagrama:

# Send a CRITICAL status for a remote connection
_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s

Enviar métricas utilizando DogStatsD y el shell

Para Linux y otros sistemas operativos tipo Unix, utiliza Bash. Para Windows, utiliza PowerShell y PowerShell-statsd (una sencilla función de PowerShell que se encarga de los bits de red).

DogStatsD crea un mensaje que contiene información sobre tu métrica, evento o check de servicio y los envía a un Agent instalado localmente como recopilador. La dirección IP de destino es 127.0.0.1 y el puerto del recopilador en UDP es 8125. Para ver más detalles sobre la configuración del Agent, consulta DogStatsD.

El formato para enviar métricas es:

<METRIC_NAME>:<VALUE>|<TYPE>|@<SAMPLE_RATE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>

Los siguientes ejemplos envían puntos de datos para una métrica GAUGE llamada custom_metric con la etiqueta shell.

En Linux:

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

echo -n "custom.metric.name:1|c"|nc -4u -w1 localhost 8125

En Windows:

PS C:\> .\send-statsd.ps1 "custom_metric:123|g|#shell"

En cualquier plataforma con Python (en Windows, se puede utilizar el intérprete Python integrado del Agent, que se encuentra en %ProgramFiles%\Datadog\Datadog Agent\embedded\python.exe, para el Agent versión 6.11 y anteriores, y en %ProgramFiles%\Datadog\Datadog Agent\embedded<PYTHON_MAJOR_VERSION>\python.exe, para el Agent versión 6.12 y posteriores):

Python 2

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) # UDP
sock.sendto("custom_metric:60|g|#shell", ("localhost", 8125))

Python 3

import socket
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) # UDP
sock.sendto("custom_metric:60|g|#shell", ("localhost", 8125))

El formato para enviar eventos es:

_e{<TITLE>.length,<TEXT>.length}:<TITLE>|<TEXT>|d:<DATE_EVENT>|h:<HOSTNAME>|p:<PRIORITY>|t:<ALERT_TYPE>|#<TAG_KEY_1>:<TAG_VALUE_1>,<TAG_2>.

Los siguientes son ejemplos de cálculos del tamaño del título y el cuerpo del evento.

En Linux:

$ title="Event from the shell"

$ text="This was sent from Bash!"

$ echo "_e{${#title},${#text}}:$title|$text|#shell,bash"  >/dev/udp/localhost/8125

En Windows:

PS C:> $title = "Event from the shell"
PS C:> $text = "This was sent from PowerShell!"
PS C:> .\send-statsd.ps1 "_e{$($title.length),$($text.Length)}:$title|$text|#shell,PowerShell"

El formato para enviar checks de servicios es:

_sc|<NAME>|<STATUS>|d:<TIMESTAMP>|h:<HOSTNAME>|#<TAG_KEY_1>:<TAG_VALUE_1>|m:<SERVICE_CHECK_MESSAGE>

En Linux:

echo -n "_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s" >/dev/udp/localhost/8125

En Windows:

PS C:\> .\send-statsd.ps1 "_sc|Redis connection|2|#env:dev|m:Redis connection timed out after 10s"

Para enviar métricas, eventos o checks de servicios en entornos contenedorizados, consulta DogStatsD en Kubernetes, junto con la configuración de APM en Kubernetes, dependiendo de tu instalación. La documentación de APM Docker también puede ser útil.