ddtrace 3.12.0

on Python PyPI

Estimated end-of-life date, accurate to within three months: 08-2026
See the support level definitions for more information.

Prelude

AI Guard is an upcoming Datadog security product currently under active design and development. Note: The Python SDK is released as a technical preview. Functionality and APIs are subject to change, and backward compatibility is not guaranteed at this stage.

Upgrade Notes

• profiling: timeline view is now enabled by default (DD_PROFILING_TIMELINE_ENABLED=True). This provides visualization of profiling data with timing information.

Deprecation Notes

• tracing
  • ddtrace.settings.__init__ imports are deprecated and will be removed in version 4.0.0.
  • Deprecate the non_active_span parameter in the HTTPPropagator.inject method. HTTPPropagator.inject(context=...) should be used to inject headers instead.
• profiling: Windows support is removed. Please file an issue if you want this reverted.

New Features

• App and API Protection (AAP): Introduce a public Python SDK that provides programmatic access to AI Guard’s public endpoint.
• asgi: Adds tracing on websocket spans with DD_TRACE_WEBSOCKET_MESSAGES_ENABLED, which replaces DD_TRACE_WEBSOCKET_MESSAGES.
• CI Visibility: This introduces an alternative method for collecting and sending test spans. In this mode, the CIVisibility tracer is kept separate from the global ddtrace tracer, which helps avoid interference between test and non-test tracer configurations. This mode is currently experimental, and can be enabled by setting the environment variable DD_CIVISIBILITY_USE_BETA_WRITER to true.
• crewai: Introduces APM and LLM Observability tracing support for CrewAI Flow kickoff/kickoff_async calls, including tracing internal flow method execution.
• LLM Observability
  • Adds support for collecting tool definitions, tool calls and tool results in the Anthropic integration.
  • Increases span event size limit from 1MB to 5MB.
  • Records agent manifest information for LangGraph compiled graphs.
  • add ability to drop spans by having a SpanProcessor return None.
  • mcp: Adds distributed tracing support for MCP tool calls across client-server boundaries by default.
    To disable distributed tracing for mcp, set the configuration: DD_MCP_DISTRIBUTED_TRACING=False for both the client and server.

Bug Fixes

• AAP
  • resolves a bug where ASGI middleware would not catch the BlockingException raised by AAP because it was aggregated in an ExceptionGroup
  • This fix resolves an issue where a malformed package would prevent reporting of other correctly formed packages to Software Composition Analysis
  • This fix resolves an issue where the route parameter was not being correctly handled in the Django path function.
• CI Visibility: This fix resolves an issue where using the pytest skipif marker with the condition passed as a keyword argument (or not provided at all) would cause the test to be reported as failed, in particular when the flaky or pytest-rerunfailures were also used.
• ddtrace_api: Fixes a bug in the ddtrace_api integration in which patch() with no arguments, and thus patch_all(), breaks the integration.
• django: fix incorrect component tag being set for django orm spans
• dynamic instrumentation: extended captured value redaction in mappings with keys of type bytes.
• openai: Resolves an issue where an uninitialized OpenAI/AsyncOpenAI client would result in an AttributeError.
• pydantic_ai: This fix resolves an issue where enabling the Pydantic AI for pydantic-ai-slim >= 0.4.4 would fail. See this issue <https://github.com/DataDog/dd-trace-py/issues/14161>_ for more details.
• tracing
  • Resolves an issue where sampling rules with null values for service, resource, or name would not match any spans, since these fields are always exported as strings and never null. Now, null and unset fields are treated the same. Ex: DD_TRACE_SAMPLING_RULES='\[{"resource": null, "sample_rate": 1}\]' will be equivalent to DD_TRACE_SAMPLING_RULES='\[{"sample_rate": 1}\]'.
  • Fix inconsistent trace sampling during partial flush (traces >300 spans). Now correctly applies sampling rules to the root span instead of a random payload span. Since traces are sampled only once, using the wrong span could bypass sampling rules and cause the agent to apply default rate limits. Fixes regression introduced in v2.8.0.
• kafka: This fix resolves an issue where the list_topics call in the Kafka integration could hang indefinitely. The integration now sets a 1-second timeout on `list_topics calls and caches both successful cluster ID results and failures (with a 5-minute retry interval) to prevent repeated slow metadata queries.
• Code Security (IAST): Fixes Gevent worker timeouts by preloading IAST early and refactoring taint sink initialization to remove legacy import-based triggers, ensuring reliable instrumentation.
• LLM Observability
  • Fixes a bug where code execution outputs done through google-genai would result in no output messages on the LLM Observability llm span.
  • langgraph: resolves ModuleNotFoundError errors when patching langgraph>=0.6.0
  • openai: fixed an issue when using the openai responses api with openai>=1.66.0,<1.66.2 would result in an AttributeError.
• Remote Config: Eagerly query Remote Config upon process startup to ensure timely configuration updates.
• Flares: Fixes to make the tracer flares match the spec.

Other Changes

• tracing: Improves debug logging in HTTPPropagator.inject method to help diagnose issues with sampling decisions.
• profiling: removed redundant sampling code from memory profile, improving overhead and accuracy. Sizes and counts of objects allocated since the last profile are now reported more accurately. ENV: DD_PROFILING_MAX_EVENTS is deprecated and does nothing. Use DD_PROFILING_HEAP_SAMPLE_SIZE to control sampling frequency of the memory profiler.