{"id":2466,"library":"ddapm-test-agent","title":"Datadog APM Test Agent","description":"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.","status":"active","version":"1.46.0","language":"en","source_language":"en","source_url":"https://github.com/Datadog/dd-apm-test-agent","tags":["datadog","apm","testing","observability","llm","cli-tool","agent-mock"],"install":[{"cmd":"pip install ddapm-test-agent","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"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.","symbol":"ddapm-test-agent","correct":"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."}],"quickstart":{"code":"# Start the basic test agent\nddapm-test-agent\n\n# Or, for LLM observability with Claude hooks\nlapdog start\n\n# Your APM client library (e.g., dd-trace-py) should be configured\n# to send traces to the agent's default port (e.g., localhost:8126).\n# Example for dd-trace-py (ensure DD_AGENT_HOST and DD_TRACE_AGENT_PORT are set appropriately)\n# export DD_AGENT_HOST=localhost\n# export DD_TRACE_AGENT_PORT=8126\n# python your_instrumented_app.py","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.40.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.","message":"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.","severity":"deprecated","affected_versions":">=1.38.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.44.0"},{"fix":"Upgrade to `ddapm-test-agent` version 1.45.1 or later to resolve Python 3.8/3.9 compatibility issues.","message":"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.","severity":"gotcha","affected_versions":"==1.45.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}