arvo-event-handler 1.1.2 → 1.1.3

package/dist/OpenTelemetry/utils.d.ts

@@ -1,11 +1,73 @@
-import { Span, SpanKind } from '@opentelemetry/api';
+import { Span, SpanKind, Tracer } from '@opentelemetry/api';
 import { ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
 export declare function getPackageInfo(): {
     name: string;
     version: string;
 };
+/**
+ * Creates an OpenTelemetry span from an ArvoEvent, facilitating distributed tracing in the Arvo system.
+ *
+ * This function is a cornerstone of Arvo's observability infrastructure, creating spans that represent
+ * discrete units of work or operations within the system. It supports both creating new root spans
+ * and continuing existing traces, enabling comprehensive end-to-end tracing across distributed components.
+ *
+ * @param spanName - A descriptive name for the span, indicating the operation being traced.
+ *                   Choose a name that clearly identifies the work being performed.
+ *
+ * @param event - The ArvoEvent that triggers the span creation. This event may contain
+ *                tracing context (traceparent and tracestate) to link this span to an existing trace.
+ *
+ * @param spanKinds - An object specifying the span's categorization across different tracing contexts:
+ * @param spanKinds.kind - OpenTelemetry SpanKind, indicating the span's role in the trace hierarchy
+ *                         (e.g., SERVER, CLIENT, INTERNAL).
+ * @param spanKinds.openInference - OpenInference span kind, used for AI/ML operation categorization.
+ * @param spanKinds.arvoExecution - ArvoExecution span kind, for Arvo-specific execution context labeling.
+ *
+ * @param tracer - The OpenTelemetry Tracer instance to use for creating the span.
+ *                 Defaults to ArvoXStateTracer if not provided.
+ *
+ * @returns A new OpenTelemetry Span object that can be used to record operation details,
+ *          set attributes, and create child spans.
+ *
+ * @remarks
+ * - If the input event contains a 'traceparent', the function will continue the existing trace,
+ *   maintaining the distributed tracing context across system boundaries.
+ * - Without a 'traceparent', a new root span is created, potentially starting a new trace.
+ * - The function automatically sets OpenInference and ArvoExecution-specific attributes,
+ *   enhancing the span's context for specialized analysis.
+ *
+ * @example
+ * ```typescript
+ * const event: ArvoEvent = createArvoEvent({
+ *   type: 'orderProcess',
+ *   data: { orderId: '12345' },
+ *   traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+ *   tracestate: "rojo=00f067aa0ba902b7",
+ *   ...
+ * });
+ *
+ * const span = createSpanFromEvent("processOrder", event, {
+ *   kind: SpanKind.INTERNAL,
+ *   openInference: OpenInferenceSpanKind.LLM,
+ *   arvoExecution: ArvoExecutionSpanKind.EVENT_HANDLER
+ * });
+ *
+ * context.with(trace.setSpan(context.active(), span), () => {
+ *  try {
+ *    // Perform order processing logic
+ *    span.setAttributes({ orderId: '12345', status: 'processing' });
+ *    // ... more processing ...
+ *    span.setStatus({ code: SpanStatusCode.OK });
+ *  } catch (error) {
+ *    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+ *  } finally {
+ *    span.end(); // Always remember to end the span
+ *  }
+ * })
+ * ```
+ */
 export declare const createSpanFromEvent: (spanName: string, event: ArvoEvent, spanKinds: {
     kind: SpanKind;
     openInference: OpenInferenceSpanKind;
     arvoExecution: ArvoExecutionSpanKind;
-}) => Span;
+}, tracer?: Tracer) => Span;

package/dist/OpenTelemetry/utils.js

@@ -45,8 +45,71 @@ function getPackageInfo() {
         return { name: 'Unknown', version: 'Unknown' };
     }
 }
-var createSpanFromEvent = function (spanName, event, spanKinds) {
+/**
+ * Creates an OpenTelemetry span from an ArvoEvent, facilitating distributed tracing in the Arvo system.
+ *
+ * This function is a cornerstone of Arvo's observability infrastructure, creating spans that represent
+ * discrete units of work or operations within the system. It supports both creating new root spans
+ * and continuing existing traces, enabling comprehensive end-to-end tracing across distributed components.
+ *
+ * @param spanName - A descriptive name for the span, indicating the operation being traced.
+ *                   Choose a name that clearly identifies the work being performed.
+ *
+ * @param event - The ArvoEvent that triggers the span creation. This event may contain
+ *                tracing context (traceparent and tracestate) to link this span to an existing trace.
+ *
+ * @param spanKinds - An object specifying the span's categorization across different tracing contexts:
+ * @param spanKinds.kind - OpenTelemetry SpanKind, indicating the span's role in the trace hierarchy
+ *                         (e.g., SERVER, CLIENT, INTERNAL).
+ * @param spanKinds.openInference - OpenInference span kind, used for AI/ML operation categorization.
+ * @param spanKinds.arvoExecution - ArvoExecution span kind, for Arvo-specific execution context labeling.
+ *
+ * @param tracer - The OpenTelemetry Tracer instance to use for creating the span.
+ *                 Defaults to ArvoXStateTracer if not provided.
+ *
+ * @returns A new OpenTelemetry Span object that can be used to record operation details,
+ *          set attributes, and create child spans.
+ *
+ * @remarks
+ * - If the input event contains a 'traceparent', the function will continue the existing trace,
+ *   maintaining the distributed tracing context across system boundaries.
+ * - Without a 'traceparent', a new root span is created, potentially starting a new trace.
+ * - The function automatically sets OpenInference and ArvoExecution-specific attributes,
+ *   enhancing the span's context for specialized analysis.
+ *
+ * @example
+ * ```typescript
+ * const event: ArvoEvent = createArvoEvent({
+ *   type: 'orderProcess',
+ *   data: { orderId: '12345' },
+ *   traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+ *   tracestate: "rojo=00f067aa0ba902b7",
+ *   ...
+ * });
+ *
+ * const span = createSpanFromEvent("processOrder", event, {
+ *   kind: SpanKind.INTERNAL,
+ *   openInference: OpenInferenceSpanKind.LLM,
+ *   arvoExecution: ArvoExecutionSpanKind.EVENT_HANDLER
+ * });
+ *
+ * context.with(trace.setSpan(context.active(), span), () => {
+ *  try {
+ *    // Perform order processing logic
+ *    span.setAttributes({ orderId: '12345', status: 'processing' });
+ *    // ... more processing ...
+ *    span.setStatus({ code: SpanStatusCode.OK });
+ *  } catch (error) {
+ *    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+ *  } finally {
+ *    span.end(); // Always remember to end the span
+ *  }
+ * })
+ * ```
+ */
+var createSpanFromEvent = function (spanName, event, spanKinds, tracer) {
     var _a;
+    if (tracer === void 0) { tracer = _1.ArvoEventHandlerTracer; }
     var spanOptions = {
         kind: spanKinds.kind,
         attributes: (_a = {},
@@ -57,10 +120,10 @@ var createSpanFromEvent = function (spanName, event, spanKinds) {
     var span;
     if (event.traceparent) {
         var inheritedContext = (0, _1.extractContext)(event.traceparent, event.tracestate);
-        span = _1.ArvoEventHandlerTracer.startSpan(spanName, spanOptions, inheritedContext);
+        span = tracer.startSpan(spanName, spanOptions, inheritedContext);
     }
     else {
-        span = _1.ArvoEventHandlerTracer.startSpan(spanName, spanOptions);
+        span = tracer.startSpan(spanName, spanOptions);
     }
     return span;
 };

package/dist/index.d.ts

@@ -10,4 +10,5 @@ import { IArvoEventRouter } from './ArvoEventRouter/types';
 import { ArvoEventRouter } from './ArvoEventRouter';
 import { createArvoEventRouter } from './ArvoEventRouter/helpers';
 import AbstractArvoEventHandler from './AbstractArvoEventHandler';
-export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, IArvoEventRouter, ArvoEventRouter, createArvoEventRouter, AbstractArvoEventHandler, };
+import { createSpanFromEvent } from './OpenTelemetry/utils';
+export { ArvoEventHandler, createArvoEventHandler, IArvoEventHandler, ArvoEventHandlerFunctionOutput, ArvoEventHandlerFunctionInput, ArvoEventHandlerFunction, PartialExcept, MultiArvoEventHandler, MultiArvoEventHandlerFunctionInput, MultiArvoEventHandlerFunctionOutput, MultiArvoEventHandlerFunction, IMultiArvoEventHandler, createMultiArvoEventHandler, isNullOrUndefined, getValueOrDefault, coalesce, coalesceOrDefault, IArvoEventRouter, ArvoEventRouter, createArvoEventRouter, AbstractArvoEventHandler, createSpanFromEvent as createOtelSpanFromEvent };

package/dist/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AbstractArvoEventHandler = exports.createArvoEventRouter = exports.ArvoEventRouter = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
+exports.createOtelSpanFromEvent = exports.AbstractArvoEventHandler = exports.createArvoEventRouter = exports.ArvoEventRouter = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
 var ArvoEventHandler_1 = __importDefault(require("./ArvoEventHandler"));
 exports.ArvoEventHandler = ArvoEventHandler_1.default;
 var helpers_1 = require("./ArvoEventHandler/helpers");
@@ -23,3 +23,5 @@ var helpers_3 = require("./ArvoEventRouter/helpers");
 Object.defineProperty(exports, "createArvoEventRouter", { enumerable: true, get: function () { return helpers_3.createArvoEventRouter; } });
 var AbstractArvoEventHandler_1 = __importDefault(require("./AbstractArvoEventHandler"));
 exports.AbstractArvoEventHandler = AbstractArvoEventHandler_1.default;
+var utils_2 = require("./OpenTelemetry/utils");
+Object.defineProperty(exports, "createOtelSpanFromEvent", { enumerable: true, get: function () { return utils_2.createSpanFromEvent; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arvo-event-handler",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "This package contains class and function for event handlers in an Arvo Event Driven system",
   "main": "dist/index.js",
   "scripts": {