Datadog APM Test Agent

1.46.0 · active · verified Fri Apr 10

The Datadog APM Test Agent is a Python-based utility that simulates the Datadog Agent for local testing and development of APM client libraries. It allows developers to capture, inspect, and validate traces, snapshots, and other observability data without requiring a full Datadog Agent setup. The current version is 1.46.0, with a frequent release cadence, often multiple times a month, for new features and bug fixes.

Warnings

gotcha Since v1.40.0, LLM Observability data forwarding to Datadog is enabled by default. If you are using the test agent for local development and do not wish to send LLM-related data to your Datadog account, you must explicitly disable this feature.
Fix: Set the `DISABLE_LLMOBS_DATA_FORWARDING` environment variable to `true`, or use the `--disable-llmobs-data-forwarding` command-line argument when starting the agent.
deprecated The VCR dependency has been removed in v1.38.0. The test agent now produces and primarily uses JSON cassettes. Existing VCR cassettes are converted to JSON on first use and then removed. Support for legacy VCR cassettes will be fully removed in version 2.0.0.
Fix: Migrate any existing VCR-specific cassette logic or rely on the agent's automatic conversion to JSON cassettes. Plan for complete removal of VCR cassette support in future major versions.
gotcha For Claude Code API calls, the recommended method changed from relying on `ANTHROPIC_BASE_URL` to using the `ddapm-test-agent-run claude` CLI launcher in v1.44.0. The new launcher also includes a Javascript fetch interceptor.
Fix: Switch to `ddapm-test-agent-run claude` for routing Claude Code API calls through the test agent proxy to ensure proper interception and instrumentation.
gotcha An issue causing `TypeError` exceptions on Python 3.8 and 3.9 when running the test agent or `lapdog` was fixed in v1.45.1. Users on version 1.45.0 might encounter these errors.
Fix: Upgrade to `ddapm-test-agent` version 1.45.1 or later to resolve Python 3.8/3.9 compatibility issues.

Install

pip install ddapm-test-agent Install stable version

Imports

ddapm-test-agent
```
This library is primarily a command-line interface (CLI) tool and is not typically imported into Python code. Its functionality is accessed by running the `ddapm-test-agent` or `lapdog` commands in a terminal.
```
The `ddapm-test-agent` package provides executable commands, not Python modules for direct import and usage within an application's code. Interaction is typically via shell commands or configured client libraries.

Quickstart

To quickly start the Datadog APM Test Agent, simply run `ddapm-test-agent` in your terminal. For LLM Observability features, especially with Claude Code, use `lapdog start`. Ensure your APM client library is configured to point to the test agent's default host (localhost) and port (e.g., 8126 for traces) via environment variables or configuration.

# Start the basic test agent
ddapm-test-agent

# Or, for LLM observability with Claude hooks
lapdog start

# Your APM client library (e.g., dd-trace-py) should be configured
# to send traces to the agent's default port (e.g., localhost:8126).
# Example for dd-trace-py (ensure DD_AGENT_HOST and DD_TRACE_AGENT_PORT are set appropriately)
# export DD_AGENT_HOST=localhost
# export DD_TRACE_AGENT_PORT=8126
# python your_instrumented_app.py

view raw JSON →