polartrace 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.1] - 2026-10-05
+
+### Changed
+
+- Requests for paths the application has no route for are no longer recorded.
+  A request (and its trace) is dropped only when the framework matched no route
+  AND the response was 404, so scanner probes such as `/vendor/phpunit/...` or
+  `/index.php` no longer bury the real endpoints. A matched route returning 404
+  and routeless traffic served by middleware (e.g. static files) are still
+  recorded. Applies to Express, Fastify and Koa
+- The exported class is now `Polartrace` (was `PolarTrace`), and the homepage
+  moved to [polartrace.io](https://www.polartrace.io)
+
+### Added
+
+- `recordUnmatchedRoutes` option. Set it to `true` to record unmatched 404s as
+  before, e.g. when hunting misrouted traffic
+
 ## [2.0.0] - 2026-09-12
 
 The first release of the 2.x line - a ground-up hardening of the 1.x agent.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 PolarTrace
+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

package/README.md

@@ -4,9 +4,9 @@
 [![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
+The Node.js agent for [Polartrace](https://www.polartrace.io). 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.
+them to the Polartrace collector - without a single line of application code.
 
 Built on [OpenTelemetry](https://opentelemetry.io).
 
@@ -83,7 +83,7 @@ The agent is configured entirely through environment variables.
 | Variable | Description |
 | --- | --- |
 | `POLARTRACE_APP_NAME` | Service name. Must be unique within your organization. |
-| `POLARTRACE_LICENSE_KEY` | Your PolarTrace license key. |
+| `POLARTRACE_LICENSE_KEY` | Your Polartrace license key. |
 
 ### Optional
 
@@ -146,9 +146,9 @@ Preloading is the recommended integration. When you need explicit control over
 configuration, construct the agent yourself:
 
 ```js
-const { PolarTrace } = require("polartrace");
+const { Polartrace } = require("polartrace");
 
-const agent = new PolarTrace({
+const agent = new Polartrace({
   apiKey: process.env.POLARTRACE_LICENSE_KEY,
   serviceName: "checkout-service",
   captureBody: false, // opt out of request-body capture entirely
@@ -180,7 +180,7 @@ app wired up with the agent.
 
 ## Support
 
-- Documentation and dashboards: [polartrace.com](https://www.polartrace.com)
+- Documentation and dashboards: [polartrace.io](https://www.polartrace.io)
 - Bugs and feature requests: [GitHub issues](https://github.com/polartrace/polartrace-nodejs-agent/issues)
 - Security reports: see [SECURITY.md](SECURITY.md)
 

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export interface PolarTraceConfig {
     captureBody?: boolean;
     captureQuery?: boolean;
     captureConsoleLogs?: boolean;
+    recordUnmatchedRoutes?: boolean;
     enableMongoSpanCollection?: boolean;
     enableRedisSpanCollection?: boolean;
     enablePostgresSpanCollection?: boolean;
@@ -45,7 +46,7 @@ export interface RequestLog {
 export interface TraceSpanData extends TraceSpan {
     serviceVersion?: string;
 }
-declare class PolarTrace {
+declare class Polartrace {
     private config;
     private connectionStatus;
     private connectionError?;
@@ -116,6 +117,7 @@ declare class PolarTrace {
     private redactSensitive;
     private getClientIp;
     private generateRequestId;
+    private isUnmatchedRouteProbe;
     private logRequest;
     private queueLog;
     private flushLogs;
@@ -127,5 +129,5 @@ declare class PolarTrace {
     shutdown(timeoutMs?: number): Promise<void>;
     destroy(): void;
 }
-export { PolarTrace };
+export { Polartrace };
 import "./register";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PolarTrace = void 0;
+exports.Polartrace = void 0;
 const api_1 = require("@opentelemetry/api");
 const trace_1 = require("./trace");
 const crypto_1 = require("crypto");
@@ -23,7 +23,7 @@ const mongo_instrumentation_1 = require("./instrumentations/mongo.instrumentatio
 const redis_instrumentation_1 = require("./instrumentations/redis.instrumentation");
 const postgres_instrumentation_1 = require("./instrumentations/postgres.instrumentation");
 const host_metrics_monitor_1 = require("./metrics/host-metrics-monitor");
-class PolarTrace {
+class Polartrace {
     constructor(config) {
         this.connectionStatus = "pending";
         this.statusAnnounced = false;
@@ -58,6 +58,7 @@ class PolarTrace {
             captureBody: true,
             captureQuery: true,
             captureConsoleLogs: true,
+            recordUnmatchedRoutes: false,
             enableMongoSpanCollection: true,
             enableRedisSpanCollection: true,
             enablePostgresSpanCollection: true,
@@ -160,7 +161,7 @@ class PolarTrace {
             throw new Error("apiKey is required (set POLARTRACE_LICENSE_KEY)");
         }
         if (this.config.apiKey.length < 10) {
-            throw new Error("apiKey does not look like a PolarTrace license key (set POLARTRACE_LICENSE_KEY)");
+            throw new Error("apiKey does not look like a Polartrace license key (set POLARTRACE_LICENSE_KEY)");
         }
     }
     setupFlushTimer() {
@@ -329,6 +330,7 @@ class PolarTrace {
                 serviceName: this.config.serviceName,
                 serviceVersion: version_1.AGENT_VERSION,
                 excludeAgentSpans: true,
+                recordUnmatchedRoutes: this.config.recordUnmatchedRoutes,
                 agentEndpoints: agentEndpointPatterns.length > 0 ? agentEndpointPatterns : undefined,
                 sharedSpanIdMap: this.spanIdMap,
                 onSpan: (span) => {
@@ -698,7 +700,10 @@ class PolarTrace {
                         requestLog.consoleLogs = capturedLogs;
                     }
                 }
-                this.logRequest(requestLog);
+                const koaRoute = ctx._matchedRoute ?? ctx.routerPath ?? ctx.router?.match;
+                if (!this.isUnmatchedRouteProbe(koaRoute, requestLog.statusCode)) {
+                    this.logRequest(requestLog);
+                }
             }
             if (thrown)
                 throw thrown;
@@ -774,6 +779,9 @@ class PolarTrace {
                     name: state.error?.name,
                 };
             }
+            const fastifyRoute = request.routeOptions?.url ?? request.routerPath ?? request.context?.config?.url;
+            if (this.isUnmatchedRouteProbe(fastifyRoute, reply.statusCode))
+                return;
             this.logRequest(requestLog);
         });
     }
@@ -793,6 +801,9 @@ class PolarTrace {
                 requestLog.consoleLogs = capturedLogs;
             }
         }
+        if (this.isUnmatchedRouteProbe(req?.route, res.statusCode)) {
+            return originalMethod.call(res, data);
+        }
         this.logRequest(requestLog);
         return originalMethod.call(res, data);
     }
@@ -871,6 +882,13 @@ class PolarTrace {
     generateRequestId() {
         return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
     }
+    isUnmatchedRouteProbe(matchedRoute, statusCode) {
+        if (this.config.recordUnmatchedRoutes)
+            return false;
+        if (statusCode !== 404)
+            return false;
+        return !matchedRoute;
+    }
     logRequest(log) {
         this.queueLog(log);
     }
@@ -1172,7 +1190,7 @@ class PolarTrace {
         diagnostics_1.diagnostics.close();
     }
 }
-exports.PolarTrace = PolarTrace;
+exports.Polartrace = Polartrace;
 function envFlag(name, fallback) {
     const raw = process.env[name]?.trim().toLowerCase();
     if (raw === undefined || raw === "") {
@@ -1194,7 +1212,7 @@ function autoInitFromEnv() {
     const logFile = process.env.POLARTRACE_LOG_FILE?.trim() || undefined;
     let agent;
     try {
-        agent = new PolarTrace({
+        agent = new Polartrace({
             apiKey,
             serviceName,
             enableConsoleLog: envFlag("POLARTRACE_ENABLE_CONSOLE_LOG", false),

package/dist/trace/trace-monitor.d.ts

@@ -28,6 +28,7 @@ export interface TraceMonitorConfig {
     serviceVersion?: string;
     onSpan: (span: TraceSpan) => void;
     excludeAgentSpans?: boolean;
+    recordUnmatchedRoutes?: boolean;
     agentEndpoints?: string[];
     sharedSpanIdMap?: Map<string, string>;
 }

package/dist/trace/trace-monitor.js

@@ -95,6 +95,9 @@ class CustomSpanProcessor {
             if (this.config.excludeAgentSpans && this.isAgentSpan(span)) {
                 return;
             }
+            if (this.isUnmatchedRouteSpan(span)) {
+                return;
+            }
             if (this.isExpressMiddlewareSpan(span)) {
                 return;
             }
@@ -175,6 +178,18 @@ class CustomSpanProcessor {
             spanName.startsWith("pg.") ||
             spanName.startsWith("pg-pool"));
     }
+    isUnmatchedRouteSpan(span) {
+        if (this.config.recordUnmatchedRoutes)
+            return false;
+        if (span.kind !== api_1.SpanKind.SERVER)
+            return false;
+        const attributes = span.attributes || {};
+        const status = Number(attributes["http.status_code"] ?? attributes["http.response.status_code"]);
+        if (status !== 404)
+            return false;
+        const route = attributes["http.route"];
+        return route === undefined || route === null || route === "";
+    }
     isInternalNoiseSpan(span) {
         const spanName = span.name?.toLowerCase() || "";
         const attributes = span.attributes || {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polartrace",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Zero-code observability agent for Node.js: distributed tracing, request logs and host metrics for Express, NestJS, Fastify and Koa apps, with automatic MongoDB, PostgreSQL and Redis instrumentation. Built on OpenTelemetry.",
   "keywords": [
     "polartrace",
@@ -27,7 +27,7 @@
     "postgresql",
     "redis"
   ],
-  "homepage": "https://www.polartrace.com",
+  "homepage": "https://www.polartrace.io",
   "repository": {
     "type": "git",
     "url": "https://github.com/polartrace/polartrace-nodejs-agent.git"
@@ -36,7 +36,7 @@
     "url": "https://github.com/polartrace/polartrace-nodejs-agent/issues"
   },
   "license": "MIT",
-  "author": "PolarTrace",
+  "author": "Polartrace",
   "engines": {
     "node": ">=18"
   },