@scope-analytics/node

@scope-analytics/node — Scope Node.js backend SDK

Zero-code analytics for AI products. Captures your server-side LLM calls (and ships them to Scope as universal events) by wrapping OpenTelemetry + Arize OpenInference rather than reinventing provider patching. Wire-compatible with the Python SDK (scope_analytics) — both emit the same universal event schema, so one Scope project can mix Python and Node services.

Published on npm (npm install @scope-analytics/node). Auto-captures four providers under both CommonJS and ESM: OpenAI + Anthropic (Arize OpenInference drop-ins), Google Gemini (@google/genai, a Scope-authored instrumentation — no drop-in exists), and the Vercel AI SDK (ai, zero-code — Scope auto-enables its telemetry and translates the native spans; see "Supported providers"). Also shipped: the OpenTelemetry → Scope exporter (handles chat-completions, the Responses API, and multimodal content shapes), the --import bootstrap, config + deploy/git_sha resolution, AsyncLocalStorage session/user/thread/url context, raw-by-default capture with an opt-in credential scrub (Python parity), and live call-and-capture + version-pin tests per provider, plus dual ESM+CJS builds. Coming next: framework middleware (Express/Fastify/Hono/Nest/Next route handlers), the Edge-runtime manual wrapper, an identify() helper, and per-field size caps.

Install

npm install @scope-analytics/node

Set your project secret key (from the Scope dashboard) in the environment:

export SCOPE_API_KEY="sk_live_…"   # or sk_test_…

Use it (two paths, both zero app-code for capture)

1. Zero-code bootstrap (recommended)

Start your server with the tracer pre-loaded — no code change, just a flag. The bootstrap must load before your app imports openai, which --import guarantees:

NODE_OPTIONS="--import @scope-analytics/node/register" node server.js

2. Explicit init

Call init() once at the very top of your entrypoint, before importing openai:

import { init } from '@scope-analytics/node';
init(); // reads SCOPE_API_KEY / SCOPE_ENDPOINT from the env (or pass { apiKey, endpoint })

import OpenAI from 'openai';
// …every OpenAI call from here on is captured and shipped to Scope.

Session stitching (optional, recommended)

Wrap each request so the LLM calls inside it are attributed to a user/session — this is what lets Scope stitch a user's activity across your frontend, backend, and LLM layers:

import { runWithContext } from '@scope-analytics/node';

app.use((req, res, next) => {
  runWithContext({ sessionId: req.headers['x-scope-session-id'], userId: req.user?.id }, next);
});

Without it, backend LLM calls get a temp_… session (captured, but not tied to a user).

Supported providers

Auto-captured with no app-code change: OpenAI (openai), Anthropic (@anthropic-ai/sdk), and Google Gemini (@google/genai) — plus the entire OpenAI-compatible ecosystem (Groq, Together, OpenRouter, DeepSeek, xAI, Azure OpenAI, Ollama, vLLM, …) reached through the openai SDK with a custom base_url, captured at the call site so the base URL is irrelevant.

Vercel AI SDK (ai) is also captured, zero-code — generateText, streamText, generateObject, streamObject. The AI SDK emits telemetry only when it's enabled per call, so @scope-analytics/node enables it for you: it injects experimental_telemetry: { isEnabled: true } into those calls, deep-merged with any telemetry config you already pass (your functionId/metadata/recordInputs/… are preserved). To opt a specific call out, set experimental_telemetry: { isEnabled: false } yourself — that's respected. If you pass your own tracer in experimental_telemetry, those spans go to your tracer rather than Scope.

Module systems (CommonJS & ESM)

Auto-capture hooks your module loader, so it must be in place before your app imports its LLM SDKs — which is exactly what the --import @scope-analytics/node/register bootstrap guarantees (it also registers the ESM loader needed to instrument imports). On that bootstrap, all four providers are captured under both CommonJS and ESM. The explicit init() path covers CommonJS (where you control require order); for ESM, use the bootstrap, since imports are hoisted and a loader can't retroactively hook modules already imported.

Privacy

Raw by default (full-fidelity capture). Opt in to a best-effort credential scrub with init({ redactPatterns: CREDENTIAL_REDACT_PATTERNS }) (exported from this package) — it keeps the key and drops the value over key=value free text in prompts/responses/messages. Not a structural guarantee.

Configuration

Option (init({…}))	Env var	Default	Notes
apiKey	SCOPE_API_KEY	— (required)	Project secret key (sk_live_…/sk_test_…). A public pk_… key is rejected.
endpoint	SCOPE_ENDPOINT	https://api.scopeai.dev	Scope ingest base URL.
environment	SCOPE_ENVIRONMENT	production	Tag on every event.
debug	SCOPE_DEBUG	false	Verbose logging.
serviceName	SCOPE_SERVICE_NAME	scope-app	OTel service.name.

Deploy metadata (git_sha, deployment_id) is read once at startup from your platform's commit env var (Railway / Vercel / Render / Heroku / Cloud Run / Lambda / GIT_COMMIT_SHA) and stamped on every event — so the analyst can reason about "what changed before the drop?". Nothing is invented when no env var is present (honest non-coverage).

Design

@scope-analytics/node is a thin Scope layer over OpenTelemetry:

• Provider instrumentations produce OpenInference GenAI spans — Arize drop-ins for OpenAI/Anthropic, a Scope-authored instrumentation for @google/genai, and the @arizeai/openinference-vercel span processor that translates the Vercel AI SDK's native spans into the same shape.
• ScopeSpanExporter translates each LLM span into a Scope universal event and POSTs { events, source: "backend_sdk" } to ${endpoint}/api/events with Authorization: Bearer <secret>.
• Telemetry is best-effort and never throws — a Scope outage can't crash or slow your app.

Development

npm install
npm test       # vitest (unit + a real-use pipeline → local HTTP collector)
npm run build  # tsup → dual ESM + CJS + .d.ts