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

package/docs/reference/classes/TracingService.md

@@ -0,0 +1,224 @@
+# Class: TracingService
+
+Service for performing tracing operations to a connector.
+
+## Implements
+
+- `ITracingComponent`
+
+## Constructors
+
+### Constructor
+
+> **new TracingService**(`options?`): `TracingService`
+
+Create a new instance of TracingService.
+
+#### Parameters
+
+##### options?
+
+[`ITracingServiceConstructorOptions`](../interfaces/ITracingServiceConstructorOptions.md)
+
+The options for the connector.
+
+#### Returns
+
+`TracingService`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+***
+
+### MAX\_GET\_TRACE\_PAGES {#max_get_trace_pages}
+
+> `readonly` `static` **MAX\_GET\_TRACE\_PAGES**: `number` = `1000`
+
+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.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`ITracingComponent.className`
+
+***
+
+### startSpan() {#startspan}
+
+> **startSpan**(`name`, `options?`): `Promise`\<`ISpan`\>
+
+Start a new span.
+
+#### Parameters
+
+##### name
+
+`string`
+
+The name of the span.
+
+##### options?
+
+`ISpanOptions`
+
+The options for the span.
+
+#### Returns
+
+`Promise`\<`ISpan`\>
+
+The started span, including its minted context.
+
+#### Implementation of
+
+`ITracingComponent.startSpan`
+
+***
+
+### endSpan() {#endspan}
+
+> **endSpan**(`span`, `status?`): `Promise`\<`void`\>
+
+End a span, finalizing its status and duration.
+
+#### Parameters
+
+##### span
+
+`ISpan`
+
+The span to end.
+
+##### status?
+
+`SpanStatus`
+
+The status to set on the span, defaults to ok.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the span has been ended.
+
+#### Implementation of
+
+`ITracingComponent.endSpan`
+
+***
+
+### query() {#query}
+
+> **query**(`traceId?`, `spanId?`, `status?`, `kind?`, `timeStart?`, `timeEnd?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: `ISpan`[]; `cursor?`: `string`; \}\>
+
+Query the spans.
+
+#### Parameters
+
+##### traceId?
+
+`string`
+
+The id of the trace to filter by.
+
+##### spanId?
+
+`string`
+
+The id of the span to filter by.
+
+##### status?
+
+`SpanStatus`
+
+The status to filter by.
+
+##### kind?
+
+`SpanKind`
+
+The kind to filter by.
+
+##### timeStart?
+
+`number`
+
+The inclusive start time to filter the span start by, as a timestamp in ms.
+
+##### timeEnd?
+
+`number`
+
+The inclusive end time to filter the span start by, as a timestamp in ms.
+
+##### cursor?
+
+`string`
+
+The cursor to request the next chunk of entities.
+
+##### limit?
+
+`number`
+
+Limit the number of entities to return.
+
+#### Returns
+
+`Promise`\<\{ `entities`: `ISpan`[]; `cursor?`: `string`; \}\>
+
+All the entities for the storage matching the conditions,
+and a cursor which can be used to request more entities.
+
+#### Implementation of
+
+`ITracingComponent.query`
+
+***
+
+### getTrace() {#gettrace}
+
+> **getTrace**(`traceId`): `Promise`\<`ISpan`[]\>
+
+Get all the spans belonging to a trace, ordered by their start time. The whole trace is paged
+into memory; paging is bounded by [TracingService.MAX\_GET\_TRACE\_PAGES](#max_get_trace_pages) as a safeguard
+against a pathologically large trace or a non-terminating cursor.
+
+#### Parameters
+
+##### traceId
+
+`string`
+
+The id of the trace to retrieve.
+
+#### Returns
+
+`Promise`\<`ISpan`[]\>
+
+The spans belonging to the trace, ordered by their start time ascending.
+
+#### Implementation of
+
+`ITracingComponent.getTrace`

package/docs/reference/functions/generateRestRoutesTracing.md

@@ -0,0 +1,25 @@
+# Function: generateRestRoutesTracing()
+
+> **generateRestRoutesTracing**(`baseRouteName`, `componentName`): `IRestRoute`\<`any`, `any`\>[]
+
+The REST routes for tracing.
+
+## Parameters
+
+### baseRouteName
+
+`string`
+
+Prefix to prepend to the paths.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes stored in the ComponentFactory.
+
+## Returns
+
+`IRestRoute`\<`any`, `any`\>[]
+
+The generated routes.

package/docs/reference/functions/tracingGetTrace.md

@@ -0,0 +1,31 @@
+# Function: tracingGetTrace()
+
+> **tracingGetTrace**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`ITracingGetTraceResponse`\>
+
+Get all the spans belonging to a trace.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`ITracingGetTraceRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`ITracingGetTraceResponse`\>
+
+A promise that resolves to the spans belonging to the trace.

package/docs/reference/functions/tracingList.md

@@ -0,0 +1,31 @@
+# Function: tracingList()
+
+> **tracingList**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`ITracingListResponse`\>
+
+Get a list of the spans.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`ITracingListRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`ITracingListResponse`\>
+
+A promise that resolves to the matching spans and an optional pagination cursor.

package/docs/reference/functions/tracingSpanEnd.md

@@ -0,0 +1,31 @@
+# Function: tracingSpanEnd()
+
+> **tracingSpanEnd**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`INoContentResponse`\>
+
+End a span.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`ITracingSpanEndRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`INoContentResponse`\>
+
+A promise that resolves to a no-content response when the span has been ended.

package/docs/reference/functions/tracingSpanStart.md

@@ -0,0 +1,31 @@
+# Function: tracingSpanStart()
+
+> **tracingSpanStart**(`httpRequestContext`, `componentName`, `request`): `Promise`\<`ITracingSpanStartResponse`\>
+
+Start a new span.
+
+## Parameters
+
+### httpRequestContext
+
+`IHttpRequestContext`
+
+The request context for the API.
+
+### componentName
+
+`string`
+
+The name of the component to use in the routes.
+
+### request
+
+`ITracingSpanStartRequest`
+
+The request.
+
+## Returns
+
+`Promise`\<`ITracingSpanStartResponse`\>
+
+A promise that resolves to the started span.

package/docs/reference/index.md

@@ -0,0 +1,22 @@
+# @twin.org/tracing-service
+
+## Classes
+
+- [TracingService](classes/TracingService.md)
+
+## Interfaces
+
+- [ITracingServiceConstructorOptions](interfaces/ITracingServiceConstructorOptions.md)
+
+## Variables
+
+- [restEntryPoints](variables/restEntryPoints.md)
+- [tagsTracing](variables/tagsTracing.md)
+
+## Functions
+
+- [generateRestRoutesTracing](functions/generateRestRoutesTracing.md)
+- [tracingSpanStart](functions/tracingSpanStart.md)
+- [tracingSpanEnd](functions/tracingSpanEnd.md)
+- [tracingList](functions/tracingList.md)
+- [tracingGetTrace](functions/tracingGetTrace.md)

package/docs/reference/interfaces/ITracingServiceConstructorOptions.md

@@ -0,0 +1,17 @@
+# Interface: ITracingServiceConstructorOptions
+
+Options for the tracing service constructor.
+
+## Properties
+
+### tracingConnectorType? {#tracingconnectortype}
+
+> `optional` **tracingConnectorType?**: `string`
+
+The type of the tracing connector to use.
+
+#### Default
+
+```ts
+tracing
+```

package/docs/reference/variables/restEntryPoints.md

@@ -0,0 +1,5 @@
+# Variable: restEntryPoints
+
+> `const` **restEntryPoints**: `IRestRouteEntryPoint`[]
+
+REST entry points for the tracing service.

package/docs/reference/variables/tagsTracing.md

@@ -0,0 +1,5 @@
+# Variable: tagsTracing
+
+> `const` **tagsTracing**: `ITag`[]
+
+The tag to associate with the routes.

package/locales/en.json

@@ -0,0 +1,7 @@
+{
+	"error": {
+		"tracingRoutes": {
+			"spanIdMismatch": "The span id in the path \"{pathSpanId}\" does not match the span id in the body \"{bodySpanId}\""
+		}
+	}
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@twin.org/tracing-service",
+	"version": "0.9.2-next.1",
+	"description": "Exposes tracing operations through service routes and API contracts for server-side integration.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/iotaledger/twin-tracing.git",
+		"directory": "packages/tracing-service"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"dependencies": {
+		"@twin.org/api-models": "next",
+		"@twin.org/core": "next",
+		"@twin.org/entity": "next",
+		"@twin.org/nameof": "next",
+		"@twin.org/tracing-models": "0.9.2-next.1",
+		"@twin.org/web": "next"
+	},
+	"main": "./dist/es/index.js",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/es/index.js",
+			"default": "./dist/es/index.js"
+		},
+		"./locales/*.json": "./locales/*.json"
+	},
+	"files": [
+		"dist/es",
+		"dist/types",
+		"locales",
+		"docs"
+	],
+	"keywords": [
+		"twin",
+		"trade",
+		"iota",
+		"framework",
+		"blockchain",
+		"tracing",
+		"service",
+		"microservice",
+		"business-logic"
+	],
+	"bugs": {
+		"url": "git+https://github.com/iotaledger/twin-tracing/issues"
+	},
+	"homepage": "https://twindev.org"
+}