polartrace 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-09-12
+
+The first release of the 2.x line - a ground-up hardening of the 1.x agent.
+Everything below ships together as 2.0.0.
+
+### Breaking
+
+- The agent no longer creates `polartrace_agent.log` in the working directory.
+  Diagnostics are off by default; set `POLARTRACE_LOG_FILE=<path>` to get an
+  append-only diagnostics file at a location you control
+- Conditions that cause silent data loss (unrecognised license key, unreachable
+  collector, batches the collector rejects) are now reported on **stderr** as a
+  single `[polartrace] ...` line, once per condition. Nothing is ever written to
+  stdout
+- A misconfigured agent under `-r polartrace` now disables itself and reports
+  why, instead of throwing during preload and preventing the host application
+  from starting
+- `express` is no longer a required peer dependency. `express`, `fastify`, `koa`
+  and `mongoose` are all optional peers, so a Fastify- or Koa-only application no
+  longer pulls in Express
+- `mongodb`, `mongoose` and `axios` are no longer runtime dependencies; the agent
+  patches the host application's own drivers and uses native `fetch`
+
+### Added
+
+- Fastify (4.x, 5.x) and Koa (2.x, 3.x) request-log capture, attached
+  automatically at instance creation
+- PostgreSQL span collection via the `pg` driver, with `db.system`,
+  `db.operation`, `db.sql.table` and `db.statement` attributes
+  (opt-out: `POLARTRACE_DISABLE_POSTGRES_SPANS`)
+- Redis span collection for `ioredis` and node-redis v4+
+  (opt-out: `POLARTRACE_DISABLE_REDIS_SPANS`)
+- Host metrics sampling: process CPU/memory, event-loop lag percentiles, host
+  load and memory, container cgroup limits
+  (opt-out: `POLARTRACE_DISABLE_HOST_METRICS`)
+- TypeScript entry points run under `-r polartrace` by picking up `tsx` or
+  `ts-node` from the host application
+- Queued telemetry is flushed on `SIGTERM`, `SIGINT` and `beforeExit`, deferring
+  to the application's own signal handlers when it has them
+- `POLARTRACE_ENDPOINT` to override the collector URL
+- `POLARTRACE_LOG_FILE` and the `logFile` config option
+
+### Changed
+
+- OpenTelemetry upgraded to the 2.x core line. HTTP spans carry both the stable
+  semantic conventions (`http.request.method`, `url.path`, ...) and their legacy
+  equivalents (`http.method`, `http.target`, ...), so the collector's wire format
+  is unchanged by the upgrade
+- `@types/express` moved to devDependencies; it is no longer installed by
+  consumers that do not use Express
+- Batches are retried only on 429/5xx/network errors, and dropped with a warning
+  on other 4xx responses (401/402/400/413) that can never succeed on retry
+- Retained failures back off exponentially (10s doubling to a 5 minute ceiling)
+  and honour the collector's `Retry-After` header on 429
+- Log and trace queues are bounded at 5000 items (drop-oldest), matching host
+  metrics, so a long collector outage cannot grow memory without limit
+- Flushes ship at most 500 items per tick instead of the entire queue
+- Flush timers are `unref()`ed, so the agent never keeps the host process alive
+- Spans now report the agent's real version as `service.version` instead of a
+  hardcoded `1.0.0`
+- The published package no longer contains internal implementation comments
+
+### Fixed
+
+- NestJS route exceptions now carry their message and stack in the request
+  log on both Nest platforms (Express and Fastify). Nest's exception layer
+  catches every route error and responds itself, so nothing ever reached the
+  underlying framework's error paths; the agent now records the exception
+  from `BaseExceptionFilter.catch` before Nest responds. 4xx `HttpException`s
+  (`NotFoundException`, validation 400s...) are expected control flow and are
+  deliberately not recorded as errors
+- Express thrown/`next(err)` route errors now carry their message and stack in
+  the request log. They travel Express's error-middleware chain (never the
+  req/res `error` events the agent listened on), so a 500 was recorded with an
+  empty error. The agent now appends a pass-through error middleware at
+  `listen()` time, after the user's stack is complete; Koa and Fastify already
+  captured these via their own hooks
+- Request headers are redacted before transmission. `Authorization`, `Cookie` and
+  `X-API-Key` were previously shipped to the collector in clear text on every
+  request, despite the documented redaction policy. `cookie` and `api-key` were
+  added to the sensitive-field list, which now covers bodies and headers alike
+- Express now captures the request body. It was read at middleware entry, before
+  `express.json()` had parsed anything, so the `body` field was always absent -
+  Fastify and Koa were unaffected
+- node-redis (v4+) commands now produce spans. The patch targeted the public
+  `client.sendCommand`, which node-redis' generated commands never call - they
+  reach the connection through a private method - so the instrumentation was
+  silently inert. The generated command methods are now wrapped directly
+- Fastify 5 and Koa 3 spans carry `http.route` again. The pinned OpenTelemetry
+  bundle predated both, so every endpoint collapsed into a bare `GET`/`POST` span
+  with no route. The OpenTelemetry stack was upgraded and Fastify's
+  instrumentation, no longer part of the auto-instrumentations bundle, is
+  registered explicitly
+- ESM entry points now produce request logs and database spans. Auto-attach was
+  installed on `Module.prototype.require`, which `import` never reaches, so an
+  ESM application silently lost all request logging. Hooks now go through
+  `Module._load`, which both module systems use
+- Inline SQL string literals in `db.statement` are replaced with `'?'`
+- Agent ingest paths are excluded from tracing by exact path. The previous bare
+  `/log` / `/logs` / `/traces` fragments matched any application route
+  containing them and erased those routes from tracing
+
+---
+
+Releases before 2.0.0 (the 1.x line) predate the public repository and are
+intentionally not documented here.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PolarTrace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# polartrace
+
+[![npm version](https://img.shields.io/npm/v/polartrace.svg)](https://www.npmjs.com/package/polartrace)
+[![node](https://img.shields.io/node/v/polartrace.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/polartrace.svg)](LICENSE)
+
+The Node.js agent for [PolarTrace](https://www.polartrace.com). It collects
+distributed traces, request logs and host metrics from your service and ships
+them to the PolarTrace collector - without a single line of application code.
+
+Built on [OpenTelemetry](https://opentelemetry.io).
+
+## Installation
+
+```bash
+npm install polartrace
+```
+
+Requires Node.js 18 or later.
+
+## Quick start
+
+Preload the agent and give it a service name and license key:
+
+```bash
+POLARTRACE_APP_NAME=checkout-service \
+POLARTRACE_LICENSE_KEY=<your-license-key> \
+node -r polartrace server.js
+```
+
+That's it. The agent starts before your application, instruments the frameworks
+and drivers it finds, and begins reporting. If your entry point is TypeScript,
+run it the same way - the agent picks up `tsx` or `ts-node` from your
+dependencies automatically.
+
+### Docker
+
+```dockerfile
+FROM node:20-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY . .
+
+ENV POLARTRACE_APP_NAME=checkout-service
+# Supply POLARTRACE_LICENSE_KEY at runtime, not in the image.
+CMD ["node", "-r", "polartrace", "server.js"]
+```
+
+```yaml
+services:
+  app:
+    build: .
+    environment:
+      POLARTRACE_APP_NAME: checkout-service
+      POLARTRACE_LICENSE_KEY: ${POLARTRACE_LICENSE_KEY}
+    command: node -r polartrace server.js
+```
+
+## What gets instrumented
+
+| Area | Support | Notes |
+| --- | --- | --- |
+| HTTP server & client | Automatic | Inbound and outbound requests, via OpenTelemetry |
+| Express | 4.x | Middleware attached automatically at app creation |
+| Fastify | 4.x, 5.x | Hooks attached automatically at instance creation |
+| Koa | 2.x, 3.x | Middleware prepended automatically |
+| NestJS | 9.x, 10.x | Via its Express/Fastify platform; route exceptions captured from Nest's exception layer |
+| MongoDB / Mongoose | mongoose ≥ 6 | Query spans with collection and operation |
+| PostgreSQL | `pg` | Query spans with `db.operation`, `db.sql.table`, `db.statement` |
+| Redis | `ioredis`, `redis` ≥ 4 | Command spans |
+| Host metrics | Automatic | Process CPU/memory, event-loop lag, host load, cgroup limits |
+
+Every framework and driver above is optional. The agent patches only what your
+application actually loads, and installs nothing on your behalf.
+
+## Configuration
+
+The agent is configured entirely through environment variables.
+
+### Required
+
+| Variable | Description |
+| --- | --- |
+| `POLARTRACE_APP_NAME` | Service name. Must be unique within your organization. |
+| `POLARTRACE_LICENSE_KEY` | Your PolarTrace license key. |
+
+### Optional
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `POLARTRACE_ENDPOINT` | `https://collector.polartrace.io/api/log` | Collector URL. |
+| `POLARTRACE_LOG_FILE` | *(none)* | Append the agent's own diagnostics to this path. |
+| `POLARTRACE_ENABLE_CONSOLE_LOG` | `false` | Mirror verbose agent diagnostics to stderr. |
+| `POLARTRACE_DISABLE_HOST_METRICS` | `false` | Turn off CPU/memory/event-loop sampling. |
+| `POLARTRACE_DISABLE_MONGO_SPANS` | `false` | Turn off MongoDB span collection. |
+| `POLARTRACE_DISABLE_POSTGRES_SPANS` | `false` | Turn off PostgreSQL span collection. |
+| `POLARTRACE_DISABLE_REDIS_SPANS` | `false` | Turn off Redis span collection. |
+
+Boolean variables accept `1` or `true`.
+
+## Data collection and redaction
+
+For each request the agent records method, path, status code, duration, client
+IP, user agent, headers, query parameters, body and any console output produced
+while handling it, along with the trace the request belongs to.
+
+Fields whose names contain `password`, `token`, `secret`, `apiKey`, `api-key`,
+`authorization`, `creditCard`, `ssn` or `cookie` are replaced with `[REDACTED]`
+before anything leaves the process - in nested objects and in **request headers**
+as well as at the top level, so `Authorization`, `Cookie` and `X-API-Key` never
+leave in the clear. Redaction happens client-side; the original values are never
+transmitted.
+
+SQL captured in `db.statement` has inline string literals replaced with `'?'`, so
+a query that interpolates a secret does not ship it. Parameterised queries are
+unaffected - the driver never hands the agent the values.
+
+If your payloads carry sensitive data under names outside that list, turn off
+body capture with the programmatic API below.
+
+## Agent diagnostics
+
+The agent is quiet by design. It writes nothing to stdout and creates no files.
+
+Problems that would otherwise cause silent data loss - an unrecognised license
+key, an unreachable collector, a rejected batch - are reported on **stderr** as a
+single line, once per condition:
+
+```
+[polartrace] collector unavailable: license key not recognised
+```
+
+For a full diagnostic trail, point `POLARTRACE_LOG_FILE` at a path you control:
+
+```bash
+POLARTRACE_LOG_FILE=/var/log/polartrace-agent.log node -r polartrace server.js
+```
+
+A misconfigured agent disables itself and reports why. It will not stop your
+application from starting.
+
+## Programmatic usage
+
+Preloading is the recommended integration. When you need explicit control over
+configuration, construct the agent yourself:
+
+```js
+const { PolarTrace } = require("polartrace");
+
+const agent = new PolarTrace({
+  apiKey: process.env.POLARTRACE_LICENSE_KEY,
+  serviceName: "checkout-service",
+  captureBody: false, // opt out of request-body capture entirely
+});
+
+app.use(agent.middleware()); // Express
+// agent.instrumentFastify(app);       // Fastify
+// app.use(agent.koaMiddleware());     // Koa
+```
+
+Call `await agent.shutdown()` to flush anything still queued before exiting.
+Under `-r polartrace` this is wired up for you: the agent flushes on `SIGTERM`,
+`SIGINT` and `beforeExit`, and defers to your own signal handlers if you have
+them.
+
+## Reliability
+
+Telemetry is queued and flushed every 10 seconds, at most 500 items per batch.
+Queues are bounded and drop oldest-first, so a collector outage cannot grow
+memory without limit. Failed batches are retried with exponential backoff up to
+5 minutes and honour the collector's `Retry-After`; batches the collector
+rejects outright are dropped rather than retried forever. Timers are `unref`ed,
+so the agent never keeps your process alive on its own.
+
+## Examples
+
+[`examples/express-basic`](examples/express-basic) is a minimal runnable Express
+app wired up with the agent.
+
+## Support
+
+- Documentation and dashboards: [polartrace.com](https://www.polartrace.com)
+- Bugs and feature requests: [GitHub issues](https://github.com/polartrace/polartrace-nodejs-agent/issues)
+- Security reports: see [SECURITY.md](SECURITY.md)
+
+## License
+
+[MIT](LICENSE)

package/dist/diagnostics.d.ts

@@ -0,0 +1,20 @@
+export type DiagnosticLevel = "error" | "warn" | "info" | "debug";
+export interface DiagnosticsOptions {
+    verbose?: boolean;
+    filePath?: string;
+}
+declare class Diagnostics {
+    private verbose;
+    private stream?;
+    private readonly announced;
+    configure(options: DiagnosticsOptions): void;
+    error(message: string): void;
+    warn(message: string): void;
+    info(message: string): void;
+    debug(message: string): void;
+    warnOnce(key: string, message: string): void;
+    private emit;
+    close(): void;
+}
+export declare const diagnostics: Diagnostics;
+export {};

package/dist/diagnostics.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diagnostics = void 0;
+const fs = __importStar(require("fs"));
+const PREFIX = "[polartrace]";
+class Diagnostics {
+    constructor() {
+        this.verbose = false;
+        this.announced = new Set();
+    }
+    configure(options) {
+        if (options.verbose !== undefined) {
+            this.verbose = options.verbose;
+        }
+        const filePath = options.filePath?.trim();
+        if (!filePath || this.stream) {
+            return;
+        }
+        try {
+            this.stream = fs.createWriteStream(filePath, { flags: "a" });
+            this.stream.on("error", () => {
+                this.stream = undefined;
+            });
+        }
+        catch (error) {
+            process.stderr.write(`${PREFIX} could not open log file ${filePath}: ${error.message}\n`);
+        }
+    }
+    error(message) {
+        this.emit("error", message);
+    }
+    warn(message) {
+        this.emit("warn", message);
+    }
+    info(message) {
+        this.emit("info", message);
+    }
+    debug(message) {
+        this.emit("debug", message);
+    }
+    warnOnce(key, message) {
+        const alreadyAnnounced = this.announced.has(key);
+        this.announced.add(key);
+        this.emit("warn", message, { toStderr: !alreadyAnnounced });
+    }
+    emit(level, message, options) {
+        if (this.stream) {
+            try {
+                this.stream.write(`${new Date().toISOString()} ${level.toUpperCase().padEnd(5)} ${message}\n`);
+            }
+            catch {
+            }
+        }
+        const isProblem = level === "error" || level === "warn";
+        const toStderr = options?.toStderr ?? true;
+        if (toStderr && (isProblem || this.verbose)) {
+            process.stderr.write(`${PREFIX} ${message}\n`);
+        }
+    }
+    close() {
+        if (!this.stream) {
+            return;
+        }
+        try {
+            this.stream.end();
+        }
+        catch {
+        }
+        this.stream = undefined;
+    }
+}
+exports.diagnostics = new Diagnostics();

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import { Request, Response, NextFunction } from "express";
+import { TraceSpan } from "./trace";
+export interface PolarTraceConfig {
+    apiKey: string;
+    serviceName: string;
+    endpoint?: string;
+    enableConsoleLog?: boolean;
+    logFile?: string;
+    captureHeaders?: boolean;
+    captureBody?: boolean;
+    captureQuery?: boolean;
+    captureConsoleLogs?: boolean;
+    enableMongoSpanCollection?: boolean;
+    enableRedisSpanCollection?: boolean;
+    enablePostgresSpanCollection?: boolean;
+    enableHostMetrics?: boolean;
+    mongoose?: any;
+}
+export interface RequestLog {
+    timestamp: string;
+    method: string;
+    path: string;
+    statusCode?: number;
+    duration: number;
+    startTime?: string;
+    endTime?: string;
+    headers?: Record<string, string | string[] | undefined>;
+    query?: Record<string, any>;
+    body?: any;
+    userAgent?: string;
+    ip?: string;
+    host?: string;
+    consoleLogs?: Array<{
+        timestamp: string;
+        level: string;
+        args: any[];
+    }>;
+    traceId?: string;
+    error?: {
+        message: string;
+        stack?: string;
+        name?: string;
+    };
+}
+export interface TraceSpanData extends TraceSpan {
+    serviceVersion?: string;
+}
+declare class PolarTrace {
+    private config;
+    private connectionStatus;
+    private connectionError?;
+    private statusAnnounced;
+    private logQueue;
+    private flushTimer?;
+    private defaultHeaders;
+    private originalConsoleLog?;
+    private originalConsoleError?;
+    private originalConsoleWarn?;
+    private originalConsoleInfo?;
+    private isFlushing;
+    private isTraceFlushing;
+    private isHostMetricsFlushing;
+    private traceMonitor?;
+    private traceQueue;
+    private traceFlushTimer?;
+    private hostMetricsMonitor?;
+    private readonly hostMetricsQueue;
+    private hostMetricsFlushTimer?;
+    private readonly HOST_METRICS_QUEUE_LIMIT;
+    private readonly LOG_QUEUE_LIMIT;
+    private readonly TRACE_QUEUE_LIMIT;
+    private readonly MAX_BATCH_SIZE;
+    private readonly FLUSH_INTERVAL;
+    private readonly API_TIMEOUT;
+    private readonly MAX_BACKOFF_MS;
+    private logConsecutiveFailures;
+    private logBackoffUntil;
+    private traceConsecutiveFailures;
+    private traceBackoffUntil;
+    private hostMetricsConsecutiveFailures;
+    private hostMetricsBackoffUntil;
+    private traceCache;
+    private parentSpanTracker;
+    private traceTimestamps;
+    private readonly TRACE_CACHE_TIMEOUT;
+    private spanIdMap;
+    constructor(config: PolarTraceConfig);
+    private postJson;
+    private shouldRetainBatch;
+    private nextBackoffMs;
+    private getBaseUrl;
+    private validateApiKey;
+    private setupFlushTimer;
+    private initializeHostMetricsMonitoring;
+    private queueHostMetricSample;
+    private describeNetworkError;
+    private validateConnection;
+    private showConnectionStatus;
+    private initializeTraceMonitoringSync;
+    private queueTraceSpan;
+    private isParentSpan;
+    private flushTrace;
+    private cleanupOldTraces;
+    private convertMongoSpanToTraceSpan;
+    private convertRedisSpanToTraceSpan;
+    private convertPostgresSpanToTraceSpan;
+    private convertSpanIdToUUID;
+    private generateUUID;
+    private getActiveTraceId;
+    middleware(): (req: Request, res: Response, next: NextFunction) => void;
+    koaMiddleware(): (ctx: any, next: () => Promise<any>) => Promise<void>;
+    instrumentFastify(app: any): void;
+    private handleResponse;
+    private interceptConsole;
+    private restoreConsole;
+    private redactSensitive;
+    private getClientIp;
+    private generateRequestId;
+    private logRequest;
+    private queueLog;
+    private flushLogs;
+    private sendLogsToAPI;
+    private flushTraces;
+    private sendTracesToAPI;
+    private flushHostMetrics;
+    private sendHostMetricsToAPI;
+    shutdown(timeoutMs?: number): Promise<void>;
+    destroy(): void;
+}
+export { PolarTrace };
+import "./register";