### Example: Django-Simple Profile Scenario

Source: https://github.com/datadog/dd-trace-py/blob/main/scripts/profiles/README.md

An example command combining the setup and run scripts for the django-simple profile scenario.

```bash
scripts/profiles/django-simple/setup.sh /tmp/delme \
&& scripts/profiles/django-simple/run.sh /tmp/delme
```

--------------------------------

### Run Profile Scenario Setup

Source: https://github.com/datadog/dd-trace-py/blob/main/scripts/profiles/README.md

Execute the setup stage for a profile scenario. Ensure the same prefix is used for both setup and run scripts.

```bash
scripts/profiles/<scenario>/setup.sh <prefix>
```

--------------------------------

### Install Git Hooks

Source: https://github.com/datadog/dd-trace-py/blob/main/hooks/README.md

Installs all configured git hooks by creating symlinks in the .git/hooks/ directory. This is the initial setup step for using the project's git hook system.

```bash
hooks/autohook.sh install
```

--------------------------------

### Local Installation from Source

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Installs the library from the local source directory using pip.

```bash
pip install .
```

--------------------------------

### Flask Integration Example

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-integrations.rst

Example of a snapshot test for the Flask integration, verifying a successful HTTP GET request.

```python
import pytest

from tests.contrib.flask.app import app
from tests.utils.trace import DEFAULT_HEADERS


@pytest.mark.snapshot
def test_flask_200(flask_client):
    assert flask_client.get("/").status_code == 200

```

--------------------------------

### Install Extension Library

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/profiling/collector/CMakeLists.txt

Installs the compiled extension target to the specified library installation directory.

```cmake
install(TARGETS ${FULL_EXTENSION_NAME} LIBRARY DESTINATION ${LIB_INSTALL_DIR})
```

--------------------------------

### Start Test Agent and Datastore Containers

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-integrations.rst

Use this command to start the test agent and any necessary datastore containers for running integration tests.

```bash
$ docker compose up -d testagent <container>
$ scripts/ddtest
> DD_AGENT_PORT=9126 riot -v run --pass-env <test_suite_name>
```

--------------------------------

### Suite Configuration Example

Source: https://github.com/datadog/dd-trace-py/blob/main/tests/README.md

Example of a suite configuration, including environment variables, parallelism, retries, pattern matching, triggering paths, and required services.

```yaml
suites:
  profile:
    env:
      DD_TRACE_AGENT_URL: ''
    parallelism: 20
    retry: 2
    pattern: profile
    paths:
      - '@bootstrap'
      - '@core'
      - '@profiling'
      - tests/profiling/*
    services:
      - redis
```

--------------------------------

### Install Library

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/datadog/profiling/dd_wrapper/CMakeLists.txt

Installs the 'dd_wrapper' target to a specified library installation directory. This is used when the library needs to be placed in a custom location.

```cmake
if(INPLACE_LIB_INSTALL_DIR)
    set(LIB_INSTALL_DIR "${INPLACE_LIB_INSTALL_DIR}")
endif()

if(LIB_INSTALL_DIR)
    install(
        TARGETS dd_wrapper
        LIBRARY DESTINATION ${LIB_INSTALL_DIR}
        ARCHIVE DESTINATION ${LIB_INSTALL_DIR}
        RUNTIME DESTINATION ${LIB_INSTALL_DIR})
endif()
```

--------------------------------

### Install Build Dependencies with Pip

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Installs all specified build dependencies, such as Cython, CMake, and setuptools-rust, using pip.

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

--------------------------------

### Allow Direct Package Installation on Previous Line

Source: https://github.com/datadog/dd-trace-py/blob/main/ci/requirements/README.md

Allow a direct package installation by placing the exception comment on the line preceding the `pip install` command. This is an alternative syntax for marking exceptions.

```yaml
# ci-deps: allow
pip install 'some-package>=1.0'
```

--------------------------------

### Local Installation in Development Mode

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Installs the library in editable mode, allowing immediate reflection of source code changes without reinstallation.

```bash
pip install -e .
```

--------------------------------

### Installing pybind11 Headers and Configuration Files

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/appsec/_iast/_taint_tracking/_vendor/pybind11/CMakeLists.txt

Installs pybind11 headers and CMake configuration files. This snippet handles the installation of the pybind11 library itself, including its configuration files for package management.

```cmake
if(PYBIND11_INSTALL)
  if(DEFINED SKBUILD_PROJECT_NAME AND SKBUILD_PROJECT_NAME STREQUAL "pybind11_global")
    install(DIRECTORY ${pybind11_INCLUDE_DIR}/pybind11 DESTINATION "${SKBUILD_HEADERS_DIR}")
  endif()
  install(DIRECTORY ${pybind11_INCLUDE_DIR}/pybind11 DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
  set(PYBIND11_CMAKECONFIG_INSTALL_DIR
      "${CMAKE_INSTALL_DATAROOTDIR}/cmake/${PROJECT_NAME}"
      CACHE STRING "install path for pybind11Config.cmake")

  if(IS_ABSOLUTE "${CMAKE_INSTALL_INCLUDEDIR}")
    set(pybind11_INCLUDEDIR "${CMAKE_INSTALL_FULL_INCLUDEDIR}")
  else()
    set(pybind11_INCLUDEDIR "$\{PACKAGE_PREFIX_DIR\}/${CMAKE_INSTALL_INCLUDEDIR}")
  endif()

  configure_package_config_file(
    tools/${PROJECT_NAME}Config.cmake.in "${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake"
    INSTALL_DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})

  write_basic_package_version_file(
    ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
    VERSION ${PROJECT_VERSION}
    COMPATIBILITY AnyNewerVersion ARCH_INDEPENDENT)

  install(
    FILES ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}Config.cmake
          ${CMAKE_CURRENT_BINARY_DIR}/${PROJECT_NAME}ConfigVersion.cmake
          tools/FindPythonLibsNew.cmake
          tools/pybind11Common.cmake
          tools/pybind11Tools.cmake
          tools/pybind11NewTools.cmake
          tools/pybind11GuessPythonExtSuffix.cmake
    DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})

  if(NOT PYBIND11_EXPORT_NAME)
    set(PYBIND11_EXPORT_NAME "${PROJECT_NAME}Targets")
  endif()

  install(TARGETS pybind11_headers EXPORT "${PYBIND11_EXPORT_NAME}")

  install(
    EXPORT "${PYBIND11_EXPORT_NAME}"
    NAMESPACE "pybind11::"
    DESTINATION ${PYBIND11_CMAKECONFIG_INSTALL_DIR})
endif()
```

--------------------------------

### Run Profile Scenario Execution

Source: https://github.com/datadog/dd-trace-py/blob/main/scripts/profiles/README.md

Execute the actual profile scenario after setup. Ensure the same prefix is used for both setup and run scripts.

```bash
scripts/profiles/<scenario>/run.sh <prefix>
```

--------------------------------

### Install VizTracer

Source: https://github.com/datadog/dd-trace-py/blob/main/benchmarks/README.rst

Installs or upgrades the viztracer package using pip.

```bash
# Install viztracer
pip install -U viztracer
```

--------------------------------

### Cache and restore .so files and shared C++ dependency install trees

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

The ext_cache.py script is used to manage cached build artifacts. Use 'restore' to copy .so files into the source tree before installation, and 'save' to copy them into the cache after a successful build.

```text
ext_cache.py restore  →  copies .so files into source tree
pip install -e .      →  skip checks fire, nothing recompiles
ext_cache.py save     →  copies .so files into cache
```

--------------------------------

### Benchmark Configuration (YAML)

Source: https://github.com/datadog/dd-trace-py/blob/main/benchmarks/README.rst

Example YAML configuration file specifying different sets of configuration variables for a benchmark scenario.

```yaml
small-size:
  size: 10
large-size:
  size: 1000
huge-size:
  size: 1000000
```

--------------------------------

### Install ddtrace with pip

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/installation_quickstart.rst

Install the ddtrace library using pip. Ensure you are using pip version 18 or above.

```bash
pip install ddtrace
```

--------------------------------

### Install Rust Toolchain

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Installs the Rust toolchain including rustc and cargo, which are required for building Rust-based native extensions.

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

--------------------------------

### Typical Remote Configuration Lifecycle

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/README.md

Demonstrates the standard pattern for managing remote configuration within a product's start and stop functions, including registering callbacks and enabling/disabling products.

```python
def start():
    # 1. Register the callback so the subscriber can dispatch payloads.
    remoteconfig_poller.register_callback("MY_PRODUCT", MyProductCallback())
    # 2. Advertise the product to the agent so it starts sending configuration.
    remoteconfig_poller.enable_product("MY_PRODUCT")

def stop(join=False):
    # 1. Stop requesting configuration from the agent.
    remoteconfig_poller.disable_product("MY_PRODUCT")
    # 2. Remove the callback.
    remoteconfig_poller.unregister_callback("MY_PRODUCT")
```

--------------------------------

### Install Extension Library

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/datadog/profiling/stack/CMakeLists.txt

Installs the built extension target (library, archive, runtime) to a specified destination directory if LIB_INSTALL_DIR is defined. This makes the compiled extension available for use in other projects or for deployment.

```cmake
if(LIB_INSTALL_DIR)
    install(
        TARGETS ${EXTENSION_NAME}
        LIBRARY DESTINATION ${LIB_INSTALL_DIR}
        ARCHIVE DESTINATION ${LIB_INSTALL_DIR}
        RUNTIME DESTINATION ${LIB_INSTALL_DIR})
endif()
```

--------------------------------

### Start tracing with ddtrace-run

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/installation_quickstart.rst

Prefix your Python entry-point command with ddtrace-run to enable tracing. Configure service name, environment, and version using environment variables.

```bash
DD_SERVICE=<app_name> DD_ENV=<environment> DD_VERSION=<version> ddtrace-run python app.py
```

--------------------------------

### Example Fuzzer Directory Structure

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-fuzzing.rst

This shows the typical file structure for a fuzzer component, including build scripts and source files.

```text
ddtrace/internal/datadog/profiling/stack/fuzz/ 
├── build.sh
├── fuzz_echion_remote_read.cpp
└── CMakeLists.txt
```

--------------------------------

### Allow Direct Package Installation with Version

Source: https://github.com/datadog/dd-trace-py/blob/main/ci/requirements/README.md

Mark a direct package installation as allowed in CI. This is recommended when a job needs a specific package not fully managed by the locked requirements, and a version specifier is provided for safety.

```yaml
# ci-deps: allow
pip install 'twine>=5.0,<6'
```

--------------------------------

### Install sccache for Faster Builds

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Installs sccache using cargo, a tool that caches compilation results to accelerate the build process for native extensions.

```bash
cargo install sccache
```

--------------------------------

### Start Testagent Service

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-testing.rst

Start the testagent service using Docker Compose outside of the testrunner shell. This is necessary if your test relies on the testagent service.

```bash
# outside of the testrunner shell
$ docker compose up -d testagent
```

--------------------------------

### Copy Integration Template

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-integrations.rst

Copy the skeleton integration template to start building a new integration. Replace '<integration>' with the actual integration name.

```bash
cp -r templates/integration ddtrace/contrib/internal/<integration>
```

--------------------------------

### Install CMake and Xcode Command Line Tools on macOS

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Installs CMake and the Xcode command line tools on macOS, which are required for building native extensions.

```bash
brew install cmake
xcode-select --install
```

--------------------------------

### Check Git Hooks Installation

Source: https://github.com/datadog/dd-trace-py/blob/main/hooks/README.md

Verify if Git hooks are installed in the .git/hooks directory. This helps in troubleshooting issues where hooks might be missing.

```bash
ls -la .git/hooks/
```

--------------------------------

### Install C++ Build Tools on Ubuntu

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Installs essential build tools like a C++ compiler (GCC) and CMake on Ubuntu systems, necessary for compiling C++ extensions.

```bash
sudo apt-get install build-essential cmake
```

--------------------------------

### Virtual Environment Creation with UV

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/appsec/_iast/_taint_tracking/_vendor/pybind11/CMakeLists.txt

Manages the creation and setup of a Python virtual environment using the 'uv' tool for pybind11's testing dependencies.

```cmake
set(PYBIND11_CREATE_WITH_UV
    ""
    CACHE STRING "Create a virtualenv if it doesn't exist")

if(NOT PYBIND11_CREATE_WITH_UV STREQUAL "")
  set(Python_ROOT_DIR "${CMAKE_CURRENT_BINARY_DIR}/.venv")
  if(EXISTS "${Python_ROOT_DIR}")
    if(EXISTS "${CMAKE_BINARY_DIR}/CMakeCache.txt")
      message(STATUS "Using existing venv at ${Python_ROOT_DIR}, remove or --fresh to recreate")
    else()
      # --fresh used to remove the cache
      file(REMOVE_RECURSE "${CMAKE_CURRENT_BINARY_DIR}/.venv")
    endif()
  endif()
  if(NOT EXISTS "${Python_ROOT_DIR}")
    find_program(UV uv REQUIRED)
    # CMake 3.19+ would be able to use COMMAND_ERROR_IS_FATAL
    message(
      STATUS "Creating venv with ${UV} venv -p ${PYBIND11_CREATE_WITH_UV} '${Python_ROOT_DIR}'")
    execute_process(COMMAND ${UV} venv -p ${PYBIND11_CREATE_WITH_UV} "${Python_ROOT_DIR}"
                    RESULT_VARIABLE _venv_result)
    if(_venv_result AND NOT _venv_result EQUAL 0)
      message(FATAL_ERROR "uv venv failed with '${_venv_result}'")
    endif()
    message(
      STATUS
        "Installing deps with ${UV} pip install -p '${Python_ROOT_DIR}' -r tests/requirements.txt"
    )
    execute_process(
      COMMAND ${UV} pip install -p "${Python_ROOT_DIR}" -r
              "${CMAKE_CURRENT_SOURCE_DIR}/tests/requirements.txt" RESULT_VARIABLE _pip_result)
    if(_pip_result AND NOT _pip_result EQUAL 0)
      message(FATAL_ERROR "uv pip install failed with '${_pip_result}'")
    endif()
  endif()
else()
  if(NOT DEFINED Python3_EXECUTABLE
     AND NOT DEFINED Python_EXECUTABLE
     AND NOT DEFINED Python_ROOT_DIR
     AND NOT DEFINED ENV{VIRTUALENV}
     AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/.venv")
    message(STATUS "Autodetecting Python in virtual environment")
    set(Python_ROOT_DIR "${CMAKE_CURRENT_SOURCE_DIR}/.venv")
  endif()
endif()
```

--------------------------------

### Configuring pkg-config Support

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/appsec/_iast/_taint_tracking/_vendor/pybind11/CMakeLists.txt

Generates and installs a .pc file for pkg-config integration. This allows other projects to easily find pybind11 using pkg-config.

```cmake
if(NOT prefix_for_pc_file)
    if(IS_ABSOLUTE "${CMAKE_INSTALL_DATAROOTDIR}")
      set(prefix_for_pc_file "${CMAKE_INSTALL_PREFIX}")
    else()
      set(pc_datarootdir "${CMAKE_INSTALL_DATAROOTDIR}")
      if(CMAKE_VERSION VERSION_LESS 3.20)
        set(prefix_for_pc_file "$\{pcfiledir\}/..")
        while(pc_datarootdir)
          get_filename_component(pc_datarootdir "${pc_datarootdir}" DIRECTORY)
          string(APPEND prefix_for_pc_file "/..")
        endwhile()
      else()
        cmake_path(RELATIVE_PATH ${CMAKE_INSTALL_PREFIX} BASE_DIRECTORY ${CMAKE_INSTALL_DATAROOTDIR}
                   OUTPUT_VARIABLE prefix_for_pc_file)
      endif()
    endif()
  endif()
  join_paths(includedir_for_pc_file "$\{prefix}" "${CMAKE_INSTALL_INCLUDEDIR}")
  configure_file("${CMAKE_CURRENT_SOURCE_DIR}/tools/pybind11.pc.in"
                 "${CMAKE_CURRENT_BINARY_DIR}/pybind11.pc" @ONLY)
  install(FILES "${CMAKE_CURRENT_BINARY_DIR}/pybind11.pc"
          DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/pkgconfig/")
```

--------------------------------

### Allow Direct Package Installation Without Version

Source: https://github.com/datadog/dd-trace-py/blob/main/ci/requirements/README.md

Mark a direct package installation as allowed without a version specifier. Use this sparingly, as it bypasses strict version control and can lead to unexpected behavior.

```yaml
# ci-deps: allow-no-version
pip install twine
```

--------------------------------

### LibFuzzer Runtime Options

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-fuzzing.rst

Configure libFuzzer's execution with these runtime options. This example sets the maximum total runtime, input size limit, and number of parallel jobs.

```bash
$ ./fuzzer corpus/ -max_total_time=60 -max_len=4096 -jobs=4

-max_total_time=N
  Run for N seconds then exit

-max_len=N
  Limit input size to N bytes

-jobs=N
  Run N parallel fuzzing jobs

-artifact_prefix=path/
  Store crash artifacts in this directory
```

--------------------------------

### Clean Build Artifacts with setup.py clean --all

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/troubleshooting.rst

This alternative method is useful when ddtrace is installed from source for local development. It removes build artifacts like egg-info, dist, .eggs, and CMake cache. Omitting --all removes only Rust targets and native extensions.

```bash
$ python -m pip uninstall ddtrace
$ python /path/to/dd-trace-py/setup.py clean --all
$ python -m pip install -e /path/to/dd-trace-py
```

--------------------------------

### Enable Automatic Profiling

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/basic_usage.rst

Import the ddtrace.profiling.auto module to automatically start capturing CPU profiling information. This is the simplest way to enable profiling.

```python
import ddtrace.profiling.auto
```

--------------------------------

### Access Test Runner Container

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-testing.rst

Start the Docker container that provides a pre-built test environment. This container is used for running various test-related commands.

```bash
$ scripts/ddtest
```

--------------------------------

### Build Process Overview

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Illustrates the main stages of the build process, including library downloading and native extension compilation.

```text
riot generate
  └─ pip install -e .
       ├─ build_py  → LibraryDownloader.run()
       │    ├─ CleanLibraries.remove_artifacts()  ← SKIPPED when INCREMENTAL=1
       │    └─ LibDDWafDownload.run()
       └─ build_ext → CustomBuildExt.run()
            ├─ build_rust()          → Rust _native extension
            ├─ build_libdd_wrapper() → libdd_wrapper.so (C++)
```

--------------------------------

### Force .so Extension and Runtime Paths (macOS)

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/datadog/profiling/dd_wrapper/CMakeLists.txt

Forces the .so extension for the library and configures build and install runtime paths for macOS, including fixing library dependencies.

```cmake
# Force .so extension for both Linux and macOS to match Python extension expectations
set_target_properties(dd_wrapper PROPERTIES SUFFIX ".so")
if(APPLE)
    # Include both paths: 3 levels for local builds (lib/ subdirectory), 2 levels for wheel installs
    set_target_properties(dd_wrapper PROPERTIES BUILD_RPATH "@loader_path/../../../native;@loader_path/../../native"
                                                INSTALL_RPATH "@loader_path/../../../native;@loader_path/../../native")
    # Add a post-build step to fix the library dependency to use @rpath
    add_custom_command(
        TARGET dd_wrapper
        POST_BUILD
        COMMAND install_name_tool -change "_native${EXTENSION_SUFFIX}" "@rpath/_native${EXTENSION_SUFFIX}"
                $<TARGET_FILE:dd_wrapper>
        COMMENT "Fixing library dependency to use @rpath")
else()
    # Include both paths: 3 levels for local builds (lib/ subdirectory), 2 levels for wheel installs
    set_target_properties(dd_wrapper PROPERTIES BUILD_RPATH "$ORIGIN/../../../native:$ORIGIN/../../native"
                                                INSTALL_RPATH "$ORIGIN/../../../native:$ORIGIN/../../native")
endif()
```

--------------------------------

### Register Remote Configuration Callback

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/README.md

Installs a callback to receive configuration payloads and periodic calls for a specific product. The RC poller starts automatically if this is the first callback registered and remote configuration is enabled.

```python
from ddtrace.internal.remoteconfig.worker import remoteconfig_poller

callback = MyProductCallback()
remoteconfig_poller.register_callback(
    "MY_PRODUCT",
    callback,
    capabilities=[MyCapabilities.SOME_FLAG],
)
```

--------------------------------

### Define a New Venv Instance in riotfile.py

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-testing.rst

Example of how to create a new Venv instance in riotfile.py to add a new test suite. This is part of the process for adding new test suites using riot.

```python
Venv(
    "test-suite-name",
    python="3.10",
    install_subdir="test_suite_name",
    dependencies=[
        "pytest",
        "pytest-xdist",
    ],
)
```

--------------------------------

### Configure RPATH for Apple and Unix Platforms

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/datadog/profiling/stack/CMakeLists.txt

Sets the INSTALL_RPATH property for the extension target, which is crucial for locating dynamic libraries at runtime. This configuration differs slightly between Apple and Unix systems and also depends on whether testing is enabled and a library installation directory is specified.

```cmake
if(APPLE)
    if(BUILD_TESTING AND LIB_INSTALL_DIR)
        set_target_properties(${EXTENSION_NAME} PROPERTIES INSTALL_RPATH "@loader_path/..;${LIB_INSTALL_DIR}"
                                                   BUILD_WITH_INSTALL_RPATH TRUE)
    else()
        set_target_properties(${EXTENSION_NAME} PROPERTIES INSTALL_RPATH "@loader_path/.." BUILD_WITH_INSTALL_RPATH
                                                                                   TRUE)
    endif()
elseif(UNIX)
    if(BUILD_TESTING AND LIB_INSTALL_DIR)
        set_target_properties(${EXTENSION_NAME} PROPERTIES INSTALL_RPATH "$ORIGIN/..;${LIB_INSTALL_DIR}"
                                                   BUILD_WITH_INSTALL_RPATH TRUE)
    else()
        set_target_properties(${EXTENSION_NAME} PROPERTIES INSTALL_RPATH "$ORIGIN/.." BUILD_WITH_INSTALL_RPATH TRUE)
    endif()
endif()
```

--------------------------------

### Upgrade pip for ddtrace installation

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/troubleshooting.rst

Ensures pip is up-to-date to properly install the ddtrace package. Use this command if pip installation fails due to missing Cython.

```bash
pip install -U pip>=18
```

--------------------------------

### Build and Run Fuzzer Locally (Manual)

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-fuzzing.rst

Navigate to your component's fuzz directory and execute the build script. Then, run the fuzzer executable with specified runtime options.

```bash
cd path/to/your/component/fuzz/ 
./build.sh
/tmp/fuzz/build/your_component/fuzz_your_component -max_total_time=60
```

--------------------------------

### uWSGI Configuration for ddtrace (>=2.0.30)

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/advanced_usage.rst

Configure uWSGI with CLI arguments for automatic instrumentation with ddtrace. Ensure threads and lazy apps are enabled, and import ddtrace.bootstrap.sitecustomize.

```bash
uwsgi --enable-threads --lazy-apps --import=ddtrace.bootstrap.sitecustomize --master --processes=5 --http 127.0.0.1:8000 --module wsgi:app
```

--------------------------------

### Display Help for build_standalone.sh

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/datadog/profiling/docs/Standalone.md

Run the script with no arguments to display its help message and available commands.

```shell
./build_standalone.sh
```

--------------------------------

### List Benchmark Scenarios

Source: https://github.com/datadog/dd-trace-py/blob/main/benchmarks/README.rst

Discover relevant benchmark suites based on git changes, specific files, or all available suites. Output is JSON with scenario names, matched files, and available config variants.

```bash
scripts/run-benchmarks --list
```

```bash
scripts/run-benchmarks --list ddtrace/_trace/span.py
```

```bash
scripts/run-benchmarks --list --all-suites
```

--------------------------------

### Setting Relative Install Directories

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/appsec/_iast/_taint_tracking/_vendor/pybind11/CMakeLists.txt

Configures the installation directory for headers based on Python include directories. This is used when USE_PYTHON_INCLUDE_DIR is enabled.

```cmake
if(USE_PYTHON_INCLUDE_DIR AND DEFINED Python_INCLUDE_DIRS)
  file(RELATIVE_PATH CMAKE_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_PREFIX} ${Python_INCLUDE_DIRS})
elseif(USE_PYTHON_INCLUDE_DIR AND DEFINED PYTHON_INCLUDE_DIR)
  file(RELATIVE_PATH CMAKE_INSTALL_INCLUDEDIR ${CMAKE_INSTALL_PREFIX} ${PYTHON_INCLUDE_DIRS})
endif()
```

--------------------------------

### Run Performance Scenario

Source: https://github.com/datadog/dd-trace-py/blob/main/benchmarks/README.rst

Compares two versions of a library for a given scenario and saves artifacts. Versions can be PyPI packages, git repositories, or local paths.

```bash
scripts/perf-run-scenario <scenario> <baseline-version> <candidate-version> --artifacts <artifacts>
```

--------------------------------

### Python Include Directory Option

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/appsec/_iast/_taint_tracking/_vendor/pybind11/CMakeLists.txt

Configures whether pybind11 headers are installed in the Python include directory instead of the default installation prefix.

```cmake
cmake_dependent_option(
  USE_PYTHON_INCLUDE_DIR
  "Install pybind11 headers in Python include directory instead of default installation prefix"
  OFF "PYBIND11_INSTALL" OFF)
```

--------------------------------

### Build All Components in Release Mode

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/datadog/profiling/docs/Standalone.md

Use the `-- Release all` flag to build all components in release mode. This is useful for creating optimized production builds.

```shell
./build_standalone.sh -- Release all
```

--------------------------------

### Example of _datadog_patch Attribute

Source: https://github.com/datadog/dd-trace-py/blob/main/scripts/integration_registry/README.md

This example demonstrates how the `_datadog_patch` attribute should be set on a patched module within an integration's patch function, as relied upon by the IntegrationRegistryManager.

```python
def patch():
    # ... other patch logic ...
    aiohttp.client._DatadogAioHTTPClientSession.__module__ = "ddtrace.contrib.aiohttp.aiohttp"
    aiohttp.client._DatadogAioHTTPClientSession._datadog_patch = True
    # ... other patch logic ...

```

--------------------------------

### Install CI Dependencies in GitHub Actions

Source: https://github.com/datadog/dd-trace-py/blob/main/ci/requirements/README.md

Install the locked CI dependencies using pip in a GitHub Actions workflow. This ensures that the CI environment uses the exact versions specified.

```yaml
- name: Install CI dependencies
  run: pip install -r ci/requirements/ci.txt
```

--------------------------------

### Control Profiler Lifecycle with API

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/basic_usage.rst

Use the Profiler object to start and stop profiling manually. The start() and stop() methods offer fine-grained control but are not intended for frequent use during application runtime.

```python
from ddtrace.profiling import Profiler

prof = Profiler()
prof.start()

# At shutdown
prof.stop()

```

--------------------------------

### Create build.sh Script for Fuzzing

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-fuzzing.rst

Develop an executable 'build.sh' script to compile the fuzzing binary. This script must be named exactly 'build.sh', use a unique build directory, and append the binary path to a manifest file.

```bash
#!/bin/bash
set -e

TARGET=fuzz_your_component
BUILD_DIR=/tmp/fuzz/build/your_component  # Use unique subdirectory
MANIFEST_FILE=/tmp/fuzz/build/fuzz_binaries.txt

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SOURCE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"

cmake -S "${SCRIPT_DIR}" -B "${BUILD_DIR}" \
      -DSTACK_USE_LIBFUZZER=ON \
      -DCMAKE_C_COMPILER=clang \
      -DCMAKE_CXX_COMPILER=clang++ \
      -DCMAKE_BUILD_TYPE=RelWithDebInfo \
      -DCMAKE_C_FLAGS="-O1 -g -fsanitize=address,undefined" \
      -DCMAKE_CXX_FLAGS="-O1 -g -fsanitize=address,undefined" \
  && cmake --build "${BUILD_DIR}" -j --target $TARGET

# Register binary in manifest (REQUIRED)
BINARY_PATH="${BUILD_DIR}/${TARGET}"
if [ -x "${BINARY_PATH}" ]; then
    echo "${BINARY_PATH}" >> "${MANIFEST_FILE}"
    echo "✅ Registered binary: ${BINARY_PATH}"
else
    echo "❌ Binary not found: ${BINARY_PATH}"
    exit 1
fi
```

--------------------------------

### Manually Start and Finish a Span

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/basic_usage.rst

Manually control the start and finish of spans using tracer.trace() and span.finish(). Ensure span.finish() is called to send the trace to Datadog. API details for Tracer.trace and Span.finish are provided.

```python
span = tracer.trace('operations.of.interest')  # span is started once created

# do some operation(s) of interest in between

# NOTE: be sure to call span.finish() or the trace will not be sent to
#       Datadog
span.finish()

```

--------------------------------

### Build and Run Fuzzer Locally with Docker

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-fuzzing.rst

Use this command to build the fuzzing Docker image and then run an interactive session to test your fuzzer locally.

```bash
$ docker build -f docker/Dockerfile.fuzz -t ddtrace-py-fuzz .
$ docker run --rm -it ddtrace-py-fuzz
```

--------------------------------

### Run Single Benchmark Scenario

Source: https://github.com/datadog/dd-trace-py/blob/main/benchmarks/README.rst

Execute a single benchmark scenario, comparing the latest PyPI version against a local version. Results are stored in the specified artifacts directory.

```bash
scripts/run-benchmarks --scenario span --artifacts ./benchmark-artifacts/
```

--------------------------------

### Configure Custom Context Provider

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/advanced_usage.rst

Replace the default context provider with a custom implementation by configuring the tracer. The custom provider must implement the BaseContextProvider interface.

```python
tracer.configure(context_provider=MyContextProvider())
```

--------------------------------

### Get Current Trace Context

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/advanced_usage.rst

Retrieve the context of the currently active trace. Returns None if no trace is active.

```python
context = tracer.current_trace_context()
```

--------------------------------

### Pybind11 Header Files List

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/appsec/_iast/_taint_tracking/_vendor/pybind11/CMakeLists.txt

Defines the list of header files that constitute the pybind11 library, used for installation and packaging.

```cmake
set(PYBIND11_HEADERS
    include/pybind11/detail/class.h
    include/pybind11/detail/common.h
    include/pybind11/detail/cpp_conduit.h
    include/pybind11/detail/descr.h
    include/pybind11/detail/dynamic_raw_ptr_cast_if_possible.h
    include/pybind11/detail/exception_translation.h
    include/pybind11/detail/function_record_pyobject.h
    include/pybind11/detail/init.h
    include/pybind11/detail/internals.h
    include/pybind11/detail/native_enum_data.h
    include/pybind11/detail/pybind11_namespace_macros.h
    include/pybind11/detail/struct_smart_holder.h
    include/pybind11/detail/type_caster_base.h
    include/pybind11/detail/typeid.h
    include/pybind11/detail/using_smart_holder.h
    include/pybind11/detail/value_and_holder.h
    include/pybind11/attr.h
    include/pybind11/buffer_info.h
    include/pybind11/cast.h
    include/pybind11/chrono.h
    include/pybind11/common.h
    include/pybind11/complex.h
    include/pybind11/conduit/pybind11_conduit_v1.h
    include/pybind11/conduit/pybind11_platform_abi_id.h
    include/pybind11/conduit/wrap_include_python_h.h
    include/pybind11/critical_section.h
    include/pybind11/options.h
    include/pybind11/eigen.h
    include/pybind11/eigen/common.h
    include/pybind11/eigen/matrix.h
    include/pybind11/eigen/tensor.h
    include/pybind11/embed.h
    include/pybind11/eval.h)
```

--------------------------------

### Passing Arguments with ddtrace-run

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/advanced_usage.rst

Pass command-line arguments to your application when using ddtrace-run. This example shows passing arguments to Gunicorn.

```bash
$ ddtrace-run gunicorn myapp.wsgi:application --max-requests 1000 --statsd-host localhost:8125
```

--------------------------------

### uWSGI Configuration for ddtrace (<2.0.30)

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/advanced_usage.rst

Configure uWSGI with CLI arguments for automatic instrumentation with ddtrace, including skip-atexit for older versions. Ensure threads and lazy apps are enabled.

```bash
uwsgi --enable-threads --lazy-apps --skip-atexit --import=ddtrace.bootstrap.sitecustomize --master --processes=5 --http 127.0.0.1:8000 --module wsgi:app
```

--------------------------------

### Enable Product for Remote Configuration

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/README.md

Adds a product to the client payload sent to the agent, signaling the intent to receive configurations for it. Ensure a callback is registered before enabling the product.

```python
remoteconfig_poller.enable_product("MY_PRODUCT")
```

--------------------------------

### Pulling Out Library Version

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-integrations.rst

Example of how to extract the version of an integrated library to conditionally instrument features. This is useful for handling version-specific behaviors.

```python
from ddtrace.contrib.flask.patch import patch_flask


def patch():
    # ...
    try:
        from flask import Flask
    except ImportError:
        return

    # Pull out the version of flask to use when instrumenting volatile features
    try:
        from flask import __version__ as flask_version
        if flask_version.startswith("2.0"):
            # Instrument features specific to Flask 2.0
            pass
        elif flask_version.startswith("1.1"):
            # Instrument features specific to Flask 1.1
            pass
        else:
            # Instrument features for other versions
            pass
    except ImportError:
        # Flask is not installed
        pass

    patch_flask()


def unpatch():
    # ...
    pass
```

--------------------------------

### Benchmark Scenario Definition (Python)

Source: https://github.com/datadog/dd-trace-py/blob/main/benchmarks/README.rst

Example of a Python scenario class inheriting from bm.Scenario, defining configurable variables and a run() generator function.

```python
import bm


class MyScenario(bm.Scenario):
    size: int

    def run(self):
        size = self.size

        def bm(loops):
            for _ in range(loops):
                2 ** size

        yield bm
```

--------------------------------

### Build Using Clang Compiler

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/datadog/profiling/docs/Standalone.md

Override the default compiler (gcc) and use clang for building by including the `--clang` flag. This is often used for testing purposes.

```shell
./build_standalone.sh --clang -- all
```

--------------------------------

### Run All Tests

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing-testing.rst

Execute all test suites for your current changes. This is the simplest way to ensure all tests pass.

```bash
# Run test suites for your current changes
$ scripts/run-tests
```

--------------------------------

### Compile Native Extensions In-Place

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Compiles native extensions in-place, which is necessary when using PYTHONPATH for local development without an editable pip install.

```bash
python setup.py build_ext --inplace
```

--------------------------------

### Project Definition and Build Directory

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/internal/datadog/profiling/dd_wrapper/CMakeLists.txt

Defines the project name, version, and language, and determines the build directory for predictable output.

```cmake
project(
    dd_wrapper
    VERSION 0.1.1
    LANGUAGES CXX)

# Build in a predictable location.  This is needed for setup.py
get_filename_component(dd_wrapper_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../ddtrace.internal.datadog.profiling"
                       ABSOLUTE)
```

--------------------------------

### uWSGI Configuration via INI file

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/advanced_usage.rst

Configure uWSGI using an INI file for automatic instrumentation with ddtrace. Required options include enable-threads, lazy-apps, and import.

```ini
;; uwsgi.ini
[uwsgi]
module = wsgi:app
http = 127.0.0.1:8000

master = true
processes = 5

;; ddtrace required options
enable-threads = 1
lazy-apps = 1
skip-atexit = 1 ; For uwsgi<2.0.30
import=ddtrace.bootstrap.sitecustomize
```

--------------------------------

### Append Scenario to Existing Run

Source: https://github.com/datadog/dd-trace-py/blob/main/benchmarks/README.rst

Add another scenario to a previous benchmark run by reusing the run ID printed at the start of the initial invocation.

```bash
scripts/run-benchmarks --scenario http_propagation_extract --run-id <run-id> --artifacts ./benchmark-artifacts/
```

--------------------------------

### Dry-Run Benchmark Execution

Source: https://github.com/datadog/dd-trace-py/blob/main/benchmarks/README.rst

Preview the execution plan for a benchmark scenario without actually running it.

```bash
scripts/run-benchmarks --dry-run --scenario span
```

--------------------------------

### ddtrace.trace.Tracer

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/api.rst

The Tracer class is the central component for managing spans and traces. It provides methods to start, finish, and manage spans, as well as to configure tracing behavior.

```APIDOC
## ddtrace.trace.Tracer

### Description
The Tracer class is the central component for managing spans and traces. It provides methods to start, finish, and manage spans, as well as to configure tracing behavior.

### Methods
- **`start_span(name, child_of=None, references=None, span_type=None, activate=False, service=None, resource=None, …)`**: Starts a new span.
- **`current_span()`**: Returns the currently active span.
- **`current_context()`**: Returns the currently active trace context.
- **`record_span(span)`**: Records a finished span.
- **`configure(**kwargs)`**: Configures the tracer settings.

### Usage
Instantiate a Tracer or use the global tracer instance to create and manage spans for your application.

### Example
```python
from ddtrace import tracer

# Start a new span
with tracer.trace('my.operation') as span:
    span.set_tag('http.status_code', 200)
    # Do work here

# Accessing the current span
current = tracer.current_span()
if current:
    current.set_tag('user.id', 123)
```
```

--------------------------------

### Run Manual Registry Update Script

Source: https://github.com/datadog/dd-trace-py/blob/main/scripts/integration_registry/README.md

Execute this command from the repository root to update all integration information in the registry.

```bash
python scripts/integration_registry/update_and_format_registry.py
```

--------------------------------

### Full Clean Rebuild Native Extensions

Source: https://github.com/datadog/dd-trace-py/blob/main/hooks/README.md

Forces a complete rebuild of all native extensions, including dependencies. Use this command when the quick rebuild is insufficient.

```bash
pip install -e . --force-reinstall --no-deps --no-build-isolation
```

--------------------------------

### Get DDLogger Instance

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/contributing.rst

Use this to initialize or retrieve a DDLogger object for emitting formatted log messages. Logs should follow established conventions for levels and content.

```python
from ddtrace.internal.logger import get_logger

logger = get_logger(__name__)
```

--------------------------------

### Run Traced Application with ddtrace

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Executes a Python application using the ddtrace command-line runner, ensuring the traced application uses the locally installed ddtrace from the repository.

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

--------------------------------

### Build System Dependencies in pyproject.toml

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/build_system.rst

Defines the build system requirements, including Cython, CMake, and setuptools-rust, as specified in the pyproject.toml file.

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

--------------------------------

### Pybind11 CMake Options

Source: https://github.com/datadog/dd-trace-py/blob/main/ddtrace/appsec/_iast/_taint_tracking/_vendor/pybind11/CMakeLists.txt

Defines various boolean and string options for configuring the pybind11 build process, such as installation behavior, test suite enablement, and Python integration.

```cmake
option(PYBIND11_INSTALL "Install pybind11 header files?" ${PYBIND11_MASTER_PROJECT})
option(PYBIND11_TEST "Build pybind11 test suite?" ${PYBIND11_MASTER_PROJECT})
option(PYBIND11_NOPYTHON "Disable search for Python" OFF)
option(PYBIND11_DISABLE_HANDLE_TYPE_NAME_DEFAULT_IMPLEMENTATION
       "To enforce that a handle_type_name<> specialization exists" OFF)
option(PYBIND11_SIMPLE_GIL_MANAGEMENT
       "Use simpler GIL management logic that does not support disassociation" OFF)
set(PYBIND11_INTERNALS_VERSION
    ""
    CACHE STRING "Override the ABI version, may be used to enable the unstable ABI.")
option(PYBIND11_USE_CROSSCOMPILING "Respect CMAKE_CROSSCOMPILING" OFF)
```

--------------------------------

### Example Span Sampling Rules File Content

Source: https://github.com/datadog/dd-trace-py/blob/main/docs/configuration.rst

Illustrates the structure of a JSON file used for span sampling rules, including service, name, sample_rate, and max_per_second.

```json
[{"sample_rate":0.5,"service":"*-service","name":"my-name-????", "max_per_second":"20"}, {"service":"xy?","name":"a*c"}]
```