Single Step APM Instrumentation (Beta)
Requirements
Single step APM instrumentation only supports tracing Java, Python, Ruby, Node.js, and .NET Core services on x86_64
architectures.
Enable APM on your services in one step
If you install or update a Datadog Agent with the Enable APM Instrumentation (beta) option selected, the Agent is installed and configured to enable APM. This allows you to automatically instrument your application, without any additional installation or configuration steps. Restart services for this instrumentation to take effect.
The following examples show how it works on each infrastructure type.
In one command, you can install, configure, and start the Agent with APM and Remote Configuration enabled, and set up automatic instrumentation of your services.
For an Ubuntu host:
Run the one-line install command:
DD_API_KEY=<YOUR_DD_API_KEY> DD_SITE="<YOUR_DD_SITE>" DD_APM_INSTRUMENTATION_ENABLED=host bash -c "$(curl -L https://s3.amazonaws.com/dd-agent/scripts/install_script_agent7.sh)"
Replace <YOUR_DD_API_KEY>
with your Datadog API.
Replace <YOUR_DD_SITE>
with your Datadog site.
Restart the services on the host or VM.
Explore the performance observability of your services in Datadog.
For a Docker Linux container:
Install the library injector:
bash -c "$(curl -L https://s3.amazonaws.com/dd-agent/scripts/install_script_docker_injection.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_APM_NON_LOCAL_TRAFFIC=true \
-e DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true \
-e DD_APM_RECEIVER_SOCKET=/opt/datadog/apm/inject/run/apm.socket \
-e DD_DOGSTATSD_SOCKET=/opt/datadog/apm/inject/run/dsd.socket \
-v /opt/datadog/apm:/opt/datadog/apm \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
gcr.io/datadoghq/agent:7
Replace <YOUR_DD_API_KEY>
with your Datadog API.
Restart the Docker containers.
Explore the performance observability of your services in Datadog.
You can enable APM by installing the Agent with the Datadog Helm chart. This deploys the Datadog Agent across all nodes in your Linux-based Kubernetes cluster with a DaemonSet.
Requirements
- Make sure you have Helm installed.
Installation
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>
apm:
instrumentation:
enabled: true
Replace <DATADOG_SITE>
with your Datadog site.
Here you can also optionally configure the following:
Run the following command:
helm install datadog-agent -f datadog-values.yaml
Enabling or disabling instrumentation for namespaces
You can choose to selectively instrument specific namespaces or choose to not instrument them.
To enable instrumentation for specific namespaces, replace enabled: true
with enabledNamespaces
configuration in your datadog-values.yaml
file:
datadog:
apiKeyExistingSecret: datadog-secret
site: <DATADOG_SITE>
apm:
instrumentation:
enabledNamespaces: # Add namespaces to instrument
- namespace_1
- namespace_2
The enabled: true
option enables instrumentation for the entire cluster. You need to remove this to only enable instrumentation for specific namespaces.
To disable instrumentation for specific namespaces, add the disabledNamespaces
configuration to your datadog-values.yaml
file:
datadog:
apiKeyExistingSecret: datadog-secret
site: <DATADOG_SITE>
apm:
instrumentation:
enabled: true
disabledNamespaces: # Add namespaces to not instrument
- namespace_1
- namespace_2
Specifying tracing library versions
You can optionally set specific tracing library versions to use. If you don’t specify a version, it defaults to the latest version. To find the latest version for a library, go to Releases in the dd-trace-<language> GitHub repo. For example, dd-trace-dotnet releases.
To set specific tracing library versions, add the following configuration to your datadog-values.yaml
file:
datadog:
apiKeyExistingSecret: datadog-secret
site: <DATADOG_SITE>
apm:
instrumentation:
enabled: true
libVersions: # Add any versions you want to set
dotnet: v2.40.0
python: v1.20.6
java: v1.22.0
js: v4.17.0
ruby: v1.15.0
Supported languages include .Net (dotnet
), Python (python
), Java (java
), Javascript (js
), and Ruby (ruby
).
Tagging observability data by environment
Set DD_ENV
in your one-line install command for Linux and the library injector installation command for Docker to automatically tag instrumented services and other telemetry that pass through the Agent with a specific environment. For example, if the Agent is installed in your staging environment, set DD_ENV=staging
to associate your observability data with staging
.
For Kubernetes, you can add this to your configuration file:
Add a - env:<env-name>
tag to datadog-values.yaml
:
datadog:
tags:
- env:staging
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 follow steps:
Removing instrumentation for specific services
Run the following commands and restart the service to stop injecting the library into the service and stop producing traces from that service.
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, remove library injectors and restart the infrastructure:
- Run:
dd-host-install --uninstall
- Restart your host.
- Uninstall local library injection:
dd-container-install --uninstall
- Restart Docker:Or use the equivalent for your environment.
- Under
apm:
, remove instrumentation:
and all following configuration in datadog-values.yaml
. - Run the following command:
helm upgrade datadog-agent -f datadog-values.yaml datadog/datadog
- Restart your services.