@twin.org/tracing-service 0.9.2-next.1

package/dist/es/tracingService.js

@@ -0,0 +1,147 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { Guards, Is } from "@twin.org/core";
+import { ComparisonOperator, LogicalOperator, SortDirection } from "@twin.org/entity";
+import { TracingConnectorFactory } from "@twin.org/tracing-models";
+/**
+ * Service for performing tracing operations to a connector.
+ */
+export class TracingService {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "TracingService";
+    /**
+     * The maximum number of pages `getTrace` will request before stopping. A safety bound that
+     * prevents an unexpectedly large trace or a non-terminating connector cursor from looping
+     * unbounded; with the default page size this still covers very large traces.
+     */
+    static MAX_GET_TRACE_PAGES = 1000;
+    /**
+     * Tracing connector used by the service.
+     * @internal
+     */
+    _tracingConnector;
+    /**
+     * Create a new instance of TracingService.
+     * @param options The options for the connector.
+     */
+    constructor(options) {
+        this._tracingConnector = TracingConnectorFactory.get(options?.tracingConnectorType ?? "tracing");
+    }
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className() {
+        return TracingService.CLASS_NAME;
+    }
+    /**
+     * Start a new span.
+     * @param name The name of the span.
+     * @param options The options for the span.
+     * @returns The started span, including its minted context.
+     */
+    async startSpan(name, options) {
+        Guards.stringValue(TracingService.CLASS_NAME, "name", name);
+        return this._tracingConnector.startSpan(name, options);
+    }
+    /**
+     * End a span, finalizing its status and duration.
+     * @param span The span to end.
+     * @param status The status to set on the span, defaults to ok.
+     * @returns A promise that resolves when the span has been ended.
+     */
+    async endSpan(span, status) {
+        Guards.object(TracingService.CLASS_NAME, "span", span);
+        await this._tracingConnector.endSpan(span, status);
+    }
+    /**
+     * Query the spans.
+     * @param traceId The id of the trace to filter by.
+     * @param spanId The id of the span to filter by.
+     * @param status The status to filter by.
+     * @param kind The kind to filter by.
+     * @param timeStart The inclusive start time to filter the span start by, as a timestamp in ms.
+     * @param timeEnd The inclusive end time to filter the span start by, as a timestamp in ms.
+     * @param cursor The cursor to request the next chunk of entities.
+     * @param limit Limit the number of entities to return.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     */
+    async query(traceId, spanId, status, kind, timeStart, timeEnd, cursor, limit) {
+        const condition = {
+            conditions: [],
+            logicalOperator: LogicalOperator.And
+        };
+        if (Is.stringValue(traceId)) {
+            condition.conditions.push({
+                property: "traceId",
+                comparison: ComparisonOperator.Equals,
+                value: traceId
+            });
+        }
+        if (Is.stringValue(spanId)) {
+            condition.conditions.push({
+                property: "spanId",
+                comparison: ComparisonOperator.Equals,
+                value: spanId
+            });
+        }
+        if (Is.stringValue(status)) {
+            condition.conditions.push({
+                property: "status",
+                comparison: ComparisonOperator.Equals,
+                value: status
+            });
+        }
+        if (Is.stringValue(kind)) {
+            condition.conditions.push({
+                property: "kind",
+                comparison: ComparisonOperator.Equals,
+                value: kind
+            });
+        }
+        if (Is.number(timeStart)) {
+            condition.conditions.push({
+                property: "startTs",
+                comparison: ComparisonOperator.GreaterThanOrEqual,
+                value: timeStart
+            });
+        }
+        if (Is.number(timeEnd)) {
+            condition.conditions.push({
+                property: "startTs",
+                comparison: ComparisonOperator.LessThanOrEqual,
+                value: timeEnd
+            });
+        }
+        const queryConnector = this._tracingConnector?.query?.bind(this._tracingConnector);
+        if (Is.function(queryConnector)) {
+            const result = await queryConnector(condition, [{ property: "startTs", sortDirection: SortDirection.Descending }], cursor, limit);
+            return { entities: result.entities, cursor: result.cursor };
+        }
+        return { entities: [] };
+    }
+    /**
+     * Get all the spans belonging to a trace, ordered by their start time. The whole trace is paged
+     * into memory; paging is bounded by {@link TracingService.MAX_GET_TRACE_PAGES} as a safeguard
+     * against a pathologically large trace or a non-terminating cursor.
+     * @param traceId The id of the trace to retrieve.
+     * @returns The spans belonging to the trace, ordered by their start time ascending.
+     */
+    async getTrace(traceId) {
+        Guards.stringValue(TracingService.CLASS_NAME, "traceId", traceId);
+        const spans = [];
+        let cursor;
+        let pages = 0;
+        do {
+            const result = await this.query(traceId, undefined, undefined, undefined, undefined, undefined, cursor);
+            spans.push(...result.entities);
+            cursor = result.cursor;
+            pages++;
+        } while (Is.stringValue(cursor) && pages < TracingService.MAX_GET_TRACE_PAGES);
+        return spans.sort((a, b) => a.startTs - b.startTs);
+    }
+}
+//# sourceMappingURL=tracingService.js.map

package/dist/es/tracingService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracingService.js","sourceRoot":"","sources":["../../src/tracingService.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { Guards, Is } from \"@twin.org/core\";\nimport {\n\tComparisonOperator,\n\tLogicalOperator,\n\tSortDirection,\n\ttype EntityCondition\n} from \"@twin.org/entity\";\nimport { nameof } from \"@twin.org/nameof\";\nimport {\n\tTracingConnectorFactory,\n\ttype ISpan,\n\ttype ISpanOptions,\n\ttype ITracingComponent,\n\ttype ITracingConnector,\n\ttype SpanKind,\n\ttype SpanStatus\n} from \"@twin.org/tracing-models\";\nimport type { ITracingServiceConstructorOptions } from \"./models/ITracingServiceConstructorOptions.js\";\n\n/**\n * Service for performing tracing operations to a connector.\n */\nexport class TracingService implements ITracingComponent {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<TracingService>();\n\n\t/**\n\t * The maximum number of pages `getTrace` will request before stopping. A safety bound that\n\t * prevents an unexpectedly large trace or a non-terminating connector cursor from looping\n\t * unbounded; with the default page size this still covers very large traces.\n\t */\n\tpublic static readonly MAX_GET_TRACE_PAGES: number = 1000;\n\n\t/**\n\t * Tracing connector used by the service.\n\t * @internal\n\t */\n\tprivate readonly _tracingConnector: ITracingConnector;\n\n\t/**\n\t * Create a new instance of TracingService.\n\t * @param options The options for the connector.\n\t */\n\tconstructor(options?: ITracingServiceConstructorOptions) {\n\t\tthis._tracingConnector = TracingConnectorFactory.get(\n\t\t\toptions?.tracingConnectorType ?? \"tracing\"\n\t\t);\n\t}\n\n\t/**\n\t * Returns the class name of the component.\n\t * @returns The class name of the component.\n\t */\n\tpublic className(): string {\n\t\treturn TracingService.CLASS_NAME;\n\t}\n\n\t/**\n\t * Start a new span.\n\t * @param name The name of the span.\n\t * @param options The options for the span.\n\t * @returns The started span, including its minted context.\n\t */\n\tpublic async startSpan(name: string, options?: ISpanOptions): Promise<ISpan> {\n\t\tGuards.stringValue(TracingService.CLASS_NAME, nameof(name), name);\n\n\t\treturn this._tracingConnector.startSpan(name, options);\n\t}\n\n\t/**\n\t * End a span, finalizing its status and duration.\n\t * @param span The span to end.\n\t * @param status The status to set on the span, defaults to ok.\n\t * @returns A promise that resolves when the span has been ended.\n\t */\n\tpublic async endSpan(span: ISpan, status?: SpanStatus): Promise<void> {\n\t\tGuards.object<ISpan>(TracingService.CLASS_NAME, nameof(span), span);\n\n\t\tawait this._tracingConnector.endSpan(span, status);\n\t}\n\n\t/**\n\t * Query the spans.\n\t * @param traceId The id of the trace to filter by.\n\t * @param spanId The id of the span to filter by.\n\t * @param status The status to filter by.\n\t * @param kind The kind to filter by.\n\t * @param timeStart The inclusive start time to filter the span start by, as a timestamp in ms.\n\t * @param timeEnd The inclusive end time to filter the span start by, as a timestamp in ms.\n\t * @param cursor The cursor to request the next chunk of entities.\n\t * @param limit Limit the number of entities to return.\n\t * @returns All the entities for the storage matching the conditions,\n\t * and a cursor which can be used to request more entities.\n\t */\n\tpublic async query(\n\t\ttraceId?: string,\n\t\tspanId?: string,\n\t\tstatus?: SpanStatus,\n\t\tkind?: SpanKind,\n\t\ttimeStart?: number,\n\t\ttimeEnd?: number,\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{\n\t\t/**\n\t\t * The spans.\n\t\t */\n\t\tentities: ISpan[];\n\t\t/**\n\t\t * An optional cursor, when defined can be used to call query to get more entities.\n\t\t */\n\t\tcursor?: string;\n\t}> {\n\t\tconst condition: EntityCondition<ISpan> = {\n\t\t\tconditions: [],\n\t\t\tlogicalOperator: LogicalOperator.And\n\t\t};\n\n\t\tif (Is.stringValue(traceId)) {\n\t\t\tcondition.conditions.push({\n\t\t\t\tproperty: \"traceId\",\n\t\t\t\tcomparison: ComparisonOperator.Equals,\n\t\t\t\tvalue: traceId\n\t\t\t});\n\t\t}\n\n\t\tif (Is.stringValue(spanId)) {\n\t\t\tcondition.conditions.push({\n\t\t\t\tproperty: \"spanId\",\n\t\t\t\tcomparison: ComparisonOperator.Equals,\n\t\t\t\tvalue: spanId\n\t\t\t});\n\t\t}\n\n\t\tif (Is.stringValue(status)) {\n\t\t\tcondition.conditions.push({\n\t\t\t\tproperty: \"status\",\n\t\t\t\tcomparison: ComparisonOperator.Equals,\n\t\t\t\tvalue: status\n\t\t\t});\n\t\t}\n\n\t\tif (Is.stringValue(kind)) {\n\t\t\tcondition.conditions.push({\n\t\t\t\tproperty: \"kind\",\n\t\t\t\tcomparison: ComparisonOperator.Equals,\n\t\t\t\tvalue: kind\n\t\t\t});\n\t\t}\n\n\t\tif (Is.number(timeStart)) {\n\t\t\tcondition.conditions.push({\n\t\t\t\tproperty: \"startTs\",\n\t\t\t\tcomparison: ComparisonOperator.GreaterThanOrEqual,\n\t\t\t\tvalue: timeStart\n\t\t\t});\n\t\t}\n\n\t\tif (Is.number(timeEnd)) {\n\t\t\tcondition.conditions.push({\n\t\t\t\tproperty: \"startTs\",\n\t\t\t\tcomparison: ComparisonOperator.LessThanOrEqual,\n\t\t\t\tvalue: timeEnd\n\t\t\t});\n\t\t}\n\n\t\tconst queryConnector = this._tracingConnector?.query?.bind(this._tracingConnector);\n\t\tif (Is.function(queryConnector)) {\n\t\t\tconst result = await queryConnector(\n\t\t\t\tcondition,\n\t\t\t\t[{ property: \"startTs\", sortDirection: SortDirection.Descending }],\n\t\t\t\tcursor,\n\t\t\t\tlimit\n\t\t\t);\n\n\t\t\treturn { entities: result.entities, cursor: result.cursor };\n\t\t}\n\n\t\treturn { entities: [] };\n\t}\n\n\t/**\n\t * Get all the spans belonging to a trace, ordered by their start time. The whole trace is paged\n\t * into memory; paging is bounded by {@link TracingService.MAX_GET_TRACE_PAGES} as a safeguard\n\t * against a pathologically large trace or a non-terminating cursor.\n\t * @param traceId The id of the trace to retrieve.\n\t * @returns The spans belonging to the trace, ordered by their start time ascending.\n\t */\n\tpublic async getTrace(traceId: string): Promise<ISpan[]> {\n\t\tGuards.stringValue(TracingService.CLASS_NAME, nameof(traceId), traceId);\n\n\t\tconst spans: ISpan[] = [];\n\t\tlet cursor: string | undefined;\n\t\tlet pages = 0;\n\n\t\tdo {\n\t\t\tconst result = await this.query(\n\t\t\t\ttraceId,\n\t\t\t\tundefined,\n\t\t\t\tundefined,\n\t\t\t\tundefined,\n\t\t\t\tundefined,\n\t\t\t\tundefined,\n\t\t\t\tcursor\n\t\t\t);\n\t\t\tspans.push(...result.entities);\n\t\t\tcursor = result.cursor;\n\t\t\tpages++;\n\t\t} while (Is.stringValue(cursor) && pages < TracingService.MAX_GET_TRACE_PAGES);\n\n\t\treturn spans.sort((a, b) => a.startTs - b.startTs);\n\t}\n}\n"]}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./models/ITracingServiceConstructorOptions.js";
+export * from "./restEntryPoints.js";
+export * from "./tracingRoutes.js";
+export * from "./tracingService.js";

package/dist/types/models/ITracingServiceConstructorOptions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Options for the tracing service constructor.
+ */
+export interface ITracingServiceConstructorOptions {
+    /**
+     * The type of the tracing connector to use.
+     * @default tracing
+     */
+    tracingConnectorType?: string;
+}

package/dist/types/restEntryPoints.d.ts

@@ -0,0 +1,5 @@
+import type { IRestRouteEntryPoint } from "@twin.org/api-models";
+/**
+ * REST entry points for the tracing service.
+ */
+export declare const restEntryPoints: IRestRouteEntryPoint[];

package/dist/types/tracingRoutes.d.ts

@@ -0,0 +1,45 @@
+import type { IHttpRequestContext, INoContentResponse, IRestRoute, ITag } from "@twin.org/api-models";
+import type { ITracingGetTraceRequest, ITracingGetTraceResponse, ITracingListRequest, ITracingListResponse, ITracingSpanEndRequest, ITracingSpanStartRequest, ITracingSpanStartResponse } from "@twin.org/tracing-models";
+/**
+ * The tag to associate with the routes.
+ */
+export declare const tagsTracing: ITag[];
+/**
+ * The REST routes for tracing.
+ * @param baseRouteName Prefix to prepend to the paths.
+ * @param componentName The name of the component to use in the routes stored in the ComponentFactory.
+ * @returns The generated routes.
+ */
+export declare function generateRestRoutesTracing(baseRouteName: string, componentName: string): IRestRoute[];
+/**
+ * Start a new span.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns A promise that resolves to the started span.
+ */
+export declare function tracingSpanStart(httpRequestContext: IHttpRequestContext, componentName: string, request: ITracingSpanStartRequest): Promise<ITracingSpanStartResponse>;
+/**
+ * End a span.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns A promise that resolves to a no-content response when the span has been ended.
+ */
+export declare function tracingSpanEnd(httpRequestContext: IHttpRequestContext, componentName: string, request: ITracingSpanEndRequest): Promise<INoContentResponse>;
+/**
+ * Get a list of the spans.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns A promise that resolves to the matching spans and an optional pagination cursor.
+ */
+export declare function tracingList(httpRequestContext: IHttpRequestContext, componentName: string, request: ITracingListRequest): Promise<ITracingListResponse>;
+/**
+ * Get all the spans belonging to a trace.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns A promise that resolves to the spans belonging to the trace.
+ */
+export declare function tracingGetTrace(httpRequestContext: IHttpRequestContext, componentName: string, request: ITracingGetTraceRequest): Promise<ITracingGetTraceResponse>;

package/dist/types/tracingService.d.ts

@@ -0,0 +1,72 @@
+import { type ISpan, type ISpanOptions, type ITracingComponent, type SpanKind, type SpanStatus } from "@twin.org/tracing-models";
+import type { ITracingServiceConstructorOptions } from "./models/ITracingServiceConstructorOptions.js";
+/**
+ * Service for performing tracing operations to a connector.
+ */
+export declare class TracingService implements ITracingComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * The maximum number of pages `getTrace` will request before stopping. A safety bound that
+     * prevents an unexpectedly large trace or a non-terminating connector cursor from looping
+     * unbounded; with the default page size this still covers very large traces.
+     */
+    static readonly MAX_GET_TRACE_PAGES: number;
+    /**
+     * Create a new instance of TracingService.
+     * @param options The options for the connector.
+     */
+    constructor(options?: ITracingServiceConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Start a new span.
+     * @param name The name of the span.
+     * @param options The options for the span.
+     * @returns The started span, including its minted context.
+     */
+    startSpan(name: string, options?: ISpanOptions): Promise<ISpan>;
+    /**
+     * End a span, finalizing its status and duration.
+     * @param span The span to end.
+     * @param status The status to set on the span, defaults to ok.
+     * @returns A promise that resolves when the span has been ended.
+     */
+    endSpan(span: ISpan, status?: SpanStatus): Promise<void>;
+    /**
+     * Query the spans.
+     * @param traceId The id of the trace to filter by.
+     * @param spanId The id of the span to filter by.
+     * @param status The status to filter by.
+     * @param kind The kind to filter by.
+     * @param timeStart The inclusive start time to filter the span start by, as a timestamp in ms.
+     * @param timeEnd The inclusive end time to filter the span start by, as a timestamp in ms.
+     * @param cursor The cursor to request the next chunk of entities.
+     * @param limit Limit the number of entities to return.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     */
+    query(traceId?: string, spanId?: string, status?: SpanStatus, kind?: SpanKind, timeStart?: number, timeEnd?: number, cursor?: string, limit?: number): Promise<{
+        /**
+         * The spans.
+         */
+        entities: ISpan[];
+        /**
+         * An optional cursor, when defined can be used to call query to get more entities.
+         */
+        cursor?: string;
+    }>;
+    /**
+     * Get all the spans belonging to a trace, ordered by their start time. The whole trace is paged
+     * into memory; paging is bounded by {@link TracingService.MAX_GET_TRACE_PAGES} as a safeguard
+     * against a pathologically large trace or a non-terminating cursor.
+     * @param traceId The id of the trace to retrieve.
+     * @returns The spans belonging to the trace, ordered by their start time ascending.
+     */
+    getTrace(traceId: string): Promise<ISpan[]>;
+}

package/docs/changelog.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [0.9.2-next.1](https://github.com/iotaledger/twin-tracing/compare/tracing-service-v0.9.2-next.0...tracing-service-v0.9.2-next.1) (2026-08-07)
+
+
+### Features
+
+* add twin-tracing repository with OTel-aligned tracing API ([59b914c](https://github.com/iotaledger/twin-tracing/commit/59b914ca631c0b765973dfa5099a8f4e6115e325))
+* add twin-tracing repository with OTel-aligned tracing API ([affcd6c](https://github.com/iotaledger/twin-tracing/commit/affcd6c1cf2fbfd34d9a8849e860e5fe66a011e3))
+* linting and dependency update ([c1a2b98](https://github.com/iotaledger/twin-tracing/commit/c1a2b988441deb59592d69c7d3b6527bcb9018b2))
+* linting and dependency update ([b65c083](https://github.com/iotaledger/twin-tracing/commit/b65c083d4f8f83c2046d29d53444b45c7a4188c7))
+
+
+### Bug Fixes
+
+* address PR review on tracing packages ([0832b5f](https://github.com/iotaledger/twin-tracing/commit/0832b5fc0e7414b4e0fd2393532df00e07ff1f43))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tracing-models bumped from 0.9.2-next.0 to 0.9.2-next.1
+
+## Changelog

package/docs/examples.md

@@ -0,0 +1,37 @@
+# Tracing Service Examples
+
+The service implements the tracing component contract and resolves a connector from the factory.
+
+## Construct the service
+
+```typescript
+import { TracingConnectorFactory } from '@twin.org/tracing-models';
+import { EntityStorageTracingConnector } from '@twin.org/tracing-connector-entity-storage';
+import { TracingService } from '@twin.org/tracing-service';
+
+TracingConnectorFactory.register('tracing', () => new EntityStorageTracingConnector());
+
+const service = new TracingService();
+```
+
+## Record and query spans
+
+```typescript
+import { SpanKind, SpanStatus } from '@twin.org/tracing-models';
+
+const span = await service.startSpan('handle-request', { kind: SpanKind.Server });
+
+await service.endSpan(span, SpanStatus.Ok);
+
+const spans = await service.query(span.context.traceId);
+
+const trace = await service.getTrace(span.context.traceId);
+```
+
+## Register the REST routes
+
+```typescript
+import { generateRestRoutesTracing, tagsTracing } from '@twin.org/tracing-service';
+
+const routes = generateRestRoutesTracing('tracing', 'tracing');
+```