La forma de inyectar bibliotecas localmente, sin tocar para nada el código de la aplicación, varía en función de dónde y cómo están instalados tu Agent y tu aplicación. Selecciona el escenario que representa tu entorno:
A través de la estrategia del controlador de admisión, el Agent utiliza el controlador de admisión Kubernetes para interceptar las solicitudes a la API Kubernetes y mutar nuevos pods para inyectar las bibliotecas de instrumentación especificadas.
La inyección de bibliotecas sólo se aplica a los pods nuevos y no tiene ningún impacto en los pods en ejecución.
Controlador de admisión Datadog habilitado. Nota: En el chart de Helm v2.35.0 y posteriores, el controlador de admisión Datadog está habilitado por defecto en el Cluster Agent.
Para Python, las aplicaciones uWSGI no son compatibles en este momento.
Para Ruby, la compatibilidad de la inyección de bibliotecas está en fase Beta. La instrumentación sólo es compatible con Ruby en aplicaciones Rails con una versión de empaquetador superior a 2.3 y sin gemas vendidas (modo de despliegue o BUNDLE_PATH).
Aplicaciones en Java, JavaScript, Python, .NET, o Ruby desplegadas en Linux con una arquitectura compatible. Para ver la lista completa de arquitecturas soportadas por lenguaje, consulta el registro de contenedores correspondiente.
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.
Datadog publica imágenes de bibliotecas de instrumentación en gcr.io, Docker Hub y Amazon ECR:
La variable de entorno DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY en la configuración del Datadog Cluster Agent especifica el registro utilizado por el controlador de admisión. El valor por defecto es gcr.io/datadoghq.
Puedes extraer la biblioteca de rastreo de un registro diferente cambiándolo por docker.io/datadog, public.ecr.aws/datadog u otra URL, si alojas las imágenes en un registro de contenedores local.
Para tus aplicaciones Kubernetes cuyas trazas quieres enviar a Datadog, configura el controlador de admisión Datadog para inyectar bibliotecas de instrumentación Java, JavaScript, Python, .NET o Ruby automáticamente. Desde un nivel superior, esto involucra los siguientes pasos, descritos en detalle a continuación:
Habilita el controlador de admisión para mutar tus pods.
Anota tus pods para seleccionar qué biblioteca de instrumentación inyectar.
Etiqueta tus pods con el etiquetado unificado de servicios para unir la telemetría de Datadog y navegar sin problemas por trazas, métricas y logs con etiquetas (tags) coherentes.
Aplica tu nueva configuración.
No es necesario generar una nueva imagen de la aplicación para inyectar la biblioteca. La inyección de bibliotecas se realiza añadiendo la biblioteca de instrumentación, por lo que no es necesario realizar ningún cambio en la imagen de la aplicación.
Por defecto, el controlador de admisión Datadog muta sólo los pods etiquetados con una etiqueta (label) específica. Para habilitar la mutación en tus pods, añade la etiqueta admission.datadoghq.com/enabled: "true" a las especificaciones del pod.
Nota: Puedes configurar el controlador de admisión Datadog para habilitar la configuración de inyección sin tener esta etiqueta (label) de pod, configurando el Cluster Agent con clusterAgent.admissionController.mutateUnlabelled (o DD_ADMISSION_CONTROLLER_MUTATE_UNLABELLED) como true.
apiVersion:apps/v1kind:Deploymentmetadata:labels:# (...)spec:template:metadata:labels:admission.datadoghq.com/enabled:"true"# Habilitar el controlador de admisión para mutar nuevos pods como parte de este desplieguespec:containers:- # (...)
Para seleccionar tus pods para la inyección de bibliotecas, utiliza las anotaciones proporcionadas en la siguiente tabla dentro de las especificaciones de tu pod:
Las versiones de biblioteca disponibles se enumeran en cada registro de contenedores, así como en los repositorios de origen del rastreador para cada lenguaje:
Nota: Para la inyección de bibliotecas .NET, si el contenedor de la aplicación utiliza una distribución Linux basada en musl (como Alpine), debes especificar una etiqueta (tag) con el sufijo -musl para la anotación del pod. Por ejemplo, para utilizar una versión de biblioteca v2.29.0, especifica la etiqueta (tag) del contenedor v2.29.0-musl.
Nota: Si ya tienes una aplicación instrumentada utilizando la versión X de la biblioteca y luego utilizas la inyección de bibliotecas para la instrumentación utilizando la versión Y de la misma biblioteca del rastreador, este no se rompe. En su lugar, se utiliza la versión de biblioteca cargada en primer lugar. Dado que la inyección de bibliotecas se produce en el nivel del controlador de admisión antes del tiempo de ejecución, tiene prioridad sobre las bibliotecas configuradas de forma manual.
Nota: Se admite el uso de la última etiqueta (tag), pero utilízala con precaución, ya que las principales versiones de bibliotecas pueden introducir cambios de última hora.
Por ejemplo, para inyectar una biblioteca Java:
apiVersion:apps/v1kind:Deploymentmetadata:labels:# (...)spec:template:metadata:labels:admission.datadoghq.com/enabled:"true"# Habilitar el controlador de admisión para mutar nuevos pods en este despliegueannotations:admission.datadoghq.com/java-lib.version:"<CONTAINER IMAGE TAG>"spec:containers:- # (...)
Con etiquetas (tags) de servicios unificadas, puedes unir la telemetría de Datadog y navegar sin problemas a través de trazas, métricas, y logs con etiquetas coherentes. Define el etiquetado unificado de servicios tanto en el objeto de despliegue como en las especificaciones de la plantilla del pod.
Define etiquetas de servicios unificadas utilizando las siguientes etiquetas (labels):
Nota: No es necesario configurar las variables de entorno para el etiquetado unificado de servicios (DD_ENV, DD_SERVICE, DD_VERSION) en la especificación de la plantilla de pods, ya que el controlador de admisión propaga los valores de etiqueta como variables de entorno al inyectar la biblioteca.
Por ejemplo:
apiVersion:apps/v1kind:Deploymentmetadata:labels:tags.datadoghq.com/env:"prod"# Etiqueta (tag) de servicio unificada - Etiqueta del entorno de desplieguetags.datadoghq.com/service:"my-service"# Etiqueta de servicio unificada - Etiqueta del servicio de desplieguetags.datadoghq.com/version:"1.1"# Etiqueta de servicio unificada - Etiqueta de la versión de despliegue# (...)spec:template:metadata:labels:tags.datadoghq.com/env:"prod"# Etiqueta de servicio unificada - Etiqueta del entorno de podtags.datadoghq.com/service:"my-service"# Etiqueta de servicio unificada - Etiqueta del servicio de podtags.datadoghq.com/version:"1.1"# Etiqueta de servicio unificada - Etiqueta de la versión de podadmission.datadoghq.com/enabled:"true"# Habilitar el comtrolador de admisión para mutar nuevos pods como parte de este despliegueannotations:admission.datadoghq.com/java-lib.version:"<CONTAINER IMAGE TAG>"spec:containers:- # (...)
La inyección de bibliotecas aprovecha la inyección de un contenedor init exclusivo en los pods.
Si la inyección ha sido exitosa, podrás ver un contenedor init llamado datadog-lib-init en tu pod:
O ejecuta kubectl describe pod <my-pod> para ver el contenedor init datadog-lib-init listado.
La Instrumentación también comienza a enviar telemetría a Datadog (por ejemplo, trazas (traces) a APM).
Si el pod de la aplicación no se inicia, ejecuta kubectl logs <my-pod> --all-containers para imprimir los logs y compararlos con los problemas conocidos que se indican a continuación.
Problema: La anotación del pod para la versión de biblioteca dotnet incluía un sufijo -musl, pero el contenedor de la aplicación se ejecuta en una distribución Linux que utiliza glibc.
Solución: Elimina el sufijo -musl de la versión de biblioteca dotnet.
Problema: El contenedor de la aplicación se ejecuta en una distribución Linux que utiliza musl-libc (por ejemplo, Alpine), pero la anotación del pod no incluye el sufijo -musl.
Solución: Añade el sufijo -musl a la versión de biblioteca dotnet.
En Python < 1.20.3 , los logs de inyección Python dan como resultado stderr. Actualiza a 1.20.3 o superior para suprimir los logs por defecto. Los logs se pueden habilitar configurando la variable de entorno DD_TRACE_DEBUG como 1.
Problema: La biblioteca ddtrace ya está instalada en el sistema, por lo que la lógica de inyección aborta la inyección del bibliotecas para evitar introducir un cambio de última hora en la aplicación.
Solución: Elimina la instalación de ddtrace, si quieres inyectar bibliotecas. En caso contrario, utiliza la biblioteca instalada (consulta la documentación), en lugar de la inyección de bibliotecas.
La inyección de bibliotecas de rastreo en hosts está en fase Beta.
Cuando tanto el Agent como tus servicios se están ejecutando en un host, real o virtual, Datadog inyecta la biblioteca de rastreo utilizando una biblioteca precargada que anula las llamadas a execve. Cualquier proceso recién iniciado es interceptado y la biblioteca de instrumentación especificada se inyecta en los servicios.
Si el host aún no tiene instalado el Datadog Agent o si quieres actualizar tu instalación del Datadog Agent, utiliza el script de instalación del Datadog Agent para instalar la inyección de bibliotecas y el Datadog Agent:
Por defecto, la ejecución del script instala la compatibilidad para Java, Node.js, Python, Ruby, y .NET. Si quieres especificar qué lenguaje instalar, configura también la variable de entornoDD_APM_INSTRUMENTATION_LIBRARIES. Los valores válidos son java, js, python, ruby y dotnet. Para especificar más de un lenguaje, utiliza una lista separada por comas:
Las siguientes variables de entorno configuran la inyección de bibliotecas. Puedes pasarlas por export, a través de la línea de comandos (export DD_CONFIG_SOURCES=BASIC), la configuración de shells o el comando de inicio.
Cada uno de los campos del archivo de configuración corresponde a una variable de entorno. Esta variable de entorno es leída por el entorno del proceso que se está iniciando y sólo afecta al proceso que se está iniciando en ese momento.
Propiedad del archivo de configuración
Variable de entorno
log_level
DD_APM_INSTRUMENTATION_DEBUG
output_paths
DD_APM_INSTRUMENTATION_OUTPUT_PATHS
env
DD_ENV
config_sources
DD_CONFIG_SOURCES
La variable de entorno DD_APM_INSTRUMENTATION_DEBUG se limita a los valores true y false (valor por defecto false). Si se configura como true, log_level se configura como debug, y si se configura como false (o no se configura en absoluto), se utiliza el log_level especificado en el archivo de configuración. La variable de entorno sólo puede definir el nivel del log como debug, no cualquier otro valor de nivel del log.
La variable de entorno DD_INSTRUMENT_SERVICE_WITH_APM controla si se habilita o no la inyección. Su valor predeterminado es TRUE. Configúrala como FALSE para deshabilitar por completo la inyección de bibliotecas.
Por defecto, los siguientes parámetros están habilitados en un proceso instrumentado:
Rastreo
La inyección de logs, suponiendo que la aplicación utiliza una gestión de logs estructurada (normalmente JSON). Para que aparezcan trazas en logs no estructurados, debes cambiar la configuración de los logs de tu aplicación para incluir parámetros para los ID de rastreo y de tramo (span) ID. Para obtener más información, consulta Correlacionar logs y trazas.
Métricas de estado
Métricas de tiempo de ejecución
Puedes cambiar esta configuración para todos los procesos instrumentados, configurando la propiedad config_sources en el archivo de configuración, o para un único proceso, configurando la variable de entorno DD_CONFIG_SOURCES para el proceso. Los parámetros válidos para las fuentes de configuración son:
Nombre de la fuente de configuración
Significado
BASIC
Aplica las configuraciones especificadas anteriormente. Si no se especifica ninguna fuente de configuración, esta es la predeterminada.
LOCAL:PATH
Aplica la configuración en la ruta especificada del sistema de archivos local. A continuación se describe el formato del archivo de configuración. Ejemplo: LOCAL:/opt/config/my_process_config.yaml
BLOB:URL
Aplica la configuración en la ruta especificada del almacén de objetos compatible con S3. A continuación se describen la URL de conexión y el formato del archivo de configuración. Ejemplo: BLOB:s3://config_bucket/my_process_config.yaml?region=us-east-1
Las palabras BASIC, LOCAL y BLOB deben ir en mayúsculas.
Los valores de las fuentes de configuración pueden separarse con puntos y comas para indicar que existen varias localizaciones posibles. Se utiliza la primera configuración que se devuelve sin error. En la configuración no se combinan varias fuentes de configuración. En el siguiente ejemplo se comprueba la configuración de un bucket de S3, a continuación se comprueba el sistema de archivos local y, por último, se utiliza la configuración integrada predeterminada:
Las soluciones de almacenamiento de blobs compatibles son:
Amazon S3 - Configura la URL con el prefijo s3://. Si te has autenticado con la CLI de AWS, utiliza esas credenciales.
Para obtener información sobre la configuración de credenciales con variables de entorno, consulta la documentación del SDK de AWS.
GCP GCS - Define la URL con el prefijo gs://. Utiliza las credenciales por defecto de la aplicación. Autentícate con gcloud auth application-default login. Para obtener más información sobre la configuración de credenciales con variables entorno, consulta la documentación de autenticación de Google Cloud.
Azure Blob - Define la URL con el prefijo azblob:// y dirígela a un nombre de contenedor de almacenamiento. Utiliza las credenciales que se encuentran en AZURE_STORAGE_ACCOUNT (es decir, el nombre del bucket), junto al menos a unaAZURE_STORAGE_KEY y un AZURE_STORAGE_SAS_TOKEN. Para obtener más información sobre la configuración de BLOB o LOCAL, consulta Suministro de fuentes de configuración .
La opciones de configuración de bibliotecas de rastreo que no se mencionan en la configuración de la inyección siguen estando disponibles para su uso a través de propiedades o variables de entorno, de la forma habitual.
Inicia tus servicios indicando la configuración de biblioteca precargada en el comando de inicio. Si no se especifica DD_CONFIG_SOURCES, se utiliza el valor especificado para config_sources en el archivo de configuración /etc/datadog-agent/inject/host_config.yaml. Si este tampoco se especifica, DD_CONFIG_SOURCES esBASIC por defecto:
Ejercita tu aplicación para empezar a generar datos de telemetría, que puedes ver como trazas en APM.
La inyección de bibliotecas de rastreo en hosts está en fase Beta.
Cuando tu Agent se ejecuta en un host y tus servicios se ejecutan en contenedores, Datadog inyecta la biblioteca de rastreo interceptando la creación del contenedor y configurando el contenedor Docker.
Se intercepta cualquier proceso recién iniciado y la biblioteca de instrumentación especificada se inyecta en el servicio.
Si el host aún no tiene instalado el Datadog Agent o si quieres actualizar tu instalación del Datadog Agent, utiliza el script de instalación del Datadog Agent para instalar la inyección de bibliotecas y el Datadog Agent:
Por defecto, la ejecución del script instala la compatibilidad para Java, Node.js, Python, Ruby, y .NET. Si quieres especificar qué lenguaje instalar, configura también la variable de entornoDD_APM_INSTRUMENTATION_LIBRARIES. Los valores válidos son java, js, python, ruby y dotnet. Para especificar más de un lenguaje, utiliza una lista separada por comas:
Si la configuración por defecto no satisface tus necesidades, puedes editar /etc/datadog-agent/inject/docker_config.yaml y añadir la siguiente configuración YAML a la inyección:
Habilita o deshabilita la inyección de bibliotecas y especifica una lista ordenada, separada por punto y coma, de los lugares donde se almacena la configuración. Se utiliza el primer valor que se devuelve sin error. La configuración no se combina a lo largo de las fuentes de configuración. Los valores válidos son:
BLOB:<URL> - Carga la configuración desde un almacén de blobs (compatible con S3) situado en <URL>.
LOCAL:<PATH> - Carga la configuración desde un archivo del sistema de archivos local en <PATH>.
BASIC - Utiliza valores por defecto. Si no se especifica config_sources, se utiliza esta configuración.
Las palabras BASIC, LOCAL, y BLOB deben ir en mayúsculas.
Los valores de las fuentes de configuración pueden separarse con puntos y comas para indicar que existen varias localizaciones posibles. Se utiliza la primera configuración que se devuelve sin error. En la configuración no se combinan varias fuentes de configuración. En el siguiente ejemplo se comprueba la configuración de un bucket de S3, a continuación se comprueba el sistema de archivos local y, por último, se utiliza la configuración integrada predeterminada:
Configura como debug, para registrar información detallada de lo que está sucediendo, o como info, warn o error, para registrar mucho menos información. Por defecto: info
output_paths
Lista de uno o más lugares donde escribir logs. Por defecto: stderr
Opcional: env
Especifica la etiqueta (tag) DD_ENV para los contenedores que se ejecutan en Docker, por ejemplo, dev, prod, staging. Por defecto: Nada.
La opciones de configuración de bibliotecas de rastreo que no se mencionan en la configuración de la inyección siguen estando disponibles para su uso a través de propiedades o variables de entorno, de la forma habitual.
Las soluciones de almacenamiento de blobs compatibles son:
Amazon S3 - Configura la URL con el prefijo s3://. Si te has autenticado con la CLI de AWS, utiliza esas credenciales.
Para obtener información sobre la configuración de credenciales con variables de entorno, consulta la documentación del SDK de AWS.
GCP GCS - Define la URL con el prefijo gs://. Utiliza las credenciales por defecto de la aplicación. Autentícate con gcloud auth application-default login. Para obtener más información sobre la configuración de credenciales con variables entorno, consulta la documentación de autenticación de Google Cloud.
Azure Blob - Define la URL con el prefijo azblob:// y dirígela a un nombre de contenedor de almacenamiento. Utiliza las credenciales que se encuentran en AZURE_STORAGE_ACCOUNT (es decir, el nombre del bucket), junto al menos a unaAZURE_STORAGE_KEY y un AZURE_STORAGE_SAS_TOKEN. Para obtener más información sobre la configuración de BLOB o LOCAL, consulta Suministro de fuentes de configuración .
Si las variables de entorno DD_ENV , DD_SERVICE o DD_VERSION se especifican en una imagen de contenedor de servicios, esos valores se utilizan para etiquetar la telemetría del contenedor.
Si no se especifican, DD_ENV utiliza el valor env definido en el archivo de configuración /etc/datadog-agent/inject/docker_config.yaml, si existe. DD_SERVICE se deriva del nombre de la imagen Docker. Una imagen con el nombre my-service:1.0 se etiqueta con DD_SERVICE de my-service.
Inicia tu Agent y tus servicios contenedorizados, como de costumbre.
Ejercita tu aplicación para empezar a generar datos de telemetría, que puedes ver como trazas en APM.
La inyección de bibliotecas de rastreo en contenedores está en fase Beta.
Cuando tu Agent y tus servicios se ejecutan en diferentes contenedores Docker, en el mismo host, Datadog inyecta la biblioteca de rastreo interceptando la creación del contenedor y configurando el contenedor Docker.
Se intercepta cualquier proceso recién iniciado y la biblioteca de instrumentación especificada se inyecta en el servicio.
Utiliza el script de shell install_script_agent7.sh para instalar automáticamente la compatibilidad de la inyección Docker. Para esto, Docker ya debe estar instalado en la máquina host.
Se instalan las bibliotecas de todos los lenguajes compatibles. Para instalar lenguajes específicos, define la variable DD_APM_INSTRUMENTATION_LIBRARIES. Los valores válidos son java, js, python, ruby y dotnet:
Habilita o deshabilita la inyección de bibliotecas y especifica una lista ordenada, separada por punto y coma, de los lugares donde se almacena la configuración. Se utiliza el primer valor que se devuelve sin error. La configuración no se combina a lo largo de las fuentes de configuración. Los valores válidos son:
BLOB:<URL> - Carga la configuración desde un almacén de blobs (compatible con S3) situado en <URL>.
LOCAL:<PATH> - Carga la configuración desde un archivo del sistema de archivos local en <PATH>.
BASIC - Utiliza valores por defecto. Si no se especifica config_sources, se utiliza esta configuración.
Las palabras BASIC, LOCAL y BLOB deben ir en mayúsculas.
Los valores de las fuentes de configuración pueden separarse con puntos y comas para indicar que existen varias localizaciones posibles. Se utiliza la primera configuración que se devuelve sin error. En la configuración no se combinan varias fuentes de configuración. En el siguiente ejemplo se comprueba la configuración de un bucket de S3, a continuación se comprueba el sistema de archivos local y, por último, se utiliza la configuración integrada predeterminada:
En este archivo de configuración, el valor de version es siempre 1. Esto hace referencia a la versión del esquema de configuración en uso, no a la versión del contenido.
La opciones de configuración de bibliotecas de rastreo que no se mencionan en la configuración de la inyección siguen estando disponibles para su uso a través de propiedades o variables de entorno, de la forma habitual.
Las soluciones de almacenamiento de blobs compatibles son:
Amazon S3 - Configura la URL con el prefijo s3://. Si te has autenticado con la CLI de AWS, utiliza esas credenciales.
Para obtener información sobre la configuración de credenciales con variables de entorno, consulta la documentación del SDK de AWS.
GCP GCS - Define la URL con el prefijo gs://. Utiliza las credenciales por defecto de la aplicación. Autentícate con gcloud auth application-default login. Para obtener más información sobre la configuración de credenciales con variables entorno, consulta la documentación de autenticación de Google Cloud.
Azure Blob - Define la URL con el prefijo azblob:// y dirígela a un nombre de contenedor de almacenamiento. Utiliza las credenciales que se encuentran en AZURE_STORAGE_ACCOUNT (es decir, el nombre del bucket), junto al menos a unaAZURE_STORAGE_KEY y un AZURE_STORAGE_SAS_TOKEN. Para obtener más información sobre la configuración de BLOB o LOCAL, consulta Suministro de fuentesde configuración .
En el archivo de composición Docker que inicia tus contenedores, utiliza los siguientes parámetros pare el Agent, configurando de forma segura tu propia clave de API Datadog para ${DD_API_KEY}:
Si las variables de entorno DD_ENV , DD_SERVICE o DD_VERSION se especifican en una imagen de contenedor de servicios, esos valores se utilizan para etiquetar la telemetría del contenedor.
Si no se especifican, DD_ENV utiliza el valor env definido en el archivo de configuración /etc/datadog-agent/inject/docker_config.yaml, si existe. DD_SERVICE se deriva del nombre de la imagen Docker. Una imagen con el nombre my-service:1.0 se etiqueta con DD_SERVICE de my-service.
Las características compatibles y las opciones de configuración de la biblioteca de rastreo son las mismas para la inyección de bibliotecas y para otros métodos de instalación, y pueden establecerse con variables de entorno. Para obtener más detalles, consulta la página de configuración de bibliotecas Datadog de tu lenguaje.
Para Kubernetes, configura las variables de entorno DD_APPSEC_ENABLED o DD_PROFILING_ENABLED como true en el archivo de despliegue del pod de aplicación subyacente.
Para hosts y contenedores, configura las variables de entorno de contenedor DD_APPSEC_ENABLED o DD_PROFILING_ENABLED como true, o en la configuración de inyección, especifica una sección additional_environment_variables como en el siguiente ejemplo de YAML:
Sólo las claves de configuración que empiezan por DD_ pueden definirse en la sección additional_environment_variables de la fuente de configuración de la inyección.