depct-loader (MVP)

Node preload loader for zero-code-change runtime instrumentation.

Usage

NODE_OPTIONS="--require /absolute/path/to/packages/loader/src/index.cjs" node server.js

Or with the CLI wrapper:

npx @depctdev/depct run -- node server.js

Optional env vars:

• DEPCT_PROJECT_ID (default: package name or cwd folder)
• DEPCT_RUN_ID (default: generated UUID)
• DEPCT_SERVER_URL (default: http://localhost:3100)
• DEPCT_EVENTS_PATH (default: /v1/events)
• DEPCT_PROJECT_ROOT (default: current working directory)
• DEPCT_INCLUDE (comma-separated include tokens)
• DEPCT_EXCLUDE (comma-separated exclude tokens)
• DEPCT_SAMPLE_RATE (default: 1)
• DEPCT_FLUSH_MAX_EVENTS (default: 20)
• DEPCT_FLUSH_INTERVAL_MS (default: 1500)
• DEPCT_DEBUG (1/true to enable debug logs)
• DEPCT_DEBUG_EVENTS (1/true to print each captured event with return/error status)
• DEPCT_COLLAPSE_FRAMEWORK_NODES (true by default; suppresses framework-only wrapper spans)

What it does

• Hooks Module._load and wraps exported functions in project files.
• Emits span lifecycle telemetry (span.start, span.finish) with parent-child links.
• Captures stable node identity (node_id) with function/file/line metadata.
• Captures per-call telemetry (request/span/timing/shapes/error class/message redacted).
• Captures structured error payloads on failing spans (error code/status/details shape + client-facing error metadata).
• Captures request metadata/shape for HTTP handlers (method/path/content type/body/query/params/files shapes).
• Uses one canonical request_id across internal spans (derived from incoming request context when available).
• Finalizes route spans on HTTP response completion (finish/close), not only on handler return.
• Captures Express client-surface metadata on spans (HTTP status/content type/response shape/error payload shape).
• Batches events in memory and posts to /v1/events.
• Patches Express route registration to attach trace and route metadata.
• Patches global fetch (when in a request context) to emit external spans.
• Fails open: telemetry failures are dropped and app behavior is preserved.