docs: update observability overview#1070
Merged
Merged
Conversation
replace concept and why pages with first-trace update sidebar flow to overview setup first-trace
clarify value for AI agent builders
use step sections and shorter onboarding flow
disable toc rendering below 1440px
|
This comment has been minimized.
This comment has been minimized.
Contributor
📝 WalkthroughWalkthroughRemoves two legacy observability docs, adds a new mental-model page, restructures overview and setup into a step-based onboarding flow, updates sidebar entries, and changes TOC rendering/styles to hide TOC on viewports ≤1440px and remove mobile TOC rendering. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 1 | ❌ 2❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
website/observability/setup.md (1)
151-163:⚠️ Potential issue | 🟠 MajorServerless code example has an unused import and a missing import.
honoServer(line 153) is imported but never used in the snippet.VoltOpsClient(line 158) is used but not imported.This will confuse readers trying to copy-paste the example.
Proposed fix
-import { VoltAgent, serverlessHono } from "@voltagent/core"; -import { honoServer } from "@voltagent/server"; +import { VoltAgent, VoltOpsClient, serverlessHono } from "@voltagent/core";
🤖 Fix all issues with AI agents
In `@website/observability/setup.md`:
- Line 30: The MD001 heading-increment issue is caused by the "### Add
Environment Variables" heading directly under the top-level "# Setup"; locate
the "### Add Environment Variables" heading (inside the StepSection) and change
it to "## Add Environment Variables" so it increments from h1→h2, or if
StepSection already renders as h2 instead, add a short linter-friendly comment
or disable (e.g., an MD001 exception) explaining that StepSection renders as h2;
reference the "### Add Environment Variables" heading and the surrounding
StepSection when making the change.
In `@website/src/css/custom.css`:
- Around line 5342-5351: The global media rule currently hides multiple TOC
selectors including .theme-doc-toc-mobile which conflicts with the CSS module
rule .tocColumn and prevents the mobile/collapsible TOC fallback discussed in
index.tsx from appearing at 997–1440px; to fix, remove or narrow the selectors
in this `@media` (max-width: 1440px) block so it no longer includes
.theme-doc-toc-mobile (and any selector that overlaps .tocColumn from
styles.module.css), or delete the entire rule if redundant, ensuring the
mobile/collapsible TOC can be rendered for mid-size screens while keeping other
intended hides intact.
In `@website/src/theme/DocItem/Layout/index.tsx`:
- Line 23: The mobile TOC is being disabled by setting const mobile = undefined,
which combined with the CSS hiding desktop TOC at max-width:1440px removes TOC
for 997–1440px; replace the placeholder with runtime breakpoint logic that
enables the mobile/collapsible TOC as a fallback (or match Docusaurus default):
e.g. compute mobile from the viewport (e.g. use window.innerWidth or a
useWindowSize/useBreakpoint hook) and set mobile = viewportWidth <= 1440 (or <=
996 to match Docusaurus), ensuring the component that uses the mobile variable
(the mobile const in this file and the desktop TOC CSS breakpoint) restores the
collapsible TOC for that range.
🧹 Nitpick comments (1)
website/src/theme/DocItem/Layout/index.tsx (1)
15-17: Stale JSDoc — still references mobile TOC.The comment says the hook decides TOC rendering "on mobile or desktop viewports," but mobile is now hard-coded to
undefined.📝 Suggested update
-/** - * Decide if the toc should be rendered, on mobile or desktop viewports - */ +/** + * Decide if the desktop toc should be rendered. + */
Deploying voltagent with
|
| Latest commit: |
f58de7f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://39aea3fe.voltagent.pages.dev |
| Branch Preview URL: | https://update-docs-overview.voltagent.pages.dev |
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
website/observability/setup.md (1)
43-127:⚠️ Potential issue | 🟡 MinorClarify how
voltOpsClientandobservabilitywork together.The documentation doesn't explain that these options are complementary:
voltOpsClientprovides VoltOps backend connectivity (telemetry, prompts, actions)observabilityhandles OpenTelemetry tracing and can auto-configure usingvoltOpsClientfrom the global registryStep 2's wording—"configure observability explicitly with
VoltOpsClient"—is misleading; you actually configure the VoltOps connection withvoltOpsClient, whilecreateVoltAgentObservabilityautomatically uses it in serverless environments if available. Adding an example showing both options together, or clarifying that they can be used independently or combined, would help developers choose the right setup.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@website/observability/setup.md` around lines 43 - 127, Update the StepSection wording to clarify that voltOpsClient and observability are complementary: voltOpsClient (VoltOpsClient) configures backend connectivity (telemetry, prompts, actions) while observability (createVoltAgentObservability / observability option on VoltAgent) configures OpenTelemetry tracing and will auto-use a registered voltOpsClient in serverless environments; make explicit they can be used independently or together and add a short example or sentence showing VoltAgent constructed with both voltOpsClient and observability to demonstrate combined usage (reference symbols: VoltOpsClient, voltOpsClient, createVoltAgentObservability, observability, VoltAgent).
🧹 Nitpick comments (1)
website/observability/setup.md (1)
147-163: Consider adding guidance on advanced configuration in serverless environments.The serverless example uses
voltOpsClientwithout mentioning whethercreateVoltAgentObservability(shown in Advanced Options) is supported in serverless environments. If advanced configuration works with serverless, show an example. If not, state this limitation explicitly.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@website/observability/setup.md` around lines 147 - 163, Clarify whether advanced configuration using createVoltAgentObservability is supported in serverless environments and update the serverlessHono/VoltAgent example accordingly: if createVoltAgentObservability is supported, add a short example showing how to call createVoltAgentObservability and pass its result into the VoltAgent config alongside serverlessHono and voltOpsClient (referencing createVoltAgentObservability, serverlessHono, VoltAgent, voltOpsClient); if it is not supported, add a single-sentence note stating that limitation and recommend the supported alternative (e.g., use the default observability setup or run createVoltAgentObservability in a non-serverless environment).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@website/observability/setup.md`:
- Around line 43-127: Update the StepSection wording to clarify that
voltOpsClient and observability are complementary: voltOpsClient (VoltOpsClient)
configures backend connectivity (telemetry, prompts, actions) while
observability (createVoltAgentObservability / observability option on VoltAgent)
configures OpenTelemetry tracing and will auto-use a registered voltOpsClient in
serverless environments; make explicit they can be used independently or
together and add a short example or sentence showing VoltAgent constructed with
both voltOpsClient and observability to demonstrate combined usage (reference
symbols: VoltOpsClient, voltOpsClient, createVoltAgentObservability,
observability, VoltAgent).
---
Duplicate comments:
In `@website/observability/setup.md`:
- Line 30: The heading "### Add Environment Variables" is skipping from the
top-level "# Setup" to an h3; verify whether the surrounding component (e.g.,
StepSection) renders an h2 — if it does, keep h3, otherwise change the heading
to "## Add Environment Variables" so it becomes an h2 and conforms to MD001;
update the markdown in website/observability/setup.md accordingly.
---
Nitpick comments:
In `@website/observability/setup.md`:
- Around line 147-163: Clarify whether advanced configuration using
createVoltAgentObservability is supported in serverless environments and update
the serverlessHono/VoltAgent example accordingly: if
createVoltAgentObservability is supported, add a short example showing how to
call createVoltAgentObservability and pass its result into the VoltAgent config
alongside serverlessHono and voltOpsClient (referencing
createVoltAgentObservability, serverlessHono, VoltAgent, voltOpsClient); if it
is not supported, add a single-sentence note stating that limitation and
recommend the supported alternative (e.g., use the default observability setup
or run createVoltAgentObservability in a non-serverless environment).
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
1 participant
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.
PR Checklist
Please check if your PR fulfills the following requirements:
Bugs / Features
What is the current behavior?
What is the new behavior?
fixes (issue)
Notes for reviewers
Summary by cubic
Restructured Observability Getting Started to help devs reach a debuggable trace faster and clarified the core mental model. Simplified setup, tightened overview, and improved TOC behavior on smaller screens.
New Features
Migration
Written for commit f58de7f. Summary will update on new commits.
Summary by CodeRabbit
Documentation
Style