Datadog APM se incluye en Envoy v1.9.0 y posteriores.
Habilitación de Datadog APM
Nota: El siguiente ejemplo de configuración corresponde a Envoy v1.19.
Los siguientes parámetros son necesarios para habilitar Datadog APM en Envoy:
- un clúster para enviar trazas al Datadog Agent
- la configuración
http_connection_manager para activar el rastreo
Añade un clúster para enviar trazas al Datadog Agent:
clusters:
... existing cluster configs ...
- name: datadog_agent
connect_timeout: 1s
type: strict_dns
lb_policy: round_robin
load_assignment:
cluster_name: datadog_agent
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: localhost
port_value: 8126
Cambia el valor de address, si Envoy se está ejecutando en un contenedor o en un entorno orquestado.
Incluye la siguiente configuración adicional en las secciones http_connection_manager para habilitar el rastreo:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
generate_request_id: true
request_id_extension:
typed_config:
"@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
use_request_id_for_trace_sampling: false
tracing:
provider:
name: envoy.tracers.datadog
typed_config:
"@type": type.googleapis.com/envoy.config.trace.v3.DatadogConfig
collector_cluster: datadog_agent
service_name: envoy-v1.19
El valor collector_cluster debe coincidir con el nombre proporcionado para el clúster del Datadog Agent. Para utilizar Envoy, puedes cambiar service_name por un valor significativo.
Con esta configuración, las solicitudes HTTP a Envoy se inician y propagan trazas de Datadog y aparecen en la interfaz de usuario APM.
Ejemplo de configuración de Envoy v1.19
El siguiente ejemplo de configuración demuestra la colocación de los elementos necesarios para habilitar el rastreo utilizando Datadog APM.
static_resources:
listeners:
- address:
socket_address:
address: 0.0.0.0
port_value: 80
traffic_direction: OUTBOUND
filter_chains:
- filters:
- name: envoy.filters.network.http_connection_manager
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
generate_request_id: true
request_id_extension:
typed_config:
"@type": type.googleapis.com/envoy.extensions.request_id.uuid.v3.UuidRequestIdConfig
use_request_id_for_trace_sampling: false
tracing:
# Utiliza el rastreador Datadog
provider:
name: envoy.tracers.datadog
typed_config:
"@type": type.googleapis.com/envoy.config.trace.v3.DatadogConfig
collector_cluster: datadog_agent # coincide con el clúster nombrado
service_name: envoy-v1.19 # nombre de servicio definido por el usuario
codec_type: auto
stat_prefix: ingress_http
route_config:
name: local_route
virtual_hosts:
- name: backend
domains:
- "*"
routes:
- match:
prefix: "/"
route:
cluster: service1
# No se deben muestrear las trazas de solicitudes de estado.
http_filters:
- name: envoy.filters.http.health_check
typed_config:
"@type": type.googleapis.com/envoy.extensions.filters.http.health_check.v3.HealthCheck
pass_through_mode: false
headers:
- exact_match: /healthcheck
name: :path
- name: envoy.filters.http.router
typed_config: {}
use_remote_address: true
clusters:
- name: service1
connect_timeout: 0.250s
type: strict_dns
lb_policy: round_robin
load_assignment:
cluster_name: service1
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: service1
port_value: 80
# Configura este clúster con la dirección del Datadog Agent
# para el envío de trazas.
- name: datadog_agent
connect_timeout: 1s
type: strict_dns
lb_policy: round_robin
load_assignment:
cluster_name: datadog_agent
endpoints:
- lb_endpoints:
- endpoint:
address:
socket_address:
address: localhost
port_value: 8126
admin:
access_log_path: "/dev/null"
address:
socket_address:
address: 0.0.0.0
port_value: 8001
Exclusión de métricas
Si utilizas la configuración de Envoy dog_statsd para informar métricas, puedes excluir la actividad del clúster datadog_agent con esta configuración adicional.
stats_config:
stats_matcher:
exclusion_list:
patterns:
- prefix: "cluster.datadog_agent."
Muestreo de Envoy
Para controlar el volumen de trazas de Envoy que se envían a Datadog, especifica una frecuencia de muestreo configurando el parámetro DD_TRACE_SAMPLING_RULES con un valor comprendido entre 0.0 (0%) y 1.0 (100%). Si no se especifica ningún valor, se enviarán el 100% de las trazas provenientes de Envoy.
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=[]
También puedes definir una frecuencia de muestreo explícita entre 0.0 (0%) y 1.0 (100%), por servicio. Por ejemplo, para configurar la frecuencia de muestreo al 10% para el servicio envoy-proxy :
DD_TRACE_SAMPLING_RULES=[{"service": "envoy-proxy","sample_rate": 0.1}]
Para configurar tu frecuencia de muestreo con DD_TRACE_SAMPLING_RULES, utiliza uno de los siguientes métodos, dependiendo de cómo ejecutes Envoy:
Por script de shell: Define la variable de entorno inmediatamente antes de ejecutar envoy en el script:
#!/bin/sh
export DD_TRACE_SAMPLING_RULES=[]
envoy -c envoy-config.yaml
En una configuración Docker Compose: define la variable de entorno en la sección environment de la definición del servicio:
services:
envoy:
image: envoyproxy/envoy:v1.19-latest
entrypoint: []
command:
- envoy
- -c
- /etc/envoy/envoy.yaml
volumes:
- './envoy.yaml:/etc/envoy/envoy.yaml:ro'
environment:
- DD_TRACE_SAMPLING_RULES=[]
Como contenedor dentro de un pod Kubernetes: Especifica la variable de entorno en la sección env de la entrada containers correspondiente de la especificación del pod:
apiVersion: v1
kind: Pod
metadata:
name: envoy
spec:
containers:
- name: envoy
image: envoyproxy/envoy:v1.20-latest
env:
- name: DD_TRACE_SAMPLING_RULES
value: "[]"
Variables de entorno
Nota: Las variables DD_AGENT_HOST, DD_TRACE_AGENT_PORT y DD_TRACE_AGENT_URL no se aplican a Envoy, ya que la dirección del Datadog Agent se configura utilizando los parámetros del clúster.
Las variables de entorno disponibles dependen de la versión del rastreador C++ incorporado en Envoy.
Es posible encontrar la versión del rastreador C++ en logs, indicada por la línea que empieza por “DATADOG TRACER CONFIGURATION”.
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:
- Descarga la versión adecuada del último lanzamiento de Nginx-Datadog en GitHub
- 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
Nota importante: Con el lanzamiento de
v1.10.0, la integración OpenTracing y Datadog del controlador Ingress ha quedado obsoleta. Como alternativa, se recomienda la integración OpenTelemetry.
Para versiones anteriores, consulta las
instrucciones basadas en OpenTracing.
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
- Instala el Agent.
- Asegúrate de que APM está habilitado para tu Agent.
- 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
Nota: Sólo se admite el servidor HTTP Apache v2.4.x para la arquitectura x86_64.
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:
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.
Coloca el archivo en el directorio donde HTTPd busca los módulos, normalmente /usr/local/apache2/modules.
Carga el módulo añadiendo la siguiente línea en el archivo de configuración:
LoadModule datadog_module modules/mod_datadog.so
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
