@hazeljs/observability 0.7.8 → 0.8.0

package/README.md

@@ -93,14 +93,15 @@ class AIService {
 The observability package follows the A2A (Agent-to-Agent) and OTel specifications to ensure your traces are compatible with the broader ecosystem.
 
 <MermaidDiagram chart={`graph TD
-    A["@Trace() Decorator"] --> B["Observability Service"]
-    B --> C["OpenTelemetry Provider"]
-    C --> D["OTLP Exporter"]
-    D --> E["Observability Platform<br/>(Jaeger, Honeycomb, Datadog)"]
-    
+A["@Trace() Decorator"] --> B["Observability Service"]
+B --> C["OpenTelemetry Provider"]
+C --> D["OTLP Exporter"]
+D --> E["Observability Platform<br/>(Jaeger, Honeycomb, Datadog)"]
+
     style A fill:#3b82f6,color:#fff
     style B fill:#6366f1,color:#fff
     style C fill:#10b981,color:#fff
+
 `} />
 
 ## API Reference
@@ -109,11 +110,7 @@ The observability package follows the A2A (Agent-to-Agent) and OTel specificatio
 
 ```typescript
 class OpenTelemetryProvider {
-  constructor(config: {
-    serviceName: string;
-    endpoint?: string;
-    headers?: Record<string, string>;
-  });
+  constructor(config: { serviceName: string; endpoint?: string; headers?: Record<string, string> });
   initialize(): void;
   shutdown(): Promise<void>;
 }
@@ -126,6 +123,7 @@ class OpenTelemetryProvider {
 ```
 
 **TraceOptions:**
+
 - `attributes`: Static attributes to add to the span.
 - `captureArgs`: Whether to capture method arguments (default: `false`).
 - `captureResult`: Whether to capture method return value (default: `false`).
@@ -152,4 +150,4 @@ Apache 2.0 © [HazelJS](https://hazeljs.ai)
 
 - [Documentation](https://hazeljs.ai/docs/packages/observability)
 - [GitHub](https://github.com/hazel-js/hazeljs)
-- [Discord](https://discord.com/channels/1448263814238965833/1448263814859456575)
+- [Discord](https://discord.gg/PxNBPzvQk7)

package/dist/decorators/trace.decorator.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tracing Decorator (@Trace)
+ * Automatically wraps a class method inside an OpenTelemetry Span for detailed observability.
+ *
+ * @param spanName Custom name for the span. Defaults to the method name.
+ */
+export declare function Trace(spanName?: string): MethodDecorator;
+//# sourceMappingURL=trace.decorator.d.ts.map

package/dist/decorators/trace.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/trace.decorator.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,CAoDxD"}

package/dist/decorators/trace.decorator.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Trace = Trace;
+const api_1 = require("@opentelemetry/api");
+/**
+ * Tracing Decorator (@Trace)
+ * Automatically wraps a class method inside an OpenTelemetry Span for detailed observability.
+ *
+ * @param spanName Custom name for the span. Defaults to the method name.
+ */
+function Trace(spanName) {
+    return (target, propertyKey, descriptor) => {
+        const originalMethod = descriptor.value;
+        if (typeof originalMethod !== 'function')
+            return descriptor;
+        const methodName = String(propertyKey);
+        const resolvedSpanName = spanName || methodName;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        descriptor.value = function (...args) {
+            const tracer = api_1.trace.getTracer('hazeljs');
+            return tracer.startActiveSpan(resolvedSpanName, (span) => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const handleError = (error) => {
+                    span.recordException(error);
+                    span.setStatus({
+                        code: api_1.SpanStatusCode.ERROR,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                    span.end();
+                    throw error;
+                };
+                try {
+                    span.setAttribute('code.function', methodName);
+                    // Execute original logic
+                    const result = originalMethod.apply(this, args);
+                    if (result instanceof Promise) {
+                        return result
+                            .then((res) => {
+                            span.setStatus({ code: api_1.SpanStatusCode.OK });
+                            span.end();
+                            return res;
+                        })
+                            .catch(handleError);
+                    }
+                    span.setStatus({ code: api_1.SpanStatusCode.OK });
+                    span.end();
+                    return result;
+                }
+                catch (error) {
+                    return handleError(error);
+                }
+            });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        };
+        return descriptor;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './opentelemetry.provider';
+export * from './decorators/trace.decorator';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+"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("./types"), exports);
+__exportStar(require("./opentelemetry.provider"), exports);
+__exportStar(require("./decorators/trace.decorator"), exports);

package/dist/opentelemetry.provider.d.ts

@@ -0,0 +1,28 @@
+import { Tracer } from '@opentelemetry/api';
+import { ObservabilityProvider, ObservabilityConfig } from './types';
+/**
+ * OpenTelemetry implementation of the ObservabilityProvider
+ */
+export declare class OpenTelemetryProvider implements ObservabilityProvider {
+    private config;
+    private provider;
+    private exporter?;
+    constructor(config: ObservabilityConfig);
+    /**
+     * Start tracking observability metrics
+     */
+    start(): Promise<void>;
+    /**
+     * Stop operations gracefully, ensuring spans flush
+     */
+    stop(): Promise<void>;
+    /**
+     * Retrieves a named tracer
+     */
+    getTracer(name: string): Tracer;
+    /**
+     * Tracking LLM cost allows the agent runtime to dynamically emit span metrics or print usage statistics
+     */
+    trackCost(model: string, promptTokens: number, completionTokens: number): void;
+}
+//# sourceMappingURL=opentelemetry.provider.d.ts.map

package/dist/opentelemetry.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opentelemetry.provider.d.ts","sourceRoot":"","sources":["../src/opentelemetry.provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAKnD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAErE;;GAEG;AACH,qBAAa,qBAAsB,YAAW,qBAAqB;IACjE,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,QAAQ,CAAC,CAAoB;gBAEzB,MAAM,EAAE,mBAAmB;IAqBvC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI/B;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;CAS/E"}

package/dist/opentelemetry.provider.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenTelemetryProvider = void 0;
+/* eslint-disable no-console */
+const api_1 = require("@opentelemetry/api");
+const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
+const exporter_trace_otlp_http_1 = require("@opentelemetry/exporter-trace-otlp-http");
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+/**
+ * OpenTelemetry implementation of the ObservabilityProvider
+ */
+class OpenTelemetryProvider {
+    constructor(config) {
+        this.config = config;
+        const resource = (0, resources_1.resourceFromAttributes)({
+            [semantic_conventions_1.SemanticResourceAttributes.SERVICE_NAME]: config.serviceName,
+        });
+        const spanProcessors = [];
+        if (config.otlpEndpoint) {
+            this.exporter = new exporter_trace_otlp_http_1.OTLPTraceExporter({
+                url: config.otlpEndpoint,
+            });
+            spanProcessors.push(new sdk_trace_node_1.BatchSpanProcessor(this.exporter));
+        }
+        this.provider = new sdk_trace_node_1.NodeTracerProvider({
+            resource,
+            ...(spanProcessors.length > 0 ? { spanProcessors } : {}),
+        });
+    }
+    /**
+     * Start tracking observability metrics
+     */
+    async start() {
+        // Register provider globally so trace decorators can pick it up
+        this.provider.register();
+        console.log(`[Observability] Started tracing service ${this.config.serviceName}`);
+    }
+    /**
+     * Stop operations gracefully, ensuring spans flush
+     */
+    async stop() {
+        try {
+            await this.provider.shutdown();
+            if (this.exporter) {
+                await this.exporter.shutdown();
+            }
+            console.log(`[Observability] Stopped tracing service ${this.config.serviceName}`);
+        }
+        catch (e) {
+            console.error('[Observability] Failed to shutdown opentelemetry gracefully', e);
+        }
+    }
+    /**
+     * Retrieves a named tracer
+     */
+    getTracer(name) {
+        return api_1.trace.getTracer(name);
+    }
+    /**
+     * Tracking LLM cost allows the agent runtime to dynamically emit span metrics or print usage statistics
+     */
+    trackCost(model, promptTokens, completionTokens) {
+        const activeSpan = api_1.trace.getActiveSpan();
+        if (activeSpan) {
+            activeSpan.setAttribute('llm.model', model);
+            activeSpan.setAttribute('llm.usage.prompt_tokens', promptTokens);
+            activeSpan.setAttribute('llm.usage.completion_tokens', completionTokens);
+            activeSpan.setAttribute('llm.usage.total_tokens', promptTokens + completionTokens);
+        }
+    }
+}
+exports.OpenTelemetryProvider = OpenTelemetryProvider;

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+import { Tracer } from '@opentelemetry/api';
+/**
+ * Interface for tracking and reporting observability metrics
+ */
+export interface ObservabilityProvider {
+    /**
+     * Initializes the tracing provider setup (e.g., OpenTelemetry NodeSDK)
+     */
+    start(): Promise<void>;
+    /**
+     * Stops and flushes the tracing provider setup
+     */
+    stop(): Promise<void>;
+    /**
+     * Retrieves the tracer
+     */
+    getTracer(name: string): Tracer;
+    /**
+     * Tracks LLM cost metrics
+     * @param model Model name (e.g., 'gpt-4o')
+     * @param promptTokens Number of tokens in the prompt
+     * @param completionTokens Number of tokens in the completion
+     */
+    trackCost(model: string, promptTokens: number, completionTokens: number): void;
+}
+/**
+ * Represents the configuration properties to setup tracing
+ */
+export interface ObservabilityConfig {
+    /** The service name to appear in tracing tools (e.g. 'agent-runtime') */
+    serviceName: string;
+    /** Otlp GRPC/HTTP exporter endpoint (e.g., Datadog, Jaeger, Zipkin) */
+    otlpEndpoint?: string;
+    /** Whether to log prompts directly to the spans (false by default for privacy) */
+    logPrompts?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEhC;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CAChF;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hazeljs/observability",
-  "version": "0.7.8",
+  "version": "0.8.0",
   "description": "Unified observability, OpenTelemetry tracing, and LLM cost tracking for HazelJS agents and flows",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -48,5 +48,5 @@
     "url": "https://github.com/hazeljs/hazel-js/issues"
   },
   "homepage": "https://hazeljs.ai",
-  "gitHead": "906cacdc08d52c4616831b888748f1d1887edb80"
+  "gitHead": "e0ed98ca074dd4f7472816d3c32ef576900dcca6"
 }