Single Step APM Instrumentation

Docs > APM > Application Instrumentation > Automatic Instrumentation > Single Step APM Instrumentation

Overview

Single Step Instrumentation (SSI) for APM installs the Datadog Agent and instruments your applications in one step, with no additional configuration steps required.

Compatibility

To see requirements for compatible languages, operating systems, and architectures, see Single Step Instrumentation compatibility.

Enabling APM on your applications

If you install or update a Datadog Agent with the Enable APM Instrumentation option selected, the Agent is installed and configured to enable APM. This automatically instruments your application, without any additional installation or configuration steps.

The following examples show how it works for each deployment type.

If you've previously used Single Step Instrumentation with Linux hosts, update to the latest version.

For an Ubuntu host:

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,ruby:2 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.

Start a new shell session.
Restart the services on the host or VM.

For a Docker Linux container:

Run the one-line installation command:

DD_APM_INSTRUMENTATION_ENABLED=docker DD_NO_AGENT_INSTALL=true bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

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.

Restart the Docker containers.
Explore the performance observability of your services in Datadog.

You can enable APM by installing the Agent with either:

Datadog Operator
Datadog Helm chart

Single Step Instrumentation doesn't instrument applications in the namespace where you install the Datadog Agent. It's recommended to install the Agent in a separate namespace in your cluster where you don't run your applications.

Requirements

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

Installing with Datadog Operator

Follow these steps to enable Single Step Instrumentation across your entire cluster with the Datadog Operator. This automatically sends traces for all applications in the cluster that are written in supported languages.

To enable Single Step Instrumentation with the Datadog Operator:

Install the Datadog Operator v1.5.0+ with Helm:

helm repo add datadog https://helm.datadoghq.com
helm repo update
helm install my-datadog-operator datadog/datadog-operator

Create a Kubernetes secret to store your Datadog API key:

kubectl create secret generic datadog-secret --from-literal api-key=$DD_API_KEY

Create datadog-agent.yaml with the spec of your Datadog Agent deployment configuration. The simplest configuration is as follows:

apiVersion: datadoghq.com/v2alpha1
kind: DatadogAgent
metadata:
  name: datadog
spec:
  global:
    site: <DATADOG_SITE>
    tags:
      - env:<AGENT_ENV>
    credentials:
      apiSecret:
        secretName: datadog-secret
        keyName: api-key
  features:
    apm:
      instrumentation:
        enabled: true
        libVersions:
          java: "1"
          dotnet: "3"
          python: "2"
          js: "5"
          ruby: "2"

Replace <DATADOG_SITE> with your Datadog site and <AGENT_ENV> with the environment your Agent is installed on (for example, env:staging).

See Advanced options for more options.

Run the following command:

kubectl apply -f /path/to/your/datadog-agent.yaml

After waiting a few minutes for the Datadog Cluster Agent changes to apply, restart your applications.

Installing with Helm

Follow these steps to enable Single Step Instrumentation across your entire cluster with Helm. This automatically sends traces for all applications in the cluster that are written in supported languages.

To enable Single Step Instrumentation with Helm:

Add the Helm Datadog repo:

 helm repo add datadog https://helm.datadoghq.com
 helm repo update

Create a Kubernetes secret to store your Datadog API key:

kubectl create secret generic datadog-secret --from-literal api-key=$DD_API_KEY

Create datadog-values.yaml and add the following configuration:

datadog:
 apiKeyExistingSecret: datadog-secret
 site: <DATADOG_SITE>
 tags:
      - env:<AGENT_ENV>
 apm:
   instrumentation:
      enabled: true
      libVersions:
         java: "1"
         dotnet: "3"
         python: "2"
         js: "5"
         ruby: "2"

Replace <DATADOG_SITE> with your Datadog site and <AGENT_ENV> with the environment your Agent is installed on (for example, env:staging).

See Advanced options for more options.

Run the following command:

helm install datadog-agent -f datadog-values.yaml datadog/datadog

After waiting a few minutes for the Datadog Cluster Agent changes to apply, restart your applications.

After you complete these steps, you may want to enable runtime metrics or view observability data from your application in the Service Catalog.

Advanced options

When you run the one-line installation command, there are a few options to customize your experience:

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

`DD_APM_INSTRUMENTATION_LIBRARIES` - customizing APM libraries

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)

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:

Datadog Operator

To enable instrumentation for specific namespaces, add enabledNamespaces configuration to datadog-agent.yaml:

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

To disable instrumentation for specific namespaces, add disabledNamespaces configuration to datadog-agent.yaml:

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

Helm

To enable instrumentation for specific namespaces, add enabledNamespaces configuration to datadog-values.yaml:

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

To disable instrumentation for specific namespaces, add disabledNamespaces configuration to datadog-values.yaml:

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

Specifying tracing library versions

Starting with Datadog Cluster Agent v7.52.0+, you can automatically instrument a subset of your applications, based on the tracing libraries you specify.

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:

Specify at the service level, or
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:

Language	Pod annotation
Java	`admission.datadoghq.com/java-lib.version: "<CONTAINER IMAGE TAG>"`
Node.js	`admission.datadoghq.com/js-lib.version: "<CONTAINER IMAGE TAG>"`
Python	`admission.datadoghq.com/python-lib.version: "<CONTAINER IMAGE TAG>"`
.NET	`admission.datadoghq.com/dotnet-lib.version: "<CONTAINER IMAGE TAG>"`
Ruby	`admission.datadoghq.com/ruby-lib.version: "<CONTAINER IMAGE TAG>"`

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 (For .NET applications using a musl-based Linux distribution like Alpine, specify a tag with the -musl suffix, such as v2.29.0-musl.)
Ruby

Exercise caution when using the latest tag, as major library releases may introduce breaking changes.

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:

Datadog Operator

For example, to instrument .NET, Python, and Node.js applications, add the following configuration to your datadog-agent.yaml file:

   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"

Helm

For example, to instrument .NET, Python, and Node.js applications, add the following configuration to your datadog-values.yaml file:

   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:

Language	gcr.io	hub.docker.com	gallery.ecr.aws
Java	gcr.io/datadoghq/dd-lib-java-init	hub.docker.com/r/datadog/dd-lib-java-init	gallery.ecr.aws/datadog/dd-lib-java-init
Node.js	gcr.io/datadoghq/dd-lib-js-init	hub.docker.com/r/datadog/dd-lib-js-init	gallery.ecr.aws/datadog/dd-lib-js-init
Python	gcr.io/datadoghq/dd-lib-python-init	hub.docker.com/r/datadog/dd-lib-python-init	gallery.ecr.aws/datadog/dd-lib-python-init
.NET	gcr.io/datadoghq/dd-lib-dotnet-init	hub.docker.com/r/datadog/dd-lib-dotnet-init	gallery.ecr.aws/datadog/dd-lib-dotnet-init
Ruby	gcr.io/datadoghq/dd-lib-ruby-init	hub.docker.com/r/datadog/dd-lib-ruby-init	gallery.ecr.aws/datadog/dd-lib-ruby-init

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.

Removing 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:

Removing instrumentation for specific services

To remove APM instrumentation and stop sending traces from a specific service, follow these steps:

Add the DD_INSTRUMENT_SERVICE_WITH_APM environment variable to the service startup command:
```
DD_INSTRUMENT_SERVICE_WITH_APM=false <service_start_command>
```
Restart the service.

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>
```
Restart the service.

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

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

Apply the configuration:

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

Restart the services you want to remove instrumentation for.

Removing APM for all services on the infrastructure

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

Run:
```
dd-host-install --uninstall
```
Restart the services on the host or VM.

Run:
```
dd-container-install --uninstall
```
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:

Datadog Operator

Set instrumentation.enabled=false in datadog-agent.yaml:

features:
  apm:
    instrumentation:
      enabled: false

Deploy the Datadog Agent with the updated configuration file:
```
kubectl apply -f /path/to/your/datadog-agent.yaml
```

Helm

Set instrumentation.enabled=false in datadog-values.yaml:

datadog:
  apm:
    instrumentation:
      enabled: false

Run the following command:

helm upgrade datadog-agent -f datadog-values.yaml datadog/datadog

Troubleshooting

Single Step Instrumentation is not taking effect

Single Step Instrumentation automatically disables when it detects custom instrumentation in your application. If you want to use SSI, you’ll need to: