diff --git a/.github/workflows/auto-node-docs.yml b/.github/workflows/auto-node-docs.yml new file mode 100644 index 000000000..af6f4b6b7 --- /dev/null +++ b/.github/workflows/auto-node-docs.yml @@ -0,0 +1,38 @@ +name: Zero-code Node docs + +on: + pull_request: + branches: [main, dev] + paths: + - 'src/pages/docs/integrations/traceai/auto.mdx' + - 'scripts/auto-*.mjs' + - '.github/workflows/auto-node-docs.yml' + workflow_dispatch: + +permissions: + contents: read + +jobs: + published-snippets: + name: Published npm snippets (Node ${{ matrix.node }}) + runs-on: ubuntu-24.04 + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + node: ['20.6.0', '22.18.0'] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node }} + - name: Audit public reference links and heading anchors + run: node scripts/auto-links.mjs + - name: Run every guide snippet with loopback provider and OTLP + run: node scripts/auto-snippets.mjs + - uses: actions/upload-artifact@v4 + if: always() + with: + name: auto-snippets-${{ matrix.node }} + path: /tmp/docs-auto-evidence + if-no-files-found: error diff --git a/package.json b/package.json index 45b31611e..d0131e8fd 100644 --- a/package.json +++ b/package.json @@ -12,7 +12,7 @@ "new-doc": "node scripts/new-doc.mjs", "audit-links": "node scripts/audit-links.mjs", "test:integrations": "node --test scripts/integrations.test.mjs scripts/new-doc.test.mjs scripts/langfuse-import.test.mjs scripts/n8n-page.test.mjs scripts/openlit-endpoint.test.mjs scripts/chromadb-java.test.mjs scripts/openllmetry-content.test.mjs", - "test:integrations:browser": "node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs", + "test:integrations:browser": "node scripts/browser-network.browser.cjs && node scripts/integrations.browser.cjs && node scripts/integrations.regression.cjs && node scripts/widget-regression.cjs && node scripts/auto.browser.mjs", "check:integrations": "tsc --allowJs --checkJs --noEmit --strict --types node --target ES2022 --module nodenext src/lib/integrations.mjs" }, "dependencies": { diff --git a/public/images/docs/integrations/traceai/auto/trace-span.png b/public/images/docs/integrations/traceai/auto/trace-span.png new file mode 100644 index 000000000..1c4c1eb2f Binary files /dev/null and b/public/images/docs/integrations/traceai/auto/trace-span.png differ diff --git a/scripts/auto-links.mjs b/scripts/auto-links.mjs new file mode 100644 index 000000000..c524a89c2 --- /dev/null +++ b/scripts/auto-links.mjs @@ -0,0 +1,23 @@ +// Audit public package references, not signed-in application routes. +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +const page = await readFile(new URL('../src/pages/docs/integrations/traceai/auto.mdx', import.meta.url), 'utf8'); +const urls = new Set([...page.matchAll(/\]\((https:\/\/github\.com\/[^)]+)\)/g)].map(match => match[1])); +const documents = new Map(); +for (const href of urls) { + const url = new URL(href); + const anchor = url.hash.slice(1); + url.hash = ''; + const source = url.href.replace('https://github.com/future-agi/traceAI/blob/', 'https://raw.githubusercontent.com/future-agi/traceAI/'); + if (!documents.has(source)) { + const response = await fetch(source, { signal: AbortSignal.timeout(30000) }); + assert.ok(response.ok, `${source}: ${response.status}`); + documents.set(source, await response.text()); + } + if (anchor && source.startsWith('https://raw.githubusercontent.com/')) { + const headings = [...documents.get(source).matchAll(/^#{1,6} (.+)$/gm)].map(match => match[1].toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, '').replace(/ /g, '-')); + assert.ok(headings.includes(anchor), `${href}: missing heading`); + } + console.log(`OK ${href}`); +} +console.log(JSON.stringify({ externalLinks: urls.size, fetchedDocuments: documents.size })); diff --git a/scripts/auto-page.test.mjs b/scripts/auto-page.test.mjs new file mode 100644 index 000000000..423b6adb4 --- /dev/null +++ b/scripts/auto-page.test.mjs @@ -0,0 +1,59 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync, existsSync } from 'node:fs'; +import { integrations, integrationNavigation } from '../src/lib/integrations.mjs'; + +const read = path => readFileSync(new URL(`../${path}`, import.meta.url), 'utf8'); +const page = read('src/pages/docs/integrations/traceai/auto.mdx'); +const route = '/docs/integrations/traceai/auto'; + +test('zero-code Node guide is discoverable from the catalog, sidebar and setup paths', () => { + const entry = integrations.find(item => item.id === 'traceai-auto'); + assert.equal(entry?.href, route); + assert.equal(entry?.category, 'frameworks'); + assert.ok(entry?.aliases.includes('@traceai/auto')); + assert.ok(JSON.stringify(integrationNavigation).includes(route)); + for (const file of ['quickstart/setup-observability', 'integrations/traceai/index']) { + assert.ok(read(`src/pages/docs/${file}.mdx`).includes(route)); + } +}); + +test('primary setup preloads a maintained package without app instrumentation', () => { + assert.match(page, /Node\.js 20\.6 or later/); + assert.match(page, /https:\/\/app\.futureagi\.com\/dashboard\/keys/); + assert.match(page, /[\s\S]*/); + for (const command of ['npm install @traceai/auto', 'node --import @traceai/auto/register app.mjs', 'NODE_OPTIONS="--import @traceai/auto/register" npm start', 'node --require @traceai/auto/register app.cjs', 'npx --no-install traceai-auto doctor']) { + assert.ok(page.includes(command), command); + } + const examples = [...page.matchAll(/```javascript\n([\s\S]*?)\n```/g)]; + assert.equal(examples.length, 1); + assert.match(examples[0][1], /import OpenAI from "openai"/); + assert.doesNotMatch(examples[0][1], /traceai|opentelemetry|instrument|register/); + assert.match(page, /Observe → my-ai-app/); + assert.match(page, /zero exit code alone does not prove export health/); +}); + +test('HTTP scope distinguishes outgoing calls from the optional incoming integration', () => { + assert.match(page, /outgoing non-AI HTTP calls are not automatically traced/); + assert.match(page, /optional `@opentelemetry\/instrumentation-http` package is installed/); + assert.match(page, /incoming HTTP server spans/); + assert.match(page, /`FI_DISABLED_INSTRUMENTATIONS=http` to disable that integration/); +}); + +test('privacy defaults, runtime boundaries and reference links remain explicit', () => { + const setup = page.split('## Try a minimal')[0]; + assert.match(setup, /captured by default/); + for (const flag of ['FI_HIDE_INPUTS=true', 'FI_HIDE_OUTPUTS=true', 'FI_HIDE_ERROR_DETAILS=true']) assert.ok(setup.includes(flag)); + assert.match(page, /PII pattern redaction[^\n]*Off by default/); + assert.match(page, /raising it does not enable base64 image export/); + assert.match(page, /Other exporters retain their own privacy policies/); + assert.match(page, /README\.md#library-coverage/); + for (const anchor of ['nextjs', 'node-server-bundlers', 'aws-lambda-and-short-lived-processes', 'edge-and-browsers']) assert.ok(page.includes(`FRAMEWORKS.md#${anchor}`)); + assert.match(page, /application-owned exporter/); + assert.match(page, /\/docs\/sdk\/tracing\/set-up-tracing/); + assert.doesNotMatch(page, /verified live|PASS\/FAIL|loopback|test harness|E2B|not tested/); + const image = page.match(/!\[[^\]]+\]\((\/images\/[^)]+)\)/)?.[1]; + assert.ok(image); + assert.ok(existsSync(new URL(`../public${image}`, import.meta.url))); + assert.match(page, /OpenAI SDK 7 with openai\/gpt-4\.1-mini through OpenRouter/); +}); diff --git a/scripts/auto-snippets.mjs b/scripts/auto-snippets.mjs new file mode 100644 index 000000000..ada978831 --- /dev/null +++ b/scripts/auto-snippets.mjs @@ -0,0 +1,185 @@ +// Execute every fenced block in the guide against published npm packages. +// Run only in a disposable E2B sandbox or CI. No real service credentials needed. +import assert from 'node:assert/strict'; +import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join, resolve } from 'node:path'; +import { createServer } from 'node:http'; +import { execFile } from 'node:child_process'; +import { promisify } from 'node:util'; +import { gunzipSync } from 'node:zlib'; + +const exec = promisify(execFile); +const page = await readFile(new URL('../src/pages/docs/integrations/traceai/auto.mdx', import.meta.url), 'utf8'); +const blocks = [...page.matchAll(/```(bash|javascript)\n([\s\S]*?)\n```/g)].map((m, index) => ({ index, language: m[1], code: m[2] })); +assert.equal(blocks.length, 10, 'Every new fenced block needs an execution case'); +const block = prefix => { + const found = blocks.find(b => b.code.startsWith(prefix)); + assert.ok(found, prefix); + return found; +}; +const done = new Set(); +const results = []; +const batches = []; +const requests = []; +const errors = []; +let collectorStatus = 200; +const app = await mkdtemp(join(tmpdir(), 'auto-docs-')); +const output = resolve(process.env.AUTO_EVIDENCE_DIR || '/tmp/docs-auto-evidence'); +await mkdir(output, { recursive: true }); +const server = createServer(async (req, res) => { + try { + const parts = []; + for await (const part of req) parts.push(part); + let raw = Buffer.concat(parts); + if (req.headers['content-encoding'] === 'gzip') raw = gunzipSync(raw); + const data = JSON.parse(raw.toString() || '{}'); + if (req.url === '/v1/chat/completions') { + assert.equal(req.headers.authorization, 'Bearer synthetic-provider-key'); + assert.equal(data.model, 'docs-test-model'); + assert.equal(data.messages[0].content, 'Say hello in one word.'); + requests.push(data); + res.writeHead(200, { 'content-type': 'application/json' }); + res.end(JSON.stringify({ id: 'chatcmpl-docs', object: 'chat.completion', created: 1700000000, model: data.model, choices: [{ index: 0, message: { role: 'assistant', content: 'Hello!' }, finish_reason: 'stop' }], usage: { prompt_tokens: 13, completion_tokens: 3, total_tokens: 16 } })); + } else if (req.url === '/tracer/v1/traces') { + assert.equal(req.headers['x-api-key'], 'synthetic-fi-api-key'); + assert.equal(req.headers['x-secret-key'], 'synthetic-fi-secret-key'); + batches.push(data); + res.writeHead(collectorStatus, { 'content-type': 'application/json' }); + res.end('{}'); + } else { + throw new Error(`Unexpected request route: ${req.url}`); + } + } catch (error) { + errors.push(error.message); + res.writeHead(500, { 'content-type': 'application/json' }); + res.end('{}'); + } +}); +await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); +const url = `http://127.0.0.1:${server.address().port}`; +// Do not inherit FI credentials, provider keys, preload flags or user profiles. +const env = { + PATH: process.env.PATH, + HOME: join(app, 'home'), + XDG_CONFIG_HOME: join(app, 'config'), + FI_BASE_URL: url, + OPENAI_BASE_URL: `${url}/v1`, + OPENAI_API_KEY: 'synthetic-provider-key', + OPENAI_MODEL: 'docs-test-model', + npm_config_registry: 'https://registry.npmjs.org', + npm_config_update_notifier: 'false', + npm_config_audit: 'false', + npm_config_fund: 'false', +}; +const setup = block('export FI_API_KEY'); +const config = setup.code.replaceAll('your-api-key', 'synthetic-fi-api-key').replaceAll('your-secret-key', 'synthetic-fi-secret-key'); +const allSpans = from => batches.slice(from).flatMap(batch => batch.resourceSpans.flatMap(resource => resource.scopeSpans.flatMap(scope => scope.spans))); +async function run(name, command, { expected = 'model', hidden = false, overrides = {} } = {}) { + const from = batches.length; + const before = requests.length; + const result = await exec('bash', ['-c', `set -euo pipefail\n${config}\n${command}`], { cwd: app, env: { ...env, ...overrides }, timeout: 180000, maxBuffer: 4 * 1024 * 1024 }); + const spans = allSpans(from); + assert.deepEqual(errors, []); + if (expected === 'model') { + assert.equal(requests.length - before, 1, `${name}: provider calls`); + assert.match(result.stdout, /Hello!/); + assert.equal(spans.length, 1, `${name}: exactly one model span, no duplicate wire span`); + const serialized = JSON.stringify(spans); + const attributes = Object.fromEntries(spans[0].attributes.map(attribute => [attribute.key, attribute.value])); + assert.equal(attributes['gen_ai.request.model'].stringValue, 'docs-test-model'); + assert.equal(Number(attributes['gen_ai.usage.input_tokens'].intValue), 13); + assert.equal(Number(attributes['gen_ai.usage.output_tokens'].intValue), 3); + assert.equal(Number(attributes['gen_ai.usage.total_tokens'].intValue), 16); + assert.ok(BigInt(spans[0].endTimeUnixNano) > BigInt(spans[0].startTimeUnixNano)); + assert.match(JSON.stringify(batches.slice(from)), /my-ai-app/); + if (hidden) assert.doesNotMatch(serialized, /Say hello in one word\.|Hello!/); + else { assert.match(serialized, /Say hello in one word\./); assert.match(serialized, /Hello!/); } + assert.doesNotMatch(serialized, /synthetic-(?:fi|provider)/); + } else if (expected === 'http-server' || expected === 'no-http') { + assert.equal(requests.length - before, 0, `${name}: no AI provider call`); + assert.match(result.stdout, /ordinary health response/); + assert.equal(spans.length, expected === 'http-server' ? 1 : 0, `${name}: HTTP span count`); + if (expected === 'http-server') { + assert.equal(spans[0].kind, 2, 'Incoming request exports a SERVER span, not a CLIENT span'); + assert.match(JSON.stringify(spans[0].attributes), /\/health/); + } + } else if (expected === 'doctor') { + const report = JSON.parse(result.stdout); + assert.equal(report.active, true); + assert.equal(report.collector, collectorStatus === 200 ? 'accepted' : 'failed'); + assert.equal(spans.length, 1); + assert.equal(spans[0].name, 'traceai.auto.doctor'); + } else if (expected === 'bootstrap') { + const report = JSON.parse(result.stdout); + assert.ok(report.integrations.some(i => i.name === 'openai' || i.id === 'openai')); + assert.ok(Array.isArray(report.install)); + assert.equal(spans.length, 0); + } + results.push({ name, spans: spans.length, providerCalls: requests.length - before, exitCode: 0 }); + console.log(JSON.stringify(results.at(-1))); + return result; +} +async function execute(prefix, options) { + const selected = block(prefix); + done.add(selected.index); + return run(prefix.split('\n')[0], selected.code, options); +} +try { + await mkdir(env.HOME, { recursive: true }); + await writeFile(join(app, 'package.json'), JSON.stringify({ name: 'auto-docs-example', private: true, scripts: { start: 'node app.mjs' } })); + await execute('npm install @traceai/auto', { expected: 'install' }); + await execute('npm install openai', { expected: 'install' }); + const example = block('import OpenAI'); + assert.doesNotMatch(example.code, /traceai|opentelemetry/); + await writeFile(join(app, 'app.mjs'), example.code); + // The CommonJS startup variant uses an equivalent normal application, no tracing imports. + await writeFile(join(app, 'app.cjs'), `const OpenAI = require('openai');\n(async () => {\n${example.code.split('\n').slice(1).join('\n')}\n})().catch(error => { console.error(error); process.exitCode = 1; });\n`); + done.add(example.index); + done.add(setup.index); // Executed before every shell command with synthetic substitutions. + await execute('node --import'); + await execute('NODE_OPTIONS='); + await execute('node --require'); + await execute('npx --no-install traceai-auto bootstrap', { expected: 'bootstrap' }); + await execute('FI_HIDE_INPUTS=', { hidden: true }); + await execute('npx --no-install traceai-auto doctor', { expected: 'doctor' }); + // Regression: doctor exit code can be zero even when collection fails. + collectorStatus = 400; + await run('doctor rejects collector errors despite exit zero', block('npx --no-install traceai-auto doctor').code, { expected: 'doctor' }); + collectorStatus = 200; + assert.equal(done.size, blocks.length, 'All page blocks executed'); + // Ordinary HTTP is not AI traffic. The optional integration traces only the + // incoming half of this request; no manual tracing APIs are used in the app. + await writeFile(join(app, 'http.mjs'), `import { createServer, get } from 'node:http'; +const server = createServer((request, response) => response.end('ordinary health response')); +await new Promise(resolve => server.listen(0, '127.0.0.1', resolve)); +try { + const body = await new Promise((resolve, reject) => { + get('http://127.0.0.1:' + server.address().port + '/health', response => { + let text = ''; + response.setEncoding('utf8'); + response.on('data', chunk => { text += chunk; }); + response.on('end', () => resolve(text)); + response.on('error', reject); + }).on('error', reject); + }); + console.log(body); +} finally { await new Promise(resolve => server.close(resolve)); } +`); + const httpCommand = block('node --import').code.replace('app.mjs', 'http.mjs'); + await run('HTTP without the optional instrumentor', httpCommand, { expected: 'no-http' }); + await run('install optional HTTP instrumentor', 'npm install @opentelemetry/instrumentation-http@0.202.0', { expected: 'install' }); + await run('HTTP integration captures incoming but not outgoing requests', httpCommand, { expected: 'http-server' }); + assert.ok(page.includes('FI_DISABLED_INSTRUMENTATIONS=http')); + await run('HTTP denylist disables incoming spans', `FI_DISABLED_INSTRUMENTATIONS=http ${httpCommand}`, { expected: 'no-http' }); + const packages = {}; + for (const name of ['@traceai/auto', 'openai', '@opentelemetry/instrumentation-http']) packages[name] = JSON.parse(await readFile(join(app, 'node_modules', name, 'package.json'), 'utf8')).version; + const receipt = { node: process.version, packages, executedBlocks: done.size, totalBlocks: blocks.length, results, scope: 'Synthetic loopback provider and OTLP only; not a live Cloud test.' }; + await writeFile(join(output, 'snippets.json'), JSON.stringify(receipt, null, 2)); + await writeFile(join(output, 'otlp.json'), JSON.stringify(batches, null, 2)); + await writeFile(join(output, 'package-lock.json'), await readFile(join(app, 'package-lock.json'))); + console.log(JSON.stringify(receipt)); +} finally { + await new Promise(resolve => server.close(resolve)); + await rm(app, { recursive: true, force: true }); +} diff --git a/scripts/auto.browser.mjs b/scripts/auto.browser.mjs new file mode 100644 index 000000000..8b721cf75 --- /dev/null +++ b/scripts/auto.browser.mjs @@ -0,0 +1,66 @@ +import assert from 'node:assert/strict'; +import { mkdir, writeFile } from 'node:fs/promises'; +import { chromium } from 'playwright'; +import { createDocsContext } from './docs-browser.cjs'; + +const base = 'http://127.0.0.1:4321'; +const route = '/docs/integrations/traceai/auto'; +const out = process.env.AUTO_EVIDENCE_DIR || process.env.INTEGRATIONS_EVIDENCE_DIR || '/tmp/docs-integrations-browser/auto'; +await mkdir(out, { recursive: true }); +const browser = await chromium.launch({ headless: true }); +const results = []; +try { + const context = await createDocsContext(browser, base,{ viewport: { width: 1440, height: 1000 }, permissions: ['clipboard-read', 'clipboard-write'] }); + const page = await context.newPage(); + const errors = []; + page.on('pageerror', error => errors.push(error.message)); + assert.equal((await page.goto(base + route, { waitUntil: 'networkidle' })).status(), 200); + await page.getByRole('heading', { name: 'Zero-code Node.js tracing', exact: true }).waitFor(); + assert.equal(await page.locator('.docs-content pre code').count(), 10); + const code = page.locator('.docs-content pre').filter({ hasText: 'npm install @traceai/auto' }); + await code.locator('.copy-button').click(); + assert.equal((await page.evaluate(() => navigator.clipboard.readText())).trim(), 'npm install @traceai/auto'); + const active = page.locator('.integration-sidebar a[aria-current="page"]'); + assert.equal(await active.getAttribute('href'), route); + const image = page.locator('img[src="/images/docs/integrations/traceai/auto/trace-span.png"]'); + await image.scrollIntoViewIfNeeded(); + await image.evaluate(img => img.decode()); + assert.equal(await image.evaluate(img => img.naturalWidth), 1440); + await page.screenshot({ path: `${out}/auto-result.png` }); + await page.evaluate(() => window.scrollTo({ top: 0, behavior: 'instant' })); + await page.screenshot({ path: `${out}/auto-setup.png` }); + await page.screenshot({ path: `${out}/auto-full.png`, fullPage: true }); + for (const href of await page.locator('.docs-content a[href^="#"]').evaluateAll(links => links.map(a => a.getAttribute('href')))) { + assert.equal(await page.locator(href).count(), 1, `Missing local anchor ${href}`); + } + results.push('page, 10 code blocks, copy button, current sidebar item, trace image and anchors'); + for (const source of ['/docs/quickstart/setup-observability', '/docs/integrations/traceai']) { + await page.goto(base + source, { waitUntil: 'networkidle' }); + await page.locator(`.docs-content a[href="${route}"]`).first().click(); + await page.waitForURL(base + route); + await page.getByRole('heading', { name: 'Zero-code Node.js tracing', exact: true }).waitFor(); + } + results.push('quickstart and overview links navigate to the guide'); + await page.goto(base + '/docs/integrations', { waitUntil: 'networkidle' }); + await page.locator('#integration-search').fill('@traceai/auto'); + const card = page.locator('[data-integration-card]:visible'); + await page.waitForFunction(() => document.querySelectorAll('[data-integration-card]:not([hidden])').length === 1); + assert.equal(await card.count(), 1); + assert.equal(await card.getAttribute('href'), route); + await card.click(); + await page.waitForURL(base + route); + results.push('package-name search discovers and opens the guide'); + const search = await page.evaluate(async route => { + const pagefind = await import('/pagefind/pagefind.js'); + const response = await pagefind.search('Zero-code Node.js'); + const entries = await Promise.all(response.results.map(result => result.data())); + return entries.some(entry => entry.url.replace(/\/$/, '') === route); + }, route); + assert.equal(search, true, 'Pagefind indexes the new page'); + results.push('Pagefind search returns the guide'); + assert.deepEqual(errors, []); + await writeFile(`${out}/browser.json`, JSON.stringify({ results, errors }, null, 2)); + console.log(JSON.stringify({ results, errors })); +} finally { + await browser.close(); +} diff --git a/scripts/browser-network.browser.cjs b/scripts/browser-network.browser.cjs new file mode 100644 index 000000000..6cc7055ea --- /dev/null +++ b/scripts/browser-network.browser.cjs @@ -0,0 +1,48 @@ +const assert = require('node:assert/strict'); +const { createServer } = require('node:http'); +const { chromium } = require('playwright'); +const { createDocsContext } = require('./docs-browser.cjs'); + +(async () => { + // Two loopback origins stand in for the docs and a stalled analytics server. + // No external service is contacted, even for the original-failure proof. + let analyticsRequests = 0; + const analytics = createServer(() => { analyticsRequests++; }); + await new Promise(resolve => analytics.listen(0, '127.0.0.1', resolve)); + const analyticsUrl = `http://127.0.0.1:${analytics.address().port}/analytics.js`; + const docs = createServer((request, response) => { + if (request.url === '/ready.js') { + response.writeHead(200, { 'content-type': 'text/javascript' }); + response.end('document.body.dataset.ready = "true";'); + } else { + response.writeHead(200, { 'content-type': 'text/html' }); + response.end(`

Docs fixture

`); + } + }); + await new Promise(resolve => docs.listen(0, '127.0.0.1', resolve)); + const base = `http://127.0.0.1:${docs.address().port}`; + let browser; + try { + browser = await chromium.launch({ headless: true }); + const original = await browser.newContext(); + const page = await original.newPage(); + await page.goto(base, { waitUntil: 'domcontentloaded' }); + await page.locator('body[data-ready="true"]').waitFor(); + await assert.rejects(page.waitForLoadState('networkidle', { timeout: 1500 }), /Timeout/); + assert.equal(analyticsRequests, 1, 'The stalled third party, not docs readiness, blocks networkidle'); + await original.close(); + + const context = await createDocsContext(browser, base); + const isolated = await context.newPage(); + assert.equal((await isolated.goto(base, { waitUntil: 'networkidle', timeout: 5000 })).status(), 200); + assert.equal(await isolated.locator('body').getAttribute('data-ready'), 'true', 'First-party script still executes'); + assert.equal(analyticsRequests, 1, 'Isolated docs checks never contact the second origin'); + await context.close(); + console.log('PASS stalled third-party reproduction; isolation retains real first-party loading'); + } finally { + await browser?.close(); + docs.closeAllConnections(); + analytics.closeAllConnections(); + await Promise.all([new Promise(resolve => docs.close(resolve)), new Promise(resolve => analytics.close(resolve))]); + } +})().catch(error => { console.error(error); process.exitCode = 1; }); diff --git a/scripts/docs-browser.cjs b/scripts/docs-browser.cjs new file mode 100644 index 000000000..b7fa7bcd5 --- /dev/null +++ b/scripts/docs-browser.cjs @@ -0,0 +1,17 @@ +// Docs UI checks exercise the built site, not analytics, font CDNs or GitHub's +// star API. Keep first-party requests real, including navigation and Pagefind. +/** + * @param {import('playwright').Browser} browser + * @param {string} base + * @param {import('playwright').BrowserContextOptions} [options] + * @returns {Promise} + */ +async function createDocsContext(browser, base, options = {}) { + const context = await browser.newContext(options); + const origin = new URL(base).origin; + await context.route('**/*', route => + new URL(route.request().url()).origin === origin ? route.continue() : route.abort()); + return context; +} + +module.exports = { createDocsContext }; diff --git a/scripts/integrations.browser.cjs b/scripts/integrations.browser.cjs index 6e18e2fd9..62dec6004 100644 --- a/scripts/integrations.browser.cjs +++ b/scripts/integrations.browser.cjs @@ -1,4 +1,5 @@ const {chromium} = require('playwright'); +const {createDocsContext} = require('./docs-browser.cjs'); const fs=require('node:fs/promises'); const assert=require('node:assert/strict'); const path=require('node:path'); @@ -20,7 +21,7 @@ async function record(name, fn) { try {const detail=await fn();results.push({nam const browser=await chromium.launch({headless:true}); for(const [name,width,height] of [['desktop',1440,1000],['tablet',768,1024],['mobile390',390,844],['mobile375',375,812]]) { await record(name+' responsive directory',async()=>{ - const ctx=await browser.newContext({viewport:{width,height},colorScheme:'dark'});const page=await ctx.newPage(); + const ctx=await createDocsContext(browser,BASE,{viewport:{width,height},colorScheme:'dark'});const page=await ctx.newPage(); await page.goto(BASE+'/docs/integrations',{waitUntil:'networkidle'});await page.locator('[data-integration-directory][data-ready]').waitFor();await page.screenshot({path:OUT+'/after-'+name+'.png'}); assert.equal(await page.locator('[data-integration-card]:visible').count(),integrations.length); @@ -29,7 +30,7 @@ async function record(name, fn) { try {const detail=await fn();results.push({nam await ctx.close();return {width,height,firstCard:first}; }); } - const ctx=await browser.newContext({viewport:{width:1440,height:1000}});const page=await ctx.newPage();const errors=[];page.on('pageerror',e=>errors.push(String(e))); + const ctx=await createDocsContext(browser,BASE,{viewport:{width:1440,height:1000}});const page=await ctx.newPage();const errors=[];page.on('pageerror',e=>errors.push(String(e))); await page.goto(BASE+'/docs/integrations',{waitUntil:'networkidle'}); const search=()=>page.locator('#integration-search'); async function query(q,n=1) {await search().fill(q);await page.waitForTimeout(450);assert.equal(await page.locator('[data-integration-card]:visible').count(),n,'query: '+q);} @@ -92,11 +93,11 @@ async function record(name, fn) { try {const detail=await fn();results.push({nam await page.goto(BASE+'/docs/integrations/google-adk',{waitUntil:'networkidle'});assert.equal(await page.locator('.integration-sidebar a[aria-current="page"]').innerText(),'Google ADK'); }); await record('reduced motion and light preference retain site dark tokens',async()=>{ - const c=await browser.newContext({viewport:{width:1440,height:1000},reducedMotion:'reduce',colorScheme:'light'});const p=await c.newPage();await p.goto(BASE+'/docs/integrations',{waitUntil:'networkidle'}); + const c=await createDocsContext(browser,BASE,{viewport:{width:1440,height:1000},reducedMotion:'reduce',colorScheme:'light'});const p=await c.newPage();await p.goto(BASE+'/docs/integrations',{waitUntil:'networkidle'}); assert.equal(await p.locator('[data-integration-card]').first().evaluate(e=>getComputedStyle(e).transitionDuration),'0s');const background=await p.locator('body').evaluate(e=>getComputedStyle(e).backgroundColor);await p.screenshot({path:OUT+'/after-light-reduced-motion.png'});await c.close();return {background}; }); await record('JavaScript disabled: all cards, category anchors and direct navigation',async()=>{ - const c=await browser.newContext({viewport:{width:375,height:812},javaScriptEnabled:false});const p=await c.newPage();await p.goto(BASE+'/docs/integrations',{waitUntil:'networkidle'});assert.equal(await p.locator('[data-integration-card]:visible').count(),integrations.length);assert.equal(await p.locator('.directory-controls').isVisible(),false);await p.screenshot({path:OUT+'/no-js-mobile.png'}); + const c=await createDocsContext(browser,BASE,{viewport:{width:375,height:812},javaScriptEnabled:false});const p=await c.newPage();await p.goto(BASE+'/docs/integrations',{waitUntil:'networkidle'});assert.equal(await p.locator('[data-integration-card]:visible').count(),integrations.length);assert.equal(await p.locator('.directory-controls').isVisible(),false);await p.screenshot({path:OUT+'/no-js-mobile.png'}); await p.locator('noscript a[href="#java"]').click();await p.locator('[href="/docs/integrations/traceai/java/google-adk"][data-integration-card]').click();await p.waitForURL('**/java/google-adk');assert.equal(await p.locator('h1').count(),1);await c.close(); }); await record('no application JavaScript errors',async()=>{assert.deepEqual(errors,[]);}); diff --git a/scripts/integrations.regression.cjs b/scripts/integrations.regression.cjs index 8ffebd31a..f01289a84 100644 --- a/scripts/integrations.regression.cjs +++ b/scripts/integrations.regression.cjs @@ -1,6 +1,7 @@ // Regressions adapted from verify-scripts/{acceptance,matrix,race-proof}.cjs. // Run against the actual built docs shell, never a standalone logo atlas. const { chromium } = require('playwright'); +const { createDocsContext } = require('./docs-browser.cjs'); const fs = require('node:fs/promises'); const path = require('node:path'); const os = require('node:os'); @@ -55,7 +56,7 @@ function luminance(rgb) { return rgb.map(v => v / 255).map(v => v <= 0.04045 ? v const manifest = JSON.parse(await fs.readFile(path.join(__dirname, '../public/images/integrations/manifest.json'))); const browser = await chromium.launch({ headless: true }); for (const width of [1440, 768, 390, 375]) { - const context = await browser.newContext({ viewport: { width, height: 1000 }, colorScheme: 'dark', reducedMotion: 'reduce' }); + const context = await createDocsContext(browser, BASE,{ viewport: { width, height: 1000 }, colorScheme: 'dark', reducedMotion: 'reduce' }); const page = await context.newPage(); await record(`F1 logo navigation unobscured and scrollable ${width}`, async () => { await page.goto(BASE + '/docs/integrations', { waitUntil: 'networkidle' }); @@ -89,7 +90,7 @@ function luminance(rgb) { return rgb.map(v => v / 255).map(v => v <= 0.04045 ? v await record(`F4 slow uncached navigation cannot inherit pending query ${width}`, async () => { // New context ensures no FastNav/prefetch cache. Hold the network response // for 1s exactly as the independent real-fill/real-click reproduction did. - const c = await browser.newContext({ viewport: { width, height: 1000 } }); + const c = await createDocsContext(browser, BASE,{ viewport: { width, height: 1000 } }); try { const p = await c.newPage(), href = '/docs/integrations/traceai/anthropic'; await p.route('**' + href, async r => { await new Promise(resolve => setTimeout(resolve, 1000)); await r.continue(); }); @@ -113,7 +114,7 @@ function luminance(rgb) { return rgb.map(v => v / 255).map(v => v <= 0.04045 ? v } finally { await c.close(); } }); for (const javaScriptEnabled of [true, false]) await record(`F5 legacy fragments ${width} JS=${javaScriptEnabled}`, async () => { - const c = await browser.newContext({ viewport: { width, height: 1000 }, javaScriptEnabled }); + const c = await createDocsContext(browser, BASE,{ viewport: { width, height: 1000 }, javaScriptEnabled }); try { const p = await c.newPage(), rows = []; for (const [fragment, target] of Object.entries({ traceai: 'directory-setup', 'llm-models': 'providers', 'orchestration-frameworks': 'frameworks', other: 'apps', 'import-traces': 'import', 'export--alerts': 'export' })) { @@ -145,7 +146,7 @@ function luminance(rgb) { return rgb.map(v => v / 255).map(v => v <= 0.04045 ? v }); if (width < 1024) for (const cached of [false, true]) for (const href of ['/docs/integrations/traceai/bedrock', '/docs', '/docs/cookbook', '/docs/sdk', '/docs/api']) { await record(`F2 mobile dismissal ${width} ${cached ? 'cached' : 'uncached'} ${href}`, async () => { - const c = await browser.newContext({ viewport: { width, height: 1000 }, reducedMotion: 'reduce' }); + const c = await createDocsContext(browser, BASE,{ viewport: { width, height: 1000 }, reducedMotion: 'reduce' }); try { const p = await c.newPage(); let permit = false, actualRequests = 0; await p.route('**' + href, async route => { @@ -196,7 +197,7 @@ function luminance(rgb) { return rgb.map(v => v / 255).map(v => v <= 0.04045 ? v const source = await fs.readFile(path.join(__dirname, '../public', asset.file), 'utf8'); if (source.includes('prefers-color-scheme')) rows.push({ key, tile: asset.tile }); } - const c = await browser.newContext({ colorScheme: 'dark' }); + const c = await createDocsContext(browser, BASE,{ colorScheme: 'dark' }); try { const p = await c.newPage(); await p.goto(BASE + '/docs/integrations', { waitUntil: 'networkidle' }); for (const row of rows) { diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index 2e745d1e6..d099b0d36 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -1,3 +1,4 @@ +import './auto-page.test.mjs'; import './pi-plugin-page.test.mjs'; import './openclaw-package-page.test.mjs'; import './goose-page.test.mjs'; diff --git a/src/lib/integrations.mjs b/src/lib/integrations.mjs index 1c01bec88..5f6b2bd97 100644 --- a/src/lib/integrations.mjs +++ b/src/lib/integrations.mjs @@ -26,6 +26,7 @@ export const integrationCategories = [ /** @type {ReadonlyArray} */ export const integrations = [ + { id: 'traceai-auto', name: 'Zero-code Node.js', href: '/docs/integrations/traceai/auto', category: 'frameworks', summary: 'Trace supported Node.js AI calls with one startup preload and no tracing imports.', method: 'traceAI preload', logo: 'generic-framework', aliases: ['@traceai/auto', 'Node.js', 'TypeScript', 'JavaScript', 'zero code', 'auto instrumentation'] }, { id: 'a2a-go', name: 'A2A Go', href: '/docs/integrations/traceai/go/a2a', category: 'frameworks', summary: 'Trace Go agent-to-agent calls on clients and servers.', method: 'traceAI SDK', logo: 'generic-framework' }, { id: 'vitest', name: 'Vitest', href: '/docs/integrations/frameworks/vitest', category: 'frameworks', summary: 'Trace test runs and workers with native OpenTelemetry.', method: 'Native OTLP', logo: 'generic-framework', aliases: ['Vitest tests'] }, { id: 'helicone', name: 'Helicone', href: '/docs/integrations/gateways/helicone', category: 'gateways', summary: 'Trace OpenAI-client calls through a self-hosted Helicone gateway.', method: 'OpenAI client', logo: 'generic-framework' }, diff --git a/src/pages/docs/integrations/traceai/auto.mdx b/src/pages/docs/integrations/traceai/auto.mdx new file mode 100644 index 000000000..d4c206d58 --- /dev/null +++ b/src/pages/docs/integrations/traceai/auto.mdx @@ -0,0 +1,199 @@ +--- +title: "Zero-code Node.js tracing" +description: "Trace Node.js AI calls in Future AGI with @traceai/auto. Install once, preload at startup, and inspect model requests, responses, timing and token usage." +--- + +See your Node.js application's AI requests, responses, timing and token usage in Future AGI without adding tracing imports or wrapping model calls. + +## Before you start + +- **Node.js 20.6 or later**, running on the server. The preload does not run in browsers or edge runtimes. +- A Future AGI **API key and secret key** from [API keys](https://app.futureagi.com/dashboard/keys). +- Your model provider's credentials. Future AGI tracing does not supply a model key. + +## Trace your application + +Use your existing app, or start with the [minimal OpenAI example](#try-a-minimal-openai-app) below. + + + + +Run in your application's directory: + +```bash +npm install @traceai/auto +``` + +OpenAI instrumentation and a global-fetch observer are included. Other dedicated integrations are optional; see [supported libraries](#supported-libraries). + + + + +Set both keys in your process environment, preferably through your deployment's secret manager. For a terminal session, replace these placeholders; do not commit credentials: + +```bash +export FI_API_KEY="your-api-key" +export FI_SECRET_KEY="your-secret-key" +export FI_PROJECT_NAME="my-ai-app" +``` + + +Prompts, responses and supported tool content are **captured by default**. Before handling sensitive data, set `FI_HIDE_INPUTS=true`, `FI_HIDE_OUTPUTS=true` and `FI_HIDE_ERROR_DETAILS=true` in the same environment. See [privacy controls](#privacy-controls). + + + + + +Replace `app.mjs` with your application's entry file: + +```bash +node --import @traceai/auto/register app.mjs +``` + +The preload runs before your application imports its AI libraries. Keep your existing provider configuration and application code unchanged. + +**Using an npm start script?** Pass the preload through `NODE_OPTIONS` instead: + +```bash +NODE_OPTIONS="--import @traceai/auto/register" npm start +``` + +Preserve any other Node flags you already use. For a **CommonJS** application, `--import` also works, or use: + +```bash +node --require @traceai/auto/register app.cjs +``` + +Choose one startup method. Do not combine duplicate preloads or manually instrument the same client. Preload each worker or child process you want to trace. + + + + +Make an AI request and consume its response. Open [Future AGI](https://app.futureagi.com), select **Observe → my-ai-app**, then open the model-call span to inspect its inputs, outputs and available usage. + +Completed spans flush when an ordinary Node process exits naturally. For explicit exits or serverless invocations, follow the [flush and lifecycle guidance](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/docs/FRAMEWORKS.md#aws-lambda-and-short-lived-processes); hard termination can lose spans. + + + + +## Try a minimal OpenAI app + +If you do not have an application yet, install the OpenAI SDK alongside `@traceai/auto`: + +```bash +npm install openai +``` + +Set `OPENAI_API_KEY` through your environment and `OPENAI_MODEL` to a model your provider account can use. Save this as **app.mjs**, then run the preload command above: + +```javascript +import OpenAI from "openai"; + +const response = await new OpenAI().chat.completions.create({ + model: process.env.OPENAI_MODEL, + messages: [{ role: "user", content: "Say hello in one word." }], +}); +console.log(response.choices[0].message.content); +``` + +This is ordinary application code—there are no tracing imports. OpenAI SDK versions 4–7 are supported. For an OpenAI-compatible gateway, configure `OPENAI_BASE_URL` and the provider's key and model as usual. + +## What you get + +![OpenAI chat completion in Future AGI with the model, prompt and completion tokens, duration, request body and response body](/images/docs/integrations/traceai/auto/trace-span.png) + +*The example above in the my-ai-app project, using OpenAI SDK 7 with openai/gpt-4.1-mini through OpenRouter.* + +- **Model-call detail:** provider, model, input/output and duration for supported calls. +- **Usage when supplied:** token counts returned by the provider; missing usage is not inferred. Streaming timing depends on the transport. +- **More application context:** installed dedicated integrations can add agent, tool, retrieval or database spans within their supported APIs. +- **OpenTelemetry compatibility:** keep an existing provider, or use an [application-owned exporter](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/docs/CONFIGURATION.md#bring-your-own-opentelemetry-destination). + +This is AI instrumentation, not a general-purpose APM agent: arbitrary functions and outgoing non-AI HTTP calls are not automatically traced. If the optional `@opentelemetry/instrumentation-http` package is installed, the preload can also add incoming HTTP server spans. Set `FI_DISABLED_INSTRUMENTATIONS=http` to disable that integration. The wire observer yields to covered model spans to avoid duplicate capture. + +## Supported libraries + +**Included:** OpenAI library hooks and observation of recognized AI protocols through the process's global `fetch`. Recognition requires a matching endpoint and request shape; not every transport is covered. + +**Optional:** install the dedicated instrumentor alongside its target library for additional coverage. Use the [generated library table](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/README.md#library-coverage) to find the package and setup mode. An import hook, an enable entry and a manual integration are different paths; auto-registration does not expand an integration's supported methods or versions. + +To see detected libraries and suggested packages, without installing anything: + +```bash +npx --no-install traceai-auto bootstrap +``` + +Run from the application directory, then install any suggested instrumentors you need and restart. Libraries reported as `manual` still need their explicit API. See the [transport and capture limits](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/docs/ARCHITECTURE.md) for wire coverage. + +## Privacy controls + +Content capture is **on by default**. To hide inputs, outputs and error details from the first request: + +```bash +FI_HIDE_INPUTS=true FI_HIDE_OUTPUTS=true FI_HIDE_ERROR_DETAILS=true \ +node --import @traceai/auto/register app.mjs +``` + +| Data | Default and control | +| --- | --- | +| Prompts, responses, tool content and transcripts | Captured where supported. Use `FI_HIDE_INPUTS` and `FI_HIDE_OUTPUTS`; granular message and text flags are also available. | +| Error details | Visible unless input/output value, message, text or invocation-parameter hiding implies error hiding. Set `FI_HIDE_ERROR_DETAILS=true` explicitly to hide details. Explicit `false` overrides the derived setting, not secret/media scrubbing. | +| Known credentials and signed URL values | Scrubbed in traceAI's export view. Unknown or transformed secrets may not be recognized; use hide flags for sensitive content. | +| PII pattern redaction | **Off by default.** Enable with `FI_PII_REDACTION=true`; pattern matching is not comprehensive PII detection. | +| Base64 media and raw audio | Recognized payloads are omitted; raw audio bytes are not exported. `FI_BASE64_IMAGE_MAX_LENGTH` defaults to `0`; raising it does not enable base64 image export. | +| Embedding vectors | Catalog wire formats retain dimensions, not vectors. `FI_HIDE_EMBEDDING_VECTORS=true` also hides vectors on library, forwarded and generic-JSON routes. | + +These controls apply to traceAI-authored values and its export view. **Other exporters retain their own privacy policies**; application-owned processors are not silently rewritten. See [all privacy flags and defaults](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/docs/CONFIGURATION.md#privacy-options). + +## Configuration essentials + +Set configuration **before startup** and restart to change it. Later initialization calls do not reconfigure the agent. + +| Variable | Purpose | +| --- | --- | +| `FI_API_KEY`, `FI_SECRET_KEY` | Complete credential pair for the default Future AGI destination. Both must come from the same configuration source. | +| `FI_PROJECT_NAME` | Set an explicit Observe project name for stable routing. | +| `FI_BASE_URL` | Future AGI collector base URL or full traces endpoint. Defaults to `https://api.futureagi.com`. | +| `FI_INSTRUMENTATIONS` | Comma-separated allowlist, such as `openai,wire`. By default, all eligible integrations are considered. | +| `FI_DISABLED_INSTRUMENTATIONS` | Denylist; takes precedence over the allowlist. | +| `FI_WIRE_CAPTURE` | Global-fetch capture and transport credential observation; defaults to `true`. | +| `FI_SAMPLE_RATE` | Root sampling ratio on agent-owned providers; defaults to `1`. Existing providers keep their sampler. | +| `FI_AUTO_DEBUG` | Set to `true` for a masked startup report. | +| `OTEL_SDK_DISABLED` | Set to `true` to disable initialization. | + +Use literal `true` or `false` for boolean settings, not `1` or `0`. The [configuration reference](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/docs/CONFIGURATION.md) covers config files, profiles, precedence and custom OpenTelemetry destinations. + +## Frameworks and deployment + +| Runtime | Setup | +| --- | --- | +| Next.js | Use a guarded `instrumentation.ts` in the Node runtime and keep the agent and target SDKs external. Never expose FI keys as `NEXT_PUBLIC_*`. [Next.js recipe](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/docs/FRAMEWORKS.md#nextjs). | +| esbuild, Vite SSR, Rollup or webpack | Opt into the Node-server adapter; plugins are inactive until configured. Keep AI SDKs external for library hooks and deploy the complete agent payload, not only the entry file. [Bundler recipes](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/docs/FRAMEWORKS.md#node-server-bundlers). | +| AWS Lambda | Initialize once outside the handler and flush at each invocation boundary. Do not rely on process exit or stack duplicate invocation wrappers. [Lambda recipe](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/docs/FRAMEWORKS.md#aws-lambda-and-short-lived-processes). | +| Browser or edge runtime | The Node preload is not supported. The `/edge` subpath is a low-level fetch observer, not a configured tracing SDK. [Edge boundaries](https://github.com/future-agi/traceAI/blob/d85da9c62d93c2661189e440c13e28f53ff85ff1/typescript/packages/traceai_auto/docs/FRAMEWORKS.md#edge-and-browsers). | + +## Troubleshooting + +Run diagnostics from the app directory with the same FI environment as your app: + +```bash +npx --no-install traceai-auto doctor +``` + +Doctor sends one test span when enabled. Inspect the JSON `active` and `collector` fields: `accepted` means the collector accepted the test export; `failed` and `not_tested (...)` are not success signals. **A zero exit code alone does not prove export health.** Doctor is a separate process, so its `pending` hooks do not tell you whether your running app has imported a library. + +| Symptom | Next step | +| --- | --- | +| Tracing is disabled | Supply both FI keys in the same source. Check `OTEL_SDK_DISABLED`, the allowlist and denylist. | +| Collector export fails | Check `FI_BASE_URL`, credentials and outbound connectivity. Initialization itself does not probe the collector. | +| `missing_instrumentor` or `manual` | Use bootstrap's suggested package, or the integration's explicit API, then restart. | +| Library remains `pending` | Load the agent before the SDK; check supported versions and keep the SDK external when bundling. | +| No wire span appears | Consume or cancel the response. Direct `undici.fetch`, `node-fetch`, WebSocket and gRPC are not global-fetch capture. Unread responses do not produce completed wire spans. | +| Output is missing or unknown | Check hide flags, the body cap and host OpenTelemetry attribute limits. Truncated or dropped content cannot be reconstructed. | +| Duplicate spans | Remove duplicate preloads or manual instrumentation of the same client; keep one global OpenTelemetry provider and one export route per destination. | + +## When to use manual instrumentation + +Use `@traceai/auto` for supported AI calls with minimal application changes. Choose [fi-core and manual tracing](/docs/sdk/tracing/set-up-tracing) when you need custom parent spans, application-specific attributes or precise control over what is traced. Use an integration's explicit wrapper or processor when its setup mode is `manual`. + +You can add custom spans around automatically traced work, but do not register a second instrumentor for the same client. Browse the [integration guides](/docs/integrations/traceai) for library-specific APIs. diff --git a/src/pages/docs/integrations/traceai/index.mdx b/src/pages/docs/integrations/traceai/index.mdx index eb9996dcb..efe46eb11 100644 --- a/src/pages/docs/integrations/traceai/index.mdx +++ b/src/pages/docs/integrations/traceai/index.mdx @@ -9,6 +9,14 @@ Trace your application by choosing an integration below and following its setup Each guide describes the setup for its integration, including any instrumentation package or native telemetry configuration it requires. +## Start without tracing code + + + + Install `@traceai/auto` and preload at startup to trace supported AI calls without changing application code. + + + ## LLM Providers diff --git a/src/pages/docs/quickstart/setup-observability.mdx b/src/pages/docs/quickstart/setup-observability.mdx index fe6dc0c1a..7b6087b90 100644 --- a/src/pages/docs/quickstart/setup-observability.mdx +++ b/src/pages/docs/quickstart/setup-observability.mdx @@ -11,6 +11,10 @@ Observe supports auto-instrumentation for OpenAI, Anthropic, LangChain, LlamaInd --- + +**Using Node.js or TypeScript?** Start with [zero-code Node.js tracing](/docs/integrations/traceai/auto): install `@traceai/auto` and preload it at startup, without tracing imports or per-call wrappers. Use that path **instead of** the explicit JS/TS instrumentation below; do not instrument the same client twice. + + Install the Future AGI instrumentation package and the OpenAI integration (used in this example).