Datadog APM es compatible con NGINX en dos configuraciones:

• NGINX funcionaba como proxy con el rastreo proporcionado por el módulo de Datadog.
• NGINX como controlador Ingress para Kubernetes.

NGINX con el módulo de Datadog

Datadog proporciona un módulo NGINX para el rastreo distribuido.

Instalación del módulo

Para instalar el módulo NGINX de Datadog, sigue las siguientes instrucciones:

1. Descarga la versión adecuada del último lanzamiento de Nginx-Datadog en GitHub
2. Elige el archivo .tar correspondiente a la versión de NGINX y a la arquitectura de CPU específicas.

Cada versión incluye dos archivos .tar por combinación de la versión de NGINX y la arquitectura de CPU. El archivo .tar principal contiene un único archivo, ngx_http_datadog_module.so, que es el módulo NGINX de Datadog. El segundo contiene símbolos de depuración y es opcional.

Para simplificar el proceso, el siguiente script descarga sólo el módulo de la última versión:

get_latest_release() {
  curl --silent "https://api.github.com/repos/$1/releases/latest" | jq --raw-output .tag_name
}

get_architecture() {
  case "$(uname -m)" in
    aarch64)
      echo "arm64"
      ;;
    arm64)
      echo "arm64"
      ;;
    x86_64)
      echo "amd64"
      ;;
    amd64)
      echo "amd64"
      ;;
    *)
      echo ""
      ;;
  esac
}

ARCH=$(get_architecture)

if [ -z "$ARCH" ]; then
    echo 1>&2 "ERROR: Architecture $(uname -m) is not supported."
    exit 1
fi

NGINX_VERSION="1.26.0"
RELEASE_TAG=$(get_latest_release DataDog/nginx-datadog)
TARBALL="ngx_http_datadog_module-${ARCH}-${NGINX_VERSION}.so.tgz"

curl -Lo ${TARBALL} "https://github.com/DataDog/nginx-datadog/releases/download/${RELEASE_TAG}/${TARBALL}"

Extrae el archivo ngx_http_datadog_module.so del archivo .tar descargado mediante tar y colócalo en el directorio de módulos de NGINX, generalmente ubicado en /usr/lib/nginx/modules.

Configuración de NGINX con el módulo de Datadog

En la sección superior de configuración de NGINX, carga el módulo de Datadog.

load_module modules/ngx_http_datadog_module.so;

La configuración por defecto se conecta a un Datadog Agent local y produce trazas para todas las localizaciones de NGINX. Especifica una configuración personalizada utilizando las directivas exclusivas datadog_* descritas en la documentación de la API del módulo de Datadog.

Por ejemplo, la siguiente configuración de NGINX define el nombre del servicio como usage-internal-nginx y la frecuencia de muestreo al 10%.

load_module modules/ngx_http_datadog_module.so;

http {
  datadog_service_name usage-internal-nginx;
  datadog_sample_rate 0.1;

  # servidores, localizaciones...
}

Controlador Ingress-NGINX para Kubernetes

Controlador v1.10.0 o posterior

1. Prepara el Datadog Agent: Asegúrate de que tu Datadog Agent tiene habilitado el consumo OTLP gRPC para actuar como recopilador de OpenTelemetry.

2. Configura el controlador Ingress: Para empezar, comprueba que la especificación del pod de tu controlador Ingress tiene definida la variable de entorno HOST_IP. Si no es así, añade la siguiente entrada al bloque env dentro de la especificación del pod:

- name: HOST_IP
  valueFrom:
    fieldRef:
      fieldPath: status.hostIP
- name: OTEL_EXPORTER_OTLP_ENDPOINT
  value: "http://$(HOST_IP):4318"

A continuación, habilita la instrumentación de OpenTelemetry para el controlador. Crea o edita un ConfigMap con los siguientes detalles:

apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  enable-opentelemetry: "true"
  otel-sampler: AlwaysOn
  # Por defecto
  # otel-service-name: "nginx"
  # otel-sampler-ratio: 0.01

Controlador v1.9.0 y anteriores

Para habilitar el rastreo en Datadog, crea o edita un ConfigMap para configurarenable-opentracing: "true" y el datadog-collector-host al que se deben enviar trazas. El nombre del ConfigMap lo cita explícitamente el argumento de línea de comandos del contenedor del controlador Ingress-NGINX; por defecto es --configmap=<POD_NAMESPACE>/nginx-configuration. Si ingress-nginx se instaló a través del chart Helm, el nombre del ConfigMap seguirá el patrón <RELEASE_NAME>-nginx-ingress-controller.

El controlador Ingress gestiona los archivos nginx.conf y /etc/nginx/opentracing.json. El rastreo está habilitado para todos los bloques de location.

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-configuration
  namespace: ingress-nginx
  labels:
    app.kubernetes.io/name: ingress-nginx
    app.kubernetes.io/part-of: ingress-nginx
data:
  enable-opentracing: "true"
  datadog-collector-host: $HOST_IP
  # Por defecto
  # datadog-service-name: "nginx"
  # datadog-collector-port: "8126"
  # datadog-operation-name-override: "nginx.handle"
  # datadog-sample-rate: "1.0"

Además, asegúrate de que la especificación del pod de tu controlador tiene definida la variable de entorno HOST_IP. Añade esta entrada al bloque env: que contiene las variables de entorno POD_NAME y POD_NAMESPACE.

- name: HOST_IP
  valueFrom:
    fieldRef:
      fieldPath: status.hostIP

Para definir un nombre de servicio diferente por Ingress utilizando anotaciones:

  nginx.ingress.kubernetes.io/configuration-snippet: |
      opentracing_tag "service.name" "custom-service-name";      

Lo anterior anula el nombre de servicio nginx-ingress-controller.ingress-nginx por defecto.

Datadog monitoriza todos los aspectos de tu entorno Istio, para que puedas:

• Visualizar cada una de las trazas distribuidas para las aplicaciones que realizan transacciones a través de la malla con APM (consulta más abajo).
• Evaluar el estado de Envoy y el plano de control de Istio mediante logs.
• Desglosar el rendimiento de tu malla de servicio mediante métricas de solicitudes, ancho de banda y consumo de recursos.
• Asignar comunicaciones de red entre contenedores, pods y servicios sobre la malla con Network Performance Monitoring.

Para obtener más información sobre la monitorización de tu entorno Istio con Datadog, consulta el blog de Istio.

Datadog APM está disponible para versiones de Istio compatibles.

Instalación del Datadog Agent

1. Instala el Agent.
2. Asegúrate de que APM está habilitado para tu Agent.
3. Descomenta el parámetro hostPort para que los sidecars de Istio puedan conectarse al Agent y enviar trazas.

Configuración e instalación de Istio

La habilitación de Datadog APM requiere una instalación personalizada de Istio para configurar dos opciones adicionales al instalar Istio.

• --set values.global.proxy.tracer=datadog
• --set values.pilot.traceSampling=100.0

istioctl manifest apply --set values.global.proxy.tracer=datadog --set values.pilot.traceSampling=100.0

Las trazas se generan cuando el espacio de nombres para el pod tiene activada la inyección de sidecars. Esto se hace añadiendo la etiqueta la etiqueta istio-injection=enabled.

kubectl label namespace example-ns istio-injection=enabled

Las trazas se generan cuando Istio es capaz de determinar que el tráfico está utilizando un protocolo basado en HTTP. Por defecto, Istio intenta detectar esto automáticamente. Puede ser configurado manualmente, nombrando los puertos en el despliegue de tu aplicación y en tu servicio. Puedes encontrar más información en la documentación de Istio para la selección de protocolos.

Por defecto, el nombre del servicio utilizado al crear trazas se genera a partir del nombre del despliegue y el espacio de nombres. Se puede configurar manualmente añadiendo una etiqueta (label) app a la plantilla del pod de despliegue:

template:
  metadata:
    labels:
      app: <SERVICE_NAME>

Para CronJobs, la etiqueta app debe añadirse a la plantilla de trabajo, ya que el nombre generado procede del Job, y no del CronJob de nivel superior.

Muestreo en Istio

Para controlar el volumen de trazas de Istio que se envían a Datadog, configura una regla de muestreo cuya "sample_rate" es un valor comprendido entre 0.0 (0%) y 1.0 (100%). Configura reglas de muestreo con la variable de entorno DD_TRACE_SAMPLING_RULES. Si no se especifica DD_TRACE_SAMPLING_RULES, el 100% de trazas de Istio se envían a Datadog.

Nota: Estas variables de entorno sólo se aplican al subconjunto de trazas indicadas por el parámetro values.pilot.traceSampling, de ahí que se requiera red --set values.pilot.traceSampling=100.0 durante la configuración de Istio.

Para utilizar las frecuencias de muestreo calculadas del Datadog Agent (10 trazas por segundo por Agent) e ignorar la regla de muestreo predeterminada, definida en 100%, configura el parámetro DD_TRACE_SAMPLING_RULES en una matriz vacía:

DD_TRACE_SAMPLING_RULES='[]'

Especificar una matriz vacía de reglas explícitamente no es lo mismo que no especificar reglas.

Para configurar DD_TRACE_SAMPLING_RULES en cada despliegue cuyo espacio de nombres está etiquetado como istio-injection=enabled, define la variable entorno como parte de la anotación apm.datadoghq.com/env de la plantilla de especificaciones del despliegue:

apiVersion: apps/v1
...
kind: Deployment
...
spec:
  template:
    metadata:
      annotations:
        apm.datadoghq.com/env: '{"DD_ENV": "prod", "DD_SERVICE": "my-service", "DD_VERSION": "v1.1", "DD_TRACE_SAMPLING_RULES": "[]"}'

apm.datadoghq.com/env es una cadena cuyo contenido es un objeto JSON que asigna nombres de variables de entorno a valores. Los valores de las variables de entorno son cadenas y, en el caso de DD_TRACE_SAMPLING_RULES, el valor de la cadena es una matriz de objetos JSON.

Variables de entorno

Las variables de entorno de los sidecars de Istio pueden definirse por cada despliegue, utilizando la anotación apm.datadoghq.com/env. Esto es único para los despliegues que emplean sidecars Istio y se define junto con las etiquetas para el etiquetado unificado de servicios.

apiVersion: apps/v1
...
kind: Deployment
...
spec:
  template:
    metadata:
      annotations:
        apm.datadoghq.com/env: '{ "DD_ENV": "prod", "DD_SERVICE": "my-service", "DD_VERSION": "v1.1"}'

Despliegue y servicio

Si los Agents en tu clúster se están ejecutando como despliegue y servicio, en lugar del DaemonSet por defecto, se requiere una opción adicional para especificar la dirección DNS y el puerto del Agent. Para un servicio llamado datadog-agent en el espacio de nombres default, esa dirección sería datadog-agent.default.svc.cluster.local:8126.

• --set values.global.tracer.datadog.address=datadog-agent.default:8126

Si Mutual TLS está habilitado para el clúster, el despliegue del Agent debe deshabilitar la inyección de sidecars, y debes agregar una política de tráfico que deshabilite TLS.

Esta anotación se añade a la plantilla de despliegue del Agent.

  template:
    metadata:
      annotations:
        sidecar.istio.io/inject: "false"

Para Istio v1.4.x, la política de tráfico puede configurarse utilizando una DestinationRule. Istio v1.5.x y posteriores no necesitan una política de tráfico adicional.

apiVersion: networking.istio.io/v1alpha3
kind: DestinationRule
metadata:
  name: datadog-agent
  namespace: istio-system
spec:
  host: datadog-agent.default.svc.cluster.local
  trafficPolicy:
    tls:
      mode: DISABLE

La selección automática de protocolos puede determinar que el tráfico entre el sidecar y el Agent es HTTP, y habilitar el rastreo. Esto se puede deshabilitar a través de la selección manual de protocolos para este servicio específico. El nombre de puerto del servicio datadog-agent puede cambiarse a tcp-traceport. Si utilizas Kubernetes v1.18 o posterior, puedes añadir appProtocol: tcp a la especificación del puerto.

Datadog APM está disponible para Kong Gateway utilizando el complemento kong-plugin-ddtrace.

Instalación

El complemento se instala mediante luarocks.

luarocks install kong-plugin-ddtrace

Kong Gateway no es un complemento incluido, por lo que debe configurarse antes de habilitarlo. Para hacerlo, incluye bundled y ddtrace en la variable de entorno KONG_PLUGINS, o define plugins=bundled,ddtrace en /etc/kong/kong.conf. A continuación, reinicia Kong Gateway para aplicar el cambio.

# Configura la variable de entorno KONG_PLUGINS o edita /etc/kong/kong.conf para habilitar el complemento ddtrace
export KONG_PLUGINS=bundled,ddtrace
kong restart

Configuración

El complemento puede habilitarse globalmente o en determinados servicios de Kong Gateway.

# Habilitado globalmente
curl -i -X POST --url http://localhost:8001/plugins/ --data 'name=ddtrace'
# Habilitado sólo para servicios específicos
curl -i -X POST --url http://localhost:8001/services/example-service/plugins/ --data 'name=ddtrace'

Existen opciones para configurar el nombre de servicio, el entorno, y otras funciones del complemento. El ejemplo siguiente define el nombre del servicio como mycorp-internal-api en el entorno prod.

curl -i -X POST --url http://localhost:8001/plugins/ --data 'name=ddtrace' --data 'config.service_name=mycorp-internal-api' --data 'config.environment=prod'

Puedes encontrar más opciones de configuración en la documentación del complemento kong-plugin-ddtrace.

Datadog proporciona un módulo HTTPd para mejorar las capacidades del servidor HTTP Apache y del servidor HTTP IHS con el rastreo APM.

Compatibilidad

Dado que el servidor HTTP IHS es esencialmente una envoltura del servidor HTTP Apache, el módulo también puede utilizarse con IHS sin ninguna modificación.

Instalación

El módulo se proporciona como una biblioteca compartido para la carga dinámica mediante HTTPd. Cada plataforma y arquitectura compatible tiene su propio artefacto alojado en el repositorio httpd de Datadog.

Para instalar el módulo:

1. Ejecuta el siguiente script para descargar la última versión del módulo:

   curl -s https://api.github.com/repos/DataDog/httpd-datadog/releases/latest \
   | grep "mod_datadog-linux-x86_64.tar.gz" \
   | cut -d : -f 2,3 \
   | tr -d \" \
   | wget -qi -
   

   Al descomprimir el archivo .tar, el archivo resultante es mod_datadog.so, la biblioteca compartida que debe ser cargada por el servidor.

2. Coloca el archivo en el directorio donde HTTPd busca los módulos, normalmente /usr/local/apache2/modules.

3. Carga el módulo añadiendo la siguiente línea en el archivo de configuración:

   LoadModule datadog_module modules/mod_datadog.so
   

4. Para habilitar el módulo, asegúrate de reiniciar o recargar HTTPd.

Configuración

Por defecto, todas las solicitudes se rastrean y se envían al Datadog Agent.

Para cambiar el comportamiento predeterminado del módulo, utiliza las directivas Datadog* descritas en la documentación de la API del módulo de Datadog.

Por ejemplo, la siguiente configuración define el nombre del servicio en my-service y la frecuencia de muestreo en 10%:

LoadModule datadog_module modules/mod_datadog.so

DatadogServiceName my-app
DatadogSamplingRate 0.1