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 servicio
  • 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 del Datadog Agent y del Cluster Agent para extraer desde GCR o ECR. Para obtener instrucciones, consulta Cambio de tu registro de contenedores.

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 consta de un servidor que se incluye en el paquete del Datadog Agent y una biblioteca cliente, disponible en varios idiomas. El servidor DogStatsD está habilitado por defecto en el puerto UDP 8125 para el Agent v6 o posterior. Puedes configurar un puerto personalizado para el servidor, si es necesario. Configura tu cliente para que coincida con la dirección y el puerto del servidor DogStatsD del Datadog Agent.

Servidor DogStatsD del Datadog Agent

Si necesitas cambiar el puerto, configura la opción dogstatsd_port en el archivo de configuración del Agent principal y reinicia el Agent. También puedes configurar DogStatsD para utilizar un socket de dominio UNIX.

Para habilitar un puerto UDP personalizado del servidor DogStatsD en el Agent:

  1. Configura el parámetro dogstatsd_port:

    ## @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 utilizar un socket de dominio 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 (tags) 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 el socket de dominio UNIX. Para comenzar a recopilar tus métricas de StatsD sobre UDP, necesitas activar la función 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 son los sockets de dominio 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.

Cliente DogStatsD

Instala la biblioteca cliente DogStatsD con tu lenguaje preferido y configúrala para que coincida con la dirección y el puerto del servidor DogStatsD del Datadog Agent.

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

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 del cliente Python de DogStatsD (incluyendo la instancia global statsd) no pueden ser compartidas entre procesos, pero son thread-safe. Debido a esto, el proceso principal y cada proceso secundario deben crear sus propias instancias de cliente o el almacenamiento en buffer debe ser explícitamente deshabilitado configurando disable_buffering como True. Para ver más detalles, consulta la documentación sobre datadog.dogstatsd.

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ámetroTipoPredeterminadoDescripción
statsd_hostCadenalocalhostHost de tu servidor DogStatsD.
statsd_portEntero8125Puerto de tu servidor DogStatsD.
statsd_socket_pathCadenanullRuta al socket de dominio UNIX de DogStatsD (anula host y port, sólo es compatible con el Agent v6 o posterior).
statsd_constant_tagsLista de cadenasnullEtiquetas para aplicar a todas las métricas, eventos y checks de servicio.
statsd_namespaceCadenanullEspacio de nombre que debe ser el prefijo de todas las métricas, eventos y 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.

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.

Referencias adicionales

PREVIEWING: gorkavicente/appsec-serverless-library-compatibility