Build System

Native Pre-Dependencies

Some native extensions are written in Rust, Cython, or C++, requiring specific dependencies to build them.

For Rust, you need the rustc and cargo tools installed. Install them by following these steps:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain stable -y

For C++, requirements vary by system, but you’ll need a C++ compiler and cmake. Install them as follows:

• On Ubuntu:

  When using GCC, you need versions that have fixes for this bug

sudo apt-get install build-essential cmake

• On macOS:

brew install cmake
xcode-select --install

Build Dependencies

To see the current build dependencies, check the [build-system] section in the pyproject.toml file. For example, at the time of writing, the dependencies are:

[build-system]
requires = ["cython", "cmake>=3.24.2,<3.28; python_version>='3.8'", "setuptools-rust<2"]

To install all dependencies in one step, use:

pip install 'cython' 'cmake>=3.24.2,<3.28' 'setuptools-rust<2'

Note that pip install -e (described below) also installs these build dependencies automatically.

Local Installation from a Local Repository

The simplest way to build and install the library in your Python environment is with pip:

pip install .

Local Installation in Development Mode

To install the library in development mode, use the -e flag:

pip install -e .

This installs the library in “editable” mode, meaning changes to the source code are immediately reflected in the installed package. This works only if you run the command from the repository’s root directory. To use ddtrace from a different directory (e.g., another project running under ddtrace), add the repository path to your PYTHONPATH environment variable:

export PYTHONPATH=/path/to/ddtrace:$PYTHONPATH

If you skip pip install -e . and use PYTHONPATH, you must manually install the build dependencies (see above) and compile the native extensions with:

python setup.py build_ext --inplace

Then, if you want to run ddtrace from the repo with another project in another directory, instead of using ddtrace-run (which with an editable or PYTHONPATH install would not find the one in the repository), do:

python -m ddtrace.commands.ddtrace_run python my_traced_app.py

Using sccache to Speed Up Builds

If you frequently rebuild native extensions or deploy to multiple containers, consider using sccache to accelerate compilation. sccache caches compilation results, reducing build times. Install it using cargo, which you should have if you followed the Rust installation steps earlier:

cargo install sccache

For the build system to locate sccache, either ensure its path is in your PATH environment variable or set the SCCACHE environment variable to its location:

export SCCACHE=/home/doe/.cargo/bin/sccache

Additionally, enable sccache by setting the DD_USE_SCCACHE environment variable:

export DD_USE_SCCACHE=1

Then, build the tracer as usual.

To verify that sccache is working after a build, check its statistics:

sccache --show-stats

If cache-hits is greater than 0 (or increases after a cached build), sccache is functioning correctly.

To change the sccache cache directory—e.g., to share it with containers via copying or mounting a volume—set the SCCACHE_DIR environment variable:

export SCCACHE_DIR=/path/to/cache

The sccache –show-stats command also displays the current cache directory.

Configuration Environment Variables

These environment variables modify aspects of the build process.

DD_COMPILE_DEBUG(DEPRECATED)

This deprecated variable will be removed in a future release. If set to 1, it compiles the tracer with debug symbols—useful for debugging the tracer itself but resulting in a slower and larger binary. This is not recommended for production. If set to 0, extensions are compiled in Release mode.

Type: Boolean

Default: (no value)

New in version v0.44.0.

DD_USE_SCCACHE

If set to 1, it enables sccache to accelerate native extension compilation (see above). This is beneficial for frequent rebuilds or multi-container deployments.

Type: Boolean

Default: (no value)

New in version v2.12.0.

DD_COMPILE_MODE

Specifies the compilation mode for native extensions. Depending on your CMake version, options typically include Release, Debug, RelWithDebInfo, and MinSizeRel. Note that Debug produces slower, larger binaries; RelWithDebInfo increases size but retains the performance of Release; and MinSizeRel reduces binary size at the cost of performance.

Type: String

Default: Release

New in version v3.3.0.

DD_COMPILE_ABSEIL

If set to 1, the tracer is compiled with the Abseil library, enhancing performance for Runtime Code Analysis features when active (DD_IAST_ENABLED=1). If set to 0, the Runtime Code Analysis extension is built without Abseil, speeding up the build process at the cost of some performance.

Type: Boolean

Default: True

New in version v3.3.0.

DD_CYTHONIZE

If enabled, then Cython extensions are included in the build. Disabling will exclude them. This is mostly useful for source distribution builds so we can skip calling cythonize on source files.

Type: Boolean

Default: True

DD_FAST_BUILD

If set to 1, the tracer is compiled with minimal optimizations (-g0) and DD_COMPILE_ABSEIL is forced to 0. This is not recommended for production due to reduced performance.

Type: Boolean

Default: (no value)

New in version v3.3.0.

DD_PROFILING_NATIVE_TESTS

If set to 1, it compiles the profiling native tests. This is useful only when modifying the library’s profiling features and is disabled by default.

Type: Boolean

Default: (no value)

New in version v2.16.0.

DD_CMAKE_INCREMENTAL_BUILD

Enables support for incremental builds of CMake extensions when doing an in-place install (e.g. editable mode).

Type: Boolean

Default: True

New in version v3.10.0.

DD_SETUP_CACHE_DOWNLOADS

Caches the download of artifacts needed by the build process.

Type: Boolean

Default: True

New in version v3.10.0.

DD_DOWNLOAD_MAX_RETRIES

Maximum number of retry attempts for transient download failures from GitHub. Retries are triggered by HTTP 429 (rate limit), 502/503/504 (server errors), and network timeouts. Uses exponential backoff with jitter between retries.

Type: Integer

Default: 10

New in version v4.1.0.

DD_DOWNLOAD_INITIAL_DELAY

Initial delay in seconds before the first retry attempt. Delay increases exponentially with backoff_factor=1.618 (Fibonacci-like). Useful for tuning retry behavior in different environments.

Type: Float

Default: 1.0

New in version v4.1.0.

DD_DOWNLOAD_MAX_DELAY

Maximum delay in seconds between retry attempts. Prevents excessive wait times during exponential backoff.

Type: Integer

Default: 120

New in version v4.1.0.