docs(api): reference docs for tracing ingest/query and create-simple-trace endpoints#4174
Open
docs(api): reference docs for tracing ingest/query and create-simple-trace endpoints#4174
Conversation
…ce endpoints Reference pages for these endpoints had no description, no per-field prose, and no example payload, making it non-obvious what shape to send. Customers had to reverse-engineer the request body from the generated schema tree. Adds: - Route docstrings on `ingest_spans`, `query_spans`, and `create_simple_trace` explaining when to use each, the body shape, and how to interpret the response (in particular, that `count < N submitted` signals partial failure). - Field descriptions on `OTelTracingRequest`, `OTelLinksResponse`, `OTelTracingResponse`, `SimpleTraceCreateRequest`, and `SimpleTraceResponse` so the OpenAPI schema tables are self-explanatory. - A worked JSON example on `ingest_spans` and guidance on choosing `ingest-spans-rpc` vs `create-simple-trace`. FastAPI picks docstrings + `Field(description=...)` up automatically when regenerating `openapi.json`, and the daily `33-update-api-docs` workflow regenerates the Docusaurus MDX from that. No docs-side changes needed.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
dosubot
Bot
added
the
size:L
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
Contributor
Railway Preview Environment
|
jp-agenta
approved these changes
Apr 17, 2026
5 tasks
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
The reference pages for
/tracing/spans/ingest,/tracing/spans/query, and/preview/tracing/traces/(create_simple_trace) had no description, no per-field prose, and no example payload — the generated schema trees alone don't tell you what to send or when to use which endpoint. A customer hit this while trying to migrate traces between two Agenta instances: they reverse-engineered the body shape, then lost every span silently to a validation edge case that the docs gave them no way to anticipate (see AGE-3734, AGE-3735).This PR adds route docstrings and Pydantic
Field(description=...)so the next person reading the reference can actually build a valid payload.Changes
ingest_spans: docstring explainingspansvstracesbody shape, attribute namespacing (ag.*), and thatcount < N submittedmeans partial failure. Includes a worked JSON example.query_spans: docstring explainingfocus="trace"vsfocus="span", windowing, and confirming thetracesshape round-trips intoingest.create_simple_trace: docstring with an explicit "use this vs/tracing/spans/ingest" guide — single-span helper for evaluator outputs, annotations, feedback, and standalone completions.OTelTracingRequest,OTelLinksResponse,OTelTracingResponse,SimpleTraceCreateRequest,SimpleTraceResponse.FastAPI reads docstrings and
Field(description=...)when regeneratingopenapi.json. The daily.github/workflows/33-update-api-docs.ymlworkflow pulls that spec and regenerates the Docusaurus MDX — so no docs-side changes are needed in this PR; the reference pages update on the next scheduled run.Related
query ↔ ingestschema asymmetry onag.metrics.duration.cumulativeunsupportedThese are the underlying bugs surfaced by the same customer report; this PR only addresses the reference-doc gap so the endpoint is usable once the fixes ship.
Test plan
uvx ruff formatanduvx ruff checkpass on the four changed filesast.parsedocs/reference/api/ingest-spans-rpc.api.mdx,query-spans-rpc.api.mdx, andcreate-simple-trace.api.mdxwith the new descriptions