Repository navigation
docs(tracing): add zero-code Node.js setup guide - #1113
Merged
Merged
Conversation
Add a discoverable guide for the published auto package, with real trace media and executable snippet, privacy, diagnostic and browser checks. Co-Authored-By: Claude Code <noreply@anthropic.com>
Verify model and token attributes directly instead of allowing raw response content to satisfy usage assertions. Co-Authored-By: Claude Code <noreply@anthropic.com>
Document the optional incoming HTTP integration and its denylist switch. Prove both paths against the published package and keep docs UI checks independent of third-party request latency without relaxing their assertions. Co-Authored-By: Claude Code <noreply@anthropic.com>
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
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
Review fixes complete; all 10 GitHub checks are green at
9f9907eacc253e3d6c8ccabbd560cc19bff04fa0. PR remains draft for human review; nothing has been merged or deployed.Add a task-oriented guide for the released
@traceai/autopackage at/docs/integrations/traceai/auto.--import, npmNODE_OPTIONSor CommonJS--require.d85da9c62d93c2661189e440c13e28f53ff85ff1from docs(auto): make zero-code Node tracing easy to start traceAI#617 rather than duplicating the generated library matrix.Review fixes
Correct HTTP scope
The exclusion now says outgoing non-AI HTTP calls. The guide explains that an installed optional
@opentelemetry/instrumentation-httppackage can add incoming HTTP server spans and thatFI_DISABLED_INSTRUMENTATIONS=httpdisables that integration.The published-package proof now makes an ordinary
/healthrequest without any manual tracing API and asserts:@opentelemetry/instrumentation-http0.202.0: exactly one SERVER span, no CLIENT/model span and no AI provider call.FI_DISABLED_INSTRUMENTATIONS=http: no HTTP spans.A page contract test also prevents the original overbroad wording from returning.
Make the browser gate independent of third-party latency
The previous head failed twice in existing integration-directory checks while waiting for
networkidle. Those contexts loaded external analytics, font CDNs and the GitHub star API. The site itself has an explicit directory-ready signal, but the tests also waited for unrelated network activity.The fix uses a small shared same-origin browser context for the directory, regression and new-guide suites, matching the isolation already used by the widget suite. First-party navigation, scripts, CSS, images and Pagefind remain real. All prior assertions and navigation timeouts remain intact; there are no retries, skipped cases, production changes or enlarged timeouts. These tests intentionally do not validate third-party analytics/CDNs and render with the site's fallback fonts.
The committed
scripts/browser-network.browser.cjsregression uses two loopback origins. With the old browser setup, the docs script executes but a stalled analytics request prevents network idle. With isolation, the same docs script executes, navigation completes and the second origin receives no new request. Reverting isolation makes the positive case fail.E2B also reproduced this on the actual built integration directory: its ready signal appeared after 226 ms, but deliberately holding the real Google tag script made
networkidlehit the same 30-second timeout, with that script still pending. In the unmodified-network control, the directory was ready after 353 ms while the GitHub star requests kept network idle waiting until about 7 seconds.The historical failed GitHub run did not retain a network capture, so the exact remote request responsible for that run cannot be identified retrospectively. The new reproduction verifies the failure mechanism rather than claiming an unobserved culprit.
Published npm proof
Final-head snippet workflow passed on Node 20.6.0 and 22.18.0, each using npm
@traceai/auto0.1.1, OpenAI 7.53.0 and the optional HTTP instrumentor 0.202.0.failedeven when the CLI exits zero.Full validation and GitHub status
Head:
9f9907eacc253e3d6c8ccabbd560cc19bff04fa0.The successful E2B run
fu-auto-docs-fix-r2-1108used Node 22.18.0 and the same npm versions above, exited 0, and the sandbox was deleted with absence confirmed. It reran:The same build/contract/browser checks pass in final-head GitHub CI. The uploaded rendered setup and trace-result screenshots were visually inspected. The full-site E2B build uses a 6 GiB Node heap in its 8 GiB sandbox; the normal GitHub build needs no configuration change.
Internal evidence is retained at
/Volumes/nik-ext-1/tmp/traceai-release-20261104/e2b/runs/fu-auto-docs-fix-r2-1108/(receipt, stdout/stderr and fetched artifacts). Downloaded CI artifacts and extracted E2B evidence are under/Volumes/nik-ext-1/tmp/agent-plugins-1106/fix-auto-ci-1108/. The first diagnostic attempt stopped because preview had not started listening; the successful rerun includes an explicit readiness wait. Both diagnostic sandboxes were deleted and their absence confirmed.Scope, limitations and rollback
This changes documentation, discovery entries and their tests. It changes no SDK runtime, production browser behavior, product API, permissions, migrations or stored data. No new repository dependency is added; the optional HTTP package is installed only inside disposable snippet-test applications. Revert the PR to remove the guide and its test/discovery additions.
All tests/builds run in E2B or GitHub Actions, never locally. Tracing proofs use synthetic credentials and loopback receivers/providers, not live model or Cloud calls. The supplied screenshot is prior real Cloud evidence and is byte-identical to its supplied source, not a claim that these loopback tests reached Cloud.
The canonical keys URL
https://app.futureagi.com/dashboard/keysis retained as requested. An earlier unsigned-in HTTP check returned 404; signed-in key creation is not claimed as verified. Public package-reference checks do not pretend to validate authenticated application routes.Self-review covers the actual
maindiff and internal minimal-code, typing, failure-mode, PR, naming and testing standards. Product E2E coverage is not applicable: this docs repository has noe2e/harness; its own browser/contract suites are the applicable gates. No Python, migration, serializer or generated product contract changed, so those mechanical gates do not apply. No Linear ticket was supplied for this documentation follow-up. Human approval, merge and docs deployment remain separate; this task does not merge or publish the site.🤖 Generated with Claude Code