neatlogs-ts
NeatLogs is an AI agent debugging and observability platform. Use this skill when instrumenting TypeScript/Node.js LLM applications with neatlogs for tracing, monitoring, debugging, observability, spa
SKILL.mdskills/neatlogs-ts/SKILL.md
GitHubNeatLogs TypeScript SDK — Agent Skill
NeatLogs auto-instruments LLM calls, agent frameworks, and custom code with these core exports:
init(), flush(), shutdown(), span(), Span(), trace(), identify(), and log().
Installation
Always install the latest published version (don't pin an older one):
npm install neatlogs@latest
# pnpm add neatlogs@latest · yarn add neatlogs@latest · bun add neatlogs@latest
Requires Node.js >= 18.
Core Principles
- Import order does NOT matter: instrumentation is per-instance via a
wrap*helper (wrapOpenAI(new OpenAI())), so static top-of-file imports are fine. No dynamicimport()gymnastics. - Scripts: end with
await flush()thenawait shutdown(). Servers: callinit()once at startup; do NOT callflush()orshutdown()on every request. - One capture owner per operation: a provider/framework wrapper, handler, hook, or processor owns the spans for calls it captures. Use
span()for your own orchestration. Usetrace()for custom attributes or a manual LLM span only when no supported capture layer owns that operation. - Region endpoint: for EU projects, set
endpoint: 'https://eu.ingest.neatlogs.com'ininit(). For other managed projects, omitendpoint,baseUrl, andNEATLOGS_ENDPOINT. Preserve an explicit self-hosted endpoint. - NEVER pass
instrumentations: [...]. The public option and registry are removed. TypeScript rejects the property, and the JavaScript compatibility guard throws a typed configuration error before telemetry starts. Use the explicit helper from the Supported Instrumentations table. - Init is single-shot:
init()configures a private telemetry provider (never registered globally — see OTel Isolation). Calling it again is a no-op (with a warning). Callshutdown()first to reinitialize (rare). - All lifecycle functions are async:
init(),flush(), andshutdown()return Promises and must be awaited. - Named imports: Always use named imports from
'neatlogs'.
Transport selection
Use this SDK for TypeScript/Node.js. Neatlogs also has SDKs for Python and Go. For a language without a supported Neatlogs SDK, default to the dependency-free HTTP ingest endpoint POST /v1/trace; if that project already emits OpenTelemetry, OTLP/gRPC is also supported. Use the neatlogs-ingest skill for the complete HTTP and gRPC contracts. Do not confuse /v1/trace nested JSON with the /v1/traces OTLP/HTTP protobuf route.
Quick Start
Complete minimal working example:
import { init, wrapOpenAI, span, flush, shutdown } from 'neatlogs';
import { OpenAI } from 'openai';
await init({
apiKey: process.env.NEATLOGS_API_KEY ?? '',
workflowName: 'my-app',
});
// wrapOpenAI patches THIS instance — import order is irrelevant.
const client = wrapOpenAI(new OpenAI());
const myWorkflow = span({ kind: 'WORKFLOW' }, async (query: string) => {
const response = await client.chat.completions.create({
model: 'gpt-4o',
messages: [{ role: 'user', content: query }],
});
return response.choices[0].message.content;
});
await myWorkflow('Hello!');
await flush();
await shutdown();
Instrumentation Workflow
- Assess: Detect what LLM providers/frameworks the project uses.
- Instrument: Choose the correct approach:
- Providers/frameworks → the matching
wrap*helper / handler / processor (see Supported Instrumentations) span()wrappers for custom orchestration codetrace()for custom span attributes and unsupported/raw operations only—never around a call already owned by a wrapper, handler, hook, processor, or instrumentor
- Providers/frameworks → the matching
- Init: Add
await init()once at startup, with noinstrumentationskey. - Verify: build/typecheck the changed project, restart any server/startup process, exercise the real instrumented path, and confirm a new NeatLogs trace with one canonical span per operation.
For a generic Next.js retrieval-and-generation example, see Retrieval-and-generation workflow verification.
Safety gate
Before any edit, confirm this service is TypeScript/Node.js. Identify its package manager from the manifest and lockfile, then read the declared and installed SDK version. Do not install or change dependencies during this inspection. Run exactly one project-local command for the detected package manager:
npm: npm exec --offline --no -- neatlogs doctor --local --json
pnpm: pnpm exec neatlogs doctor --local --json
Yarn: yarn run neatlogs doctor --local --json
Bun: bun --no-install run neatlogs doctor --local --json
These commands let the package manager select the platform-specific local
executable, including the Windows shim. Do not substitute npx, pnpm dlx,
yarn dlx, bunx, a Wizard command, or another downloaded Doctor. Local
mode must be read-only and network-free. It requires no credential and must not
change source or configuration. Require format_version: "neatlogs.doctor/v2", runtime.language: "typescript", and
runtime.schema_version: "2". Compare runtime.sdk_version with the
installed project package to prove that the runner did not select another copy.
Do not compare it with one hardcoded patch version.
If the command is missing or its result has the wrong format, language, schema, or installed-package identity, fail closed. Check the canonical package registry for the latest published stable release. If the project uses an older release, show the exact upgrade command for the detected package manager and obtain explicit user approval before running it. Accept newer compatible releases and never downgrade one. If the installed release is already current but lacks Doctor v2, stop and give safe manual/support remediation. Rerun local Doctor after any approved upgrade. Do not edit while this gate is unresolved.
A local pass proves only that the installed SDK produced and validated its
controlled in-process envelope. It does not prove that the application is
instrumented, that anything was exported, or that a hosted trace is visible.
Preserve every reason_code and remediation_code exactly. Treat a warning,
failure, or unknown future code as manual/support remediation unless the code is
explicitly safe/fixable here. The only source fixes allowed by this gate are:
INSTRUMENTOR_INACTIVE: apply only this skill's documented initialization or wrapper/hook step.ROOT_MISSING: add only the already-requested, documented WORKFLOW boundary at a confirmed entry point.ROOT_NOT_ENDED: add only this skill's documented lifecycle hook.
Do not edit for credential, authentication, transport, backend, ambiguous ownership, or unknown codes. Never reproduce backend PII, routing, mapping, or finalization implementation. Before any build, test, or user-workflow command, show the exact command and obtain explicit user approval. Make reruns idempotent: reread the target first and never duplicate initialization, wrappers, roots, or shutdown hooks. Keep a pre-edit diff. If an approved check fails, use the rollback plan to revert only the edits from this run when they can be isolated safely. Otherwise, stop and give manual recovery instructions that preserve unrelated user work.
After instrumentation, obtain approval for the project checks and one representative real workflow. Obtain separate approval for the authenticated probe. Use only a credential already supplied through the process environment. Never print it, place it in command arguments or files, copy it into output, or put it in agent context.
Run the matching project-local command:
npm: npm exec --offline --no -- neatlogs doctor --probe --json
pnpm: pnpm exec neatlogs doctor --probe --json
Yarn: yarn run neatlogs doctor --probe --json
Bun: bun --no-install run neatlogs doctor --probe --json
Probe mode sends one controlled four-span trace through POST /v1/traces with
x-neatlogs-doctor: v1, then reads that exact trace through
GET /api/traces/v3/{trace_id} with the same project credential. Accept a
probe pass only when capture and readback trace IDs match, the trace is
finalized, exactly four spans contain one meaningful WORKFLOW root with
AGENT→LLM and root→TOOL relationships, there are no duplicates, required
semantics and I/O are present, and token values remain numeric. Never infer
success from installation, local logs, exporter flush, HTTP 2xx, or any
uncorrelated trace. Probe success proves the controlled path only. Verify the
real user workflow separately through the completion gate below.
Public CLI credentials after SDK verification
The project key supports SDK Doctor probe readback without public CLI login. If it is the only credential available, report optional CLI readback as waiting on a human and verify the application's exact trace separately in the dashboard. A controlled probe is not proof of the real workflow.
For terminal readback, follow the neatlogs-public-api-cli skill or
https://docs.neatlogs.com/cli if that skill is unavailable. Its 0.2.1 guidance
uses explicit dashboard host, OAuth profile or service-token selection, and
project discovery before project-scoped reads. Keep the SDK key available to
the app; it must not override CLI authentication. Check publication and installed
version before using 0.2.1 options; the CLI skill documents the 0.2.0 fallback.
Completion gate
After local Doctor passes and the requested instrumentation is in place:
- Show the exact project build, test, and real-workflow commands and obtain explicit user approval before running them.
- Run only the approved checks. Restart a long-running process so it loads the new initialization and wrappers; keep reruns idempotent.
- Exercise one representative real user workflow. End every opened span and use the documented flush/shutdown lifecycle for that process type.
- Through the target project's normal product trace view or supported public
read path, verify that exact run is finalized, has one meaningful root and
the expected semantic hierarchy, and contains no duplicate operation spans.
If using a terminal public read, follow the separate
neatlogs-public-api-cliskill; its app-origin credentials andneatlogs traces getcommand are not the SDK's ingest key or Doctor. Its root and parent checks cover the canonical public projection, not emitted span topology.
Keep project credentials in the process environment or client secret storage; never put them in commands, output, files, or agent context. Do not use a legacy marker-discovery protocol. Installation, local logs, exporter flush, HTTP 2xx, a local Doctor pass, and a separate probe pass are not proof that the application's real workflow is correct. If the exact user trace cannot be inspected, report the missing access or observation as a blocker and provide rollback/manual recovery instructions without claiming completion.
init() Reference
import { init } from 'neatlogs';
await init(options);
| Parameter | Type | Default | Description |
|---|---|---|---|
apiKey |
string |
undefined |
API key (or set NEATLOGS_API_KEY env var). If neither is set, spans are created locally but silently not exported |
workflowName |
string |
derived from process.argv[1] |
Name for this workflow/application |
tags |
string[] |
undefined |
Tags for filtering in dashboard |
userId |
string |
undefined |
The operator running the SDK (developer / service account), NOT your app's end-user. For end-user & session identity, see Sessions & End-Users |
sampleRate |
number |
1.0 |
Sampling rate (0.0 to 1.0) |
flushInterval |
number |
5 |
Seconds between batch flushes |
batchSize |
number |
100 |
Max spans per batch |
debug |
boolean |
false |
Enable verbose logging |
disableExport |
boolean |
false |
Disable span export to backend |
captureLogs |
boolean |
false |
Capture log() calls as LOG spans |
pii |
'redact' | 'hash' | false |
undefined |
PII detection setting |
piiEnabled |
boolean |
undefined |
Override team-level server-side PII redaction |
piiSpanTypes |
string[] |
undefined |
Override which span types have PII redaction |
mask |
MaskFunction |
undefined |
Client-side mask function |
metadata |
Record<string, any> |
undefined |
Custom metadata to attach to all spans |
tracerProvider |
BasicTracerProvider |
undefined |
Caller-owned private provider. Neatlogs adds its processors + flushes it, but never registers it globally or shuts it down |
registerShutdownHandlers |
boolean |
true when Neatlogs owns the provider, else false |
Register beforeExit/SIGTERM/SIGINT flush + shutdown handlers |
OTel Isolation
Neatlogs runs on a private TracerProvider and a private active-context store — it never registers globally, and never adopts or shuts down a foreign global provider. A co-tenant tracer's active span (Datadog, Braintrust, another OTel SDK) can't become a Neatlogs parent, and vice-versa; trace(), auto-roots, log(), and isRootSpan() all resolve the active span from the private store.
tracerProvider(init option): pass your ownBasicTracerProvider— the SDK adds processors + flushes but never registers it globally or shuts it down.registerShutdownHandlers(init option):beforeExit/SIGTERM/SIGINTflush + shutdown; defaultstruewhen Neatlogs owns the provider (so scripts drain spans),falsewhen you passtracerProvider.injectTraceContext(carrier): caller-side W3C propagation. Returnsfalseif no valid Neatlogs span is active.extractTraceContext(carrier, fn): callee-side continuation. Runsfnunder the inbound remote parent in Neatlogs' private context and returns its sync value or Promise. Invalid/missing headers are a fail-open passthrough.
import { extractTraceContext, injectTraceContext, trace } from 'neatlogs';
const headers: Record<string, string> = {};
if (injectTraceContext(headers)) await fetch(url, { headers });
await extractTraceContext(request.headers, () =>
trace({ name: 'remote_work' }, async () => { /* joins caller's trace */ }),
);
Trace Output
setTraceOutput(value) stamps neatlogs.trace.output on the active trace's ROOT span, so the dashboard shows a meaningful output instead of a raw status object (e.g. an agent that suspends awaiting input). No-op outside a trace; never throws.
import { trace, setTraceOutput } from 'neatlogs';
await trace({ name: 'turn', sessionId }, async () => {
const plan = await proposePlan();
setTraceOutput(plan.title); // show the plan, not the raw status object
});
Sessions & End-Users
Track your app's end-users and group a conversation's turns so you can analyze usage/cost/errors per customer & segment, view multi-turn timelines, and do per-customer replay.
Model: one turn = one trace; a session groups the turns of a conversation (pass the same sessionId on every turn). The end-user is per session. Identity is stamped on the trace ROOT only — the backend rolls it up; child spans ignore these fields. init() does not accept any session/end-user param.
Three ways to declare identity (per-request):
// 1. On a trace() root
await trace({ name: 'turn', sessionId: 'conv_123', endUserId: 'u_456', endUserMetadata: { plan: 'pro' } }, async () => { /* ... */ });
// 2. On a span() root
span({ kind: 'WORKFLOW', sessionId: 'conv_123', endUserId: 'u_456', endUserMetadata: { plan: 'pro' } }, fn);
// 3. Wrapper-only code (no root of your own — you only call neatlogs.wrap(...))
await identify({ sessionId: 'conv_123', endUserId: 'u_456', endUserMetadata: { plan: 'pro' } }, async () => {
await client.chat.completions.create(/* ... */); // the LLM root inherits the identity
});
Lineage uses parentSessionId; application-defined fields use one arbitrary sessionCustomFields object:
await identify({
sessionId: 'child_123',
parentSessionId: 'parent_456',
sessionCustomFields: { feature_name: 'chat', entry_point: 'slack', tenant: 'acme' },
}, runTurn);
Never hardcode a custom key as a new SDK option. Custom fields are encoded under neatlogs.session.custom_fields.
For retrieval spans, always emit the canonical neatlogs.retriever.*
namespace. neatlogs.retrieval.* is an ingestion-only legacy alias.
Browser SDK (
neatlogs/browser) uses the same field names —endUserId,endUserMetadata,sessionId— as client-constructor defaults or per-call ontrace()/trackAI().
Supported Instrumentations
There is no instrumentations: [...] path in the TypeScript SDK. Each library gets an explicit helper you attach to the object yourself. This is the ONLY supported mechanism.
| Library | Helper | Import from |
|---|---|---|
openai |
wrapOpenAI(client) |
neatlogs or neatlogs/openai |
@anthropic-ai/sdk |
wrapAnthropic(client) |
neatlogs or neatlogs/anthropic |
| Azure OpenAI | wrapAzureOpenAI(client) |
neatlogs/azure-openai |
@aws-sdk/client-bedrock-runtime |
wrapBedrock(client) |
neatlogs/bedrock |
@google/genai (Gemini / AI Studio, provider=google) |
wrapGoogleGenAI(client), wrapGoogleGenAIChat(chat) |
neatlogs/google-genai |
@google/genai in Vertex mode (provider=vertex_ai) |
wrapVertexAI(client), wrapVertexAIChat(chat) |
neatlogs/vertex-ai |
| OpenRouter | wrapOpenRouterAgent(client), wrapCallModel(fn) |
neatlogs/openrouter-agent |
Vercel AI SDK (ai) |
wrapAISDK(ai) |
neatlogs/ai |
| Mastra | wrapMastra(entity), wrapMastraRerank(fn) |
neatlogs/mastra |
@anthropic-ai/claude-agent-sdk |
wrapClaudeAgentSDK(sdk) |
neatlogs/claude-agent-sdk |
@langchain/core (covers LangGraph) |
langchainHandler() → config.callbacks |
neatlogs or neatlogs/langchain |
| OpenAI Agents SDK | openaiAgentsProcessor() → addTraceProcessor() |
neatlogs |
| Strands / Pi agents | strandsHooks(agent) / piAgentHooks(agent) |
neatlogs |
| OpenCode | NeatlogsOpencodePlugin |
neatlogs/opencode |
The direct provider wrappers (wrapOpenAI, wrapAnthropic, wrapAzureOpenAI, wrapBedrock, wrapGoogleGenAI, wrapVertexAI, wrapOpenRouterAgent) keep a parentless LLM as the trace root. A standalone non-root provider or manual operation receives one automatic WORKFLOW parent. Framework helpers root themselves.
Why the instrumentations key was removed
Global OpenInference/OTel-contrib instrumentors create and activate spans on process-global context, which a private Neatlogs provider cannot isolate in either direction. The TypeScript SDK therefore has no public instrumentations option or runtime registry. A compatibility guard rejects the removed property before initialization and points to explicit per-instance helpers:
The "openai" auto-instrumentation uses the global OpenTelemetry context and cannot
guarantee isolation from other tracing SDKs (Datadog, etc.).
Use wrapOpenAI() from 'neatlogs/openai' for isolated tracing. Neatlogs does not
support shared global-context instrumentation.
No provider/framework key is accepted, including formerly advertised no-op keys. Python retains a limited fallback instrumentations=[...] path for uncovered providers; do not port that list into TypeScript.
HTTP auto-instrumentation (fetch/undici) is always enabled by
init()for trace context propagation — nothing to configure.
Reference Docs
For deep dives, see the companion reference files:
- Custom instrumentation with
span(),Span(), andtrace()→references/decorators-and-traces.md - Raw HTTP LLM calls (fetch/undici/axios — wrappers are BLIND, need manual spans; streaming lifecycle + per-provider field paths) →
references/raw-http-llm.md - Framework-specific integration patterns →
references/framework-integrations.md - Troubleshooting and common mistakes →
references/troubleshooting.md - Multiple independent workflows in one codebase (a copilot + a summarizer + a background job, each a distinct dashboard workflow) → use the
neatlogs-multi-workflowskill.workflowNameoninit()is process-wide/single-shot; give each feature its ownWORKFLOWroot viatrace({ name, kind: 'WORKFLOW', attributes: { 'neatlogs.workflow.name': ... } }, …).
Environment Variables
| Variable | Description |
|---|---|
NEATLOGS_API_KEY |
API key (alternative to apiKey param) |
NEATLOGS_DISABLE_EXPORT |
Set to "true" to disable span export |
Data Masking and PII
NeatLogs supports both client-side and server-side PII redaction.
Client-Side Masking
Provide a mask callback to init() to redact sensitive data before spans leave the process. You can also pass mask per-span via span({ mask: fn }) or trace({ mask: fn }).
import { init } from 'neatlogs';
import type { MaskFunction } from 'neatlogs';
const redactPii: MaskFunction = (spanData) => {
for (const key of Object.keys(spanData)) {
if (key.includes('email') || key.includes('password')) {
spanData[key] = '[REDACTED]';
}
}
return spanData;
};
await init({ mask: redactPii });
Server-Side PII Redaction
Enable automatic server-side redaction:
await init({
piiEnabled: true,
});
Documentation
Full documentation: https://docs.neatlogs.com/