polartrace 2.0.0

package/dist/trace/trace-monitor.js

@@ -0,0 +1,376 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceMonitor = void 0;
+const version_1 = require("../version");
+const sdk_node_1 = require("@opentelemetry/sdk-node");
+const auto_instrumentations_node_1 = require("@opentelemetry/auto-instrumentations-node");
+const instrumentation_fastify_1 = require("@opentelemetry/instrumentation-fastify");
+const resources_1 = require("@opentelemetry/resources");
+const api_1 = require("@opentelemetry/api");
+const crypto_1 = require("crypto");
+const diagnostics_1 = require("../diagnostics");
+function withLegacyHttpAttributes(attributes) {
+    const out = { ...attributes };
+    const has = (key) => out[key] !== undefined;
+    const backfill = (legacy, value) => {
+        if (value !== undefined && !has(legacy))
+            out[legacy] = value;
+    };
+    backfill("http.method", out["http.request.method"]);
+    backfill("http.status_code", out["http.response.status_code"]);
+    backfill("http.scheme", out["url.scheme"]);
+    backfill("http.user_agent", out["user_agent.original"]);
+    backfill("net.peer.ip", out["network.peer.address"]);
+    backfill("net.peer.port", out["network.peer.port"]);
+    backfill("net.host.name", out["server.address"]);
+    backfill("net.host.port", out["server.port"]);
+    backfill("http.flavor", out["network.protocol.version"]);
+    const path = out["url.path"];
+    const query = out["url.query"];
+    if (typeof path === "string") {
+        backfill("http.target", query ? `${path}?${query}` : path);
+    }
+    const host = out["server.address"] !== undefined && out["server.port"] !== undefined
+        ? `${out["server.address"]}:${out["server.port"]}`
+        : out["server.address"];
+    backfill("http.host", host);
+    if (out["url.full"] !== undefined) {
+        backfill("http.url", out["url.full"]);
+    }
+    else if (typeof out["url.scheme"] === "string" &&
+        host !== undefined &&
+        typeof path === "string") {
+        backfill("http.url", `${out["url.scheme"]}://${host}${path}`);
+    }
+    return out;
+}
+class CustomSpanProcessor {
+    constructor(config) {
+        this.config = config;
+        this.spanIdMap = config.sharedSpanIdMap || new Map();
+    }
+    static isUnsetOtlpSpanId(id) {
+        if (id === undefined || id === null) {
+            return true;
+        }
+        const t = String(id).trim().toLowerCase();
+        return t.length === 0 || /^0+$/.test(t);
+    }
+    convertSpanIdToUUID(spanId) {
+        if (!spanId)
+            return spanId;
+        if (spanId.length === 32) {
+            return spanId;
+        }
+        if (this.spanIdMap.has(spanId)) {
+            return this.spanIdMap.get(spanId);
+        }
+        const uuidString = (0, crypto_1.randomUUID)().replace(/-/g, "");
+        this.spanIdMap.set(spanId, uuidString);
+        if (this.spanIdMap.size > 10000) {
+            const entries = Array.from(this.spanIdMap.entries());
+            this.spanIdMap.clear();
+            entries.slice(-5000).forEach(([key, value]) => {
+                this.spanIdMap.set(key, value);
+            });
+        }
+        return uuidString;
+    }
+    onStart(span) {
+    }
+    onEnd(span) {
+        try {
+            if (this.isMongoDbSpanFromOTEL(span)) {
+                return;
+            }
+            if (this.isRedisSpanFromOTEL(span)) {
+                return;
+            }
+            if (this.isPostgresSpanFromOTEL(span)) {
+                return;
+            }
+            if (this.isInternalNoiseSpan(span)) {
+                return;
+            }
+            if (this.config.excludeAgentSpans && this.isAgentSpan(span)) {
+                return;
+            }
+            if (this.isExpressMiddlewareSpan(span)) {
+                return;
+            }
+            const startTimeNs = span.startTime[0] * 1000000000 + span.startTime[1];
+            const endTimeNs = span.endTime[0] * 1000000000 + span.endTime[1];
+            const durationMs = (endTimeNs - startTimeNs) / 1000000;
+            const rawParentSpanId = span.parentSpanContext?.spanId ||
+                span.parentSpanId ||
+                span.parentContext?.spanId ||
+                undefined;
+            const originalSpanId = span.spanContext().spanId;
+            const spanIdUUID = this.convertSpanIdToUUID(originalSpanId);
+            const parentSpanIdUUID = CustomSpanProcessor.isUnsetOtlpSpanId(rawParentSpanId)
+                ? undefined
+                : this.convertSpanIdToUUID(rawParentSpanId);
+            const traceSpan = {
+                traceId: span.spanContext().traceId,
+                spanId: spanIdUUID,
+                parentSpanId: parentSpanIdUUID,
+                name: span.name,
+                kind: this.getSpanKind(span.kind),
+                startTime: startTimeNs,
+                endTime: endTimeNs,
+                duration: durationMs,
+                status: {
+                    code: span.status.code === api_1.SpanStatusCode.ERROR ? "ERROR" : "OK",
+                    message: span.status.message,
+                },
+                attributes: withLegacyHttpAttributes(this.sanitizeAttributes(span.attributes)),
+                events: span.events?.map((event) => ({
+                    name: event.name,
+                    timestamp: event.time[0] * 1000000000 + event.time[1],
+                    attributes: this.sanitizeAttributes(event.attributes || {}),
+                })),
+                links: span.links?.map((link) => ({
+                    traceId: link.context.traceId,
+                    spanId: this.convertSpanIdToUUID(link.context.spanId),
+                })),
+                resource: span.resource?.attributes
+                    ? this.sanitizeAttributes(span.resource.attributes)
+                    : undefined,
+            };
+            const route = traceSpan.attributes?.["http.route"] ||
+                traceSpan.attributes?.["http.target"];
+            diagnostics_1.diagnostics.debug(`span ${traceSpan.name} [${traceSpan.kind}] ` +
+                `trace=${traceSpan.traceId.substring(0, 8)} ` +
+                `span=${traceSpan.spanId.substring(0, 8)} ` +
+                `parent=${traceSpan.parentSpanId?.substring(0, 8) ?? "root"} ` +
+                `${traceSpan.duration.toFixed(2)}ms` +
+                (route ? ` ${route}` : ""));
+            this.config.onSpan(traceSpan);
+        }
+        catch (error) {
+            diagnostics_1.diagnostics.debug(`error processing span: ${error.message}`);
+        }
+    }
+    isMongoDbSpanFromOTEL(span) {
+        const attributes = span.attributes || {};
+        const dbSystem = attributes["db.system"];
+        const spanName = span.name?.toLowerCase() || "";
+        return (dbSystem === "mongodb" ||
+            spanName.includes("mongodb") ||
+            spanName.includes("mongoose"));
+    }
+    isRedisSpanFromOTEL(span) {
+        const attributes = span.attributes || {};
+        const dbSystem = attributes["db.system"];
+        const spanName = span.name?.toLowerCase() || "";
+        return (dbSystem === "redis" ||
+            spanName.startsWith("redis") ||
+            spanName.startsWith("ioredis"));
+    }
+    isPostgresSpanFromOTEL(span) {
+        const attributes = span.attributes || {};
+        const dbSystem = attributes["db.system"];
+        const spanName = span.name?.toLowerCase() || "";
+        return (dbSystem === "postgresql" ||
+            spanName.startsWith("pg.") ||
+            spanName.startsWith("pg-pool"));
+    }
+    isInternalNoiseSpan(span) {
+        const spanName = span.name?.toLowerCase() || "";
+        const attributes = span.attributes || {};
+        const noiseSpanNames = [
+            "tcp.connect",
+            "tcp.socket",
+            "dns.lookup",
+            "net.connect",
+            "socket.connect",
+            "connect",
+        ];
+        if (noiseSpanNames.some((noise) => spanName.includes(noise))) {
+            return true;
+        }
+        if (span.kind === api_1.SpanKind.INTERNAL) {
+            const hasOnlyNetworkAttrs = Object.keys(attributes).every((key) => key.startsWith("net.") ||
+                key.startsWith("tcp.") ||
+                key.startsWith("dns.") ||
+                key === "peer.address" ||
+                key === "peer.port");
+            const hasMeaningfulAttrs = Object.keys(attributes).some((key) => key.startsWith("http.") ||
+                key.startsWith("db.") ||
+                key.startsWith("rpc.") ||
+                key.startsWith("messaging.") ||
+                key === "service.name" ||
+                key === "operation.name");
+            if (hasOnlyNetworkAttrs && !hasMeaningfulAttrs) {
+                return true;
+            }
+        }
+        return false;
+    }
+    isAgentSpan(span) {
+        if (span.kind !== api_1.SpanKind.CLIENT) {
+            return false;
+        }
+        const attributes = withLegacyHttpAttributes(span.attributes || {});
+        const httpUrl = attributes["http.url"] || attributes["url"];
+        if (!httpUrl || typeof httpUrl !== "string") {
+            return false;
+        }
+        const agentEndpoints = this.config.agentEndpoints || [
+            "/api/traces",
+            "/api/log",
+            "/api/logs",
+            "/api/host-metrics",
+            "/api/service/validate",
+        ];
+        const trimTrailingSlash = (value) => value.replace(/\/+$/, "") || "/";
+        let pathname = httpUrl;
+        let absolute = "";
+        try {
+            const parsed = new URL(httpUrl);
+            pathname = parsed.pathname;
+            absolute = `${parsed.origin}${parsed.pathname}`;
+        }
+        catch {
+        }
+        const absoluteEndpoints = agentEndpoints.filter((endpoint) => /^https?:\/\//i.test(endpoint));
+        if (absolute && absoluteEndpoints.length > 0) {
+            return absoluteEndpoints.some((endpoint) => trimTrailingSlash(absolute) === trimTrailingSlash(endpoint));
+        }
+        return agentEndpoints
+            .filter((endpoint) => !/^https?:\/\//i.test(endpoint))
+            .some((endpoint) => trimTrailingSlash(pathname) === trimTrailingSlash(endpoint));
+    }
+    isExpressMiddlewareSpan(span) {
+        if (span.kind !== api_1.SpanKind.INTERNAL) {
+            return false;
+        }
+        const name = span.name || "";
+        const lower = name.toLowerCase();
+        return (lower.startsWith("middleware - ") ||
+            lower.startsWith("request handler - "));
+    }
+    getSpanKind(kind) {
+        switch (kind) {
+            case api_1.SpanKind.SERVER:
+                return "SERVER";
+            case api_1.SpanKind.CLIENT:
+                return "CLIENT";
+            case api_1.SpanKind.INTERNAL:
+                return "INTERNAL";
+            case api_1.SpanKind.PRODUCER:
+                return "PRODUCER";
+            case api_1.SpanKind.CONSUMER:
+                return "CONSUMER";
+            default:
+                return "UNKNOWN";
+        }
+    }
+    sanitizeAttributes(attributes) {
+        const sanitized = {};
+        const sensitiveFields = [
+            "password",
+            "token",
+            "secret",
+            "apiKey",
+            "authorization",
+            "creditCard",
+            "ssn",
+        ];
+        for (const [key, value] of Object.entries(attributes)) {
+            if (sensitiveFields.some((field) => key.toLowerCase().includes(field.toLowerCase()))) {
+                sanitized[key] = "[REDACTED]";
+            }
+            else {
+                try {
+                    JSON.stringify(value);
+                    sanitized[key] = value;
+                }
+                catch {
+                    sanitized[key] = String(value);
+                }
+            }
+        }
+        return sanitized;
+    }
+    shutdown() {
+        return Promise.resolve();
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+}
+class TraceMonitor {
+    constructor(config) {
+        this.isInitialized = false;
+        this.config = config;
+    }
+    get initialized() {
+        return this.isInitialized;
+    }
+    async initialize() {
+        if (this.isInitialized) {
+            return;
+        }
+        try {
+            const resource = (0, resources_1.resourceFromAttributes)({
+                "service.name": this.config.serviceName,
+                "service.version": this.config.serviceVersion || version_1.AGENT_VERSION,
+            });
+            const spanProcessor = new CustomSpanProcessor(this.config);
+            const instrumentations = {
+                "@opentelemetry/instrumentation-fs": {
+                    enabled: false,
+                },
+                "@opentelemetry/instrumentation-mongoose": {
+                    enabled: false,
+                },
+                "@opentelemetry/instrumentation-mongodb": {
+                    enabled: false,
+                },
+                "@opentelemetry/instrumentation-ioredis": {
+                    enabled: false,
+                },
+                "@opentelemetry/instrumentation-redis": {
+                    enabled: false,
+                },
+                "@opentelemetry/instrumentation-redis-4": {
+                    enabled: false,
+                },
+                "@opentelemetry/instrumentation-http": {
+                    enabled: true,
+                },
+                "@opentelemetry/instrumentation-express": {
+                    enabled: true,
+                },
+                "@opentelemetry/instrumentation-koa": {
+                    enabled: true,
+                },
+            };
+            this.sdk = new sdk_node_1.NodeSDK({
+                resource,
+                spanProcessors: [spanProcessor],
+                instrumentations: [
+                    (0, auto_instrumentations_node_1.getNodeAutoInstrumentations)(instrumentations),
+                    new instrumentation_fastify_1.FastifyInstrumentation(),
+                ],
+            });
+            this.sdk.start();
+            this.isInitialized = true;
+            globalThis.__POLARTRACE_MONGO_INSTRUMENTATION_ENABLED__ = true;
+            diagnostics_1.diagnostics.debug("OpenTelemetry SDK started - http/express tracing active");
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize trace monitoring: ${error.message}`);
+        }
+    }
+    destroy() {
+        if (this.sdk) {
+            this.sdk.shutdown().catch((err) => {
+                diagnostics_1.diagnostics.debug(`error shutting down OpenTelemetry SDK: ${err}`);
+            });
+        }
+        this.isInitialized = false;
+    }
+}
+exports.TraceMonitor = TraceMonitor;

package/dist/ts-loader.d.ts

@@ -0,0 +1 @@
+export declare function registerTypeScriptLoaderIfNeeded(): void;

package/dist/ts-loader.js

@@ -0,0 +1,75 @@
+"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.registerTypeScriptLoaderIfNeeded = registerTypeScriptLoaderIfNeeded;
+const module_1 = require("module");
+const path = __importStar(require("path"));
+const TS_ENTRY_PATTERN = /\.(ts|mts|cts|tsx)$/i;
+function loadFromHost(moduleId) {
+    const anchor = path.join(process.cwd(), "package.json");
+    const hostRequire = (0, module_1.createRequire)(anchor);
+    try {
+        return hostRequire(moduleId);
+    }
+    catch {
+        return null;
+    }
+}
+function registerTypeScriptLoaderIfNeeded() {
+    const entry = process.argv[1] || "";
+    if (!TS_ENTRY_PATTERN.test(entry)) {
+        return;
+    }
+    const tsx = loadFromHost("tsx/cjs/api");
+    if (tsx && typeof tsx.register === "function") {
+        tsx.register();
+        return;
+    }
+    const tsNode = loadFromHost("ts-node");
+    if (tsNode && typeof tsNode.register === "function") {
+        tsNode.register({
+            transpileOnly: true,
+            compilerOptions: {
+                module: "commonjs",
+                target: "ES2020",
+                esModuleInterop: true,
+                resolveJsonModule: true,
+            },
+        });
+        return;
+    }
+    process.stderr.write(`[polartrace] Cannot run TypeScript entry "${entry}" - install ts-node or tsx as a dependency of your app:\n` +
+        `  npm install --save-dev ts-node typescript\n`);
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const AGENT_VERSION: string;

package/dist/version.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_VERSION = void 0;
+function readAgentVersion() {
+    try {
+        return require("../package.json").version;
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+exports.AGENT_VERSION = readAgentVersion();

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "polartrace",
+  "version": "2.0.0",
+  "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",
+    "observability",
+    "monitoring",
+    "apm",
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "distributed-tracing",
+    "telemetry",
+    "instrumentation",
+    "profiling",
+    "performance",
+    "logging",
+    "metrics",
+    "express",
+    "nestjs",
+    "fastify",
+    "koa",
+    "mongodb",
+    "mongoose",
+    "postgres",
+    "postgresql",
+    "redis"
+  ],
+  "homepage": "https://www.polartrace.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/polartrace/polartrace-nodejs-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/polartrace/polartrace-nodejs-agent/issues"
+  },
+  "license": "MIT",
+  "author": "PolarTrace",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./register": {
+      "require": "./dist/register.js",
+      "import": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/register.js"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint \"src/**/*.ts\""
+  },
+  "peerDependencies": {
+    "express": "^4.0.0",
+    "fastify": "^4.0.0 || ^5.0.0",
+    "koa": "^2.0.0 || ^3.0.0",
+    "mongoose": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "koa": {
+      "optional": true
+    },
+    "mongoose": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.79.0",
+    "@opentelemetry/instrumentation": "^0.221.0",
+    "@opentelemetry/instrumentation-express": "^0.69.0",
+    "@opentelemetry/instrumentation-fastify": "^0.57.0",
+    "@opentelemetry/instrumentation-http": "^0.221.0",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-node": "^0.221.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.69.0",
+    "@typescript-eslint/parser": "^8.69.0",
+    "eslint": "^8.57.1",
+    "express": "^4.18.2",
+    "typescript": "^5.3.3"
+  },
+  "overrides": {
+    "qs": "^6.16.0"
+  }
+}