Repository navigation
docs(auto): make zero-code Node tracing easy to start - #617
Merged
Merged
Conversation
Replace the implementation-led README with quick start, source-derived coverage, privacy defaults, deployment recipes and focused references. Preserve capture details and correct custom-exporter authentication and wire-transport claims. Add documentation regression checks and an executable consumer recipe harness. Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
- "What you get" opens with a screenshot of the README's own OpenAI example as it appears in Future AGI: a real run of @traceai/auto 0.1.0 with OpenAI SDK 7 and openai/gpt-4.1-mini through OpenRouter (model, provider, 13/3/16 tokens, cost, 885 ms, request and response). - `npm install @traceai/auto` and `npm install openai` instead of pinned versions. The quick start was verified in E2B with OpenAI SDK 5, 6 and 7.53.0 through --import, NODE_OPTIONS and CommonJS --require (one LLM span with output and usage each); @traceai/openai hooks ^4-^7. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
nik13
marked this pull request as ready for review
November 8, 2026 11:15
This was referenced Nov 8, 2026
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
Make the released
@traceai/autopackage understandable and usable from GitHub in two minutes, without changing runtime behavior.0.1.0install and a single Node preload; cover ESM, CommonJS andNODE_OPTIONS.fi-coreinstrumentation.docs/ARCHITECTURE.md; add complete configuration and framework references.Why
The old 736-line README led with implementation details, obscured the first successful request, omitted settings and mixed setup instructions with internal test/release notes. The root README did not expose the zero-code package at all.
The structure follows task-first patterns from OpenTelemetry zero-code, OpenLLMetry JS, OpenInference JS, Langfuse, Sentry and Datadog, while taking every product claim from traceAI's own code.
Verification
All execution used E2B with synthetic credentials, a loopback OTLP receiver and a mocked OpenAI-compatible provider. No real model calls or customer/Cloud data were used.
Final exact-head run
fu-auto-readme-head-f5dd0c53-1108ecompleted successfully; fetchedsource-head.txtmatchesf5dd0c53557bc122be17b9a9731c455214016a1f. Earlier full recipe run:fu-auto-readme-recipes-1108c.Final results:
@traceai/auto@0.1.0consumer and the packed workspace consumer, 34 total.NODE_OPTIONS, the root quickstart, a custom exporter without FI credentials, content-hidden TOML, esbuild, Vite SSR, Rollup, webpack, two warm Lambda invocations, and a real Next production build/start.accepted;--no-checkand bootstrap sent no test spans. The edge observer did not create an implicit exporter.safety.test.tsBuffer/BodyInit TypeScript compilation failure. Both failures reproduce on unchanged base00c0313790f6493830cae6b0cd536f40da791fc1infu-auto-readme-base-full-1108d; no runtime/test suppression is included. That base run additionally exposed a build-order catalog byte-identity failure, absent from the final packed-consumer sequence.get_inforeturned 404.CI and existing base failures
The required Python tests check is green. At the completed qualification snapshot: 103 passed, 15 failed, 3 skipped, 0 pending. The 15 failed checks are existing compatibility failures, not new documentation regressions. Every remaining failure was compared against a completed
devrun at2c3a6e8700a0e76b6c8c0c6b820017cffe0c4804:openai.test.tssnapshotsservice.name, getsunknown_service:/usr/local/bin/nodecontract/otlp_wire.mjs:57expectssession.id=thread-contract-1Transient GitHub HTTP 504 download failures were retried. VoltAgent now passes; the integration retry progressed to the Codex assertion, which was then independently reproduced by retrying the base integration workflow. No unrelated assertions, snapshots, workflows or runtime behavior were changed to hide these failures.
This remains a draft as requested. Engineering qualification uses the task's explicit allowance for proven pre-existing non-required CI failures; it is not a claim that all checks are green. A human approval is still required before merge.
Reproduction entry points:
typescript/packages/traceai_auto:node scripts/generate-readme.cjs --checkandpnpm exec jest --runInBand test/docs.test.ts.node <checkout>/typescript/packages/traceai_auto/test/docs-consumer.cjs <consumer> <receipts-directory>. This writes fixtures and replaces that disposable consumer'sdist/directory.pnpm --filter @traceai/auto... --filter @traceai/vercel... install --frozen-lockfile --ignore-scripts,pnpm run build:deps, build@traceai/genkitand@traceai/vercel, then build@traceai/auto; pack core, semantic conventions, OpenAI and auto into a separate clean consumer.Receipt root on the task owner's machine:
/Volumes/nik-ext-1/tmp/traceai-release-20261104/e2b/runs/. Each run records stdout/stderr, source, exit status and sandbox deletion verification. Consumer assertions are committed in this PR; no private credentials are needed to reproduce them.Scope and rollout
Documentation, generated coverage and documentation tests only. No runtime source, package versions, dependencies, lockfiles, default flags or APIs changed. No migration or deployment is needed; revert the documentation commits to roll back. The published npm README will only change on a later authorized package publication; this PR does not publish anything.
The docs-site clone has no dedicated
@traceai/autopage. Its existing tracing/integration pages describe manual instrumentors rather than this process preload. That separate docs-site follow-up is intentionally not included here. Existing SDK guide screenshots are not presented as an auto-instrumentation demo; no screenshot was fabricated.No Linear ticket was supplied for this documentation follow-up; none has been invented. Repository review/approval requirements still apply. No merge, admin override or package publication is requested by this PR.
Follow-up commit (d85da9c)
@traceai/auto0.1.0, OpenAI SDK 7 andopenai/gpt-4.1-minithrough OpenRouter. It shows the model, provider, 13/3/16 tokens, cost, 885 ms, and the request and response. The trace went from an E2B run to a loopback collector and was forwarded to Cloud with process identity stripped, matching fi-core 1.2.1. No placeholder imagery.npm install @traceai/autoandnpm install openai. The quick start was verified in E2B against@traceai/autofrom npm with OpenAI SDK 5, 6 and 7.53.0. Each of--import,NODE_OPTIONSand CommonJS--requiregave one LLM span with output and usage.@traceai/openaihooks^4–^7.🤖 Generated with Claude Code