Overview

In a Kubernetes environment, use Single Step Instrumentation (SSI) for APM to install the Datadog Agent and instrument your applications with the Datadog APM SDKs in one step.

Requirements

• Kubernetes v1.20+
• Helm for deploying the Datadog Operator.
• Kubectl CLI for installing the Datadog Agent.

Enable APM on your applications

Follow these steps to enable Single Step Instrumentation across your entire cluster. This automatically sends traces from all applications written in supported languages.

Note: To instrument only specific namespaces or pods, see workload targeting in Advanced options.

1. In Datadog, go to the Install the Datadog Agent on Kubernetes page.

2. Follow the on-screen instructions to choose your installation method, select an API key, and set up the Operator or Helm repository.

3. In the Configure datadog-agent.yaml section, go to Additional configuration > Application Observability, and turn on APM Instrumentation.

4. Deploy the Agent using the generated configuration file.

5. Restart your applications.

Configure Unified Service Tags

Unified Service Tags (USTs) apply consistent tags across traces, metrics, and logs, making it easier to navigate and correlate your observability data.

Recommended: Configure USTs with ddTraceConfigs as part of workload targeting.

With SSI, you can automatically extract UST values from pod labels and metadata without modifying individual deployments: To use the recommended ddTraceConfigs approach, ensure you have the following software components:

Note: Replace app-name with any label that contains your service name (e.g., service, app, component). You can configure multiple labels this way.

datadog:
  # Make pod labels available as tags in Datadog
  kubernetesResourcesLabelsAsTags:
    pods:
      app-name: service
    deployments.apps:
      app-name: service
    replicasets.apps:
      app-name: service

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

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: my-services
          podSelector:
            matchExpressions:
            - key: app-name           # Target pods with this label
              operator: Exists
          ddTraceConfigs:
            - name: DD_SERVICE      # Extract service name from pod label
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['app-name']
            # DD_VERSION automatically extracted from image tags
            # DD_ENV inherited from cluster-level tags above

Configure USTs in deployment manifests

If your setup doesn’t use labels suitable for UST extraction, you can set USTs directly in your deployment manifests using environment variables. This approach requires modifying each deployment individually, but offers precise control.

For complete instructions, see setting USTs for Kubernetes services.

Enable SDK-dependent products and features

After SSI loads the Datadog SDK into your applications and enables distributed tracing, you can configure additional products that rely on the SDK. These include capabilities such as Continuous Profiler, Application Security Monitoring, and trace ingestion controls.

Use one of the following setup methods:

• Configure with workload targeting (recommended):

  By default, Single Step Instrumentation instruments all services in all namespaces. Use workload targeting to limit instrumentation to specific namespaces, pods, or workloads, and apply custom configurations.

• Set environment variables:

  Enable products by setting environment variables directly in your application configuration.

Advanced options

Use the following advanced options to customize how Single Step Instrumentation behaves in your environment. These settings are optional and typically only needed in specialized setups.

Target specific workloads

By default, SSI instruments all services in all namespaces in your cluster. Depending on your Agent version, use one of the following configuration methods to refine which services are instrumented and how.

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

Change the default image registry

Datadog publishes instrumentation libraries images on gcr.io, Docker Hub, and Amazon ECR:

The DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY environment variable in the Datadog Cluster Agent configuration specifies the registry used by the Admission Controller. The default value is gcr.io/datadoghq.

You can pull the tracing library from a different registry by changing it to docker.io/datadog, public.ecr.aws/datadog, or another URL if you are hosting the images in a local container registry.

For instructions on changing your container registry, see Changing Your Container Registry.

Use a private container registry

If your organization does not allow direct pulls from public registries (such as gcr.io, docker.io, or public.ecr.aws), you can host the required Datadog images internally and configure the Admission Controller to use them.

To use SSI with a private container registry:

1. Follow these instructions to mirror Datadog’s container images to your private registry.

   You only need the images for the languages you are instrumenting. If you’re not sure which ones you need, here’s a baseline that covers most use cases:

   • 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

   You can find these images on gcr.io, Docker Hub, or Amazon ECR Public Gallery.

2. Tag the images according to your configuration.

   The versions you mirror must match the versions configured in your workloads, which might be set in one of the following ways:

   • globally in the Agent config using ddTraceVersions, or
   • per-pod using annotations like admission.datadoghq.com/java-lib.version.

   If no version is explicitly configured, the default version (0) is used.

   For example:

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

   This configuration requires the following image tags:

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

3. Update the Cluster Agent configuration to use your private registry.

   Set the DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY environment variable in your Cluster Agent config to use your private registry.

For more details on changing your container registry, see Changing Your Container Registry.

Remove Single Step APM instrumentation from your Agent

If you don’t want to collect trace data for a particular service, host, VM, or container, complete the following steps:

Remove instrumentation for specific services

To remove APM instrumentation and stop sending traces from a specific service, you can do one of the following:

Use workload selection (recommended)

With workload selection (available for Agent v7.64+), you can enable and disable tracing for specific applications. See configuration details here.

Use the Datadog Admission Controller

As an alternative, or for a version of the agent that does not support workload selection, you can also disable pod mutation by adding a label to your pod.

1. Set the admission.datadoghq.com/enabled: label to "false" for the pod spec:

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

2. Apply the configuration:

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

3. Restart the services you want to remove instrumentation for.

Remove APM for all services on the infrastructure

To stop producing traces, uninstall APM and restart the infrastructure:

The file you need to configure depends on if you enabled Single Step Instrumentation with Datadog Operator or Helm:

Best practices

After you enable SSI, all supported processes in the cluster are automatically instrumented and begin producing traces within minutes.

To control where APM is activated and reduce overhead, consider the following best practices.

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"

Troubleshooting

If you encounter problems enabling APM with SSI, see the SSI troubleshooting guide.

Further reading

추가 유용한 문서, 링크 및 기사:

Enable Runtime MetricsDOCUMENTATION Learn about init container resource usageDOCUMENTATION Instrument your applications using local SDK injectionDOCUMENTATION