Zero-code Node.js tracing

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.
  • 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 below.

Install the package

Run in your application’s directory:

npm install @traceai/auto

OpenAI instrumentation and a global-fetch observer are included. Other dedicated integrations are optional; see supported libraries.

Configure your project

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:

export FI_API_KEY="your-api-key"
export FI_SECRET_KEY="your-secret-key"
export FI_PROJECT_NAME="my-ai-app"

Warning

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.

Start with the preload

Replace app.mjs with your application’s entry file:

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:

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:

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.

Open the trace

Make an AI request and consume its response. Open Future AGI, 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; 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:

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:

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

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.

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 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:

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 for wire coverage.

Privacy controls

Content capture is on by default. To hide inputs, outputs and error details from the first request:

FI_HIDE_INPUTS=true FI_HIDE_OUTPUTS=true FI_HIDE_ERROR_DETAILS=true \
node --import @traceai/auto/register app.mjs
DataDefault and control
Prompts, responses, tool content and transcriptsCaptured where supported. Use FI_HIDE_INPUTS and FI_HIDE_OUTPUTS; granular message and text flags are also available.
Error detailsVisible 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 valuesScrubbed in traceAI’s export view. Unknown or transformed secrets may not be recognized; use hide flags for sensitive content.
PII pattern redactionOff by default. Enable with FI_PII_REDACTION=true; pattern matching is not comprehensive PII detection.
Base64 media and raw audioRecognized 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 vectorsCatalog 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.

Configuration essentials

Set configuration before startup and restart to change it. Later initialization calls do not reconfigure the agent.

VariablePurpose
FI_API_KEY, FI_SECRET_KEYComplete credential pair for the default Future AGI destination. Both must come from the same configuration source.
FI_PROJECT_NAMESet an explicit Observe project name for stable routing.
FI_BASE_URLFuture AGI collector base URL or full traces endpoint. Defaults to https://api.futureagi.com.
FI_INSTRUMENTATIONSComma-separated allowlist, such as openai,wire. By default, all eligible integrations are considered.
FI_DISABLED_INSTRUMENTATIONSDenylist; takes precedence over the allowlist.
FI_WIRE_CAPTUREGlobal-fetch capture and transport credential observation; defaults to true.
FI_SAMPLE_RATERoot sampling ratio on agent-owned providers; defaults to 1. Existing providers keep their sampler.
FI_AUTO_DEBUGSet to true for a masked startup report.
OTEL_SDK_DISABLEDSet to true to disable initialization.

Use literal true or false for boolean settings, not 1 or 0. The configuration reference covers config files, profiles, precedence and custom OpenTelemetry destinations.

Frameworks and deployment

RuntimeSetup
Next.jsUse 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.
esbuild, Vite SSR, Rollup or webpackOpt 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.
AWS LambdaInitialize once outside the handler and flush at each invocation boundary. Do not rely on process exit or stack duplicate invocation wrappers. Lambda recipe.
Browser or edge runtimeThe Node preload is not supported. The /edge subpath is a low-level fetch observer, not a configured tracing SDK. Edge boundaries.

Troubleshooting

Run diagnostics from the app directory with the same FI environment as your app:

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.

SymptomNext step
Tracing is disabledSupply both FI keys in the same source. Check OTEL_SDK_DISABLED, the allowlist and denylist.
Collector export failsCheck FI_BASE_URL, credentials and outbound connectivity. Initialization itself does not probe the collector.
missing_instrumentor or manualUse bootstrap’s suggested package, or the integration’s explicit API, then restart.
Library remains pendingLoad the agent before the SDK; check supported versions and keep the SDK external when bundling.
No wire span appearsConsume 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 unknownCheck hide flags, the body cap and host OpenTelemetry attribute limits. Truncated or dropped content cannot be reconstructed.
Duplicate spansRemove 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 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 for library-specific APIs.

Was this page helpful?

Questions & Discussion