Información general

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

Requisitos

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

Activa APM en tus aplicaciones

Sigue estos steps (UI) / pasos (generic) para activar la instrumentación de un solo step (UI) / paso (generic) en todo tu clúster. Esto envía automáticamente las traces (trazas) 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 page (página) de Instalación del Datadog Agent en Kubernetes.

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

3. En la sección Configurar datadog-agent.yaml, ve a Additional configuration > Application Observability (Configuración adicional > Observabilidad de la aplicación) y activa APM Instrumentation (Instrumentación de APM).

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

5. Reinicia tus aplicaciones.

Configurar tags (etiquetas) de servicio unificadas

Las tags (etiquetas) de servicio unificadas (UST) aplican tags (etiquetas) coherentes en todas las traces (trazas), métricas y logs, lo que facilita la navegación y la correlación de tus datos de observabilidad. Puedes configurar las UST mediante la extracción automática de etiquetas (recomendado), mediante la configuración explícita con ddTraceConfigs o en manifiestos de despliegue.

(Recomendado) Configurar las UST mediante la extracción automática de etiquetas

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

Nota: Este método no es compatible con la Configuración remota. Si utilizas la Configuración remota, consulta Configurar UST explícitamente con ddTraceConfigs.

Requisitos previos

Configuración

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

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 tag (etiqueta) service utilizando el valor de la etiqueta app.kubernetes.io/name para cualquier carga de trabajo instrumentada que incluya esta etiqueta.

Configurar UST explícitamente 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 para cargas de trabajo específicas, utiliza ddTraceConfigs para asignar 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

Configurar UST en manifiestos de despliegue

Si tu configuración no utiliza etiquetas adecuadas para la extracción de UST, puedes establecer 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 configuración de UST para servicios de Kubernetes .

Activar productos y funciones dependientes del kit de desarrollo de software (SDK)

Después de que SSI cargue el kit de desarrollo de software (SDK) de Datadog en tus aplicaciones y active el rastreo distribuido, puedes configurar productos adicionales que dependan del kit de desarrollo de software (SDK). Estos incluyen capacidades tales como Continuous Profiler, Monitorización de seguridad de las aplicaciones y controles de ingesta de traces (trazas).

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

• Configuración 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 step (UI) / paso (generic) en tu entorno. Estos ajustes son opcionales y normalmente solo se necesitan en configuraciones especializadas.

Cargas de trabajo específicas

Por defecto, 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"  ## 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

   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: # 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: # 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"

Cambiar el registro de imágenes 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 Datadog Agent del clúster especifica el registro utilizado por el controlador de admisión. El valor predeterminado 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 Cómo cambiar el registro de contenedores.

Utilizar un registro privado de contenedores

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 SSI con un registro privado de contenedores:

1. Sigue estas instrucciones para replicar las imágenes del 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 cases (incidencias) 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 las imágenes según tu configuración.

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

   • globalmente en la configuración del Agent con ddTraceVersions o
   • por cada pod mediante anotaciones como admission.datadoghq.com/java-lib.version.

   Si no se configuras explícitamente ninguna 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 tags (etiquetas) de imagen:

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

3. Actualiza la configuración del Agent del clúster para utilizar tu registro privado.

   Configure la variable de entorno DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY en tu configuración del Agent del clúster para utilizar tu registro privado.

Para obtener más detalles sobre cómo cambiar el registro de contenedores, consulta Cómo cambiar el registro de contenedores.

Uso de una interfaz de red de contenedores en EKS

Cuando se utiliza un CNI como Calico, los nodos del plano de control no pueden iniciar connections (conexiones) de red con el controlador de admisión de Datadog e informan de un error “Dirección no admitida”. Para utilizar la instrumentación de un solo step (UI) / paso (generic), modifica el Agent del clúster de Datadog con el parámetro useHostNetwork: true.

datadog:
  ...

clusterAgent:
  useHostNetwork: true

  admissionController:
    ...

Eliminación de la instrumentación de un solo step (UI) / paso (generic) de APM desde tu Agent

Si no deseas 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 de APM y dejar de enviar traces (trazas) desde un servicio específico, puedes realizar una de las siguientes acciones:

Utilizar la selección de la carga de trabajo (recomendado)

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

Utilizar el controlador de admisión de Datadog

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

1. Establece la etiqueta admission.datadoghq.com/enabled: en "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 SSI, todos los procesos compatibles del clúster se instrumentan automáticamente y comienzan a producir traces (trazas) en cuestión de minutos.

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

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"

Solucionar problemas

Si tienes problemas para activar APM con SSI, consulta la Guía de resolución de problemas de 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 los recursos del contenedor de inicializaciónDOCUMENTACIÓN Instrumenta tus aplicaciones mediante la inserción del kit de desarrollo de software (SDK) localDOCUMENTACIÓN