Descripción general

En un entorno de Kubernetes, utilice la instrumentación de un solo paso (SSI) para APM para instalar el Datadog Agent e instrumentar sus aplicaciones con los Datadog SDKs en un solo paso.

Requisitos

• Kubernetes v1.20+.
• Helm para desplegar el Datadog Operator.
• Kubectl CLI para instalar el Datadog Agent.
• Compatibilidad del entorno confirmada según la guía de compatibilidad de instrumentación de un solo paso.

Habilitar APM en sus aplicaciones

Siga estos pasos para habilitar la instrumentación de un solo paso en todo su clúster. Esto envía automáticamente trazas de todas las aplicaciones escritas en lenguajes compatibles.

Nota: Para instrumentar solo espacios de nombres o pods específicos, consulte la segmentación de carga de trabajo en Opciones avanzadas.

1. En Datadog, vea la página Instalar el Datadog Agent en Kubernetes.

2. Siga las instrucciones en pantalla para elegir su método de instalación, seleccionar una clave de API y configurar el repositorio del Datadog Operator o de Helm.

3. En la sección Configurar datadog-agent.yaml, ve a Configuración adicional > Observabilidad de aplicaciones y activa Instrumentación APM.

4. Despliega el Agente utilizando el archivo de configuración generado.

5. Reinicie sus aplicaciones.

Configurar Etiquetas de Servicio Unificadas

Las Etiquetas de Servicio Unificadas (USTs) aplican etiquetas consistentes a través de trazas, métricas y registros, facilitando la navegación y correlación de sus datos de observabilidad. Puede configurar USTs a través de la extracción automática de etiquetas (recomendado), mediante la configuración explícita con ddTraceConfigs o en manifiestos de despliegue.

(Recomendado) Configure USTs a través de la extracción automática de etiquetas

Con SSI, puede extraer automáticamente los valores de UST de las etiquetas y metadatos de los pods sin modificar despliegues individuales. Para hacer esto, configure kubernetesResourcesLabelsAsTags para mapear sus etiquetas de Kubernetes existentes a las etiquetas de servicio de Datadog.

Nota: Este método no es compatible con Remote Configuration. Si está utilizando Remote Configuration, consulte Configure USTs explícitamente con ddTraceConfigs.

Requisitos previos

Configuración

Reemplace app.kubernetes.io/name en el siguiente ejemplo con cualquier etiqueta que contenga el nombre de su servicio (por ejemplo, service.kubernetes.io/name o component). Puede configurar múltiples etiquetas de esta manera.

datadog:
  # Automatically extract service names from Kubernetes labels
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service     # Modern Kubernetes label
    deployments.apps:
      app.kubernetes.io/name: service
    replicasets.apps:
      app.kubernetes.io/name: service

  # Set environment globally for the entire cluster
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true

Con esta configuración, Datadog establece automáticamente la etiqueta service utilizando el valor de la etiqueta app.kubernetes.io/name para cualquier carga de trabajo instrumentada que incluya esta etiqueta.

Configure USTs explícitamente con ddTraceConfigs

En la mayoría de los casos, la configuración automática es suficiente. Sin embargo, si necesita un control granular sobre la configuración para cargas de trabajo específicas, utilice ddTraceConfigs para mapear explícitamente etiquetas a configuraciones de servicio:

datadog:
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service
    deployments.apps:
      app.kubernetes.io/name: service

  # Set environment globally for the entire cluster
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: frontend-services
          podSelector:
            matchLabels:
              tier: frontend
          ddTraceConfigs:
            - name: DD_SERVICE       # Explicitly override service name
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['app.kubernetes.io/name']
            # DD_ENV inherited from cluster-level tags above
            # DD_VERSION automatically extracted from image tags

Configure USTs en manifiestos de despliegue

Si su configuración no utiliza etiquetas adecuadas para la extracción de UST, puede establecer USTs directamente en sus manifiestos de despliegue utilizando variables de entorno. Este enfoque requiere modificar cada despliegue individualmente, pero ofrece un control preciso.

Para instrucciones completas, consulta configuración de USTs para servicios de Kubernetes.

Habilitar productos y características dependientes del SDK

Después de que SSI cargue el SDK de Datadog en tus aplicaciones y habilite el rastreo distribuido, puedes configurar productos adicionales que dependen del SDK:

Note: All variables accept true or false. DD_PROFILING_ENABLED also accepts auto, which profiles only eligible processes and is recommended for SSI.

Utilice uno de los siguientes métodos de configuración:

• Configurar con orientación de carga de trabajo (recomendado):

  Por defecto, la instrumentación de un solo paso instrumenta todos los servicios en todos los espacios de nombres. Utilice la orientación de carga de trabajo para limitar la instrumentación a espacios de nombres, pods o cargas de trabajo específicos, y aplique configuraciones personalizadas.

• Establecer variables de entorno:

  Habilite productos configurando variables de entorno directamente en la configuración de su aplicación.

Opciones avanzadas

Utilice las siguientes opciones avanzadas para personalizar cómo se comporta la instrumentación de paso único en su entorno. Estas configuraciones son opcionales y generalmente solo se necesitan en configuraciones especializadas.

Configurar modos de inyección

SSI admite múltiples modos de inyección, que controlan cómo se entregan los archivos del inyector y de la biblioteca APM a los contenedores de su aplicación. Generalmente, no necesita configurar esta opción manualmente. Considere ajustarla si observa retrasos significativos en el inicio de los pods o un uso de recursos (CPU, memoria) superior al esperado durante la inicialización del pod. Para más información sobre cómo funciona el inyector, consulte Comportamiento del inyector con la instrumentación de un solo paso.

Antes de usar el modo csi, instale y active el Datadog CSI driver. Si está implementando con Helm, también establezca datadog.csi.enabled: true en su datadog-values.yaml. Consulte la documentación del Datadog CSI driver para los pasos de instalación y los requisitos específicos del entorno, como GKE Autopilot.

Configura el modo de inyección globalmente

datadog:
  apm:
    instrumentation:
      injectionMode: <mode>

features:
  apm:
    instrumentation:
      injectionMode: <mode>

Configure el modo de inyección por pod

Para anular el modo de inyección para un pod específico, agregue la siguiente anotación a la especificación del pod:

metadata:
  annotations:
    admission.datadoghq.com/apm-inject.injection-mode: "<mode>"

Valores soportados: init_container, csi.

Dirija cargas de trabajo específicas

Por defecto, SSI instrumenta todos los servicios en todos los espacios de nombres de su clúster. Dependiendo de la versión de su Datadog Agent, utilice uno de los siguientes métodos de configuración para refinar qué servicios se instrumentan y cómo.

   apm:
     instrumentation:
       enabled: true
       disabledNamespaces:
         - "jenkins"
       targets:
         - name: "all-remaining-services"
           ddTraceVersions:
             java: "default"
             python: "3.1.0"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: "login-service_namespace"
          namespaceSelector:
            matchNames:
              - "login-service"
          ddTraceVersions:
            java: "default"
          ddTraceConfigs:
            - name: "DD_PROFILING_ENABLED"  ## profiling is enabled for all services in this namespace
              value: "auto"
        - name: "billing-service_apps"
          namespaceSelector:
            matchLabels:
              app: "billing-service"
          ddTraceVersions:
            python: "3.1.0"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "db-user"
           podSelector:
             matchLabels:
               app: "db-user"
           ddTraceVersions:
             java: "default"
           ddTraceConfigs:   ## trace configs set for services in matching pods
             - name: "DD_DATA_STREAMS_ENABLED"
               value: "true"
         - name: "user-request-router"
           podSelector:
             matchLabels:
               webserver: "user"
           ddTraceVersions:
             php: "default"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "login-service-namespace"
           namespaceSelector:
             matchNames:
               - "login-service"
           podSelector:
             matchLabels:
               app: "password-resolver"
           ddTraceVersions:
             java: "default"
           ddTraceConfigs:
             - name: "DD_PROFILING_ENABLED"
               value: "auto"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "default-target"
           podSelector:
               matchExpressions:
                 - key: app
                   operator: NotIn
                   values:
                   - app1
                   - app2

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "web-apps-with-security"
           namespaceSelector:
             matchNames:
               - "web-apps"
           ddTraceVersions:
             java: "default"
             python: "default"
           ddTraceConfigs:
             - name: "DD_APPSEC_ENABLED"
               value: "true"
             - name: "DD_PROFILING_ENABLED"
               value: "auto"

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

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

   datadog:
      apm:
        instrumentation:
          enabled: true
          enabledNamespaces: # Add namespaces to instrument
             - namespace_1
             - namespace_2

   datadog:
      apm:
        instrumentation:
          enabled: true
          disabledNamespaces: # Add namespaces to not instrument
            - namespace_1
            - namespace_2

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

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

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

Cambie el registro de contenedor predeterminado

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 Agente de Clúster de Datadog especifica el registro utilizado por el Controlador de Admisión. El valor predeterminado es gcr.io/datadoghq.

Puede obtener el SDK de un registro diferente cambiándolo a docker.io/datadog, public.ecr.aws/datadog o a otra URL si está alojando las imágenes en un registro de contenedor local.

Para obtener instrucciones sobre cómo cambiar su registro de contenedor, consulte Cambiar su registro de contenedor.

Utilice un registro de contenedor privado

Si su organización no permite descargas directas de registros públicos (como gcr.io, docker.io o public.ecr.aws), puede alojar las imágenes requeridas de Datadog internamente y configurar el Controlador de Admisión para usarlas.

Para usar SSI con un registro de contenedor privado:

1. Siga estas instrucciones para reflejar las imágenes de contenedor de Datadog en su registro privado.

   Solo necesita las imágenes para los lenguajes que está instrumentando. Si no está seguro de cuáles necesita, aquí hay una línea base que cubre la mayoría de los casos de uso:

   • apm-inject
   • dd-lib-java-init
   • dd-lib-python-init
   • dd-lib-dotnet-init
   • dd-lib-php-init
   • dd-lib-ruby-init
   • dd-lib-js-init

   Puede encontrar estas imágenes en gcr.io, Docker Hub o Amazon ECR Public Gallery.

2. Etiquete las imágenes de acuerdo a su configuración.

   Las versiones que refleja deben coincidir con las versiones configuradas en sus cargas de trabajo, que pueden estar establecidas de una de las siguientes maneras:

   • globalmente en la configuración del Agente usando ddTraceVersions, o
   • por pod usando anotaciones como admission.datadoghq.com/java-lib.version.

   Si no se configura explícitamente una versión, se utiliza la versión predeterminada (0).

   Por ejemplo:

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "default-target"
           ddTraceVersions:
             java: "1"
             python: "3"
   

   Esta configuración requiere las siguientes etiquetas de imagen:

   • apm-inject:0
   • dd-lib-java-init:1
   • dd-lib-python-init:3

3. Actualice la configuración del Agente de Clúster de Datadog para utilizar su registro privado.

   Establezca la variable de entorno DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY en la configuración de su Agente de Clúster de Datadog para utilizar su registro privado.

Para más detalles sobre cómo cambiar tu registro de contenedores, consulta Cambiando Tu Registro de Contenedores.

Usando una Interfaz de Red de Contenedores en EKS

Al usar un CNI como Calico, los nodos del plano de control no pueden iniciar conexiones de red al Controlador de Admisión de Datadog y reportan un error de “Dirección no permitida”. Para usar la instrumentación de Un Solo Paso, modifique el Agente de Clúster de Datadog con el parámetro useHostNetwork: true.

datadog:
  ...

clusterAgent:
  useHostNetwork: true

  admissionController:
    ...

Elimine la instrumentación de APM de Un Solo Paso de su Agente

Si no desea recopilar datos de trazas para un servicio, host, VM o contenedor en particular, complete los siguientes pasos:

Elimine la instrumentación para servicios específicos

Para eliminar la instrumentación de APM y dejar de enviar trazas desde un servicio específico, puede hacer una de las siguientes acciones:

Utilice reglas de instrumentación para dirigir cargas de trabajo específicas (recomendado)

Con las reglas de instrumentación (disponibles para el Agente v7.64+), puede habilitar y deshabilitar la producción de trazas para aplicaciones específicas. Consulte los detalles de configuración aquí

Utilice el Controlador de Admisión de Datadog

Como alternativa, o para una versión del agente que no soporte reglas de instrumentación, también puede deshabilitar la mutación de pods añadiendo una etiqueta a su pod.

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

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

2. Aplique la configuración:

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

3. Reinicie los servicios de los cuales desea eliminar la instrumentación.

Elimine APM para todos los servicios en la infraestructura

Para dejar de producir trazas, desinstale APM y reinicie la infraestructura:

El archivo que necesita configurar depende de si habilitó la Instrumentación de Paso Único con Datadog Operator o Helm:

Mejores prácticas

Después de habilitar SSI, todos los procesos soportados en el clúster se instrumentan automáticamente y comienzan a producir trazas en minutos.

Para controlar dónde se activa APM y reducir la sobrecarga, considere las siguientes mejores prácticas.

targets:
  - name: login-service
    namespaceSelector:
      matchNames: ["login-service"]
    ddTraceVersions:
      java: "1.48.2"    # pin version

targets:
  - name: default-target          # tag any pod *without* an override
    ddTraceVersions:
      java:   "1"   # stay on latest v1.x
      python: "3"   # stay on latest v3.x
      js:     "5"   # NodeJS
      php:    "1"
      dotnet: "3"

Solución de problemas

Si encuentra problemas al habilitar APM con SSI, consulte la guía de solución de problemas de SSI.

Lectura adicional

Más enlaces, artículos y documentación útiles:

Habilitar métricas en tiempo de ejecuciónDOCUMENTACIÓN Aprender sobre el uso de recursos de contenedores initDOCUMENTACIÓN Instrumente sus aplicaciones utilizando la inyección local del SDK.DOCUMENTACIÓN Configurando la instrumentación de un solo paso en KubernetesCENTRO DE APRENDIZAJE