---
title: Understanding Injector Behavior with Single Step Instrumentation
description: >-
  Learn how the injector works with Single Step Instrumentation to automatically
  instrument applications at runtime without manual configuration.
breadcrumbs: >-
  Docs > APM > Tracing Guides > Understanding Injector Behavior with Single Step
  Instrumentation
---

# Understanding Injector Behavior with Single Step Instrumentation

## Overview{% #overview %}

The injector is a shared library that automatically instruments applications at runtime. With [Single Step Instrumentation](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm), the injector automates environment setup and tracer initialization, eliminating the need for manual configuration.

## How the injector is loaded{% #how-the-injector-is-loaded %}

### Linux{% #linux %}

On Linux systems, the injector uses the `LD_PRELOAD` mechanism—a dynamic linking feature in Unix-like environments—to load itself into all dynamically linked processes. This can happen in two ways:

- Explicitly, by setting the `LD_PRELOAD` environment variable.
- Implicitly, by modifying the system-wide `/etc/ld.so.preload` file.

### Docker{% #docker %}

In Docker environments, the injector uses the same `LD_PRELOAD` mechanism as on Linux hosts to load into application processes at runtime. This allows it to initialize tracing logic and modify environment variables before the application starts.

To enable this, Datadog provides a custom `runc` shim that replaces Docker's default container runtime. The shim's purpose is to:

1. Inject the shared library (the injector) into the container.
1. Set the `LD_PRELOAD` environment variable, ensuring the injector is loaded into all dynamically linked processes inside the container.

### Kubernetes{% #kubernetes %}

In Kubernetes environments, injection is handled by the Datadog Admission Controller, which uses a mutating admission webhook. When a pod is scheduled, the controller:

1. Evaluates whether the pod should be instrumented based on configured selectors (such as namespaces, labels, or specific pod properties).
1. Mutates the pod spec to:
   - Use the Datadog CSI driver to mount the injector and tracer libraries
   - Set environment variables (like `LD_PRELOAD`)
   - Mount volumes to persist injected libraries

The default delivery method uses init containers, but SSI supports additional [injection modes](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm/kubernetes/#configure-injection-modes) that may better suit your environment.

## Injector behavior{% #injector-behavior %}

After the injector is loaded into a process's memory space—regardless of platform—it performs the following:

- Detects the application's runtime (such as Python, Node.js, PHP, Java, .NET, and Ruby).
- Modifies environment variables or command-line arguments to load the appropriate tracer SDK.
- Emits telemetry to report status and aid in debugging.
- Includes fallback logic to allow the application to continue running uninstrumented if injection fails.

## Further reading{% #further-reading %}

- [Single Step APM Instrumentation](https://docs.datadoghq.com/tracing/trace_collection/automatic_instrumentation/single-step-apm)