●Change8

Migrating to Datadog SDK v4.8.0

Version v4.8.0 introduces 2 breaking changes. This guide details how to update your code.

Released: 4/30/2026

2
Breaking Changes
11
Migration Steps
30
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

claude_agent_sdkDD_TRACE_RAY_SUBMISSION_SPANS_ENABLEDray.job.submitray.jobDD_TRACE_INFERRED_PROXY_SERVICES_ENABLEDDD_TRACE_INFERRED_SPANS_ENABLEDddtrace.contrib.dbapi.TracedConnectionddtrace.contrib.dbapi.TracedCursorddtrace.contrib.dbapi_async.TracedAsyncConnectionDD_AI_GUARD_BLOCKAIGuardAbortErrorDD_TEST_OPTIMIZATION_MANIFEST_FILEDD_TEST_OPTIMIZATION_PAYLOADS_IN_FILESExperimentRun.as_dataframeLLMObs.submit_evaluationLLMObs.get_spansDD_API_KEYDD_APP_KEYDD_TRACE_WRAP_SPAN_NAME_INCLUDE_CLASSDD_WRAP_SPAN_NAME_INCLUDE_CLASSDD_AI_GUARD_BLOCKgoogle_cloud_pubsubDD_GOOGLE_CLOUD_PUBSUB_PROPAGATION_AS_SPAN_LINKSOTEL_TRACES_EXPORTERddtrace.appsec.ai_guard.integrations.litellm.DatadogAIGuardGuardraillitellmazure_cosmosllama-index-coreDD_AGENTLESS_LOG_SUBMISSION_ENABLEDDD_LOGS_INJECTION

Breaking Changes

●Issue #1

Tool span resource names for claude_agent_sdk have changed from the tool name (e.g. "Read", "Bash") to "claude_agent_sdk.tool". Users relying on tool resource names must update them to include the specific tool name as a suffix (e.g. "claude_agent_sdk.tool.Read").

●Issue #2

Ray submission tracing configuration has changed: `ray.job.submit` spans are removed. Ray job submission outcome is now reported on the existing `ray.job` span via `ray.job.submit_status`.

Migration Steps

  1. 1
    If you rely on tool resource names for `claude_agent_sdk` spans, update your resource name matching logic to expect the format `claude_agent_sdk.tool.<tool_name>` instead of just `<tool_name>`.
  2. 2
    If you were using `DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED`, rename it to `DD_TRACE_INFERRED_SPANS_ENABLED` to avoid deprecation warnings.
  3. 3
    If you were using the `pin` parameter in DBAPI traced connections/cursors, remove it and manage configuration via integration configuration or environment variables.
  4. 4
    If using RAGAS evaluations, update your code to manually submit evaluation results.
  5. 5
    To enable tracing of Ray submission spans (`task.submit`, `actor_method.submit`), set the environment variable `DD_TRACE_RAY_SUBMISSION_SPANS_ENABLED=true`.
  6. 6
    To control whether inferred Google Cloud Pub/Sub push spans link to the producer trace or start a new trace, use `DD_GOOGLE_CLOUD_PUBSUB_PROPAGATION_AS_SPAN_LINKS`.
  7. 7
    To enable AI Guard blocking behavior locally based on Datadog UI settings, ensure `DD_AI_GUARD_BLOCK` is set to `True` (default) or unset. Set to `False` for monitor-only mode.
  8. 8
    To enable tracing via `@tracer.wrap` to include the class name in the span name, set `DD_TRACE_WRAP_SPAN_NAME_INCLUDE_CLASS=true`.
  9. 9
    If using LLM Observability span retrieval, ensure `DD_API_KEY` and `DD_APP_KEY` are configured for API access.
  10. 10
    If using CI Visibility log submission, set `DD_AGENTLESS_LOG_SUBMISSION_ENABLED=true` for agentless setups or `DD_LOGS_INJECTION=true` when using the Datadog Agent.
  11. 11
    If you require OTLP HTTP/JSON export, set the environment variable `OTEL_TRACES_EXPORTER=otlp`.

Release Summary

This release introduces significant new features across AI Observability (LLM, AI Guard, ASM), CI Visibility (Bazel offline support), and various integrations like Ray, Pub/Sub, and LlamaIndex. It also includes several breaking changes related to resource naming in claude_agent_sdk and Ray tracing configuration.

Need More Details?

View the full release notes and all changes for Datadog SDK v4.8.0.

View Full Changelog