@contrail/telemetry 2.1.0 → 2.2.0-alpha-tracing.1

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.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,3 @@
+import { Attributes, Span } from '@opentelemetry/api';
+export type TraceSectionAttrs = Attributes | ((span: Span) => Attributes | void);
+export declare function traceSection<T>(name: string, attrs: TraceSectionAttrs, fn: (span: Span) => Promise<T>): Promise<T>;

package/lib/tracing/trace-section.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceSection = traceSection;
+const api_1 = require("@opentelemetry/api");
+const tracer = api_1.trace.getTracer('contrail');
+async function traceSection(name, attrs, fn) {
+    return tracer.startActiveSpan(name, async (span) => {
+        try {
+            if (typeof attrs === 'function') {
+                const computed = attrs(span);
+                if (computed)
+                    span.setAttributes(computed);
+            }
+            else {
+                span.setAttributes(attrs);
+            }
+            return await fn(span);
+        }
+        catch (err) {
+            span.recordException(err);
+            span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}

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

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

package/lib/tracing/traced.decorator.js

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

package/package.json

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