DOCSEARCHbyAlgolia
Submit Docs

dd-trace-go

repository·main·Indexed 21 days ago

https://github.com/datadog/dd-trace-go

Datadog's Go client libraries providing Application Performance Monitoring (APM), Continuous Profiling, and Application Security Management (ASM) for Go applications. The repository includes the v2 tracer, the datadog-lambda-go v2 package for AWS Lambda instrumentation, an APIM Callout service for Azure and Boomi gateways, and an ASM Service Extension for Google Cloud Service Extensions.

Tokens
80.4K
Snippets
278
Records
379
Agent score
75%

What's inside dd-trace-go

  1. Overview of Datadog Go Client Libraries

    main

    The dd-trace-go repository provides client-side components for the Datadog product suite:

    • Application Performance Monitoring (APM): Uses github.com/DataDog/dd-trace-go/v2/ddtrace/tracer to trace requests across web servers, databases, and microservices. Automatic instrumentation for common libraries is available in the github.com/DataDog/dd-trace-go/v2/contrib package.
    • Continuous Profiling: Uses github.com/DataDog/dd-trace-go/v2/profiler to collect CPU, memory, and synchronization profiles to identify bottlenecks.
    • Application Security Management (ASM): Integrated into the APM tracer to detect and protect against application-level attacks. Enabled via DD_APPSEC_ENABLED=true.

  2. Overview of Datadog Test Optimization (Civisibility)

    main

    The internal/civisibility package implements Datadog's Test Optimization for Go. It is designed to improve CI efficiency by bootstrapping tracing and log streaming, providing manual test lifecycle APIs, and auto-instrumenting the standard Go testing package.

    Key capabilities include:

    • Intelligent Test Runner (ITR): Optimizes test execution based on repository changes.
    • Flake Management: Supports early flake detection and flaky retries.
    • Impacted Tests: Identifies and runs only tests affected by code changes.
    • Test Management: Provides subtest-level directives (quarantine, disable, retry) and code coverage integration.
    • CI Integration: Normalizes metadata from various CI providers (GitHub Actions, Jenkins, etc.) and streams logs to Datadog.

  4. Use Config Audit to track DD_* environment variable migrations

    main
    The configaudit tool is an inventory utility used to report the migration status of DD_* environment-variable configurations. It identifies whether variables have been migrated to internal/config or if legacy direct reads still exist in the codebase. This is primarily used to track the migration backlog and ensure that legacy reads are replaced with calls to the internal/config singleton.

  5. What is the Config Inverter tool?

    main

    The Config Inverter is a development tool used to transform the contents of supported_configurations.json into Go code.

    This file contains the list of known environment variables used in dd-trace-go, including their versions, aliases, and telemetry keys. This mechanism is used by the internal/env package to ensure that only known environment variables are read via env.Lookup or env.Get.

    Important: Using os.Getenv or os.LookupEnv is forbidden by linter rules; you must use the internal/env package. If an environment variable is not present in the supported_configurations.json file, the generated code will not recognize it and will always return an empty string "".

  6. What is Orchestrion and how does it work?

    main

    Orchestrion is a tool that enables auto-instrumentation for dd-trace-go at compile time. It uses Aspect-Oriented Programming (AOP) and the Go toolexec command to identify specific nodes in your Go source code and automatically insert instrumentation.

    Instrumentation is driven by the imports present in the orchestrion.tool.go file at the project's root.

    For instructions on how to use Orchestrion in your own project, refer to the official user guide.

  7. Understand Auto Release Tagger idempotency

    main

    The autoreleasetagger is designed to be idempotent.

    • Successful Re-run: If you run the tool twice with the same --version, it is a no-op (exit 0, no new commits, no duplicate tags) provided all expected tags already point at HEAD and the version file matches.
    • Partial State Recovery: If a previous run was interrupted (e.g., the root tag was created but contrib tags were not), the tool will detect the incomplete state and repair the missing tags without creating a new commit.

    This allows CI pipelines to safely retry on transient failures.

  8. Understand Config Audit output categories

    main

    The audit tool categorizes the status of environment variables into three types:

    StatusMeaning
    UNMIGRATEDThe variable is read outside internal/config and is not yet handled by loadConfig. These represent the migration backlog.
    STILL_READThe variable is migrated, but at least one caller outside internal/config is still reading it directly. Migration is incomplete; legacy reads should be replaced with calls to the singleton.
    UNTRACKEDThe variable is read in code but missing from internal/env/supported_configurations.json. This usually indicates a bug that requires adding the variable to the JSON or removing the read.

  9. How contrib integrations work (Concept)

    main
    Datadog contrib packages use an embedding pattern to provide seamless instrumentation. When you import a contrib package instead of the original, the functions provided have the same signature as the original library. However, the returned objects are wrappers that embed the original return values. This allows your existing code to function normally while Datadog traces the operations in the background.

  10. Understand the Instrumentation Telemetry Client Architecture

    main

    The dd-trace-go instrumentation telemetry client is designed to collect and ship telemetry data (integrations, configuration, dependencies, products, logs, and metrics) to a backend or Datadog Agent.

    Data Flow

    1. Data Sources: Various components (Integrations, Configuration, Dependencies, Products, Logs, Metrics) collect raw data.
    2. Client: Acts as the orchestrator. It manages configuration and gathers data from all sources.
    3. Mapper: Transforms data from sources into specific payload types like app-started, app-closing, heartbeat, extended-heartbeat, and message-batch.
    4. Flush & Queue: Data is flushed from sources. If the Writer fails, data is moved to a Queue to prevent loss.
    5. Writer: Sends the serialized transport.Payload to the backend or the Datadog Agent.

  11. How subtest directives and retries work

    main

    The subtest management feature allows Go subtests to honor Datadog Test Management directives while maintaining parent behavior. The system uses a hierarchical testIdentity (module, suite, base name, full name) to perform lookups.

    Lookup Logic: When a subtest is executed, the system looks for an exact match for its identity. If no exact match is found, it falls back to ancestor segments (e.g., if TestParent/Sub1/Sub2 has no directive, it checks TestParent/Sub1, then TestParent).

    Retry Ownership (Attempt-to-Fix): To prevent double retries and conflicting telemetry, the system enforces strict ownership rules:

    1. Parent only: The parent orchestrates retries. Subtests inherit tagging but test.is_retry is false for child spans.
    2. Subtest only: The parent remains neutral; the subtest wraps itself and emits its own retry spans.
    3. Parent & Subtest: The parent takes precedence. The child inherits attempt-to-fix tagging but emits zero retry tags to ensure telemetry is only counted once.
    4. Parent Quarantine + Attempt-to-Fix: The parent remains the retry owner. Children inherit the quarantine tag but do not emit retry spans.

  12. How Go `testing` auto-instrumentation works

    main

    Civisibility automatically instruments testing.M, testing.T, and testing.B to capture execution metadata and coordinate with the Datadog backend.

    Subtest Ownership and Directives

    Subtests resolve directives (like quarantine or retry) using hierarchical identity (e.g., TestParent/SubChild). The package implements specific Attempt-to-fix ownership rules to determine which level of the test hierarchy manages retries:

    1. Parent-only directives: The parent orchestrates retries and tags success/failure. Children inherit tagging but do not emit their own retry spans.
    2. Child-only directives: The subtest is wrapped locally (if the feature flag is enabled and an exact match exists), leaving the parent neutral.
    3. Conflict (Parent + Child): The parent wins. Subtests receive tags but do not run retries.
    4. Quarantine + Attempt-to-fix: The parent remains the retry owner and inherits quarantine tags. If a parent is quarantined but not requesting attempt-to-fix, children are free to execute their own retries if explicitly configured.

    Coverage Capture

    The coverage/ component builds code coverage payloads and uploads them. Per-test Go coverage includes:

    • files[].filename
    • files[].bitmap (raw Go FileBitmap bytes, if line coverage is available)