arvo-event-handler 1.1.2 → 1.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -0
- package/dist/OpenTelemetry/utils.d.ts +64 -2
- package/dist/OpenTelemetry/utils.js +66 -3
- package/dist/index.d.ts +2 -1
- package/dist/index.js +3 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -23,6 +23,17 @@ Key features of Arvo include:
|
|
|
23
23
|
|
|
24
24
|
Whether you're building a small microservice or a large-scale distributed system, my hope with Arvo is to offers you some of the tools and patterns to help you succeed in the world of event-driven architecture.
|
|
25
25
|
|
|
26
|
+
## Arvo suite
|
|
27
|
+
|
|
28
|
+
Arvo is a collection of libraries which allows you to build the event driven system in the Arvo pattern. However, if you feel you don't have to use them or you can use them as you see fit.
|
|
29
|
+
|
|
30
|
+
| Scope | NPM | Github | Documentation |
|
|
31
|
+
| ------------ | ------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
|
|
32
|
+
| Orchestration | https://www.npmjs.com/package/arvo-xstate?activeTab=readme | https://github.com/SaadAhmad123/arvo-xstate | https://saadahmad123.github.io/arvo-xstate/index.html |
|
|
33
|
+
| Core | https://www.npmjs.com/package/arvo-core?activeTab=readme | https://github.com/SaadAhmad123/arvo-core | https://saadahmad123.github.io/arvo-core/index.html |
|
|
34
|
+
| Event Handling | https://www.npmjs.com/package/arvo-event-handler?activeTab=readme | https://github.com/SaadAhmad123/arvo-event-handler | https://saadahmad123.github.io/arvo-event-handler/index.html |
|
|
35
|
+
|
|
36
|
+
|
|
26
37
|
# Arvo - Event Handler
|
|
27
38
|
|
|
28
39
|
This package contains the event handler primitive required to enable an Arvo Event Driven System. These are light weight classes and types which take care of event listening, contract bound type inference, distributed open telemetry and much more.
|
|
@@ -1,11 +1,73 @@
|
|
|
1
|
-
import { Span, SpanKind } from '@opentelemetry/api';
|
|
1
|
+
import { Span, SpanKind, Tracer } from '@opentelemetry/api';
|
|
2
2
|
import { ArvoEvent, ArvoExecutionSpanKind, OpenInferenceSpanKind } from 'arvo-core';
|
|
3
3
|
export declare function getPackageInfo(): {
|
|
4
4
|
name: string;
|
|
5
5
|
version: string;
|
|
6
6
|
};
|
|
7
|
+
/**
|
|
8
|
+
* Creates an OpenTelemetry span from an ArvoEvent, facilitating distributed tracing in the Arvo system.
|
|
9
|
+
*
|
|
10
|
+
* This function is a cornerstone of Arvo's observability infrastructure, creating spans that represent
|
|
11
|
+
* discrete units of work or operations within the system. It supports both creating new root spans
|
|
12
|
+
* and continuing existing traces, enabling comprehensive end-to-end tracing across distributed components.
|
|
13
|
+
*
|
|
14
|
+
* @param spanName - A descriptive name for the span, indicating the operation being traced.
|
|
15
|
+
* Choose a name that clearly identifies the work being performed.
|
|
16
|
+
*
|
|
17
|
+
* @param event - The ArvoEvent that triggers the span creation. This event may contain
|
|
18
|
+
* tracing context (traceparent and tracestate) to link this span to an existing trace.
|
|
19
|
+
*
|
|
20
|
+
* @param spanKinds - An object specifying the span's categorization across different tracing contexts:
|
|
21
|
+
* @param spanKinds.kind - OpenTelemetry SpanKind, indicating the span's role in the trace hierarchy
|
|
22
|
+
* (e.g., SERVER, CLIENT, INTERNAL).
|
|
23
|
+
* @param spanKinds.openInference - OpenInference span kind, used for AI/ML operation categorization.
|
|
24
|
+
* @param spanKinds.arvoExecution - ArvoExecution span kind, for Arvo-specific execution context labeling.
|
|
25
|
+
*
|
|
26
|
+
* @param tracer - The OpenTelemetry Tracer instance to use for creating the span.
|
|
27
|
+
* Defaults to ArvoXStateTracer if not provided.
|
|
28
|
+
*
|
|
29
|
+
* @returns A new OpenTelemetry Span object that can be used to record operation details,
|
|
30
|
+
* set attributes, and create child spans.
|
|
31
|
+
*
|
|
32
|
+
* @remarks
|
|
33
|
+
* - If the input event contains a 'traceparent', the function will continue the existing trace,
|
|
34
|
+
* maintaining the distributed tracing context across system boundaries.
|
|
35
|
+
* - Without a 'traceparent', a new root span is created, potentially starting a new trace.
|
|
36
|
+
* - The function automatically sets OpenInference and ArvoExecution-specific attributes,
|
|
37
|
+
* enhancing the span's context for specialized analysis.
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* ```typescript
|
|
41
|
+
* const event: ArvoEvent = createArvoEvent({
|
|
42
|
+
* type: 'orderProcess',
|
|
43
|
+
* data: { orderId: '12345' },
|
|
44
|
+
* traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
|
|
45
|
+
* tracestate: "rojo=00f067aa0ba902b7",
|
|
46
|
+
* ...
|
|
47
|
+
* });
|
|
48
|
+
*
|
|
49
|
+
* const span = createSpanFromEvent("processOrder", event, {
|
|
50
|
+
* kind: SpanKind.INTERNAL,
|
|
51
|
+
* openInference: OpenInferenceSpanKind.LLM,
|
|
52
|
+
* arvoExecution: ArvoExecutionSpanKind.EVENT_HANDLER
|
|
53
|
+
* });
|
|
54
|
+
*
|
|
55
|
+
* context.with(trace.setSpan(context.active(), span), () => {
|
|
56
|
+
* try {
|
|
57
|
+
* // Perform order processing logic
|
|
58
|
+
* span.setAttributes({ orderId: '12345', status: 'processing' });
|
|
59
|
+
* // ... more processing ...
|
|
60
|
+
* span.setStatus({ code: SpanStatusCode.OK });
|
|
61
|
+
* } catch (error) {
|
|
62
|
+
* span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
|
|
63
|
+
* } finally {
|
|
64
|
+
* span.end(); // Always remember to end the span
|
|
65
|
+
* }
|
|
66
|
+
* })
|
|
67
|
+
* ```
|
|
68
|
+
*/
|
|
7
69
|
export declare const createSpanFromEvent: (spanName: string, event: ArvoEvent, spanKinds: {
|
|
8
70
|
kind: SpanKind;
|
|
9
71
|
openInference: OpenInferenceSpanKind;
|
|
10
72
|
arvoExecution: ArvoExecutionSpanKind;
|
|
11
|
-
}) => Span;
|
|
73
|
+
}, tracer?: Tracer) => Span;
|
|
@@ -45,8 +45,71 @@ function getPackageInfo() {
|
|
|
45
45
|
return { name: 'Unknown', version: 'Unknown' };
|
|
46
46
|
}
|
|
47
47
|
}
|
|
48
|
-
|
|
48
|
+
/**
|
|
49
|
+
* Creates an OpenTelemetry span from an ArvoEvent, facilitating distributed tracing in the Arvo system.
|
|
50
|
+
*
|
|
51
|
+
* This function is a cornerstone of Arvo's observability infrastructure, creating spans that represent
|
|
52
|
+
* discrete units of work or operations within the system. It supports both creating new root spans
|
|
53
|
+
* and continuing existing traces, enabling comprehensive end-to-end tracing across distributed components.
|
|
54
|
+
*
|
|
55
|
+
* @param spanName - A descriptive name for the span, indicating the operation being traced.
|
|
56
|
+
* Choose a name that clearly identifies the work being performed.
|
|
57
|
+
*
|
|
58
|
+
* @param event - The ArvoEvent that triggers the span creation. This event may contain
|
|
59
|
+
* tracing context (traceparent and tracestate) to link this span to an existing trace.
|
|
60
|
+
*
|
|
61
|
+
* @param spanKinds - An object specifying the span's categorization across different tracing contexts:
|
|
62
|
+
* @param spanKinds.kind - OpenTelemetry SpanKind, indicating the span's role in the trace hierarchy
|
|
63
|
+
* (e.g., SERVER, CLIENT, INTERNAL).
|
|
64
|
+
* @param spanKinds.openInference - OpenInference span kind, used for AI/ML operation categorization.
|
|
65
|
+
* @param spanKinds.arvoExecution - ArvoExecution span kind, for Arvo-specific execution context labeling.
|
|
66
|
+
*
|
|
67
|
+
* @param tracer - The OpenTelemetry Tracer instance to use for creating the span.
|
|
68
|
+
* Defaults to ArvoXStateTracer if not provided.
|
|
69
|
+
*
|
|
70
|
+
* @returns A new OpenTelemetry Span object that can be used to record operation details,
|
|
71
|
+
* set attributes, and create child spans.
|
|
72
|
+
*
|
|
73
|
+
* @remarks
|
|
74
|
+
* - If the input event contains a 'traceparent', the function will continue the existing trace,
|
|
75
|
+
* maintaining the distributed tracing context across system boundaries.
|
|
76
|
+
* - Without a 'traceparent', a new root span is created, potentially starting a new trace.
|
|
77
|
+
* - The function automatically sets OpenInference and ArvoExecution-specific attributes,
|
|
78
|
+
* enhancing the span's context for specialized analysis.
|
|
79
|
+
*
|
|
80
|
+
* @example
|
|
81
|
+
* ```typescript
|
|
82
|
+
* const event: ArvoEvent = createArvoEvent({
|
|
83
|
+
* type: 'orderProcess',
|
|
84
|
+
* data: { orderId: '12345' },
|
|
85
|
+
* traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
|
|
86
|
+
* tracestate: "rojo=00f067aa0ba902b7",
|
|
87
|
+
* ...
|
|
88
|
+
* });
|
|
89
|
+
*
|
|
90
|
+
* const span = createSpanFromEvent("processOrder", event, {
|
|
91
|
+
* kind: SpanKind.INTERNAL,
|
|
92
|
+
* openInference: OpenInferenceSpanKind.LLM,
|
|
93
|
+
* arvoExecution: ArvoExecutionSpanKind.EVENT_HANDLER
|
|
94
|
+
* });
|
|
95
|
+
*
|
|
96
|
+
* context.with(trace.setSpan(context.active(), span), () => {
|
|
97
|
+
* try {
|
|
98
|
+
* // Perform order processing logic
|
|
99
|
+
* span.setAttributes({ orderId: '12345', status: 'processing' });
|
|
100
|
+
* // ... more processing ...
|
|
101
|
+
* span.setStatus({ code: SpanStatusCode.OK });
|
|
102
|
+
* } catch (error) {
|
|
103
|
+
* span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
|
|
104
|
+
* } finally {
|
|
105
|
+
* span.end(); // Always remember to end the span
|
|
106
|
+
* }
|
|
107
|
+
* })
|
|
108
|
+
* ```
|
|
109
|
+
*/
|
|
110
|
+
var createSpanFromEvent = function (spanName, event, spanKinds, tracer) {
|
|
49
111
|
var _a;
|
|
112
|
+
if (tracer === void 0) { tracer = _1.ArvoEventHandlerTracer; }
|
|
50
113
|
var spanOptions = {
|
|
51
114
|
kind: spanKinds.kind,
|
|
52
115
|
attributes: (_a = {},
|
|
@@ -57,10 +120,10 @@ var createSpanFromEvent = function (spanName, event, spanKinds) {
|
|
|
57
120
|
var span;
|
|
58
121
|
if (event.traceparent) {
|
|
59
122
|
var inheritedContext = (0, _1.extractContext)(event.traceparent, event.tracestate);
|
|
60
|
-
span =
|
|
123
|
+
span = tracer.startSpan(spanName, spanOptions, inheritedContext);
|
|
61
124
|
}
|
|
62
125
|
else {
|
|
63
|
-
span =
|
|
126
|
+
span = tracer.startSpan(spanName, spanOptions);
|
|
64
127
|
}
|
|
65
128
|
return span;
|
|
66
129
|
};
|
package/dist/index.d.ts
CHANGED
|
@@ -10,4 +10,5 @@ import { IArvoEventRouter } from './ArvoEventRouter/types';
|
|
|
10
10
|
import { ArvoEventRouter } from './ArvoEventRouter';
|
|
11
11
|
import { createArvoEventRouter } from './ArvoEventRouter/helpers';
|
|
12
12
|
import AbstractArvoEventHandler from './AbstractArvoEventHandler';
|
|
13
|
-
|
|
13
|
+
import { createSpanFromEvent } from './OpenTelemetry/utils';
|
|
14
|
+
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
CHANGED
|
@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
|
3
3
|
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
4
|
};
|
|
5
5
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
-
exports.AbstractArvoEventHandler = exports.createArvoEventRouter = exports.ArvoEventRouter = exports.coalesceOrDefault = exports.coalesce = exports.getValueOrDefault = exports.isNullOrUndefined = exports.createMultiArvoEventHandler = exports.MultiArvoEventHandler = exports.createArvoEventHandler = exports.ArvoEventHandler = void 0;
|
|
6
|
+
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;
|
|
7
7
|
var ArvoEventHandler_1 = __importDefault(require("./ArvoEventHandler"));
|
|
8
8
|
exports.ArvoEventHandler = ArvoEventHandler_1.default;
|
|
9
9
|
var helpers_1 = require("./ArvoEventHandler/helpers");
|
|
@@ -23,3 +23,5 @@ var helpers_3 = require("./ArvoEventRouter/helpers");
|
|
|
23
23
|
Object.defineProperty(exports, "createArvoEventRouter", { enumerable: true, get: function () { return helpers_3.createArvoEventRouter; } });
|
|
24
24
|
var AbstractArvoEventHandler_1 = __importDefault(require("./AbstractArvoEventHandler"));
|
|
25
25
|
exports.AbstractArvoEventHandler = AbstractArvoEventHandler_1.default;
|
|
26
|
+
var utils_2 = require("./OpenTelemetry/utils");
|
|
27
|
+
Object.defineProperty(exports, "createOtelSpanFromEvent", { enumerable: true, get: function () { return utils_2.createSpanFromEvent; } });
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "arvo-event-handler",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.4",
|
|
4
4
|
"description": "This package contains class and function for event handlers in an Arvo Event Driven system",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"scripts": {
|
|
@@ -49,7 +49,7 @@
|
|
|
49
49
|
},
|
|
50
50
|
"dependencies": {
|
|
51
51
|
"@opentelemetry/api": "^1.9.0",
|
|
52
|
-
"arvo-core": "^1.1.
|
|
52
|
+
"arvo-core": "^1.1.13",
|
|
53
53
|
"uuid": "^10.0.0",
|
|
54
54
|
"zod": "^3.23.8"
|
|
55
55
|
}
|