DogStatsD

La forma más sencilla de introducir tus métricas de aplicación personalizadas en Datadog es enviarlas a DogStatsD, un servicio de agregación de métricas incluido con el Datadog Agent. DogStatsD implementa el protocolo StatsD y añade algunas extensiones específicas de Datadog:

  • Tipo de métrica de histograma
  • Checks de servicios
  • Eventos
  • Etiquetado

Cualquier cliente de StatsD compatible funciona con DogStatsD y el Agent, pero no incluye las extensiones específicas de Datadog.

Nota: DogStatsD NO implementa los temporizadores de StatsD como un tipo nativo de métrica (aunque los admite a través de histogramas).

DogStatsD está disponible en Docker Hub y GCR:

Docker Hub está sujeto a límites en la tasa de extracción de imágenes. Si no eres cliente de Docker Hub, Datadog recomienda que actualices tu configuración de Datadog Agent y Cluster Agent para extraer desde GCR o ECR. Para obtener instrucciones, consulta Cambiar tu registro de contenedor.

Cómo funciona

DogStatsD acepta métricas personalizadas, eventos y checks de servicio mediante UDP y periódicamente los agrega y reenvía a Datadog.

Como utiliza UDP, tu aplicación puede enviar métricas a DogStatsD y reanudar su trabajo sin esperar respuesta. Si DogStatsD deja de estar disponible, tu aplicación no sufrirá ninguna interrupción.

dogstatsd

A medida que recibe datos, DogStatsD agrega múltiples puntos de datos para cada métrica única en un único punto de datos durante un periodo denominado el intervalo de descarga. DogStatsD utiliza un intervalo de descarga de 10 segundos.

Configuración

DogStatsD está habilitado por defecto en el puerto UDP 8125 para el Agent v6+. Si no necesitas cambiar este puerto, consulta directamente cómo configurar DogStatsD en tu código.

Agent

Por defecto, DogStatsD escucha en el puerto UDP 8125. Si necesitas cambiar esto, configura la opción dogstatsd_port en el archivo principal de configuración del Agent, y reinicia el Agent. También puedes configurar DogStatsD para utilizar un socket de dominio de Unix. Para habilitar un puerto UDP de servidor DogStatsD personalizado para el Agent:

  1. Edita tu archivo datadog.yaml para eliminar los comentarios de los parámetros use_dogstatsd y dogstatsd_port:

    ## @param use_dogstatsd - boolean - optional - default: true
    ## Set this option to false to disable the Agent DogStatsD server.
    #
    use_dogstatsd: true
    
    ## @param dogstatsd_port - integer - optional - default: 8125
    ## Override the Agent DogStatsD port.
    ## Note: Make sure your client is sending to the same UDP port.
    #
    dogstatsd_port: 8125
    
  2. Reinicia tu Agent.

Por defecto, DogStatsD escucha en el puerto UDP 8125, por lo que debes vincular este puerto a tu puerto host cuando ejecutes el Agent en un contenedor. Si tus métricas de StatsD provienen de fuera de localhost, debes establecer DD_DOGSTATSD_NON_LOCAL_TRAFFIC en true para permitir la recopilación de métrica. Para ejecutar el Agent con el servidor de DogStatsD activo, ejecuta el siguiente comando:

docker run -d --cgroupns host \
              --pid host \
              -v /var/run/docker.sock:/var/run/docker.sock:ro \
              -v /proc/:/host/proc/:ro \
              -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
              -e DD_API_KEY=<DATADOG_API_KEY> \
              -e DD_DOGSTATSD_NON_LOCAL_TRAFFIC="true" \
              -p 8125:8125/udp \
              gcr.io/datadoghq/agent:latest

Si necesitas cambiar el puerto utilizado para recopilar métricas de StatsD, utiliza la variable de entorno DD_DOGSTATSD_PORT="<NEW_DOGSTATSD_PORT>. También puedes configurar DogStatsD para usar un socket de dominio de Unix.

Detección de origen a través de UDP

La detección de origen es compatible con el Agent v6.10.0+, y permite a DogStatsD detectar de dónde proceden las métricas de contenedor y automáticamente etiquetar las métricas. Cuando este modo está activado, todas las métricas recibidas a través de UDP son etiquetadas por las mismas etiquetas de pod como métricas de Autodiscovery.

La detección del origen en entornos distintos a Kubernetes se basa en una extensión del protocolo DogStatsD en Datagram Format and Shell Usage. Para habilitar la función en el Agent, establece la variable de entorno DD_DOGSTATSD_ORIGIN_DETECTION_CLIENT en true.

Nota: La detección de origen no es compatible con entornos de Fargate.

La recopilación de métricas de StatsD está habilitada por defecto en socket de dominio de Unix. Para empezar a recopilar tus métricas de StatsD mediante UDP, necesitas activar la característica de DogStatsD en la configuración del Operator.

  1. Añade features.dogstatsd.hostPortConfig.enabled a tu manifiesto datadog-agent.yaml:

    features:
        dogstatsd:
            hostPortConfig:
                enabled: true
    

    Este es un ejemplo de manifiesto datadog-agent.yaml:

    apiVersion: datadoghq.com/v2alpha1
    kind: DatadogAgent
    metadata:
      name: datadog
    spec:
      global:
        credentials:
          apiSecret:
            secretName: datadog-secret
            keyName: api-key
      features:
        dogstatsd:
          hostPortConfig:
            enabled: true
    

    Esto permite al Agent recopilar métricas de StatsD mediante UDP en el puerto 8125.

  2. Aplica el cambio:

    kubectl apply -f datadog-agent.yaml
    

Atención: El parámetro features.dogstatsd.hostPortConfig.hostPort abre un puerto en tu host. Asegúrate de que tu cortafuegos solo permite el acceso desde tus aplicaciones o fuentes de confianza. Si tu plugin de red no admite hostPorts, entonces añade hostNetwork: true en las especificaciones de tu pod de Agent. Esto comparte el espacio de nombres de red de tu host con el Datadog Agent. También significa que todos los puertos abiertos en el contenedor se abren en el host. Si un puerto se utiliza tanto en el host como en tu contenedor, entran en conflicto (ya que comparten el mismo espacio de nombres de red) y el pod no arranca. Algunas instalaciones de Kubernetes no permiten esto.

Enviar métricas de StatsD al Agent

Tu aplicación necesita una forma fiable de determinar la dirección IP de su host. Esto se simplifica en Kubernetes 1.7, que amplía el conjunto de atributos que puedes pasar a tus pods como variables de entorno. En las versiones 1.7 y posteriores, puedes pasar la IP host a cualquier pod añadiendo una variable de entorno a PodSpec. Por ejemplo, el manifiesto de tu aplicación podría tener este aspecto:

env:
    - name: DD_AGENT_HOST
      valueFrom:
          fieldRef:
              fieldPath: status.hostIP

Con esto, cualquier pod que ejecute tu aplicación es capaz de enviar métricas de DogStatsD con el puerto 8125 en $DD_AGENT_HOST.

Nota: Como práctica recomendada, Datadog recomienda utilizar el etiquetado de servicio unificado al asignar atributos. Éste une la telemetría de Datadog mediante el uso de tres etiquetas estándares: env, service y version. Para saber cómo unificar tu entorno, consulta etiquetado de servicio unificado.

Detección de origen a través de UDP

La detección de origen es compatible con Agent 6.10.0+ y permite a DogStatsD detectar de dónde proceden las métricas de contenedor y etiquetar métricas automáticamente. Cuando este modo está activado, todas las métricas recibidas a través de UDP son etiquetadas por las mismas etiquetas de pod como métricas de Autodiscovery.

  1. Para activar la detección de origen, añade la configuración global.originDetectionUnified.enabled a tu manifiesto datadog-agent.yaml:

    global:
        originDetectionUnified:
            enabled: true
    

Notas:

  • Una alternativa a UDP es socket de dominio de Unix.
  • La detección de origen con UDP puede utilizar el ID del pod como ID de entidad.

Para utilizar el ID del pod como ID de entidad, añade las siguientes líneas al manifiesto de tu aplicación:

env:
    - name: DD_ENTITY_ID
      valueFrom:
          fieldRef:
              fieldPath: metadata.uid

Para establecer cardinalidad de etiquetas para las métricas recopiladas mediante la detección de origen, establece el ajuste features.dogstatsd.tagCardinality en low (por defecto), orchestrator o high.

Nota: Para UDP, las etiquetas pod_name no se añaden por defecto para evitar crear demasiadas métricas personalizadas.

Reunir métricas personalizadas con DogStatsD con helm:

  1. Actualiza tu archivo datadog-values.yaml para habilitar DogStatsD:

      dogstatsd:
        port: 8125
        useHostPort: true
        nonLocalTraffic: true
    

    Nota: La funcionalidad hostPort requiere un proveedor de red que se adhiera a la especificación CNI, como Calico, Canal o Flannel. Para obtener más información, incluida una solución para los proveedores de red que no sean CNI, consulta la documentación de Kubernetes: Los servicios de HostPort no funcionan.

    Atención: El parámetro hostPort abre un puerto en tu host. Asegúrate de que tu cortafuegos solo permite el acceso desde tus aplicaciones o fuentes de confianza. Si tu complemento de red no admite hostPorts, añade hostNetwork: true en las especificaciones de pod de tu Agent. Esto comparte el espacio de nombres de red de tu host con el Datadog Agent. Esto también significa que todos los puertos abiertos en el contenedor se abren en el host. Si un puerto se utiliza tanto en el host como en tu contenedor, entran en conflicto (ya que comparten el mismo espacio de nombres de red) y el pod no arranca. Algunas instalaciones de Kubernetes no permiten esto.

  2. Actualiza tu configuración de Agent:

    helm upgrade -f datadog-values.yaml <RELEASE_NAME> datadog/datadog
    
  3. Actualiza tus pods de aplicación: tu aplicación necesita una forma fiable de determinar la dirección IP de su host. Esto se simplifica en Kubernetes 1.7, que amplía el conjunto de atributos que puedes pasar a tus pods como variables de entorno. En las versiones 1.7 y posteriores, puedes pasar la IP host a cualquier pod añadiendo una variable de entorno a PodSpec. Por ejemplo, el manifiesto de tu aplicación podría tener este aspecto:

    env:
        - name: DD_AGENT_HOST
          valueFrom:
              fieldRef:
                  fieldPath: status.hostIP
    

    Con esto, cualquier pod que ejecute tu aplicación es capaz de enviar métricas de DogStatsD mediante el puerto 8125 en $DD_AGENT_HOST.

Código

Instalar el cliente de DogStatsD

Las bibliotecas de clientes oficiales de Datadog-DogStatsD están disponibles para los siguientes idiomas. Cualquier cliente de StatsD compatible funciona con DogStatsD y Agent, pero no incluye las características específicas de Datadog mencionadas anteriormente:

pip install datadog
gem install dogstatsd-ruby
go get github.com/DataDog/datadog-go/v5/statsd

El cliente Java Datadog StatsD se distribuye con maven central, y puede ser descargado desde Maven. Comienza añadiendo la siguiente configuración a tu pom.xml:

<dependency>
    <groupId>com.datadoghq</groupId>
    <artifactId>java-dogstatsd-client</artifactId>
    <version>4.2.1</version>
</dependency>

Añade lo siguiente a tu composer.json:

"datadog/php-datadogstatsd": "1.4.*"

Nota: La primera versión de Composer es 0.0.3.

O clona manualmente el repositorio en github.com/DataDog/php-datadogstatsd y configúralo con require './src/DogStatsd.php'.

Instala el paquete directamente mediante la CLI de Nuget u obtén PackageReference de NuGet:

dotnet add package DogStatsD-CSharp-Client

Instanciar el cliente de DogStatsD

Una vez instalado tu cliente DogStatsD, instálalo en tu código:

from datadog import initialize, statsd

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

initialize(**options)
Por defecto, las instancias de cliente de Python DogStatsD (incluyendo la instancia global statsd ) no pueden compartirse a través de procesos, pero son seguras para los subprocesos. Debido a esto, el proceso principal y cada subproceso deben crear sus propias instancias del cliente o el buffering debe ser explícitamente deshabilitado, estableciendo disable_buffering en True. Consulta la documentación sobre datadog.dogstatsd para más detalles.
# Import the library
require 'datadog/statsd'

# Create a DogStatsD client instance.
statsd = Datadog::Statsd.new('localhost', 8125)
Si utilizas DogStatsD con el Agent de contenedor o en Kubernetes, debes instanciar el host al que se reenvían las métricas de StatsD con la variable de entorno $DD_DOGSTATSD_SOCKET si utilizas un socket de dominio de Unix, o con la variable de entorno $DD_AGENT_HOST si utilizas el método de enlace de puertos host.
dogstatsd_client, err := statsd.New("127.0.0.1:8125")
if err != nil {
    log.Fatal(err)
}

Para más opciones, consulta GoDoc de Datadog.

import com.timgroup.statsd.NonBlockingStatsDClientBuilder;
import com.timgroup.statsd.StatsDClient;

public class DogStatsdClient {

    public static void main(String[] args) throws Exception {

        StatsDClient statsd = new NonBlockingStatsDClientBuilder()
            .prefix("statsd")
            .hostname("localhost")
            .port(8125)
            .build();


        // alternatively
        StatsDClient statsdAlt = new NonBlockingStatsDClient(
            new NonBlockingStatsDClientBuilder(
                .prefix("statsd")
                .hostname("localhost")
                .port(8125)
                .resolve()));

    }
}

Instanciar un nuevo objeto DogStatsD utilizando composer:

<?php

require __DIR__ . '/vendor/autoload.php';

use DataDog\DogStatsd;

$statsd = new DogStatsd(
    array('host' => '127.0.0.1',
          'port' => 8125,
     )
  );

Configurar la clase de DogStatsD:

// The code is located under the StatsdClient namespace
using StatsdClient;

// ...

var dogstatsdConfig = new StatsdConfig
{
    StatsdServerName = "127.0.0.1",
    StatsdPort = 8125,
};

using (var dogStatsdService = new DogStatsdService())
{
    if (!dogStatsdService.Configure(dogstatsdConfig))
        throw new InvalidOperationException("Cannot initialize DogstatsD. Set optionalExceptionHandler argument in the `Configure` method for more information.");
    // ...
} // Flush metrics not yet sent

Parámetros de instanciación del cliente

Nota: Como práctica recomendada, Datadog recomienda utilizar el etiquetado de servicio unificado al asignar etiquetas. Éste une la telemetría de Datadog mediante el uso de tres etiquetas estándares: env, service y version. Para saber cómo unificar tu entorno, consulta etiquetado de servicio unificado.

Además de la configuración obligatoria de DogStatsD (url y port), tu cliente de DogStatsD dispone de los siguientes parámetros opcionales:

ParámetroTipoPor defectoDescripción
statsd_hostCadenalocalhostEl host de tu servidor de DogStatsD.
statsd_portEntero8125El puerto de tu servidor de DogStatsD.
statsd_socket_pathCadenanullLa ruta al socket de dominio de DogStatsD Unix (anula host y port, solo compatibles con el Agent v6+).
statsd_constant_tagsLista de cadenasnullEtiquetas para aplicar a todas las métricas, eventos y checks de servicio.
statsd_namespaceCadenanullEspacio de nombres para preestablecer todas las métricas, eventos checks de servicio.

Para conocer la lista completa de todos los parámetros opcionales disponibles para datadog.initialize(), así como los parámetros que solo están disponibles cuando se instancian explícitamente instancias de datadog.dogstatsd.DogStatsd, consulta la biblioteca de Datadog Python.

ParámetroTipoPredeterminadaDescripción
hostCadenalocalhostEl host de tu servidor de DogStatsD.
portEntero8125El puerto de tu servidor de DogStatsD.
socket_pathCadenanullLa ruta al socket de dominio de Unix DogStatsD (anula host y port, solo compatibles con Agent v6+).
tagsLista de cadenasnullEtiquetas para aplicarse a todas las métricas, eventos y checks de servicio.
namespaceCadenanullEspacio de nombres para preestablecer a todas las métricas, eventos y checks de servicio.
single_threadBooleanofalseHace que el cliente envíe las métricas en el subproceso principal cuando está activado en lugar de en un subproceso compañero.

Para consultar la lista completa de los parámetros opcionales, consulta el repositorio de DogStatsD-Ruby en GitHub.

El cliente Go dispone de múltiples opciones para configurar el comportamiento de tu cliente.

ParámetroTipoDescripción
WithNamespace()CadenaConfigurar un espacio de nombres para preestablecer a todas las métricas, eventos y checks de servicio.
WithTags()Lista de cadenasEtiquetas globales aplicadas a cada métrica, evento y check de servicio.

Para conocer todas las opciones disponibles, consulta GoDoc de Datadog.

A partir de la versión 2.10.0, la forma recomendada de instanciar el cliente es con el NonBlockingStatsDClientBuilder. Puedes usar los siguientes métodos de compilación para definir los parámetros del cliente.

Método de compilaciónTipoPredeterminadaDescripción
prefix(String val)CadenanuloEl prefijo que se aplicará a todas las métricas, eventos y checks de servicio.
hostname(String val)CadenalocalhostEl nombre de host del servidor StatsD de destino.
port(int val)Entero8125El puerto del servidor StatsD de destino.
constantTags(String... val)Cadena varargsnuloEtiquetas globales que se aplicarán a cada métrica, evento y check de servicio.
blocking(boolean val)BooleanofalseEl tipo de cliente a instanciar: bloqueante o no bloqueante.
socketbufferSize(int val)Entero-1El tamaño del buffer del socket subyacente.
enableTelemetry(boolean val)BooleanofalseInformes de telemetría de clientes.
entityID(String val)CadenanuloID de la entidad para la detección del origen.
errorHandler(StatsDClientErrorHandler val)EnteronuloGestor de errores en caso de error interno del cliente.
maxPacketSizeBytes(int val)Entero8192/1432El tamaño máximo del paquete; 8192 para UDS, 1432 para UDP.
processorWorkers(int val)Entero1El número de subprocesos de trabajo del procesador que ensamblan buffers para su envío.
senderWorkers(int val)Entero1Número de subprocesos de remitente que envían buffers al socket.
poolSize(int val)Entero512Tamaño del grupo de buffer del paquete de red.
queueSize(int val)Entero4096Número máximo de mensajes sin procesar en la cola.
timeout(int val)Entero100El tiempo de inactividad en milisegundos para las operaciones de bloqueo. Solo se aplica a sockets de unix.

Para obtener más información, busca el paquete de Java DogStatsD para la clase NonBlockingStatsDClient y la clase NonBlockingStatsDClientBuilder. Asegúrate de ver la versión que coincida con la versión de tu cliente.

| Parámetro | Tipo | Por defecto | Descripción

hostCadenalocalhostEl host de tu servidor de DogStatsD. Si no está establecido, el Agent usa la variable de entorno DD_AGENT_HOST o DD_DOGSTATSD_URL.
portEntero8125El puerto de tu servidor de DogStatsD. Si no está establecido, el Agent usa la variable de entorno DD_DOGSTATSD_PORT o DD_DOGSTATSD_URL.
socket_pathCadenanullLa ruta al socket de dominio de DogStatsD Unix (anula host y port). Solo es compatible con Agent v6+. Si no está establecido, el Agent usa la variable de entorno DD_DOGSTATSD_URL.
global_tagsLista de cadenasnullEtiquetas para aplicar a todas las métricas, eventos y checks de servicio. La etiqueta @dd.internal.entity_id se adjunta a etiquetas globales de la variable de entorno DD_ENTITY_ID.
ParámetroTipoPredeterminadaDescripción
StatsdServerNameCadenalocalhostEl nombre de host del servidor StatsD de destino.
StatsdPortEntero8125El puerto del servidor StatsD de destino.
PrefixCadenanullPrefijo que se aplica a cada métrica, evento y check de servicio.
ConstantTagsLista de cadenasnullEtiquetas globales que se aplicarán a cada métrica, evento y check de servicio.

Sumérgete en DogStatsD

DogStatsD y StatsD son en general similares, sin embargo, DogStatsD contiene características avanzadas que son específicas de Datadog, incluidos los tipos de datos, eventos, checks de servicio y etiquetas disponibles:


Si estás interesado en aprender más sobre el formato de datagram utilizado por DogStatsD, o quieres desarrollar tu propia biblioteca de Datadog, consulta la sección datagram y shell usage, que también explica cómo enviar métricas y eventos directamente desde la línea de comandos.

Lectura adicional