For an Ubuntu host:

1. Run the one-line installation command:

   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)"
   

   Replace <YOUR_DD_API_KEY> with your Datadog API key, <YOUR_DD_SITE> with your Datadog site, and <AGENT_ENV> with the environment your Agent is installed on (for example, staging).

   See Advanced options for more options.

2. Start a new shell session.

3. Restart the services on the host or VM.

For a Docker Linux container:

1. Run the one-line installation command:

   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)"
   

2. Configure the Agent in 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
   

   Replace <YOUR_DD_API_KEY> with your Datadog API key and <AGENT_ENV> with the environment your Agent is installed on (for example, staging).
   See Advanced options for more options.
3. Restart the Docker containers.
4. Explore the performance observability of your services in Datadog.

You can enable APM by installing the Agent with either:

• Datadog Operator
• Datadog Helm chart

Requirements

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

DD_APM_INSTRUMENTATION_LIBRARIES - customizing APM libraries

By default, Java, Python, Ruby, Node.js, PHP and .NET Core Datadog APM libraries are installed when DD_APM_INSTRUMENTATION_ENABLED is set. DD_APM_INSTRUMENTATION_LIBRARIES is used to override which libraries are installed. The value is a comma-separated string of colon-separated library name and version pairs.

Example values for DD_APM_INSTRUMENTATION_LIBRARIES:

• DD_APM_INSTRUMENTATION_LIBRARIES="java:1" - install only the Java Datadog APM library pinned to the major version 1 release line.
• DD_APM_INSTRUMENTATION_LIBRARIES="java:1,python:2" - install only the Java and Python Datadog APM libraries pinned to the major versions 1 and 2 respectively.
• DD_APM_INSTRUMENTATION_LIBRARIES="java:1.38.0,python:2.10.5" - install only the Java and Python Datadog APM libraries pinned to the specific versions 1.38.0 and 2.10.5 respectively.

Available versions are listed in source repositories for each language:

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

DD_APM_INSTRUMENTATION_LIBRARIES - customizing APM libraries

By default, Java, Python, Ruby, Node.js and .NET Core Datadog APM libraries are installed when DD_APM_INSTRUMENTATION_ENABLED is set. DD_APM_INSTRUMENTATION_LIBRARIES is used to override which libraries are installed. The value is a comma-separated string of colon-separated library name and version pairs.

Example values for DD_APM_INSTRUMENTATION_LIBRARIES:

• DD_APM_INSTRUMENTATION_LIBRARIES="java:1" - install only the Java Datadog APM library pinned to the major version 1 release line.
• DD_APM_INSTRUMENTATION_LIBRARIES="java:1,python:2" - install only the Java and Python Datadog APM libraries pinned to the major versions 1 and 2 respectively.
• DD_APM_INSTRUMENTATION_LIBRARIES="java:1.38.0,python:2.10.5" - install only the Java and Python Datadog APM libraries pinned to the specific versions 1.38.0 and 2.10.5 respectively.

Available versions are listed in source repositories for each language:

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

Configuring instrumentation for namespaces and pods

By default, Single Step Instrumentation instruments all services in all namespaces in your cluster. Alternatively, you can create targeting blocks with the targets label to specify which workloads to instrument and what configurations to apply.

Each target block has the following keys:

The file you need to configure depends on how you enabled Single Step Instrumentation:

• If you enabled SSI with Datadog Operator, edit datadog-agent.yaml.
• If you enabled SSI with Helm, edit datadog-values.yaml.

Example configurations

Review the following examples demonstrating how to select specific services:

   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_SERVICE"
              value: "login-service"
            - name: "DD_ENV"
              value: "prod"
            - 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"
          ddTraceConfigs:
            - name: "DD_SERVICE"
              value: "billing-service"
            - name: "DD_ENV"
              value: "prod

   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_SERVICE"
               value: "db-user"
             - name: "DD_ENV"
               value: "prod"
             - name: "DD_DSM_ENABLED"  
               value: "true"
         - name: "user-request-router"
           podSelector:
             matchLabels:
               webserver: "user"
           ddTraceVersions:
             php: "default"
           ddTraceConfigs:
             - name: "DD_SERVICE"
               value: "user-request-router"
             - name: "DD_ENV"
               value: "prod

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

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

Enabling or disabling instrumentation for namespaces

You can choose to enable or disable instrumentation for applications in specific namespaces. You can only set enabledNamespaces or disabledNamespaces, not both.

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

   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

Specifying tracing library versions

Specify Datadog tracing libraries and their versions to automatically instrument applications written in those languages. You can configure this in two ways, which are applied in the following order of precedence:

1. Specify at the service level, or
2. Specify at the cluster level.

Default: If you don’t specify any library versions and apm.instrumentation.enabled=true, applications written in supported languages are automatically instrumented using the latest tracing library versions.

Specifying at the service level

To automatically instrument applications in specific pods, add the appropriate language annotation and library version for your application in your pod spec:

Replace <CONTAINER IMAGE TAG> with the desired library version. Available versions are listed in the Datadog container registries and tracer source repositories for each language:

• Java
• Node.js
• Python
• .NET
• Ruby
• PHP

For example, to automatically instrument Java applications:

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

Specifying at the cluster level

If you don’t enable automatic instrumentation for specific pods using annotations, you can specify which languages to instrument across the entire cluster using the Single Step Instrumentation configuration. When apm.instrumentation.libVersions is set, only applications written in the specified languages will be instrumented, using the specified library versions.

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

   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"

   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"

Container registries

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.

1. Add the DD_INSTRUMENT_SERVICE_WITH_APM environment variable to the service startup command:

   DD_INSTRUMENT_SERVICE_WITH_APM=false <service_start_command>
   

2. Restart the service.

1. Add the DD_INSTRUMENT_SERVICE_WITH_APM environment variable to the service startup command:

   docker run -e DD_INSTRUMENT_SERVICE_WITH_APM=false <service_start_command>
   

2. Restart the service.

Using workload selection (recommended)

With workload selection, you can enable and disable tracing for specific applications. See configuration details here.

Using 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.

1. Run:

   dd-host-install --uninstall
   

2. Restart the services on the host or VM.

1. Run:

   dd-container-install --uninstall
   

2. Restart Docker:

   systemctl restart docker
   

   Or use the equivalent for your environment.

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