Sync LLM Observability API documentation with Go implementation #33632
+54
−11
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Updated API documentation to match the Go implementation (source of truth). ## Changes by Endpoint ### POST /api/intake/llm-obs/v1/trace/spans 📄 **Doc:** `content/en/llm_observability/instrumentation/api.md` 🔧 **Handler:** `TraceHandler.CreateSpans` (`internal/adapters/handlersv1/http/trace.go`) | Change | Field | Details | |--------|-------|---------| | ✅ Added | `ml_app_version` | string (in SpansPayload) | | ✅ Added | `model_name` | string (in Meta) | | ✅ Added | `model_provider` | string (in Meta) | | ✅ Added | `model_version` | string (in Meta) | | ✅ Added | `tool_calls` | array of ToolCall (in Message) | | ✅ Added | `tool_results` | array of ToolResult (in Message) | | ✅ Added | `tool_definitions` | array of ToolDefinition (in Meta) | | ✅ Added | `ranking` | int (in Document) | | ✅ Added | `metadata` | object (in Document) | | ✅ Added | `name` | string (in Prompt, primary field) | | 🔄 Type fix | `metrics` | Updated to flexible map structure | | 🔄 Required fix | `content` | Made optional in Message | --- ### POST /api/intake/llm-obs/v2/eval-metric 📄 **Doc:** `content/en/llm_observability/instrumentation/api.md` 🔧 **Handler:** `EvalMetricsHandlerV2.CreateEvalMetrics` (`internal/adapters/handlersv1/http/eval_metric.go`) | Change | Field | Details | |--------|-------|---------| | ✅ Added | `ml_app_version` | string (in EvalMetric) | | ✅ Added | `trace_id` | string (top-level in EvalMetric) | | ✅ Added | `span_id` | string (top-level in EvalMetric) | | ✅ Added | `metadata` | object (in EvalMetric) | | 🔄 Required fix | `span_id`, `trace_id` | Marked as required in SpanContext | | 🔄 Required fix | `key`, `value` | Marked as required in TagContext | --- ### POST /api/v2/llm-obs/v1/spans/events/search 📄 **Doc:** `content/en/llm_observability/evaluations/export_api.md` 🔧 **Handler:** `TraceHandler.SearchSpans` (`internal/adapters/handlersv2/http/trace.go`) | Change | Field | Details | |--------|-------|---------| | 🔄 Type fix | `limit` | integer → int64 (in PageQuery) | --- ### GET /api/v2/llm-obs/v1/spans/events 📄 **Doc:** `content/en/llm_observability/evaluations/export_api.md` 🔧 **Handler:** `TraceHandler.ListSpans` (`internal/adapters/handlersv2/http/trace.go`) | Change | Field | Details | |--------|-------|---------| | 🔄 Type fix | `start_ns` | integer → uint64 (in SearchedSpan) | --- ## Summary | Change Type | Count | |-------------|-------| | Fields added | 14 | | Type fixes | 3 | | Required fixes | 1 | | **Total** | **18** | ## Key Updates - **Tool support**: Added `tool_calls` and `tool_results` to Message type for LLM function calling - **Model tracking**: Added model_name, model_provider, model_version fields to Meta - **Tool definitions**: Added tool_definitions array to Meta for documenting available tools - **RAG support**: Added ranking and metadata fields to Document type - **Flexible metrics**: Updated Metrics to reflect flexible map structure accepting custom keys - **Prompt identifier**: Changed primary field from `id` to `name` (kept `id` as deprecated) - **Version tracking**: Added ml_app_version to both SpansPayload and EvalMetric - **Required fields**: Fixed required status for SpanContext and TagContext fields 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Contributor
Preview links (active after the
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Updated API documentation to match the Go implementation (source of truth).
Changes by Endpoint
POST /api/intake/llm-obs/v1/trace/spans
📄 Doc:
content/en/llm_observability/instrumentation/api.md🔧 Handler:TraceHandler.CreateSpans(internal/adapters/handlersv1/http/trace.go)ml_app_versionmodel_providermodel_versiontool_callsmetadatanamePOST /api/intake/llm-obs/v2/eval-metric
📄 Doc:
content/en/llm_observability/instrumentation/api.md🔧 Handler:EvalMetricsHandlerV2.CreateEvalMetrics(internal/adapters/handlersv1/http/eval_metric.go)ml_app_versionspan_id,trace_idPOST /api/v2/llm-obs/v1/spans/events/search
📄 Doc:
content/en/llm_observability/evaluations/export_api.md🔧 Handler:TraceHandler.SearchSpans(internal/adapters/handlersv2/http/trace.go)limitGET /api/v2/llm-obs/v1/spans/events
📄 Doc:
content/en/llm_observability/evaluations/export_api.md🔧 Handler:TraceHandler.ListSpans(internal/adapters/handlersv2/http/trace.go)start_nsSummary
Key Updates
tool_callsandtool_resultsto Message type for LLM function callingidtoname(keptidas deprecated)🤖 Generated with Claude Code
What does this PR do? What is the motivation?
Merge instructions
Merge readiness:
For Datadog employees:
Your branch name MUST follow the
<name>/<description>convention and include the forward slash (/). Without this format, your pull request will not pass CI, the GitLab pipeline will not run, and you won't get a branch preview. Getting a branch preview makes it easier for us to check any issues with your PR, such as broken links.If your branch doesn't follow this format, rename it or create a new branch and PR.
[6/5/2025] Merge queue has been disabled on the documentation repo. If you have write access to the repo, the PR has been reviewed by a Documentation team member, and all of the required checks have passed, you can use the Squash and Merge button to merge the PR. If you don't have write access, or you need help, reach out in the #documentation channel in Slack.
Additional notes