arvo-event-handler 2.0.4 → 2.1.1

package/dist/OpenTelemetry/types.d.ts

@@ -1,48 +0,0 @@
-import { SpanKind, Tracer } from '@opentelemetry/api';
-import { ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
-export type PackageJson = {
-    name: string;
-    version: string;
-    [key: string]: any;
-};
-/**
- * Configuration options for OpenTelemetry integration in execution context.
- *
- * This type defines how tracing should be configured and inherited within
- * the execution pipeline.
- */
-export type OpenTelemetryConfig = {
-    /**
-     * Specifies the context from which to inherit OpenTelemetry context.
-     * - 'event': Inherits context from the event that triggered the execution
-     * - 'execution': Inherits context from the parent execution context
-     */
-    inheritFrom: 'event' | 'execution';
-    /**
-     * Optional OpenTelemetry tracer instance to use for creating spans.
-     * If not provided, a default tracer may be used depending on the implementation.
-     */
-    tracer: Tracer | null;
-};
-/**
- * Interface defining the required parameters for creating a handler execution span.
- *
- * @interface ICreateHandlerExecutionSpan
- * @property {string} spanName - The name to be assigned to the created span
- * @property {Object} spanKinds - Object containing different span kind classifications
- * @property {SpanKind} spanKinds.kind - OpenTelemetry span kind
- * @property {OpenInferenceSpanKind} spanKinds.openInference - OpenInference-specific span classification
- * @property {ArvoExecutionSpanKind} spanKinds.arvoExecution - Arvo execution-specific span classification
- * @property {ArvoEvent} event - The Arvo event associated with this span
- * @property {EventHandlerExecutionOtelConfiguration} opentelemetryConfig - Configuration for OpenTelemetry behavior
- */
-export interface ICreateOtelSpan {
-    spanName: string;
-    spanKinds: {
-        kind: SpanKind;
-        openInference: OpenInferenceSpanKind;
-        arvoExecution: ArvoExecutionSpanKind;
-    };
-    event: ArvoEvent;
-    opentelemetryConfig?: OpenTelemetryConfig;
-}

package/dist/OpenTelemetry/types.js

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

package/dist/OpenTelemetry/utils.d.ts

@@ -1,87 +0,0 @@
-import { Span, SpanKind, Tracer, Context } from '@opentelemetry/api';
-import { ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
-import { ICreateOtelSpan } from './types';
-export declare const extractContext: (traceparent: string, tracestate: string | null) => Context;
-/**
- * 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;
-}, tracer: Tracer) => Span;
-/**
- * Creates an OpenTelemetry span for tracking handler execution.
- *
- * This function creates a span either from an existing event or as a new span,
- * depending on the configuration. It includes attributes for both OpenInference
- * and Arvo execution span kinds.
- *
- * @param params - Parameters for creating the handler execution span
- * @param params.spanName - Name of the span to be created
- * @param params.spanKinds - Object containing different span kind classifications
- * @param params.event - The Arvo event associated with this span
- * @param params.opentelemetryConfig - OpenTelemetry configuration
- *
- * @returns A new OpenTelemetry span configured according to the parameters
- */
-export declare const createOtelSpan: ({ spanName, spanKinds, event, opentelemetryConfig, }: ICreateOtelSpan) => Span;

package/dist/OpenTelemetry/utils.js

@@ -1,133 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createOtelSpan = exports.createSpanFromEvent = exports.extractContext = void 0;
-var api_1 = require("@opentelemetry/api");
-var arvo_core_1 = require("arvo-core");
-var _1 = require(".");
-// Helper function to extract context from traceparent and tracestate
-var extractContext = function (traceparent, tracestate) {
-    var extractedContext = api_1.propagation.extract(api_1.context.active(), {
-        traceparent: traceparent,
-        tracestate: tracestate !== null && tracestate !== void 0 ? tracestate : undefined,
-    });
-    return extractedContext;
-};
-exports.extractContext = extractContext;
-/**
- * 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;
-    var spanOptions = {
-        kind: spanKinds.kind,
-        attributes: (_a = {},
-            _a[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = spanKinds.openInference,
-            _a[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = spanKinds.arvoExecution,
-            _a),
-    };
-    var span;
-    if (event.traceparent) {
-        var inheritedContext = (0, exports.extractContext)(event.traceparent, event.tracestate);
-        span = tracer.startSpan(spanName, spanOptions, inheritedContext);
-    }
-    else {
-        span = tracer.startSpan(spanName, spanOptions);
-    }
-    return span;
-};
-exports.createSpanFromEvent = createSpanFromEvent;
-/**
- * Creates an OpenTelemetry span for tracking handler execution.
- *
- * This function creates a span either from an existing event or as a new span,
- * depending on the configuration. It includes attributes for both OpenInference
- * and Arvo execution span kinds.
- *
- * @param params - Parameters for creating the handler execution span
- * @param params.spanName - Name of the span to be created
- * @param params.spanKinds - Object containing different span kind classifications
- * @param params.event - The Arvo event associated with this span
- * @param params.opentelemetryConfig - OpenTelemetry configuration
- *
- * @returns A new OpenTelemetry span configured according to the parameters
- */
-var createOtelSpan = function (_a) {
-    var _b;
-    var _c;
-    var spanName = _a.spanName, spanKinds = _a.spanKinds, event = _a.event, opentelemetryConfig = _a.opentelemetryConfig;
-    opentelemetryConfig = opentelemetryConfig !== null && opentelemetryConfig !== void 0 ? opentelemetryConfig : {
-        inheritFrom: 'event',
-        tracer: null,
-    };
-    var spanOptions = {
-        kind: spanKinds.kind,
-        attributes: (_b = {},
-            _b[arvo_core_1.OpenInference.ATTR_SPAN_KIND] = spanKinds.openInference,
-            _b[arvo_core_1.ArvoExecution.ATTR_SPAN_KIND] = spanKinds.arvoExecution,
-            _b),
-    };
-    var tracer = (_c = opentelemetryConfig.tracer) !== null && _c !== void 0 ? _c : (0, _1.fetchOpenTelemetryTracer)();
-    return opentelemetryConfig.inheritFrom === 'event'
-        ? (0, exports.createSpanFromEvent)(spanName, event, spanKinds, tracer)
-        : tracer.startSpan(spanName, spanOptions);
-};
-exports.createOtelSpan = createOtelSpan;