Instrumentación de un solo paso para APM

Documentos > APM > Instrumentación de aplicación > Instrumentación automática > Instrumentación de un solo paso para APM

Información general

La Instrumentación de un solo paso (SSI) para APM instala el Datadog Agent e instrumenta tus aplicaciones en un solo paso, sin necesidad de pasos adicionales de configuración.

Compatibilidad

Para ver los requisitos de los lenguajes, sistemas operativos y arquitecturas compatibles, consulta Compatibilidad de la instrumentación de un solo paso.

Habilitar APM en tus aplicaciones

Si instalas o actualizas un Datadog Agent con la opción Enable APM Instrumentation (Habilitar la Instrumentación de APM) seleccionada, el Agent se instala y configura para habilitar APM. Esto instrumenta automáticamente tu aplicación, sin ningún paso adicional de instalación o configuración.

Los siguientes ejemplos muestran cómo funciona para cada tipo de despliegue.

Si ya has utilizado la instrumentación de un solo paso con hosts Linux, actualiza a la última versión.

Para un host Ubuntu:

Ejecuta el comando de instalación de una línea:

DD_API_KEY=<YOUR_DD_API_KEY> DD_SITE="<YOUR_DD_SITE>" DD_APM_INSTRUMENTATION_ENABLED=host DD_APM_INSTRUMENTATION_LIBRARIES="java:1,python:2,js:5,dotnet:3,php:1" DD_ENV=<AGENT_ENV> bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

Sustituye <YOUR_DD_API_KEY> por tu clave de API Datadog, <YOUR_DD_SITE> por tu sitio Datadog y <AGENT_ENV> por el entorno en el que está instalado tu Agent (por ejemplo, staging).

Para ver más opciones, consulta Opciones avanzadas.

Inicia una nueva sesión de shell.
Reinicia los servicios en el host o la máquina virtual.

Para un contenedor Linux Docker:

Ejecuta el comando de instalación de una línea:

DD_APM_INSTRUMENTATION_ENABLED=docker DD_APM_INSTRUMENTATION_LIBRARIES="java:1,python:2,js:5,dotnet:3,php:1" DD_NO_AGENT_INSTALL=true bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

Configura el Agent en Docker:

docker run -d --name dd-agent \
  -e DD_API_KEY=<YOUR_DD_API_KEY> \
  -e DD_APM_ENABLED=true \
  -e DD_ENV=<AGENT_ENV> \
  -e DD_APM_NON_LOCAL_TRAFFIC=true \
  -e DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true \
  -e DD_APM_RECEIVER_SOCKET=/var/run/datadog/apm.socket \
  -e DD_DOGSTATSD_SOCKET=/var/run/datadog/dsd.socket \
  -v /var/run/datadog:/var/run/datadog \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  gcr.io/datadoghq/agent:7

Sustituye <YOUR_DD_API_KEY> por tu clave de API Datadog y <AGENT_ENV> por el entorno en el que está instalado tu Agent (por ejemplo, staging).

Para ver más opciones, consulta Opciones avanzadas.

Reinicia los contenedores Docker.
Explora la observabilidad del rendimiento de tus servicios en Datadog.

Puedes habilitar APM instalando el Agent con cualquiera de las dos opciones:

Datadog Operator
Helm Chart Datadog

La instrumentación de un solo paso no instrumenta aplicaciones en el espacio de nombres donde instalas el Datadog Agent. Se recomienda instalar el Agent en un espacio de nombres separado en tu clúster, donde no ejecutes tus aplicaciones.

Requisitos

Kubernetes v1.20 y posterior
Helm para desplegar el Datadog Operator.
CLI Kubectl para instalar el Datadog Agent.

Instalación con el Datadog Operator

Sigue estos pasos para habilitar la instrumentación de un solo paso en todo tu clúster con el Datadog Operator. Esto envía automáticamente trazas para todas las aplicaciones en el clúster que están escritas en lenguajes compatibles.

Para habilitar la instrumentación de un solo paso con el Datadog Operator:

Instala el Datadog Operator: v1.5.0 o superior con Helm:

helm repo add datadog https://helm.datadoghq.com
helm repo update
helm install my-datadog-operator datadog/datadog-operator

Crea un secreto Kubernetes para almacenar tu clave de API Datadog:

kubectl create secret generic datadog-secret --from-literal api-key=$DD_API_KEY

Crea datadog-agent.yaml con las especificaciones de configuración del despliegue de tu Datadog Agent. La siguiente configuración es la más sencilla:

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    site: <DATADOG_SITE>
    tags:
      - env:<AGENT_ENV>
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key
  features:
    apm:
      instrumentation:
        enabled: true
        libVersions:
          java: "1"
          dotnet: "3"
          python: "2"
          js: "5"

Sustituye <DATADOG_SITE> por tu sitio Datadog y <AGENT_ENV> por el entorno en el que está instalado tu Agent (por ejemplo, env:staging).

Para ver más opciones, consulta Opciones avanzadas.

Ejecuta el siguiente comando:

kubectl apply -f /path/to/your/datadog-agent.yaml

Espera unos minutos a que se apliquen los cambios del Datadog Cluster Agent y reinicia tus aplicaciones.

Instalación con Helm

Sigue estos pasos para habilitar la instrumentación de un solo paso en todo tu clúster con Helm. Esto envía automáticamente trazas para todas las aplicaciones en el clúster que están escritas en lenguajes compatibles.

Para habilitar la instrumentación de un solo paso con Helm:

Añade el repositorio de Datadog Helm:

 helm repo add datadog https://helm.datadoghq.com
 helm repo update

Crea un secreto Kubernetes para almacenar tu clave de API Datadog:

kubectl create secret generic datadog-secret --from-literal api-key=$DD_API_KEY

Crea datadog-values.yaml y añade la siguiente configuración:

datadog:
 apiKeyExistingSecret: datadog-secret
 site: <DATADOG_SITE>
 tags:
      - env:<AGENT_ENV>
 apm:
   instrumentation:
      enabled: true
      libVersions:
         java: "1"
         dotnet: "3"
         python: "2"
         js: "5"

Sustituye <DATADOG_SITE> por tu sitio Datadog y <AGENT_ENV> por el entorno en el que está instalado tu Agent (por ejemplo, env:staging).

Para ver más opciones, consulta Opciones avanzadas.

Ejecuta el siguiente comando:

helm install datadog-agent -f datadog-values.yaml datadog/datadog

Espera unos minutos a que se apliquen los cambios del Datadog Cluster Agent y reinicia tus aplicaciones.

Una vez completados estos pasos, puede que desees activar métricas de tiempo de ejecución o ver los datos de observabilidad de tu aplicación en el Catálogo de software.

Opciones avanzadas

Cuando ejecutas el comando de instalación de una línea, hay algunas opciones disponibles para personalizar tu experiencia:

`DD_APM_INSTRUMENTATION_LIBRARIES`: personalizar bibliotecas de APM

Por defecto, las bibliotecas de Datadog APM para Java, Python, Ruby, Node.js y .NET Core se instalan cuando se establece DD_APM_INSTRUMENTATION_ENABLED. DD_APM_INSTRUMENTATION_LIBRARIES se utiliza para anular qué bibliotecas se instalan. El valor es una cadena separada por comas de pares de nombres y versiones de biblioteca separados por dos puntos.

Valores de ejemplo para DD_APM_INSTRUMENTATION_LIBRARIES:

DD_APM_INSTRUMENTATION_LIBRARIES="java:1": instala sólo la biblioteca de Datadog APM para Java fijada a la línea de lanzamiento de la versión principal 1.
DD_APM_INSTRUMENTATION_LIBRARIES="java:1,python:2": instala sólo las bibliotecas de Datadog APM para Java y Python fijadas a las versiones principales 1 y 2 respectivamente.
DD_APM_INSTRUMENTATION_LIBRARIES="java:1.38.0,python:2.10.5": instala sólo las bibliotecas de Datadog APM para Java y Python fijadas a las versiones específicas 1.38.0 y 2.10.5 respectivamente.

Las versiones disponibles figuran en los repositorios fuentes de cada lenguaje:

Java (java)
Node.js (js)
Python (python)
.NET (dotnet)
Ruby (ruby)
PHP (php)

`DD_APM_INSTRUMENTATION_LIBRARIES`: personaliza bibliotecas de APM

Valores de ejemplo para DD_APM_INSTRUMENTATION_LIBRARIES:

DD_APM_INSTRUMENTATION_LIBRARIES="java:1": instala sólo la biblioteca de Datadog APM para Java fijada a la línea de lanzamiento de la versión principal 1.
DD_APM_INSTRUMENTATION_LIBRARIES="java:1,python:2": instala sólo las bibliotecas de Datadog APM para Java y Python fijadas a las versiones principales 1 y 2 respectivamente.
DD_APM_INSTRUMENTATION_LIBRARIES="java:1.38.0,python:2.10.5": instala sólo las bibliotecas de Datadog APM para Java y Python fijadas a las versiones específicas 1.38.0 y 2.10.5 respectivamente.

Las versiones disponibles figuran en los repositorios fuentes de cada lenguaje:

Java (java)
Node.js (js)
Python (python)
.NET (dotnet)
Ruby (ruby)
[PHP][13] (php)

Habilitar o deshabilitar la instrumentación para espacios de nombres

Puedes elegir habilitar o deshabilitar la instrumentación para aplicaciones en espacios de nombres específicos. Sólo puedes definir espacios de nombres habilitados o espacios de nombres deshabilitados, no ambos.

El archivo que tienes que configurar depende de si has habilitado la instrumentación de un solo paso con el Datadog Operator o con Helm:

Datadog Operator

Para habilitar la instrumentación para espacios de nombres específicos, añade la configuración enabledNamespaces a datadog-agent.yaml:

   features:
     apm:
       instrumentation:
         enabled: true
         enabledNamespaces: # Add namespaces to instrument
           - default
           - applications

Para deshabilitar la instrumentación para determinados espacios de nombres, añade la configuración disabledNamespaces a datadog-agent.yaml:

   features:
     apm:
       instrumentation:
         enabled: true
         disabledNamespaces: # Add namespaces to not instrument
           - default
           - applications

Helm

Para habilitar la instrumentación para espacios de nombres específicos, añade la configuración enabledNamespaces a datadog-values.yaml:

   datadog:
      apm:
        instrumentation:
          enabled: true
          enabledNamespaces: # Añadir espacios de nombres que se van a instrumentar
             - namespace_1
             - namespace_2

Para deshabilitar la instrumentación para determinados espacios de nombres, añade la configuración disabledNamespaces a datadog-values.yaml:

   datadog:
      apm:
        instrumentation:
          enabled: true
          disabledNamespaces: # Añadir espacios de nombres que no se van a instrumentar
            - namespace_1
            - namespace_2

Especificación de versiones de bibliotecas de rastreo

A partir del Datadog Cluster Agent v7.52.0 o superior, puedes instrumentar automáticamente un subconjunto de tus aplicaciones, basándose en las bibliotecas de rastreo que especifiques.

Especifica bibliotecas de rastreo de Datadog y sus versiones para instrumentar automáticamente las aplicaciones escritas en esos lenguajes. Puedes configurarlo de dos maneras, que se aplican en el siguiente orden de precedencia:

Especificarlas a nivel del servicio o bien
Especificarlas a nivel del clúster.

Por defecto: Si no especificas ninguna versión de biblioteca yapm.instrumentation.enabled=true, las aplicaciones escritas en los lenguajes soportados se instrumentan automáticamente utilizando las últimas versiones de bibliotecas de rastreo.

Especificación a nivel del servicio

Para instrumentar automáticamente aplicaciones en pods específicos, añade la anotación de lenguaje y la versión de biblioteca adecuadas para tu aplicación en la especificación de tu pod:

Lenguaje	Anotación del pod
Java	`admission.datadoghq.com/java-lib.version: "<CONTAINER IMAGE TAG>"`
Node.js	`admission.datadoghq.com/js-lib.version: "<CONTAINER IMAGE TAG>"`
Python	`admission.datadoghq.com/python-lib.version: "<CONTAINER IMAGE TAG>"`
.NET	`admission.datadoghq.com/dotnet-lib.version: "<CONTAINER IMAGE TAG>"`
Ruby	`admission.datadoghq.com/ruby-lib.version: "<CONTAINER IMAGE TAG>"`

Sustituye <CONTAINER IMAGE TAG> por la versión de biblioteca deseada. Las versiones disponibles se enumeran en los registros de contenedores de Datadog y en los repositorios de orígenes de rastreadores para cada lenguaje:

Ten cuidado al utilizar la última etiqueta (tag), ya que las mayores versiones de bibliotecas pueden introducir cambios de última hora.

Por ejemplo, para instrumentar aplicaciones Java automáticamente:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    # ...
spec:
  template:
    metadata:
      annotations:
        admission.datadoghq.com/java-lib.version: "<CONTAINER IMAGE TAG>"
    spec:
      containers:
        - # ...

Especificación a nivel del clúster

Si no habilitas la instrumentación automática para pods específicos utilizando las anotaciones, puedes especificar qué lenguajes instrumentar en todo el clúster utilizando la configuración de la instrumentación de un solo paso. Cuando se define apm.instrumentation.libVersions, sólo se instrumentan las aplicaciones escritas en los lenguajes especificados, utilizando las versiones de biblioteca especificadas.

El archivo que tienes que configurar depende de si has habilitado la instrumentación de un solo paso con el Datadog Operator o con Helm:

Datadog Operator

Por ejemplo, para instrumentar aplicaciones .NET, Python, y Node.js añade la siguiente configuración a tu archivo datadog-agent.yaml:

   features:
     apm:
       instrumentation:
         enabled: true
         libVersions: # Add any libraries and versions you want to set
            dotnet: "3.2.0"
            python: "1.20.6"
            js: "4.17.0"

Helm

Por ejemplo, para instrumentar aplicaciones .NET, Python, y Node.js añade la siguiente configuración a tu archivo datadog-values.yaml:

   datadog:
     apm:
       instrumentation:
         enabled: true
         libVersions: # Add any libraries and versions you want to set
            dotnet: "3.2.0"
            python: "1.20.6"
            js: "4.17.0"

Registros de contenedores

Datadog publica imágenes de bibliotecas de instrumentación en gcr.io, Docker Hub y Amazon ECR:

Lenguaje	gcr.io	hub.docker.com	gallery.ecr.aws
Java	gcr.io/datadoghq/dd-lib-java-init	hub.docker.com/r/datadog/dd-lib-java-init	gallery.ecr.aws/datadog/dd-lib-java-init
Node.js	gcr.io/datadoghq/dd-lib-js-init	hub.docker.com/r/datadog/dd-lib-js-init	gallery.ecr.aws/datadog/dd-lib-js-init
Python	gcr.io/datadoghq/dd-lib-python-init	hub.docker.com/r/datadog/dd-lib-python-init	gallery.ecr.aws/datadog/dd-lib-python-init
.NET	gcr.io/datadoghq/dd-lib-dotnet-init	hub.docker.com/r/datadog/dd-lib-dotnet-init	gallery.ecr.aws/datadog/dd-lib-dotnet-init
Ruby	gcr.io/datadoghq/dd-lib-ruby-init	hub.docker.com/r/datadog/dd-lib-ruby-init	gallery.ecr.aws/datadog/dd-lib-ruby-init

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 obtener instrucciones sobre cómo cambiar el registro de contenedores, consulta Para cambiar tu registro de contenedores.

Eliminar la instrumentación de un solo paso APM de tu Agent

Si no quieres recopilar datos de trazas de un determinado servicio, host, máquina virtual o contenedor, sigue los pasos que se indican a continuación:

Eliminación de la instrumentación para servicios específicos

Para eliminar la instrumentación APM y dejar de enviar trazas desde un servicio específico, sigue estos pasos:

Añade la variable de entorno DD_INSTRUMENT_SERVICE_WITH_APM al comando de inicio de servicio:
```
DD_INSTRUMENT_SERVICE_WITH_APM=false <service_start_command>
```
Reinicia el servicio.

Añade la variable de entorno DD_INSTRUMENT_SERVICE_WITH_APM al comando de inicio de servicio:
```
docker run -e DD_INSTRUMENT_SERVICE_WITH_APM=false <service_start_command>
```
Reinicia el servicio.

Establece la etiqueta admission.datadoghq.com/enabled: en "false" para la especificación del pod:

spec:
  template:
    metadata:
      labels:
        admission.datadoghq.com/enabled: "false"

Aplica la configuración:

kubectl apply -f /path/to/your/deployment.yaml

Reinicia los servicios de los que quieres eliminar la instrumentación.

Eliminación de APM para todos los servicios en la infraestructura

Para dejar de producir trazas, desinstala APM y reinicia la infraestructura:

Ejecuta:
```
dd-host-install --uninstall
```
Reinicia los servicios en el host o la máquina virtual.

Ejecuta:
```
dd-container-install --uninstall
```
Reinicia Docker:
```
systemctl restart docker
```
O utiliza el equivalente para tu entorno.

El archivo que tienes que configurar depende de si has habilitado la instrumentación de un solo paso con el Datadog Operator o con Helm:

Datadog Operator

Configura instrumentation.enabled=false en datadog-agent.yaml:

features:
  apm:
    instrumentation:
      enabled: false

Despliega el Datadog Agent con el archivo de configuración actualizado:
```
kubectl apply -f /path/to/your/datadog-agent.yaml
```

Helm

Configura instrumentation.enabled=false en datadog-values.yaml:

datadog:
  apm:
    instrumentation:
      enabled: false

Ejecuta el siguiente comando:

helm upgrade datadog-agent -f datadog-values.yaml datadog/datadog

Solucionar problemas

La instrumentación de paso único no surte efecto

La instrumentación de paso único se desactiva automáticamente cuando detecta instrumentación personalizada en tu aplicación. Si deseas utilizar SSI, tendrás que: