@tracescout/node

Server-side TraceScout SDK for Node.js: structured log ingestion and automatic outbound HTTP(S) request capture (network events), with trace-context correlation to your browser sessions and logs.

• Node 18+ · ESM + CommonJS · TypeScript types included · zero runtime dependencies
• Express middleware for inbound trace-context propagation (optional peer)

Install

npm install @tracescout/node

The latest dist-tag is the current stable release. Prerelease builds remain available under the beta tag (npm install @tracescout/node@beta).

Quick start

import { TraceScoutNode, logger } from '@tracescout/node';

TraceScoutNode.init({
  projectId: process.env.TRACESCOUT_PROJECT_ID!,
  ingestKey: process.env.TRACESCOUT_INGEST_KEY,   // required in production
  serviceName: 'api-server',
});

logger.info('checkout completed', { fields: { orderId: 'o_123' } });

That's it — logs batch to TraceScout, and your service's outbound HTTP calls are captured automatically as network events (method, URL, status, duration, headers and bodies, error classification), correlated by W3C trace context. Browse them under Network in the TraceScout dashboard.

By default request bodies are captured up to 25 KiB and response bodies up to 50 KiB of UTF-8 bytes; each side is independently configurable up to a hard ceiling of 64 KiB (65,536 bytes). Bodies larger than the cap are truncated to the first N captured bytes (state truncated), and the SDK always reports the declared / observed / captured byte counts so the UI can show "Showing first 50 KB of 148 KB". Fetch/undici bodies are not part of this — see below.

Outbound capture notes

• Covers http/https, axios, got, node-fetch, and (metadata) global fetch/undici. Fetch/undici bodies are intentionally not read — they are reported with an explicit stream_not_safely_observable state, never falsely as captured or empty.
• A non-removable sanitization baseline always redacts credential-bearing headers (authorization, cookie, x-api-key, …), query parameters (api_key, access_token, password, …), JSON body fields (password, accessToken, clientSecret, …) and Bearer/JWT/known-provider token values before anything leaves your process.
• Add your own masking or drop events entirely:

TraceScoutNode.init({
  // ...
  captureOutboundRequests: {
    // Per-side body caps (UTF-8 BYTES). Defaults 25600 / 51200; hard max 65536.
    maxRequestBodyBytes: 25 * 1024,        // default; raise up to 65536
    maxResponseBodyBytes: 50 * 1024,       // default; raise up to 65536
    mask: { redactHeaders: ['x-internal-token'], redactBodyFields: ['ssn'] },
    beforeNetworkSend: (event) => event,   // already sanitized; return null to drop
    // enabled: false,                     // opt out entirely
  },
});

• Body size limits are measured in UTF-8 bytes, applied after sanitization, and enforced independently per side:

  • maxRequestBodyBytes — default 25600 (25 KiB)
  • maxResponseBodyBytes — default 51200 (50 KiB)
  • Both clamp to [0, 65536]; values above the 64 KiB ceiling are reduced to it, negatives to 0.
  • maxBodyBytes is deprecated. If set, it is used as the fallback for a side that has no explicit per-side value. Precedence per side: explicit per-side → legacy maxBodyBytes → new default.
  • A body exceeding its cap is captured as its first-N-bytes prefix and marked truncated; declared/observed/captured byte counts are always reported.

• Fetch/undici bodies are unchanged by these limits. Global fetch and explicit undici request/response bodies are never read (they cannot be observed without disturbing the stream); they are reported with an explicit stream_not_safely_observable state, never falsely as captured or empty.

• Emergency kill switch: set TRACESCOUT_CAPTURE_OUTBOUND=false in the environment to disable capture regardless of code config. Logs keep flowing.

• The SDK never captures its own ingestion traffic, never overwrites an existing traceparent, and sends no baggage to third parties unless you explicitly allowlist a host.

Express correlation (optional)

import express from 'express';
import { expressMiddleware } from '@tracescout/node';

const app = express();
app.use(expressMiddleware());
// requests now carry trace/request context into every log + network event

Docs

Full documentation: https://docs.tracescout.com/docs/getting-started/server-setup

License

Licensed under the Apache License 2.0 (see also NOTICE). "TraceScout" names, logos, and trademarks remain reserved — Apache-2.0 does not grant trademark rights.