Información general

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

Requisitos

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

Activar APM en tus aplicaciones

Sigue estos pasos para activar la instrumentación de un solo paso en todo tu clúster. Esta acción envía automáticamente trazas (traces) de todas las aplicaciones escritas en los lenguajes compatibles.

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

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

2. Sigue las instrucciones que aparecen en pantalla para seleccionar el método de instalación, seleccionar una clave de API y configurar el Operator o el repositorio de Helm.

3. En la sección Configure datadog-agent.yaml (Configurar datadog-agent.yaml), ve a Additional Configuration > Application Observability (Configuración adicional > Observabilidad de aplicaciones) y activa la instrumentación APM.

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

5. Reinicia tus aplicaciones.

Configurar etiquetas (tags) de servicio unificadas

Las etiquetas (tags) de servicio unificadas (UST) aplican etiquetas (tags) coherentes en trazas, métricas y logs, lo que facilita la navegación y la correlación de tus datos de observabilidad. Puedes configurar UST mediante la extracción de etiquetas (labels), que es la opción recomendada, o en manifiestos de despliegue.

(Recomendado) Configurar UST mediante la extracción de etiquetas (labels)

Con la SSI, puedes extraer automáticamente los valores de las UST de etiquetas (labels) y metadatos de pods sin modificar los despliegues individuales. Para ello, configura kubernetesResourcesLabelsAsTags para asignar tus etiquetas (labels) de Kubernetes existentes a tags (etiquetas) de servicios Datadog.

Requisitos previos

Configuración automática

Sustituye app.kubernetes.io/name en el siguiente ejemplo por cualquier etiqueta (label) que contenga el nombre de tu servicio (por ejemplo, service.kubernetes.io/name o component). Puedes configurar varias etiquetas (labels) de esta forma.

datadog:
  # Extraer automáticamente nombres de servicio de las etiquetas (labels) de Kubernetes
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service     # Etiqueta (label) moderna de Kubernetes
    deployments.apps:
      app.kubernetes.io/name: service
    replicasets.apps:
      app.kubernetes.io/name: service

  # Configurar el entorno globalmente para todo el clúster
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true

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

Control explícito con ddTraceConfigs

En la mayoría de los casos, la configuración automática es suficiente. Sin embargo, si necesitas un control granular sobre las configuraciones de cargas de trabajo específicas, utiliza ddTraceConfigs para asignar explícitamente etiquetas (labels) a configuraciones de servicio:

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

  # Configurar el entorno globalmente para todo el clúster
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: frontend-services
          podSelector:
            matchLabels:
              tier: frontend
          ddTraceConfigs:
            - name: DD_SERVICE       # Anular explícitamente el nombre de servicio
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['app.kubernetes.io/name']
            # DD_ENV heredada de etiquetas (tags) a nivel del clúster de aquí arriba
            # DD_VERSION extraída automáticamente de etiquetas (tags) de imagen

Configurar UST en manifiestos de despliegue

Si tu configuración no utiliza las etiquetas (labels) adecuadas para la extracción de UST, puedes configurar las UST directamente en tus manifiestos de despliegue utilizando variables de entorno. Este enfoque requiere modificar cada despliegue individualmente, pero ofrece un control preciso.

Para obtener instrucciones completas, consulta la configuración de UST para servicios de Kubernetes.

Activar productos y funciones dependientes de SDK

Después de que la SSI cargue el SDK de Datadog en tus aplicaciones y active el rastreo distribuido, puedes configurar productos adicionales que dependan del SDK. Estos incluyen funciones tales como Continuous Profiler, Application Security Monitoring y los controles de ingesta de trazas.

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

• Configurar con cargas de trabajo específicas (recomendado):

  Por defecto, Single Step Instrumentation instrumenta todos los servicios en todos los espacios de nombres. Utiliza la orientación a las cargas de trabajo para limitar la instrumentación a espacios de nombres, pods y cargas de trabajo específicos, y aplica configuraciones personalizadas.

• Configurar variables de entorno:

  Activa productos definiendo variables de entorno directamente en la configuración de tu aplicación.

Opciones avanzadas

Utiliza las siguientes opciones avanzadas para personalizar el comportamiento de la instrumentación de un solo paso en tu entorno. Estos ajustes son opcionales y normalmente solo son necesarios en configuraciones especializadas.

Cargas de trabajo específicas del destino

Por defecto, la SSI instrumenta todos los servicios en todos los espacios de nombres de tu clúster. Según cuál sea tu versión del Agent, utiliza uno de los siguientes métodos de configuración para refinar qué servicios se instrumentan y de qué manera.

   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"  ## la generación de perfiles está activada para todos los servicios en este espacio de nombres
              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:   ## configuraciones de rastreo definidas para servicios en pods coincidentes
             - 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

   features:
     apm:
       instrumentation:
         enabled: true
         enabledNamespaces: # Añadir espacios de nombres que se van a instrumentar
           - default
           - applications

   features:
     apm:
       instrumentation:
         enabled: true
         disabledNamespaces: # Añadir espacios de nombres que no se van a instrumentar
           - default
           - applications

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

   datadog:
      apm:
        instrumentation:
          enabled: true
          disabledNamespaces: # Añadir espacios de nombres que no se van a instrumentar
            - 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: # Añadir las librerías y versiones que quieras configurar
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

   datadog:
     apm:
       instrumentation:
         enabled: true
         libVersions: # Añadir las librerías y versiones que quieras configurar
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

Cambiar el registro de imágenes por defecto

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

Utilizar un registro de contenedores privado

Si tu organización no permite extracciones directas de registros públicos (como gcr.io, docker.io o public.ecr.aws), puedes alojar internamente las imágenes necesarias de Datadog y configurar el controlador de admisión para que las utilice.

Para utilizar la SSI con un registro de contenedores privado:

1. Sigue estas instrucciones para replicar las imágenes de contenedor de Datadog en tu registro privado.

   Solo necesitas las imágenes para los lenguajes que estás instrumentando. Si no estás seguro de cuáles necesitas, esta es una referencia 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

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

2. Etiqueta (tag) las imágenes según su configuración.

   Las versiones que reflejas deben coincidir con las versiones configuradas en tus cargas de trabajo, que pueden definirse de una de las siguientes maneras:

   • Globalmente en la configuración del Agent utilizando ddTraceVersions, o bien
   • Por pod, utilizando anotaciones como admission.datadoghq.com/java-lib.version.

   Si no se configura explícitamente ninguna versión, se utiliza la versión por defecto (0).

   Por ejemplo:

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

   Esta configuración requiere las siguientes etiquetas (tags) de imagen:

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

3. Actualiza la configuración del Cluster Agent para utilizar tu registro privado.

   Configura la variable de entorno DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY en la configuración de tu Cluster Agent para utilizar tu registro privado.

Para obtener más información sobre cómo cambiar el registro de contenedores, consulta Cambiar el registro de contenedores.

Uso de una interfaz de red de contenedores (CNI) en EKS

Cuando se utiliza una CNI como Calico, los nodos del plano de control no pueden iniciar conexiones de red con el controlador de admisión de Datadog e informan de un error “Address is not allowed”. Para utilizar la instrumentación de un solo paso, modifica el Cluster Agent de Datadog con el parámetro useHostNetwork: true.

datadog:
  ...

clusterAgent:
  useHostNetwork: true

  admissionController:
    ...

Eliminar la instrumentación de un solo paso 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 en servicios específicos

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

Utilizar la selección de cargas de trabajo (recomendado).

Con la selección de cargas de trabajo (disponible para el Agent v7.64 o posterior), puedes activar y desactivar el rastreo para aplicaciones específicas. Consulta los detalles de configuración aquí.

Uso del controlador de admisión de Datadog

Como alternativa, o para una versión del Agent que no admite la selección de cargas de trabajo, también puedes desactivar la mutación de pods añadiendo una etiqueta (label) a tu pod.

1. Configura la etiqueta (label) admission.datadoghq.com/enabled: como "false" para la especificación del pod:

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

2. Aplica la configuración:

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

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

Eliminar APM para todos los servicios de la infraestructura

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

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:

Prácticas recomendadas

Tras activar la SSI, todos los procesos compatibles del clúster se instrumentan automáticamente y comienzan a generar trazas en cuestión de minutos.

Para controlar dónde se activa APM y reducir los gastos generales, ten en cuenta las siguientes prácticas recomendadas.

targets:
  - name: login-service
    namespaceSelector:
      matchNames: ["login-service"]
    ddTraceVersions:
      java: "1.48.2"    # fijar versión

targets:
  - name: default-target          # etiquetar cualquier pod *sin* uan anulación
    ddTraceVersions:
      java:   "1"   # permanecer en la v1.x más reciente
      python: "3"   # permanecer en la v3.x más reciente
      js:     "5"   # NodeJS
      php:    "1"
      dotnet: "3"

Solucionar problemas

Si tienes problemas para activar APM con SSI, consulta la guía de resolución de problemas de la SSI.

Referencias adicionales

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

Habilitar métricas de tiempo de ejecuciónDOCUMENTACIÓN Más información sobre el uso de recursos del contenedor de inicializaciónDOCUMENTACIÓN Instrumentación de tus aplicaciones mediante la inyección local de SDKDOCUMENTACIÓN