@contrail/telemetry 2.2.0-alpha-tracing.0 → 2.2.0-alpha-tracing.2

package/CHANGELOG.md

@@ -7,6 +7,11 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- **`traceSection(name, attrs, fn)` helper** — opens an OTel span around a section of work, sets attributes (static or computed from the span), and ends the span automatically with error recording on throw.
+- **`@Traced(name, staticAttrs?)` decorator** — class-method decorator that wraps a method's invocation in a `traceSection` span. Auto-sets the OTel-spec `code.function.name` attribute to `${ClassName}.${methodName}` so the actor is searchable without callers having to set it. For dynamic attributes derived from arguments or results, set them inside the body via `trace.getActiveSpan()?.setAttribute(...)`.
+
 ## [2.1.0] - 2026-04-29
 
 ### Added

package/lib/index.browser.d.ts

@@ -7,6 +7,7 @@
 import pino from 'pino';
 import type { Logger } from 'pino';
 export * from './semantic-conventions';
+export * from './tracing';
 export { ATTR_LOG_MESSAGE, ATTR_LOG_BODY, ATTR_LOG_PAYLOAD } from './logger/semantic-conventions';
 export { PINO_LEVEL_TO_OTEL_SEVERITY, PINO_LEVEL_TO_NAME } from './logger/logger-config';
 export { parseOtelResourceAttributes } from './logger/parse-otel-resource-attributes';

package/lib/index.browser.js

@@ -31,6 +31,7 @@ exports.flushLogs = flushLogs;
 const pino_1 = __importDefault(require("pino"));
 // --- Re-export browser-safe modules as-is ---
 __exportStar(require("./semantic-conventions"), exports);
+__exportStar(require("./tracing"), exports);
 var semantic_conventions_1 = require("./logger/semantic-conventions");
 Object.defineProperty(exports, "ATTR_LOG_MESSAGE", { enumerable: true, get: function () { return semantic_conventions_1.ATTR_LOG_MESSAGE; } });
 Object.defineProperty(exports, "ATTR_LOG_BODY", { enumerable: true, get: function () { return semantic_conventions_1.ATTR_LOG_BODY; } });

package/lib/index.d.ts

@@ -1,2 +1,3 @@
 export * from './logger';
 export * from './semantic-conventions';
+export * from './tracing';

package/lib/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./logger"), exports);
 __exportStar(require("./semantic-conventions"), exports);
+__exportStar(require("./tracing"), exports);

package/lib/tracing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './trace-section';
+export * from './traced.decorator';

package/lib/tracing/index.js

@@ -0,0 +1,18 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./trace-section"), exports);
+__exportStar(require("./traced.decorator"), exports);

package/lib/tracing/trace-section.d.ts

@@ -0,0 +1,4 @@
+import { Attributes, Span } from '@opentelemetry/api';
+export type TraceSectionAttributes = Attributes | ((span: Span) => Attributes | void);
+export declare function traceSection<T>(name: string, attributes: TraceSectionAttributes, fn: (span: Span) => T): T;
+export declare function traceSection<T>(name: string, attributes: TraceSectionAttributes, fn: (span: Span) => Promise<T>): Promise<T>;

package/lib/tracing/trace-section.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceSection = traceSection;
+const api_1 = require("@opentelemetry/api");
+const tracer = api_1.trace.getTracer('contrail');
+function applyAttributes(span, attributes) {
+    if (typeof attributes === 'function') {
+        const computed = attributes(span);
+        if (computed)
+            span.setAttributes(computed);
+    }
+    else {
+        span.setAttributes(attributes);
+    }
+}
+function recordError(span, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    span.recordException(err instanceof Error ? err : new Error(message));
+    span.setStatus({ code: api_1.SpanStatusCode.ERROR, message });
+}
+function traceSection(name, attributes, fn) {
+    return tracer.startActiveSpan(name, (span) => {
+        try {
+            applyAttributes(span, attributes);
+            const result = fn(span);
+            if (result && typeof result.then === 'function') {
+                return result.then((val) => {
+                    span.end();
+                    return val;
+                }, (err) => {
+                    recordError(span, err);
+                    span.end();
+                    throw err;
+                });
+            }
+            span.end();
+            return result;
+        }
+        catch (err) {
+            recordError(span, err);
+            span.end();
+            throw err;
+        }
+    });
+}

package/lib/tracing/traced.decorator.d.ts

@@ -0,0 +1,2 @@
+import { Attributes } from '@opentelemetry/api';
+export declare function Traced(name: string, staticAttributes?: Attributes): (target: any, key: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/lib/tracing/traced.decorator.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Traced = Traced;
+const trace_section_1 = require("./trace-section");
+function Traced(name, staticAttributes = {}) {
+    return function (target, key, descriptor) {
+        var _a;
+        const original = descriptor.value;
+        const className = typeof target === 'function' ? target.name : (_a = target === null || target === void 0 ? void 0 : target.constructor) === null || _a === void 0 ? void 0 : _a.name;
+        const keyName = String(key);
+        const codeFunctionName = className && className !== 'Object' && className !== 'Function' ? `${className}.${keyName}` : keyName;
+        const attributes = { ...staticAttributes, 'code.function.name': codeFunctionName };
+        descriptor.value = function (...args) {
+            return (0, trace_section_1.traceSection)(name, attributes, () => original.apply(this, args));
+        };
+        return descriptor;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contrail/telemetry",
-  "version": "2.2.0-alpha-tracing.0",
+  "version": "2.2.0-alpha-tracing.2",
   "description": "Telemetry and monitoring utilities for contrail services",
   "main": "lib/index.js",
   "browser": "lib/index.browser.js",