From 4aa6b9c75519875cf40da5331c1c6b84507a0b8a Mon Sep 17 00:00:00 2001 From: Syed Sarjeel Yusuf Date: Sun, 16 Nov 2025 16:55:21 +0100 Subject: [PATCH 1/9] Restructure SSI compatibility documentation for clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add tab-based platform selection (Linux Host, Docker, Kubernetes, Windows IIS) - Consolidate tracer and language requirements into single section with language tabs - Update OS versions to exact tested distros (no open-ended ranges) - Move Linux distributions table to reference section at end - Replace 'tracer' terminology with 'SDK' throughout - Replace 'injecting' with 'loading' for friendlier language - Improve information hierarchy: Platform → OS → Runtime - Add consistent structure to each language tab (SDK version, runtime versions, limitations) - Clarify SDK version vs runtime version relationship --- .../single-step-apm/compatibility.md | 272 ++++++++++++------ 1 file changed, 178 insertions(+), 94 deletions(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md index d56ff060331..552859d4230 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md @@ -10,192 +10,276 @@ further_reading: Single Step Instrumentation (SSI) has specific compatibility requirements that vary by language and environment. This page outlines supported versions, known limitations, and conditions that may impact Single Step Instrumentation for your specific setup. -## Operating systems +## Where are your applications running? -The following operating systems and architectures are compatible: +Select your deployment platform to see compatibility requirements and limitations: -| OS | Version | Architecture | -|--------------|-----------|---------------| -| Amazon Linux | 2022+ | x86_64, arm64 | -| CentOS | 7+, 8+ | x86_64, arm64 | -| Debian | 10-12 | x86_64, arm64 | -| Red Hat | 7+ | x86_64, arm64 | -| Ubuntu | 20+ (LTS) | x86_64, arm64 | -| Fedora | 40 | x86_64, arm64 | -| AlmaLinux | 8+ | x86_64, arm64 | -| Oracle Linux | 8+ | x86_64, arm64 | -| Rocky Linux | 8+ | x86_64, arm64 | +{{< tabs >}} +{{% tab "Linux Host" %}} -
For additional operating system requirements specific to your programming language, see Language specific requirements.
+### Compatibility -## Deployment environments +**Status**: GA -The following environments are compatible: +**Supported operating systems**: See [Linux distributions reference](#linux-distributions-reference) -| Environment | Requirements & Limitations | Support | -|-----------------|---------------------------------------------------------|---------| -| Linux | Not supported on hardened environments such as SELinux. | GA | -| Docker on Linux | | GA | -| Kubernetes | Requires [Datadog Admission Controller][1] to be enabled.
Only supports Linux nodepools | GA | -| Windows IIS | Requires Agent v7.67.1+ and Tracer v3.19.0+.
Only .NET applications running in IIS are supported. | GA | +**Supported architectures**: x86_64, arm64 +### Requirements -### Environment-specific requirements +- Datadog Agent installed with APM Instrumentation enabled +- One of the [supported Linux distributions](#linux-distributions-reference) -#### Linux virtual machines (VMs) +### Limitations + +- **SELinux**: Not supported on hardened environments such as SELinux +- **Small VM instances**: You may encounter timeouts with smaller VM instances such as `t2.micro`. Upgrade to a larger instance such as `t2.small` or higher + +{{% /tab %}} + +{{% tab "Docker" %}} + +### Compatibility + +**Status**: GA + +**Supported operating systems**: See [Linux distributions reference](#linux-distributions-reference) + +**Supported architectures**: x86_64, arm64 + +### Requirements -You may encounter timeouts with smaller VM instances such as `t2.micro`. In this case, you should upgrade to a larger instance such as `t2.small`. +- Datadog Agent installed with APM Instrumentation enabled +- Docker running on one of the [supported Linux distributions](#linux-distributions-reference) -#### Docker containers +### Limitations -- **Rootless Docker mode**: If you are using Docker in rootless mode (that is, Docker running without root privileges for added security), you need to configure the socket path to ensure SSI can connect to Docker. Update the socket path in `/etc/datadog-agent/inject/docker_config.yaml` to match your environment. By default, this path is set to `/run/user/$UID/docker.sock`, but it may vary based on your setup. +- **Rootless Docker mode**: If you are using Docker in rootless mode (Docker running without root privileges for added security), you need to configure the socket path to ensure SSI can connect to Docker. Update the socket path in `/etc/datadog-agent/inject/docker_config.yaml` to match your environment. By default, this path is set to `/run/user/$UID/docker.sock`, but it may vary based on your setup. - **Custom `runc` shims**: If your environment uses custom `runc` shims (for GPU support or other specialized tasks), you must adjust your configuration to avoid conflicts. SSI requires its own `runc` shim to enable automatic instrumentation within Docker containers. To ensure compatibility, update the `runtimes` property in `/etc/datadog-agent/inject/docker_config.yaml` to include both your custom shim and the Datadog shim. -#### Kubernetes with Windows pods +{{% /tab %}} -For Kubernetes clusters with Windows pods, use namespace inclusion/exclusion or specify an annotation in the application to exclude them from library injection. +{{% tab "Kubernetes" %}} -## Tracer libraries +### Compatibility -
+**Status**: GA -SSI instrumentation depends on both the tracer version and your application's language version. Specifically: +**Supported node pools**: Linux only (see [Linux distributions reference](#linux-distributions-reference)) -- SSI must be compatible with the tracer version -- That tracer version must support the language version you're using +**Supported architectures**: x86_64, arm64 -If either requirement isn't met, SSI falls back gracefully and your application runs uninstrumented. +### Requirements -
+- [Datadog Admission Controller][1] must be enabled +- Kubernetes nodes running one of the [supported Linux distributions](#linux-distributions-reference) -SSI [automatically downloads][2] a compatible tracer version based on your application's language. The following tracer versions support injection with SSI: +### Limitations -| Tracer Language | Version | -|------------------|-----------| -| Java | 1.44.0+ | -| Python | 2.20.1+ | -| Node.js | 4+ | -| .NET | 3.7.0+ | -| Ruby | 2.5.0+ | -| PHP | 1.6.0+ | +- **Linux node pools only**: Only Linux node pools are supported +- **Windows pods**: For Kubernetes clusters with Windows pods, use namespace inclusion/exclusion or specify an annotation in the application to exclude them from library injection +{{% /tab %}} -## Language-specific requirements +{{% tab "Windows IIS" %}} -While Single Step Instrumentation itself does not directly require a specific language version, compatibility depends on whether a supported tracer version exists for that language version. See the [Tracer libraries](#tracer-libraries) section for details. +### Compatibility -To check which language versions are supported for your runtime, see the compatibility documentation for each tracer: +**Status**: GA -For a complete list of supported language versions, see the compatibility documentation for each tracer: +**Supported runtimes**: .NET only + +### Requirements + +- Datadog Agent v7.67.1 or higher +- Datadog .NET SDK v3.19.0 or higher +- Applications running in IIS + +### Limitations -- [Java tracer compatibility][4] -- [Python tracer compatibility][5] -- [Ruby tracer compatibility][6] -- [Node.js tracer compatibility][7] -- [.NET Core tracer compatibility][8] -- [.NET Framework tracer compatibility][9] -- [PHP tracer compatibility][10] +- **IIS only**: Only .NET applications running in IIS are supported +- **Other .NET applications**: .NET applications not running in IIS are not supported -The following section provides additional notes, troubleshooting guidance, and known limitations for each language: +{{% /tab %}} +{{< /tabs >}} + +## Supported language runtimes + +SSI automatically instruments applications written in the following languages by loading the Datadog Language SDK at runtime. + +### Understanding SDK and runtime compatibility + +
+ +SSI compatibility depends on two factors: + +1. **SDK version**: SSI must support the Datadog Language SDK version (minimum versions listed below) +2. **Runtime version**: The Datadog Language SDK must support your application's language runtime version + +If either requirement isn't met, SSI falls back gracefully and your application runs uninstrumented. + +
+ +SSI [automatically downloads][2] a compatible Datadog Language SDK version based on your application's language. Select your language below to see minimum SDK versions, supported runtime versions, and any limitations: {{< programming-lang-wrapper langs="java,python,ruby,nodejs,dotnet,php" >}} {{< programming-lang lang="java" >}} -### Limitations +### Minimum SDK version -By default, SSI does not instrument some Java applications and libraries to avoid performance overhead or low-value traces. These exclusions are defined in the [Java tracer denylist][1]. If your workload is included, the injector skips attaching the Java agent. +**Java SDK**: 1.44.0 or higher -### Troubleshooting +### Supported runtime versions -**Environment variable length**: If your application uses extensive command-line options or environment variables, you might encounter initialization failures. This typically occurs when you have many JVM arguments or other startup configurations. To resolve this: - - Minimize non-essential JVM arguments - - Consider moving some configurations to a `.properties` file - - Check application logs for specific initialization errors +For a complete list of supported Java versions, see the [Java SDK compatibility documentation][4]. + +### Limitations + +By default, SSI does not instrument some Java applications and libraries to avoid performance overhead or low-value traces. These exclusions are defined in the [Java SDK denylist](https://github.com/DataDog/dd-trace-java/blob/master/metadata/requirements.json). If your workload is included, SSI skips loading the Java SDK. -### Known warnings +### Known issues -When using SSI for Java 24+, you may see warnings related to JNI native access or `sun.misc.Unsafe` memory access. These warnings can be suppressed with the `--illegal-native-access=allow` and `--sun-misc-unsafe-memory-access=allow` environment variables. See [JEP 472][2] and [JEP 498][3] for more information. +**Environment variable length**: If your application uses extensive command-line options or environment variables, you might encounter initialization failures. This typically occurs when you have many JVM arguments or other startup configurations. To resolve this: +- Minimize non-essential JVM arguments +- Consider moving some configurations to a `.properties` file +- Check application logs for specific initialization errors -[1]: https://github.com/DataDog/dd-trace-java/blob/master/metadata/requirements.json -[2]: https://openjdk.org/jeps/472 -[3]: https://openjdk.org/jeps/498 +**Java 24+ warnings**: When using SSI for Java 24+, you may see warnings related to JNI native access or `sun.misc.Unsafe` memory access. These warnings can be suppressed with the `--illegal-native-access=allow` and `--sun-misc-unsafe-memory-access=allow` environment variables. See [JEP 472](https://openjdk.org/jeps/472) and [JEP 498](https://openjdk.org/jeps/498) for more information. {{< /programming-lang >}} {{< programming-lang lang="python" >}} -### Default system repository support +### Minimum SDK version + +**Python SDK**: 2.20.1 or higher + +### Supported runtime versions + +**Minimum Python version**: 3.7 or higher + +For a complete list of supported Python versions, see the [Python SDK compatibility documentation][5]. -Single Step Instrumentation requires Python 3.7+, which is available by default only on: +### Operating system considerations + +Python 3.7+ is available by default only on: - CentOS Stream 8+ - Red Hat Enterprise Linux 8+ +For other distributions, you may need to install Python 3.7+ separately. + {{< /programming-lang >}} {{< programming-lang lang="ruby" >}} -### Troubleshooting +### Minimum SDK version -When uninstalling Single Step Instrumentation from a Ruby application, follow these steps to prevent errors: +**Ruby SDK**: 2.5.0 or higher -1. **Before uninstalling**: Make a backup of your `Gemfile` and `Gemfile.lock`. -2. **After uninstalling**: - - Restore your original `Gemfile` and `Gemfile.lock`, or - - Run `bundle install` to rebuild your dependencies. +### Supported runtime versions -### Additional information +For a complete list of supported Ruby versions, see the [Ruby SDK compatibility documentation][6]. + +### Operating system requirements - Requires Linux distributions using glibc 2.27 or newer - Not compatible with Alpine Linux or other musl-based distributions +### Known issues + +**Uninstalling SSI**: When uninstalling Single Step Instrumentation from a Ruby application, follow these steps to prevent errors: + +1. **Before uninstalling**: Make a backup of your `Gemfile` and `Gemfile.lock` +2. **After uninstalling**: + - Restore your original `Gemfile` and `Gemfile.lock`, or + - Run `bundle install` to rebuild your dependencies + {{< /programming-lang >}} {{< programming-lang lang="nodejs" >}} -### Default system repository support -Default system repositories include supported Node.js versions only on: +### Minimum SDK version + +**Node.js SDK**: 4.0 or higher + +### Supported runtime versions + +For a complete list of supported Node.js versions, see the [Node.js SDK compatibility documentation][7]. + +### Operating system considerations + +Supported Node.js versions are available by default only on: - CentOS Stream 9+ - Red Hat Enterprise Linux 9+ -### Additional information -- Instrumentation of ESM modules is not currently supported. +For other distributions, you may need to install Node.js separately. + +### Limitations + +- **ESM modules**: Instrumentation of ESM (ECMAScript modules) is not currently supported {{< /programming-lang >}} {{< programming-lang lang="dotnet" >}} -## Supported .NET runtimes +### Minimum SDK version -SSI supports both .NET Core and .NET runtimes. See the tracer documentation for version compatibility details: +**.NET SDK**: 3.7.0 or higher -- [.NET Core tracer compatibility][8] -- [.NET Framework tracer compatibility][9] +### Supported runtime versions -[8]: /tracing/trace_collection/compatibility/dotnet-core -[9]: /tracing/trace_collection/compatibility/dotnet-framework +SSI supports both .NET Core and .NET Framework runtimes. For a complete list of supported versions, see: + +- [.NET Core SDK compatibility][8] +- [.NET Framework SDK compatibility][9] {{< /programming-lang >}} -{{< programming-lang lang="PHP" >}} +{{< programming-lang lang="php" >}} + +### Minimum SDK version -### PHP extensions +**PHP SDK**: 1.6.0 or higher -SSI disables automatically when it detects: +### Supported runtime versions + +For a complete list of supported PHP versions, see the [PHP SDK compatibility documentation][10]. + +### Limitations + +SSI automatically disables when it detects: - PHP's Just-In-Time (JIT) compilation - Any of the following extensions: - - Xdebug + - Xdebug - ionCube Loader - NewRelic - Blackfire - pcov - -
If you need to run the SSI alongside these tools, you can force it to enable by setting: DD_INJECT_FORCE=true
+ +
If you need to run SSI alongside these tools, you can force it to enable by setting: DD_INJECT_FORCE=true
{{< /programming-lang >}} {{< /programming-lang-wrapper >}} +## Linux distributions reference + +The following Linux distributions and architectures are supported for SSI across all deployment platforms (Linux hosts, Docker, Kubernetes): + +| OS | Version | Architecture | +|--------------|----------------|---------------| +| Amazon Linux | 2022, 2023 | x86_64, arm64 | +| CentOS | 7, 8 | x86_64, arm64 | +| Debian | 10, 11, 12 | x86_64, arm64 | +| Red Hat | 7, 8, 9 | x86_64, arm64 | +| Ubuntu | 20, 22, 24 (LTS) | x86_64, arm64 | +| Fedora | 40 | x86_64, arm64 | +| AlmaLinux | 8 | x86_64, arm64 | +| Oracle Linux | 8 | x86_64, arm64 | +| Rocky Linux | 8 | x86_64, arm64 | + +
For additional operating system requirements specific to your programming language, see Language-specific requirements.
## Further reading From 78a21a9f9497d2811fbf7546ada2a5666c442921 Mon Sep 17 00:00:00 2001 From: Syed Sarjeel Yusuf Date: Sun, 16 Nov 2025 17:39:14 +0100 Subject: [PATCH 2/9] Fix link formatting in language tabs - Move reference-style links inside each language tab for proper rendering - Use numbered references [1], [2], etc. within each tab context - Remove global reference links that weren't rendering in tabs - Ensure all SDK compatibility links render as clickable links --- .../single-step-apm/compatibility.md | 42 +++++++++++-------- 1 file changed, 25 insertions(+), 17 deletions(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md index 552859d4230..ed599e51c26 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md @@ -133,11 +133,11 @@ SSI [automatically downloads][2] a compatible Datadog Language SDK version based ### Supported runtime versions -For a complete list of supported Java versions, see the [Java SDK compatibility documentation][4]. +For a complete list of supported Java versions, see the [Java SDK compatibility documentation][1]. ### Limitations -By default, SSI does not instrument some Java applications and libraries to avoid performance overhead or low-value traces. These exclusions are defined in the [Java SDK denylist](https://github.com/DataDog/dd-trace-java/blob/master/metadata/requirements.json). If your workload is included, SSI skips loading the Java SDK. +By default, SSI does not instrument some Java applications and libraries to avoid performance overhead or low-value traces. These exclusions are defined in the [Java SDK denylist][2]. If your workload is included, SSI skips loading the Java SDK. ### Known issues @@ -146,7 +146,12 @@ By default, SSI does not instrument some Java applications and libraries to avoi - Consider moving some configurations to a `.properties` file - Check application logs for specific initialization errors -**Java 24+ warnings**: When using SSI for Java 24+, you may see warnings related to JNI native access or `sun.misc.Unsafe` memory access. These warnings can be suppressed with the `--illegal-native-access=allow` and `--sun-misc-unsafe-memory-access=allow` environment variables. See [JEP 472](https://openjdk.org/jeps/472) and [JEP 498](https://openjdk.org/jeps/498) for more information. +**Java 24+ warnings**: When using SSI for Java 24+, you may see warnings related to JNI native access or `sun.misc.Unsafe` memory access. These warnings can be suppressed with the `--illegal-native-access=allow` and `--sun-misc-unsafe-memory-access=allow` environment variables. See [JEP 472][3] and [JEP 498][4] for more information. + +[1]: /tracing/trace_collection/compatibility/java/ +[2]: https://github.com/DataDog/dd-trace-java/blob/master/metadata/requirements.json +[3]: https://openjdk.org/jeps/472 +[4]: https://openjdk.org/jeps/498 {{< /programming-lang >}} @@ -160,7 +165,7 @@ By default, SSI does not instrument some Java applications and libraries to avoi **Minimum Python version**: 3.7 or higher -For a complete list of supported Python versions, see the [Python SDK compatibility documentation][5]. +For a complete list of supported Python versions, see the [Python SDK compatibility documentation][1]. ### Operating system considerations @@ -170,6 +175,8 @@ Python 3.7+ is available by default only on: For other distributions, you may need to install Python 3.7+ separately. +[1]: /tracing/trace_collection/compatibility/python + {{< /programming-lang >}} {{< programming-lang lang="ruby" >}} @@ -180,7 +187,7 @@ For other distributions, you may need to install Python 3.7+ separately. ### Supported runtime versions -For a complete list of supported Ruby versions, see the [Ruby SDK compatibility documentation][6]. +For a complete list of supported Ruby versions, see the [Ruby SDK compatibility documentation][1]. ### Operating system requirements @@ -196,6 +203,8 @@ For a complete list of supported Ruby versions, see the [Ruby SDK compatibility - Restore your original `Gemfile` and `Gemfile.lock`, or - Run `bundle install` to rebuild your dependencies +[1]: /tracing/trace_collection/compatibility/ruby + {{< /programming-lang >}} {{< programming-lang lang="nodejs" >}} @@ -206,7 +215,7 @@ For a complete list of supported Ruby versions, see the [Ruby SDK compatibility ### Supported runtime versions -For a complete list of supported Node.js versions, see the [Node.js SDK compatibility documentation][7]. +For a complete list of supported Node.js versions, see the [Node.js SDK compatibility documentation][1]. ### Operating system considerations @@ -220,6 +229,8 @@ For other distributions, you may need to install Node.js separately. - **ESM modules**: Instrumentation of ESM (ECMAScript modules) is not currently supported +[1]: /tracing/trace_collection/compatibility/nodejs + {{< /programming-lang >}} {{< programming-lang lang="dotnet" >}} @@ -232,8 +243,11 @@ For other distributions, you may need to install Node.js separately. SSI supports both .NET Core and .NET Framework runtimes. For a complete list of supported versions, see: -- [.NET Core SDK compatibility][8] -- [.NET Framework SDK compatibility][9] +- [.NET Core SDK compatibility][1] +- [.NET Framework SDK compatibility][2] + +[1]: /tracing/trace_collection/compatibility/dotnet-core +[2]: /tracing/trace_collection/compatibility/dotnet-framework {{< /programming-lang >}} @@ -245,7 +259,7 @@ SSI supports both .NET Core and .NET Framework runtimes. For a complete list of ### Supported runtime versions -For a complete list of supported PHP versions, see the [PHP SDK compatibility documentation][10]. +For a complete list of supported PHP versions, see the [PHP SDK compatibility documentation][1]. ### Limitations @@ -260,6 +274,8 @@ SSI automatically disables when it detects:
If you need to run SSI alongside these tools, you can force it to enable by setting: DD_INJECT_FORCE=true
+[1]: /tracing/trace_collection/compatibility/php + {{< /programming-lang >}} {{< /programming-lang-wrapper >}} @@ -287,11 +303,3 @@ The following Linux distributions and architectures are supported for SSI across [1]: /containers/cluster_agent/admission_controller/ [2]: /tracing/guide/injectors/ -[3]: /tracing/trace_collection/automatic_instrumentation/dd_libraries/ -[4]: /tracing/trace_collection/compatibility/java/ -[5]: /tracing/trace_collection/compatibility/python -[6]: /tracing/trace_collection/compatibility/ruby -[7]: /tracing/trace_collection/compatibility/nodejs -[8]: /tracing/trace_collection/compatibility/dotnet-core -[9]: /tracing/trace_collection/compatibility/dotnet-framework -[10]: /tracing/trace_collection/compatibility/php From 698bec1003cc2534057d20e3aa34067da4ba4ce5 Mon Sep 17 00:00:00 2001 From: Dominique Alessi Date: Wed, 19 Nov 2025 18:55:06 -0500 Subject: [PATCH 3/9] copy edits --- .../single-step-apm/compatibility.md | 55 ++++++++----------- 1 file changed, 23 insertions(+), 32 deletions(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md index ed599e51c26..27e8a6512ed 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md @@ -8,9 +8,9 @@ further_reading: ## Overview -Single Step Instrumentation (SSI) has specific compatibility requirements that vary by language and environment. This page outlines supported versions, known limitations, and conditions that may impact Single Step Instrumentation for your specific setup. +Single Step Instrumentation (SSI) has specific compatibility requirements that vary by operating system, environment, and language runtime. This page outlines supported platforms, requirements, and known limitations that may impact SSI for your specific setup. -## Where are your applications running? +## Compatibility by deployment environment Select your deployment platform to see compatibility requirements and limitations: @@ -19,16 +19,14 @@ Select your deployment platform to see compatibility requirements and limitation ### Compatibility -**Status**: GA - -**Supported operating systems**: See [Linux distributions reference](#linux-distributions-reference) - -**Supported architectures**: x86_64, arm64 +- **Status**: GA +- **Supported operating systems**: See [Linux distributions reference](#linux-distributions-reference) +- **Supported architectures**: x86_64, arm64 ### Requirements -- Datadog Agent installed with APM Instrumentation enabled -- One of the [supported Linux distributions](#linux-distributions-reference) +- Datadog Agent with APM Instrumentation enabled +- A [supported Linux distribution](#linux-distributions-reference) ### Limitations @@ -41,16 +39,14 @@ Select your deployment platform to see compatibility requirements and limitation ### Compatibility -**Status**: GA - -**Supported operating systems**: See [Linux distributions reference](#linux-distributions-reference) - -**Supported architectures**: x86_64, arm64 +- **Status**: GA +- **Supported operating systems**: See [Linux distributions reference](#linux-distributions-reference) +- **Supported architectures**: x86_64, arm64 ### Requirements -- Datadog Agent installed with APM Instrumentation enabled -- Docker running on one of the [supported Linux distributions](#linux-distributions-reference) +- Datadog Agent with APM Instrumentation enabled +- Docker running on a [supported Linux distribution](#linux-distributions-reference) ### Limitations @@ -64,31 +60,30 @@ Select your deployment platform to see compatibility requirements and limitation ### Compatibility -**Status**: GA - -**Supported node pools**: Linux only (see [Linux distributions reference](#linux-distributions-reference)) - -**Supported architectures**: x86_64, arm64 +- **Status**: GA +- **Supported node pools**: Linux only (see [Linux distributions reference](#linux-distributions-reference)) +- **Supported architectures**: x86_64, arm64 ### Requirements -- [Datadog Admission Controller][1] must be enabled -- Kubernetes nodes running one of the [supported Linux distributions](#linux-distributions-reference) +- [Datadog Admission Controller][1] enabled +- Kubernetes nodes running a [supported Linux distribution](#linux-distributions-reference) ### Limitations - **Linux node pools only**: Only Linux node pools are supported - **Windows pods**: For Kubernetes clusters with Windows pods, use namespace inclusion/exclusion or specify an annotation in the application to exclude them from library injection +[1]: /containers/cluster_agent/admission_controller/ + {{% /tab %}} {{% tab "Windows IIS" %}} ### Compatibility -**Status**: GA - -**Supported runtimes**: .NET only +- **Status**: GA +- **Supported runtimes**: .NET only ### Requirements @@ -106,9 +101,7 @@ Select your deployment platform to see compatibility requirements and limitation ## Supported language runtimes -SSI automatically instruments applications written in the following languages by loading the Datadog Language SDK at runtime. - -### Understanding SDK and runtime compatibility +SSI automatically instruments applications written in the following languages by [loading a compatible Datadog Language SDK][2] at runtime. Select your language below to see minimum SDK versions, supported runtime versions, and any limitations.
@@ -117,12 +110,10 @@ SSI compatibility depends on two factors: 1. **SDK version**: SSI must support the Datadog Language SDK version (minimum versions listed below) 2. **Runtime version**: The Datadog Language SDK must support your application's language runtime version -If either requirement isn't met, SSI falls back gracefully and your application runs uninstrumented. +If either requirement isn't met, SSI falls back gracefully and your application runs without instrumentation.
-SSI [automatically downloads][2] a compatible Datadog Language SDK version based on your application's language. Select your language below to see minimum SDK versions, supported runtime versions, and any limitations: - {{< programming-lang-wrapper langs="java,python,ruby,nodejs,dotnet,php" >}} {{< programming-lang lang="java" >}} From b8ec6238289c4730a73fc7f319ce70856345814e Mon Sep 17 00:00:00 2001 From: Dominique Alessi Date: Wed, 19 Nov 2025 19:09:03 -0500 Subject: [PATCH 4/9] fixing nits --- .../single-step-apm/compatibility.md | 37 +++++++++---------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md index 27e8a6512ed..66080335c72 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md @@ -8,11 +8,11 @@ further_reading: ## Overview -Single Step Instrumentation (SSI) has specific compatibility requirements that vary by operating system, environment, and language runtime. This page outlines supported platforms, requirements, and known limitations that may impact SSI for your specific setup. +Single Step Instrumentation (SSI) has compatibility requirements that vary by operating system, environment, and language runtime. This page outlines supported platforms, requirements, and known limitations that may impact SSI for your specific setup. -## Compatibility by deployment environment +## Compatibility by application environment -Select your deployment platform to see compatibility requirements and limitations: +Select your environment to see compatibility requirements and limitations: {{< tabs >}} {{% tab "Linux Host" %}} @@ -30,8 +30,8 @@ Select your deployment platform to see compatibility requirements and limitation ### Limitations -- **SELinux**: Not supported on hardened environments such as SELinux -- **Small VM instances**: You may encounter timeouts with smaller VM instances such as `t2.micro`. Upgrade to a larger instance such as `t2.small` or higher +- **SELinux**: Hardened SELinux environments are not supported. +- **Small VM instances**: Very small instance types (for example, `t2.micro`) can experience timeouts. Use a larger instance type such as `t2.small` or higher. {{% /tab %}} @@ -50,9 +50,8 @@ Select your deployment platform to see compatibility requirements and limitation ### Limitations -- **Rootless Docker mode**: If you are using Docker in rootless mode (Docker running without root privileges for added security), you need to configure the socket path to ensure SSI can connect to Docker. Update the socket path in `/etc/datadog-agent/inject/docker_config.yaml` to match your environment. By default, this path is set to `/run/user/$UID/docker.sock`, but it may vary based on your setup. - -- **Custom `runc` shims**: If your environment uses custom `runc` shims (for GPU support or other specialized tasks), you must adjust your configuration to avoid conflicts. SSI requires its own `runc` shim to enable automatic instrumentation within Docker containers. To ensure compatibility, update the `runtimes` property in `/etc/datadog-agent/inject/docker_config.yaml` to include both your custom shim and the Datadog shim. +- **Rootless Docker mode**: When running Docker in rootless mode, update the socket path in `/etc/datadog-agent/inject/docker_config.yaml` so SSI can connect to Docker. The default path is `/run/user/$UID/docker.sock`, but your environment may differ. +- **Custom `runc` shims**: If your environment uses custom `runc` shims (for example, for GPU workloads), update the `runtimes` entry in `/etc/datadog-agent/inject/docker_config.yaml` to include both your custom runtime and the Datadog runtime required for SSI. {{% /tab %}} @@ -61,7 +60,7 @@ Select your deployment platform to see compatibility requirements and limitation ### Compatibility - **Status**: GA -- **Supported node pools**: Linux only (see [Linux distributions reference](#linux-distributions-reference)) +- **Supported node pools**: Linux nodes only (see [Linux distributions reference](#linux-distributions-reference)) - **Supported architectures**: x86_64, arm64 ### Requirements @@ -71,8 +70,8 @@ Select your deployment platform to see compatibility requirements and limitation ### Limitations -- **Linux node pools only**: Only Linux node pools are supported -- **Windows pods**: For Kubernetes clusters with Windows pods, use namespace inclusion/exclusion or specify an annotation in the application to exclude them from library injection +- **Linux node pools only**: Only Linux node pools are supported. +- **Windows pods**: For Kubernetes clusters with Windows pods, use namespace inclusion/exclusion or specify an annotation in the application to exclude them from library injection. [1]: /containers/cluster_agent/admission_controller/ @@ -93,8 +92,8 @@ Select your deployment platform to see compatibility requirements and limitation ### Limitations -- **IIS only**: Only .NET applications running in IIS are supported -- **Other .NET applications**: .NET applications not running in IIS are not supported +- **IIS only**: Only .NET applications running in IIS are supported. +- **Other .NET applications**: .NET applications not running in IIS are not supported. {{% /tab %}} {{< /tabs >}} @@ -107,10 +106,10 @@ SSI automatically instruments applications written in the following languages by SSI compatibility depends on two factors: -1. **SDK version**: SSI must support the Datadog Language SDK version (minimum versions listed below) -2. **Runtime version**: The Datadog Language SDK must support your application's language runtime version +1. **SDK version**: SSI must support the Datadog Language SDK version (minimum versions listed below). +2. **Runtime version**: The Datadog Language SDK must support your application's language runtime version. -If either requirement isn't met, SSI falls back gracefully and your application runs without instrumentation. +If either requirement is not met, SSI falls back gracefully and your application runs without instrumentation. @@ -128,7 +127,7 @@ For a complete list of supported Java versions, see the [Java SDK compatibility ### Limitations -By default, SSI does not instrument some Java applications and libraries to avoid performance overhead or low-value traces. These exclusions are defined in the [Java SDK denylist][2]. If your workload is included, SSI skips loading the Java SDK. +By default, SSI does not instrument some Java applications and libraries to avoid performance overhead or non-actionable traces. These exclusions are defined in the [Java SDK denylist][2]. If your workload is included, SSI skips loading the Java SDK. ### Known issues @@ -218,7 +217,7 @@ For other distributions, you may need to install Node.js separately. ### Limitations -- **ESM modules**: Instrumentation of ESM (ECMAScript modules) is not currently supported +- **ESM modules**: Instrumentation of ESM (ECMAScript modules) is not supported. [1]: /tracing/trace_collection/compatibility/nodejs @@ -286,7 +285,7 @@ The following Linux distributions and architectures are supported for SSI across | Oracle Linux | 8 | x86_64, arm64 | | Rocky Linux | 8 | x86_64, arm64 | -
For additional operating system requirements specific to your programming language, see Language-specific requirements.
+
For additional operating system requirements specific to your programming language, see Supported language runtimes.
## Further reading From 3c1fc0efe213ea03b8ac200ab521ed957c8a51e0 Mon Sep 17 00:00:00 2001 From: domalessi <111786334+domalessi@users.noreply.github.com> Date: Mon, 24 Nov 2025 14:06:01 -0500 Subject: [PATCH 5/9] Update content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md --- .../automatic_instrumentation/single-step-apm/compatibility.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md index 66080335c72..bcc4b53d08c 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md @@ -93,7 +93,6 @@ Select your environment to see compatibility requirements and limitations: ### Limitations - **IIS only**: Only .NET applications running in IIS are supported. -- **Other .NET applications**: .NET applications not running in IIS are not supported. {{% /tab %}} {{< /tabs >}} From aacec3b7dab353a665a8f00baf759a8c704b4fef Mon Sep 17 00:00:00 2001 From: domalessi <111786334+domalessi@users.noreply.github.com> Date: Mon, 24 Nov 2025 14:06:30 -0500 Subject: [PATCH 6/9] Update content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md --- .../automatic_instrumentation/single-step-apm/compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md index bcc4b53d08c..4e305a882f4 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md @@ -99,7 +99,7 @@ Select your environment to see compatibility requirements and limitations: ## Supported language runtimes -SSI automatically instruments applications written in the following languages by [loading a compatible Datadog Language SDK][2] at runtime. Select your language below to see minimum SDK versions, supported runtime versions, and any limitations. +SSI automatically instruments applications written in the following languages by [loading a compatible Datadog Language SDK][2] at runtime. Select your language to see minimum SDK versions, supported runtime versions, and any limitations.
From 82362c9859fecd1f1c0cf6248343f57345f8262e Mon Sep 17 00:00:00 2001 From: domalessi <111786334+domalessi@users.noreply.github.com> Date: Mon, 24 Nov 2025 14:07:35 -0500 Subject: [PATCH 7/9] Update content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md --- .../automatic_instrumentation/single-step-apm/compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md index 4e305a882f4..e46e75535ab 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md @@ -105,7 +105,7 @@ SSI automatically instruments applications written in the following languages by SSI compatibility depends on two factors: -1. **SDK version**: SSI must support the Datadog Language SDK version (minimum versions listed below). +1. **SDK version**: SSI must support the Datadog Language SDK version. 2. **Runtime version**: The Datadog Language SDK must support your application's language runtime version. If either requirement is not met, SSI falls back gracefully and your application runs without instrumentation. From 5752585b1bb3e1ce07bf9d7d8dd4936a75baf072 Mon Sep 17 00:00:00 2001 From: domalessi <111786334+domalessi@users.noreply.github.com> Date: Mon, 24 Nov 2025 14:11:24 -0500 Subject: [PATCH 8/9] Update content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md --- .../single-step-apm/compatibility.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md index e46e75535ab..78abb23f020 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md @@ -187,10 +187,10 @@ For a complete list of supported Ruby versions, see the [Ruby SDK compatibility **Uninstalling SSI**: When uninstalling Single Step Instrumentation from a Ruby application, follow these steps to prevent errors: -1. **Before uninstalling**: Make a backup of your `Gemfile` and `Gemfile.lock` -2. **After uninstalling**: - - Restore your original `Gemfile` and `Gemfile.lock`, or - - Run `bundle install` to rebuild your dependencies +1. **Before uninstalling**: Make a backup of your `Gemfile` and `Gemfile.lock`. +2. **After uninstalling**, do one of the following: + - Restore your original `Gemfile` and `Gemfile.lock`. + - Run `bundle install` to rebuild your dependencies. [1]: /tracing/trace_collection/compatibility/ruby From 2d7c98463db073e1fec70c5fece6f8145dbe67a6 Mon Sep 17 00:00:00 2001 From: domalessi <111786334+domalessi@users.noreply.github.com> Date: Mon, 24 Nov 2025 14:12:24 -0500 Subject: [PATCH 9/9] Update content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md --- .../automatic_instrumentation/single-step-apm/compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md index 78abb23f020..561ded41a3d 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/single-step-apm/compatibility.md @@ -261,7 +261,7 @@ SSI automatically disables when it detects: - Blackfire - pcov -
If you need to run SSI alongside these tools, you can force it to enable by setting: DD_INJECT_FORCE=true
+
If you need to run SSI alongside these tools, you can force it to enable by setting DD_INJECT_FORCE=true.
[1]: /tracing/trace_collection/compatibility/php