Compatibility

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.

Operating systems

The following operating systems and architectures are compatible:

OSVersionArchitecture
Amazon Linux2022+x86_64, arm64
CentOS7+, 8+x86_64, arm64
Debian10-12x86_64, arm64
Red Hat7+x86_64, arm64
Ubuntu20+ (LTS)x86_64, arm64
Fedora40x86_64, arm64
AlmaLinux8+x86_64, arm64
Oracle Linux8+x86_64, arm64
Rocky Linux8+x86_64, arm64
For additional operating system requirements specific to your programming language, see Language specific requirements.

Platforms

The following container platforms are compatible:

EnvironmentRequirements & LimitationsSupport
LinuxNot supported on hardened environments such as SELinuxGA
Docker on LinuxGA
KubernetesDatadog Admission Controller enabledGA

Platform-specific requirements

Linux virtual machines (VMs)

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.

Docker containers

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

  • 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

For Kubernetes clusters with Windows pods, use namespace inclusion/exclusion or specify an annotation in the application to exclude them from library injection.

Tracer libraries

SSI instrumentation depends on both the tracer version and your application’s language version. Specifically:

  • SSI must be compatible with the tracer version
  • That tracer version must support the language version you’re using

If either requirement isn’t met, SSI falls back gracefully and your application runs uninstrumented.

SSI automatically downloads a compatible tracer version based on your application’s language. The following tracer versions support injection with SSI:

Tracer LanguageVersion
Java1.44.0+
Python2.20.1+
Node.js4+
.NET3.7.0+
Ruby2.5.0+
PHP1.6.0+

Language-specific requirements

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 section for details.

To check which language versions are supported for your runtime, see the compatibility documentation for each tracer:

For a complete list of supported language versions, see the compatibility documentation for each tracer:

The following section provides additional notes, troubleshooting guidance, and known limitations for each language:

Troubleshooting

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

Default system repository support

Single Step Instrumentation requires Python 3.7+, which is available by default only on:

  • CentOS Stream 8+
  • Red Hat Enterprise Linux 8+
Using Single Step Instrumentation with Ruby applications is in Preview.

Troubleshooting

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.

Additional information

  • Requires Linux distributions using glibc 2.27 or newer
  • Not compatible with Alpine Linux or other musl-based distributions

Default system repository support

Default system repositories include supported Node.js versions only on:

  • CentOS Stream 9+
  • Red Hat Enterprise Linux 9+

Additional information

  • Instrumentation of ESM modules is not currently supported.

Supported .NET runtimes

SSI supports both .NET Core and .NET runtimes. See the tracer documentation for version compatibility details:

PHP extensions

SSI disables automatically when it detects:

  • PHP’s Just-In-Time (JIT) compilation
  • Any of the following extensions:
    • 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

Further reading

Additional helpful documentation, links, and articles:

Single Step APM InstrumentationDOCUMENTATION more more
PREVIEWING: domalessi/ssi-best-practices