Skip to content

docs(tracing): add zero-code Node.js setup guide - #1113

Merged
nik13 merged 3 commits into
mainfrom
docs/zero-code-node
Nov 8, 2026
Merged

nik13 merged 3 commits into
mainfrom
docs/zero-code-node

Conversation

@nik13

@nik13 nik13 commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

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/auto package at /docs/integrations/traceai/auto.

  • Install once, set FI credentials/project and preload with ESM --import, npm NODE_OPTIONS or CommonJS --require.
  • Run an ordinary OpenAI application with no tracing imports and inspect the supplied real Future AGI trace screenshot, accurately captioned as OpenAI SDK 7 through OpenRouter.
  • Explain default-on content capture, hide flags, default-off PII redaction, omitted base64/audio, optional integrations, configuration, framework boundaries, diagnostics and when to use manual tracing.
  • Link the guide from the catalog/sidebar, observability quickstart and traceAI overview.
  • Keep package references pinned to the reviewed traceAI commit d85da9c62d93c2661189e440c13e28f53ff85ff1 from 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-http package can add incoming HTTP server spans and that FI_DISABLED_INSTRUMENTATIONS=http disables that integration.

The published-package proof now makes an ordinary /health request without any manual tracing API and asserts:

  • Without the optional instrumentor: no HTTP spans.
  • With @opentelemetry/instrumentation-http 0.202.0: exactly one SERVER span, no CLIENT/model span and no AI provider call.
  • With 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.cjs regression 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 networkidle hit 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/auto 0.1.1, OpenAI 7.53.0 and the optional HTTP instrumentor 0.202.0.

  • All 10/10 fenced blocks are extracted from the actual MDX and executed. Only credential placeholders are replaced with synthetic values; provider and OTLP endpoints are loopback mocks.
  • ESM, npm start, CommonJS and privacy-mode startup each make one provider call and export exactly one model span. Assertions cover model identity, normalized input/output/total tokens (13/3/16), positive duration, project routing, captured content, hidden content and absence of synthetic credentials in model spans.
  • Bootstrap returns its library/install report without exporting. Doctor exports its test span; collector rejection is correctly reported as failed even when the CLI exits zero.
  • All three HTTP scope cases above pass.
  • Nine public reference URLs/heading targets across four documents pass.
  • Each matrix leg uploads the receipt, emitted OTLP and exact npm lock as an Actions artifact.

Full validation and GitHub status

Head: 9f9907eacc253e3d6c8ccabbd560cc19bff04fa0.

Workflow Final-head result
PR Checks All four jobs pass, including the previously failing Docs build & Pagefind job and its complete browser step
Zero-code Node docs Both published-package matrix legs pass
FastMCP native examples Both native-contract legs pass
Temporal Go native tracing Both OTLP-contract legs pass

The successful E2B run fu-auto-docs-fix-r2-1108 used Node 22.18.0 and the same npm versions above, exited 0, and the sandbox was deleted with absence confirmed. It reran:

  • All 10 guide blocks, model/usage/privacy/doctor assertions and the three HTTP scope cases.
  • 273 contract tests, zero failures; integration type checking.
  • Link audit: zero broken navigation/content links; 31 existing orphan-page warnings.
  • All nine public reference links and their heading targets.
  • Astro production build and Pagefind: 850 pages indexed.
  • 15 directory checks + 52 existing regressions, all passing, plus the stalled-network regression and widget keyboard/focus/restore checks.
  • Focused guide navigation, all 10 rendered blocks, copy button, sidebar, trace-image decoding, anchors, quickstart/overview links, package-name catalog search and Pagefind search; no application page errors.

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/keys is 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 main diff and internal minimal-code, typing, failure-mode, PR, naming and testing standards. Product E2E coverage is not applicable: this docs repository has no e2e/ 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

nik13 and others added 3 commits November 8, 2026 03:31
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>
@nik13
nik13 marked this pull request as ready for review November 8, 2026 12:29
@nik13
nik13 merged commit ec130d5 into main Nov 8, 2026
10 checks passed
@nik13
nik13 deleted the docs/zero-code-node branch November 8, 2026 12:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant