--- title: Single Step APM Instrumentation on Linux description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > APM > Application Instrumentation > Single Step APM Instrumentation > Single Step APM Instrumentation on Linux --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Single Step APM Instrumentation on Linux ## Overview{% #overview %} On a Linux host or VM, use Single Step Instrumentation (SSI) for APM to install the Datadog Agent and [instrument](https://docs.datadoghq.com/tracing/glossary.md#instrumentation) your applications in one step, with no additional configuration required. Install the `dd-apm` skill in your AI coding agent for guided APM setup. Run this command: ```shell npx skills add https://github.com/datadog-labs/agent-skills --skill dd-apm --full-depth -y ``` ## Enable APM on your applications{% #enable-apm-on-your-applications %} {% alert level="info" %} Before proceeding, confirm that your environment is compatible by reviewing the [SSI compatibility guide.](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md) {% /alert %} ### New Agent installation{% #new-agent-installation %} If you don't yet have a Datadog Agent installed, install the Agent and enable SSI in one step. 1. Run the following command on your Linux host or VM: ```shell DD_API_KEY= \ DD_SITE="" \ DD_APM_INSTRUMENTATION_ENABLED=host \ bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)" ``` Replace `` with your [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys). The command installs or updates the Agent and the SSI packages. By default, SSI installs the latest SDK versions. To pin specific versions, add the `DD_APM_INSTRUMENTATION_LIBRARIES` variable with comma-separated `language:major` pairs. Available versions are listed in the source repositories for each language: [Java](https://github.com/DataDog/dd-trace-java/releases) (`java`), [Node.js](https://github.com/DataDog/dd-trace-js/releases) (`js`), [Python](https://github.com/DataDog/dd-trace-py/releases) (`python`), [.NET](https://github.com/DataDog/dd-trace-dotnet/releases) (`dotnet`), [Ruby](https://github.com/DataDog/dd-trace-rb/releases) (`ruby`), [PHP](https://github.com/DataDog/dd-trace-php/releases) (`php`). 1. Restart your applications. {% alert level="info" %} SSI adds a small amount of startup time to instrumented applications. If this overhead is not acceptable for your use case, contact [Datadog Support](https://docs.datadoghq.com/help/). {% /alert %} #### Generate the command from Datadog{% #generate-the-command-from-datadog %} To get a command pre-filled with your API key and site, go to the [Install the Datadog Agent on Linux](https://app.datadoghq.com/fleet/install-agent/latest?platform=linux) page and turn on Application Performance Monitoring under Core Observability. {% image source="https://docs.dd-static.net/images/tracing/trace_collection/enable_apm.cad28cf3327209d96016469b36115ff3.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/enable_apm.cad28cf3327209d96016469b36115ff3.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The 'Customize your Agent coverage' section of in-app instructions for installing the Datadog Agent on Linux" /%} {% callout %} # Important note for users on the following Datadog sites: app.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com To select SDK versions from dropdowns, click Customize Library Versions. {% image source="https://docs.dd-static.net/images/tracing/trace_collection/customize_library_versions.de76e4cbbf1683594fe7ea0c01498176.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/customize_library_versions.de76e4cbbf1683594fe7ea0c01498176.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The 'Customize library versions' dropdown in the instructions for installing the Datadog Agent on Linux" /%} {% /callout %} Then copy and run the generated command. ### Existing Agent installation{% #existing-agent-installation %} If you already have a Datadog Agent installed, re-run the Agent installation command from New Agent installation on the host. The command updates the existing Agent and enables SSI. Alternatively, use Fleet Automation to enable SSI from Datadog: 1. In Datadog, go to [**Fleet Automation > Configuration**](https://app.datadoghq.com/fleet/agent-management). 1. Click Configure Agents. 1. Apply filters to select the agents you want to configure, then click **Next**. {% image source="https://docs.dd-static.net/images/tracing/trace_collection/filter-agents.7b3bb1ea5af768de16afd2e3089d7b0c.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/filter-agents.7b3bb1ea5af768de16afd2e3089d7b0c.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The agent filtering screen in Fleet Automation, with options to scope by environment, operating system, and hostname" /%} 1. Click the Application Performance Monitoring (APM) tile, then click Next. {% image source="https://docs.dd-static.net/images/tracing/trace_collection/select-products-core-obs.c1bd26a0d16cbbdfc0814f5f3a958a87.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/select-products-core-obs.c1bd26a0d16cbbdfc0814f5f3a958a87.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The product selection screen in Fleet Automation, showing the Application Performance Monitoring (APM) tile" /%} 1. In the Configure SDKs Installation screen, click Yes to automatically install the SDKs. Select Use latest version, or uncheck to specify individual SDK versions. {% image source="https://docs.dd-static.net/images/tracing/trace_collection/configure-sdks-installation.3710936d8ac9f5deadf749496e2f3a68.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/configure-sdks-installation.3710936d8ac9f5deadf749496e2f3a68.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The Configure SDKs Installation screen in Fleet Automation, with options to enable automatic SDK installation and select versions" /%} 1. Click **Next**. 1. Review your configuration and click Deploy Configuration. ## Verify the installation{% #verify-the-installation %} 1. Confirm the Agent is running: ```shell sudo datadog-agent status ``` 1. Confirm that SSI injection is armed on the host: ```shell cat /etc/ld.so.preload && ls /opt/datadog-packages/ | grep apm ``` The output lists the APM injector library in `/etc/ld.so.preload` and one or more `datadog-apm-*` packages. 1. After your applications receive traffic, confirm your services appear on the [APM Services page](https://app.datadoghq.com/apm/services). If they don't appear within a few minutes, follow the [SSI troubleshooting guide](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm/troubleshooting.md). ## Configure Unified Service Tags{% #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. Learn how to [set USTs for Linux services](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging.md?tab=kubernetes#non-containerized-environment). ## Enable SDK-dependent products and features{% #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: | Product | Environment variable | | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | [Runtime Metrics](https://docs.datadoghq.com/tracing/metrics/runtime_metrics.md) | `DD_RUNTIME_METRICS_ENABLED` | | [Log Injection](https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces.md) | `DD_LOGS_INJECTION` | | [Continuous Profiler](https://docs.datadoghq.com/profiler.md) | `DD_PROFILING_ENABLED` | | [Data Streams Monitoring](https://docs.datadoghq.com/data_streams.md) | `DD_DATA_STREAMS_ENABLED` | | [App and API Protection](https://docs.datadoghq.com/security/application_security.md) | `DD_APPSEC_ENABLED` | | [Runtime Code Analysis (IAST)](https://docs.datadoghq.com/security/code_security/iast.md) | `DD_IAST_ENABLED` | | [Dynamic Instrumentation](https://docs.datadoghq.com/tracing/trace_collection/dynamic_instrumentation.md) | `DD_DYNAMIC_INSTRUMENTATION_ENABLED` | | [Data Jobs Monitoring](https://docs.datadoghq.com/data_jobs.md) | `DD_DATA_JOBS_ENABLED` | | [Software Composition Analysis](https://docs.datadoghq.com/security/code_security/software_composition_analysis.md) | `DD_APPSEC_SCA_ENABLED` | **Note**: All variables accept `true` or `false`. `DD_PROFILING_ENABLED` also accepts `auto`, which profiles only eligible processes and is recommended for SSI. Use one of the following setup methods: - **[Configure in `application_monitoring.yaml`](https://docs.datadoghq.com/tracing/trace_collection/library_config/application_monitoring_yaml.md)**: Configure products and features across all services on a host without modifying application command lines. - **[Set environment variables](https://docs.datadoghq.com/tracing/trace_collection/library_config.md)**: Enable products by setting environment variables directly in your application configuration. ## Advanced options{% #advanced-options %} ### Update SDK version{% #update-sdk-version %} The SDK version is fixed when you run the Agent installation command. To update the SDK versions: 1. Re-run the Agent installation command. This command also updates the Agent to the latest version. 1. Restart your applications. ### Define instrumentation rules{% #define-instrumentation-rules %} {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com {% alert level="warning" %} Instrumentation rules are not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md) ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} Instrumentation rules (available for Agent v7.73+) let you control which processes are automatically instrumented by SSI on Linux hosts. To configure instrumentation rules: 1. In Datadog, go to APM > Service Setup > [Manage Instrumentation Rules](https://app.datadoghq.com/apm/service-setup/workload-selection). 1. Click Add or Edit Rules. 1. Define instrumentation rules: 1. Click Add New Rule, then choose Allow Rule or Block Rule to specify whether matching processes should be instrumented. 1. Name your rule. 1. Add one or more conditions. See Define rule conditions to learn more. {% image source="https://docs.dd-static.net/images/tracing/trace_collection/define_instrumentation_rule.3676784434032a84eb248a75a996342a.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/define_instrumentation_rule.3676784434032a84eb248a75a996342a.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The instrumentation rules UI, showing configuration options for defining a rule" /%} 1. (Optional) Drag and drop rules to reorder them. **Note**: Rules are evaluated in order. After a process matches a rule, subsequent rules are ignored. 1. Set the default behavior (allow or block) for processes that do not match any rule. 1. Click Next to preview your rules. 1. Click Deploy Rules. If Remote Configuration is enabled, rules are deployed to every host and applied on those with SSI enabled within 50 seconds. Alternatively, click Export to export the configuration file and apply it manually to your hosts. #### Define rule conditions{% #define-rule-conditions %} Each rule consists of one or more conditions. A condition includes the following elements: - Attribute: The process property that the rule evaluates. - Operator: The comparison logic (`equals`, `not equals`, `prefix`, or `contains`). - Value: The text or pattern to match, such as a process name or command-line flag. Supported attributes include: | Attribute | Description | Example | | -------------------- | ------------------------------------------------- | --------------------- | | Operating System | OS of the host. | `linux` | | Executable | Executable name of the process. | `python3.11` | | Executable Full Path | Full path of the executable. | `/usr/bin/python3.11` | | Arguments | Command-line arguments used to start the process. | `--env=production` | | Working Directory | Working directory of the process. | `/app` | | Language | Programming language detected for the process. | `python` | | Entry Point File | The specific file used to launch the application. | `app.py`, `server.js` | #### Example use cases{% #example-use-cases %} Review the following examples demonstrating how to apply instrumentation rules: {% collapsible-section %} ##### Example 1: Instrument all processes except specific ones Instrument all processes by default. Add block rules to exclude services that would add noise without value, such as analytics cron jobs and Java batch processors. {% image source="https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-example-1.7ece2768c405f33dc7f2aaa819dcedab.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-example-1.7ece2768c405f33dc7f2aaa819dcedab.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Two block instrumentation rules targeting Working Directory and Entry Point File conditions, with a default of allow instrumentation" /%} {% /collapsible-section %} {% collapsible-section %} ##### Example 2: Instrument only specific processes Block all instrumentation by default. Add allow rules to opt specific processes into APM. This approach gives you precise control and works well for gradual rollouts. For example, to instrument only a checkout service and a customer portal, create allow rules using Working Directory, then set the default behavior to Block Instrumentation. {% image source="https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-linux-example-2.cdb6cc2bf1616c960a303df30fed0266.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/instrumentation-rules-linux-example-2.cdb6cc2bf1616c960a303df30fed0266.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Two allow instrumentation rules targeting services in specific working directories, with a default of block instrumentation" /%} {% /collapsible-section %} ## Remove Single Step APM instrumentation from your Agent{% #remove-single-step-apm-instrumentation-from-your-agent %} To stop producing traces for all services on your infrastructure: 1. Run: ```shell dd-host-install --uninstall ``` 1. Restart the services on the host or VM. ## Troubleshooting{% #troubleshooting %} If you encounter problems enabling APM with SSI, see the [SSI troubleshooting guide](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm/troubleshooting.md). ## Further reading{% #further-reading %} Additional helpful documentation, links, and articles: - [Enable Runtime Metrics](https://docs.datadoghq.com/tracing/metrics/runtime_metrics.md) - [Manage service tracing across hosts with Single Step Instrumentation rules](https://www.datadoghq.com/blog/single-step-instrumentation-rules/)