docs(python): Lean Agent Tracing hub and richer manual instrumentation - #18926
docs(python): Lean Agent Tracing hub and richer manual instrumentation#18926vgrozdanic wants to merge 2 commits into
Conversation
Move manual span recipes off the Set Up page so the hub matches the lean Node/Cloudflare pattern: bootstrap, stack links, conversations, privacy/streaming options, then a link out for manual work. Co-Authored-By: opencode <noreply@opencode.ai>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
Document start-time common attributes, richer chat/agent/tool recipes, message part types, streaming guidance, and cost derivation notes so manual setup covers dashboards, conversations, and tool errors. Co-Authored-By: opencode <noreply@opencode.ai>
vgrozdanic
changed the title
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2231aaf5b5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| Complex values (messages, tool definitions, arrays) must be **JSON strings** — span attributes only accept primitives. | ||
|
|
||
| Prompt, response, and tool content are treated as PII. They are only captured when `send_default_pii=True` (or per-integration `include_prompts`). See <PlatformLink to="/agent-tracing/#privacy-controls">Privacy Controls</PlatformLink>. |
There was a problem hiding this comment.
When developers follow the manual examples below, start_span(attributes=...) and span.set_data(...) attach prompts, responses, and tool data directly; send_default_pii and an integration's include_prompts setting control attributes added by integrations, but do not remove attributes supplied manually. Consequently, these examples send AI content even when send_default_pii=False or include_prompts=False, contrary to this privacy guarantee. Explicitly condition the sensitive assignments on the configured privacy setting or warn that manual instrumentation must enforce this policy itself.
AGENTS.md reference: AGENTS.md:L81-L83
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
that is kind of obvious since it is manual instrumentation, if you attach it there, it's gonna be there
ArthurKnaus
left a comment
ArthurKnaus
left a comment
There was a problem hiding this comment.
Much better! 🙌 Just a few nits from my side:
| <Expandable title="AI Request span attributes"> | ||
| <Include name="tracing/ai-agents-module/ai-client-span" /> | ||
| </Expandable> | ||
| [Conversations](/product/agents/conversations/) groups multi-turn AI activity into a single replay of messages and tool calls. Use `set_conversation_id()` so every AI span in a chat session shares the same `gen_ai.conversation.id`. |
There was a problem hiding this comment.
Can we link more detailed docs about conversation id? As we have recommendations / limitations about how they should look like.
| ) | ||
| ``` | ||
|
|
||
| Keep system prompts in `gen_ai.system_instructions`, not inside `gen_ai.input.messages`, so they do not pollute conversation titles. |
There was a problem hiding this comment.
so they do not pollute conversation titles feels a bit out of place and could leave the reader confused as it requires knowledge about the conversation title generation.
| Messages use `{role, parts}` where each part has a `type`. Common types: | ||
|
|
||
| - `text` — user-visible content | ||
| - `reasoning` — internal thinking (not shown in the user-facing Conversations view) | ||
| - `tool_call` / `tool_call_response` — tool invocations linked by a shared `id` |
There was a problem hiding this comment.
I would extend on this, unknown types will not be displayed / exposed prominently in the UI. They remain hidden in the raw attribute values.
| except Exception as exc: | ||
| span.set_status("internal_error") | ||
| span.set_data("error.type", type(exc).__name__) | ||
| raise | ||
| ``` | ||
|
|
||
| Marking failed tools with an error status populates the Tool Errors widget. | ||
|
|
||
| <Expandable title="Execute Tool span attributes"> | ||
| <Include name="tracing/ai-agents-module/execute-tool-span" /> | ||
| </Expandable> |
There was a problem hiding this comment.
should we also recommend creating an issue for errors?
2 participants
DESCRIBE YOUR PR
Python Agent Tracing setup matches the lean Node/Cloudflare hub: bootstrap, stack links, conversations, privacy/streaming options, then a link out for manual work. Manual instrumentation lives on its own page with start-time common attributes, fuller chat/agent/tool recipes (system instructions, tool definitions, response IDs, cache tokens, tool errors), message part types for reasoning and tool calls, streaming guidance without a consume-the-stream sample, and a note that Sentry derives cost from model + usage.
Product and integration links that pointed at the old in-hub span anchors now target the manual page.
IS YOUR CHANGE URGENT?
PRE-MERGE CHECKLIST