@sophonz/node-sdk 0.0.1 → 0.1.0

package/README.md

@@ -35,6 +35,59 @@ console.log('Application running');
 await shutdown();
 ```
 
+### Framework Middleware
+
+The SDK ships request middleware so applications never need to import
+`@opentelemetry/api` directly. The middleware copies baggage entries onto the
+active span, captures the client IP and user-agent, and forwards them to the
+mutable trace context.
+
+```ts
+import express from 'express';
+import { sophonzExpressMiddleware } from '@sophonz/node-sdk';
+
+const app = express();
+app.use(sophonzExpressMiddleware());
+```
+
+```ts
+import Koa from 'koa';
+import { sophonzKoaMiddleware } from '@sophonz/node-sdk';
+
+const app = new Koa();
+app.use(sophonzKoaMiddleware());
+```
+
+Both accept the same options:
+
+- `captureBaggage?: boolean` - Copy baggage entries (prefixed `baggage.`). Default `true`.
+- `captureClientIp?: boolean` - Capture `http.client.ip`. Default `true`.
+- `captureUserAgent?: boolean` - Capture `http.user_agent`. Default `true`.
+- `attributes?: Attributes | ((req) => Attributes)` - Extra static or per-request attributes.
+
+### Re-exported OpenTelemetry API
+
+The OTel API surface is re-exported so you don't have to add
+`@opentelemetry/api` / `@opentelemetry/api-logs` as direct dependencies:
+
+```ts
+import { trace, context, propagation, metrics, logs } from '@sophonz/node-sdk';
+
+const span = trace.getActiveSpan();
+```
+
+### Debugging payloads
+
+```ts
+import { init, enableDebugPayloadExporters } from '@sophonz/node-sdk';
+
+init({ service: 'my-app' });
+if (process.env.SOPHONZ_DEBUG_PAYLOAD === 'true') {
+  // Dump every exported span/log to the terminal alongside the OTLP exporter.
+  void enableDebugPayloadExporters();
+}
+```
+
 ### Command-line Instrumentation
 
 Wrap your Node.js application with the preload binary:
@@ -67,6 +120,18 @@ Gracefully shut down the SDK and flush all telemetry.
 
 Set global trace attributes on the mutable context.
 
+### `sophonzExpressMiddleware(options?): RequestHandler`
+
+Express request middleware that enriches the active span and mutable trace context with baggage, client IP, and user-agent.
+
+### `sophonzKoaMiddleware(options?): Middleware`
+
+Koa equivalent of `sophonzExpressMiddleware`.
+
+### `enableDebugPayloadExporters(): Promise<void>`
+
+Attach console exporters to the initialized providers to print every span and log record. Call after `init`/`initSDK`.
+
 ### SDKConfig Options
 
 - `service?: string` - Service name (default from env or auto-detected)

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sophonz/node-sdk",
-    "version": "0.0.1",
+    "version": "0.1.0",
     "homepage": "https://sophonz.com",
     "repository": {
         "type": "git",

package/build/src/api.d.ts

@@ -0,0 +1,5 @@
+export { context, diag, metrics, propagation, trace, ProxyTracerProvider, SpanKind, SpanStatusCode, ValueType, createContextKey, isSpanContextValid, isValidSpanId, isValidTraceId, } from '@opentelemetry/api';
+export type { Attributes, AttributeValue, Baggage, BaggageEntry, Context, Counter, Histogram, Meter, Span, SpanContext, SpanOptions, TextMapPropagator, Tracer, TracerProvider, } from '@opentelemetry/api';
+export { logs, SeverityNumber } from '@opentelemetry/api-logs';
+export type { Logger as OtelApiLogger, LogRecord } from '@opentelemetry/api-logs';
+//# sourceMappingURL=api.d.ts.map

package/build/src/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/api.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,OAAO,EACP,IAAI,EACJ,OAAO,EACP,WAAW,EACX,KAAK,EACL,mBAAmB,EACnB,QAAQ,EACR,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,aAAa,EACb,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,UAAU,EACV,cAAc,EACd,OAAO,EACP,YAAY,EACZ,OAAO,EACP,OAAO,EACP,SAAS,EACT,KAAK,EACL,IAAI,EACJ,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,MAAM,EACN,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE/D,YAAY,EAAE,MAAM,IAAI,aAAa,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC"}

package/build/src/api.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SeverityNumber = exports.logs = exports.isValidTraceId = exports.isValidSpanId = exports.isSpanContextValid = exports.createContextKey = exports.ValueType = exports.SpanStatusCode = exports.SpanKind = exports.ProxyTracerProvider = exports.trace = exports.propagation = exports.metrics = exports.diag = exports.context = void 0;
+var api_1 = require("@opentelemetry/api");
+Object.defineProperty(exports, "context", { enumerable: true, get: function () { return api_1.context; } });
+Object.defineProperty(exports, "diag", { enumerable: true, get: function () { return api_1.diag; } });
+Object.defineProperty(exports, "metrics", { enumerable: true, get: function () { return api_1.metrics; } });
+Object.defineProperty(exports, "propagation", { enumerable: true, get: function () { return api_1.propagation; } });
+Object.defineProperty(exports, "trace", { enumerable: true, get: function () { return api_1.trace; } });
+Object.defineProperty(exports, "ProxyTracerProvider", { enumerable: true, get: function () { return api_1.ProxyTracerProvider; } });
+Object.defineProperty(exports, "SpanKind", { enumerable: true, get: function () { return api_1.SpanKind; } });
+Object.defineProperty(exports, "SpanStatusCode", { enumerable: true, get: function () { return api_1.SpanStatusCode; } });
+Object.defineProperty(exports, "ValueType", { enumerable: true, get: function () { return api_1.ValueType; } });
+Object.defineProperty(exports, "createContextKey", { enumerable: true, get: function () { return api_1.createContextKey; } });
+Object.defineProperty(exports, "isSpanContextValid", { enumerable: true, get: function () { return api_1.isSpanContextValid; } });
+Object.defineProperty(exports, "isValidSpanId", { enumerable: true, get: function () { return api_1.isValidSpanId; } });
+Object.defineProperty(exports, "isValidTraceId", { enumerable: true, get: function () { return api_1.isValidTraceId; } });
+var api_logs_1 = require("@opentelemetry/api-logs");
+Object.defineProperty(exports, "logs", { enumerable: true, get: function () { return api_logs_1.logs; } });
+Object.defineProperty(exports, "SeverityNumber", { enumerable: true, get: function () { return api_logs_1.SeverityNumber; } });

package/build/src/debug.d.ts

@@ -0,0 +1,2 @@
+export declare const enableDebugPayloadExporters: () => Promise<void>;
+//# sourceMappingURL=debug.d.ts.map

package/build/src/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/debug.ts"],"names":[],"mappings":"AAuBA,eAAO,MAAM,2BAA2B,QAAa,OAAO,CAAC,IAAI,CAyBhE,CAAC"}

package/build/src/debug.js

@@ -0,0 +1,49 @@
+"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.enableDebugPayloadExporters = void 0;
+const enableDebugPayloadExporters = async () => {
+    var _a, _b, _c, _d;
+    const { trace } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/api')));
+    const { logs } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/api-logs')));
+    const { SimpleSpanProcessor, ConsoleSpanExporter } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/sdk-trace-base')));
+    const { SimpleLogRecordProcessor, ConsoleLogRecordExporter } = await Promise.resolve().then(() => __importStar(require('@opentelemetry/sdk-logs')));
+    const traceProvider = trace.getTracerProvider();
+    const traceDelegate = (_b = (_a = traceProvider.getDelegate) === null || _a === void 0 ? void 0 : _a.call(traceProvider)) !== null && _b !== void 0 ? _b : traceProvider;
+    (_c = traceDelegate.addSpanProcessor) === null || _c === void 0 ? void 0 : _c.call(traceDelegate, new SimpleSpanProcessor(new ConsoleSpanExporter()));
+    const logProvider = logs.getLoggerProvider();
+    (_d = logProvider.addLogRecordProcessor) === null || _d === void 0 ? void 0 : _d.call(logProvider, new SimpleLogRecordProcessor(new ConsoleLogRecordExporter()));
+};
+exports.enableDebugPayloadExporters = enableDebugPayloadExporters;

package/build/src/index.d.ts

@@ -1,5 +1,8 @@
+export * from './api';
+export * from './debug';
 export * from './gcp';
 export * from './logger';
+export * from './middleware';
 export * from './otel';
 export { recordException, setupExpressErrorHandler, setupKoaErrorHandler, } from '@sophonz/instrumentation-node-exception';
 export type { MutableAsyncLocalStorageContextManager } from "./MutableAsyncLocalStorageContextManager";

package/build/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,yCAAyC,CAAC;AAEjD,YAAY,EAAE,sCAAsC,EAAE,MAAM,0CAA0C,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,yCAAyC,CAAC;AAEjD,YAAY,EAAE,sCAAsC,EAAE,MAAM,0CAA0C,CAAA"}

package/build/src/index.js

@@ -2,8 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setupKoaErrorHandler = exports.setupExpressErrorHandler = exports.recordException = void 0;
 const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./api"), exports);
+tslib_1.__exportStar(require("./debug"), exports);
 tslib_1.__exportStar(require("./gcp"), exports);
 tslib_1.__exportStar(require("./logger"), exports);
+tslib_1.__exportStar(require("./middleware"), exports);
 tslib_1.__exportStar(require("./otel"), exports);
 var instrumentation_node_exception_1 = require("@sophonz/instrumentation-node-exception");
 Object.defineProperty(exports, "recordException", { enumerable: true, get: function () { return instrumentation_node_exception_1.recordException; } });

package/build/src/middleware.d.ts

@@ -0,0 +1,25 @@
+import type * as http from 'node:http';
+import { type Attributes } from '@opentelemetry/api';
+export interface SophonzMiddlewareOptions {
+    captureBaggage?: boolean;
+    captureClientIp?: boolean;
+    captureUserAgent?: boolean;
+    attributes?: Attributes | ((requestOrContext: unknown) => Attributes);
+}
+interface ExpressLikeRequest extends http.IncomingMessage {
+    ip?: string;
+    get?: (name: string) => string | undefined;
+}
+interface KoaLikeContext {
+    ip?: string;
+    get?: (name: string) => string;
+    request?: {
+        ip?: string;
+        get?: (name: string) => string;
+    };
+}
+type ExpressNext = (error?: unknown) => void;
+export declare const sophonzExpressMiddleware: (options?: SophonzMiddlewareOptions) => (req: ExpressLikeRequest, _res: http.ServerResponse, next: ExpressNext) => void;
+export declare const sophonzKoaMiddleware: (options?: SophonzMiddlewareOptions) => (ctx: KoaLikeContext, next: () => Promise<void>) => Promise<void>;
+export {};
+//# sourceMappingURL=middleware.d.ts.map

package/build/src/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,IAAI,MAAM,WAAW,CAAC;AAEvC,OAAO,EACL,KAAK,UAAU,EAIhB,MAAM,oBAAoB,CAAC;AAO5B,MAAM,WAAW,wBAAwB;IAKvC,cAAc,CAAC,EAAE,OAAO,CAAC;IAIzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAI1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAK3B,UAAU,CAAC,EAAE,UAAU,GAAG,CAAC,CAAC,gBAAgB,EAAE,OAAO,KAAK,UAAU,CAAC,CAAC;CACvE;AAED,UAAU,kBAAmB,SAAQ,IAAI,CAAC,eAAe;IACvD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,UAAU,cAAc;IACtB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/B,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;KAAE,CAAC;CAC3D;AAED,KAAK,WAAW,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAyD7C,eAAO,MAAM,wBAAwB,GACnC,UAAS,wBAA6B,MAUpC,KAAK,kBAAkB,EACvB,MAAM,IAAI,CAAC,cAAc,EACzB,MAAM,WAAW,KAChB,IAqBJ,CAAC;AAcF,eAAO,MAAM,oBAAoB,GAC/B,UAAS,wBAA6B,MAUpC,KAAK,cAAc,EACnB,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,KACxB,OAAO,CAAC,IAAI,CAyBhB,CAAC"}

package/build/src/middleware.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sophonzKoaMiddleware = exports.sophonzExpressMiddleware = void 0;
+const api_1 = require("@opentelemetry/api");
+const otel_1 = require("./otel");
+const getBaggageAttributes = () => {
+    const baggage = api_1.propagation.getBaggage(api_1.context.active());
+    const attrs = {};
+    baggage === null || baggage === void 0 ? void 0 : baggage.getAllEntries().forEach(([key, entry]) => {
+        attrs[`baggage.${key}`] = entry.value;
+    });
+    return attrs;
+};
+const getHeader = (req, name) => {
+    var _a;
+    if (typeof req.get === 'function') {
+        return req.get(name);
+    }
+    const value = (_a = req.headers) === null || _a === void 0 ? void 0 : _a[name.toLowerCase()];
+    return Array.isArray(value) ? value[0] : value;
+};
+const applyAttributes = (attrs) => {
+    const span = api_1.trace.getActiveSpan();
+    if (span) {
+        for (const [key, value] of Object.entries(attrs)) {
+            if (value != null) {
+                span.setAttribute(key, value);
+            }
+        }
+    }
+    (0, otel_1.setTraceAttributes)(attrs);
+};
+const resolveExtraAttributes = (attributes, requestOrContext) => {
+    if (typeof attributes === 'function') {
+        return attributes(requestOrContext);
+    }
+    return attributes !== null && attributes !== void 0 ? attributes : {};
+};
+const sophonzExpressMiddleware = (options = {}) => {
+    const { captureBaggage = true, captureClientIp = true, captureUserAgent = true, attributes, } = options;
+    return (req, _res, next) => {
+        var _a, _b, _c, _d;
+        try {
+            const attrs = {};
+            if (captureBaggage) {
+                Object.assign(attrs, getBaggageAttributes());
+            }
+            if (captureClientIp) {
+                attrs['http.client.ip'] = (_c = (_a = req.ip) !== null && _a !== void 0 ? _a : (_b = req.socket) === null || _b === void 0 ? void 0 : _b.remoteAddress) !== null && _c !== void 0 ? _c : '';
+            }
+            if (captureUserAgent) {
+                attrs['http.user_agent'] = (_d = getHeader(req, 'user-agent')) !== null && _d !== void 0 ? _d : '';
+            }
+            Object.assign(attrs, resolveExtraAttributes(attributes, req));
+            applyAttributes(attrs);
+        }
+        catch {
+        }
+        next();
+    };
+};
+exports.sophonzExpressMiddleware = sophonzExpressMiddleware;
+const sophonzKoaMiddleware = (options = {}) => {
+    const { captureBaggage = true, captureClientIp = true, captureUserAgent = true, attributes, } = options;
+    return async (ctx, next) => {
+        var _a, _b, _c, _d, _e;
+        try {
+            const attrs = {};
+            if (captureBaggage) {
+                Object.assign(attrs, getBaggageAttributes());
+            }
+            if (captureClientIp) {
+                attrs['http.client.ip'] = (_c = (_a = ctx.ip) !== null && _a !== void 0 ? _a : (_b = ctx.request) === null || _b === void 0 ? void 0 : _b.ip) !== null && _c !== void 0 ? _c : '';
+            }
+            if (captureUserAgent) {
+                const ua = typeof ctx.get === 'function'
+                    ? ctx.get('user-agent')
+                    : (_e = (_d = ctx.request) === null || _d === void 0 ? void 0 : _d.get) === null || _e === void 0 ? void 0 : _e.call(_d, 'user-agent');
+                attrs['http.user_agent'] = ua !== null && ua !== void 0 ? ua : '';
+            }
+            Object.assign(attrs, resolveExtraAttributes(attributes, ctx));
+            applyAttributes(attrs);
+        }
+        catch {
+        }
+        await next();
+    };
+};
+exports.sophonzKoaMiddleware = sophonzKoaMiddleware;

package/build/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.0.1";
+export declare const VERSION = "0.1.0";
 //# sourceMappingURL=version.d.ts.map

package/build/src/version.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.0.1';
+exports.VERSION = '0.1.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sophonz/node-sdk",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "homepage": "https://sophonz.com",
   "repository": {
     "type": "git",