@toa.io/extensions.telemetry 1.0.0-alpha.240 → 1.0.0-alpha.246

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/grafana.md ADDED
@@ -0,0 +1,45 @@
1
+ # Grafana stack setup
2
+
3
+ Toa-specific notes for wiring application traces into Tempo, Prometheus and Grafana.
4
+ Reference configuration: [`observability/`](../../observability) in the Toa repository.
5
+
6
+ ## Local environment
7
+
8
+ The application environment needs:
9
+
10
+ - [Tempo](https://grafana.com/oss/tempo/) with OTLP/HTTP enabled (port `4318`)
11
+ and Prometheus with `--web.enable-remote-write-receiver`
12
+ (see [`tempo.yaml`](../../observability/tempo.yaml) for the metrics-generator wiring)
13
+ - Grafana with a Prometheus datasource and a Tempo datasource
14
+ with `serviceMap.datasourceUid` pointing at it
15
+ (see [`grafana-datasources.yaml`](../../observability/grafana-datasources.yaml))
16
+
17
+ Enable the export in the application context:
18
+
19
+ ```yaml
20
+ # context.toa.yaml
21
+
22
+ telemetry:
23
+ traces:
24
+ exporters:
25
+ console: ~
26
+ otlp:
27
+ endpoint: http://localhost:4318
28
+ ```
29
+
30
+ ## Production
31
+
32
+ - Point `exporters.otlp.endpoint` at any OTLP/HTTP receiver (`/v1/traces` is appended).
33
+ Use `headers` for authentication (e.g. Grafana Cloud `Authorization: Basic ...`).
34
+ - Skip the usual per-process `service.name` setup (`OTEL_SERVICE_NAME` and the like):
35
+ Toa attributes spans to component ids (`default.orders`) or `exposition` automatically,
36
+ even when multiple components run in a single process.
37
+ - For the service graph, enable the Tempo metrics-generator with `service-graphs`
38
+ and `span-metrics` processors, and add `messaging.destination.name`
39
+ to `peer_attributes` — event destinations then appear as virtual nodes
40
+ between producers and consumers.
41
+ - Sampling is head-based and decided by Toa (see [Sampling](readme.md#sampling)),
42
+ so no tail sampling is required on the collector side; `sample` and `rate`
43
+ are the knobs controlling the exported volume.
44
+ - Spans are sent in batches (512 spans or every 5 seconds) and flushed on process exit;
45
+ abrupt termination (`SIGKILL`) may lose the last batch.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@toa.io/extensions.telemetry",
3
- "version": "1.0.0-alpha.240",
3
+ "version": "1.0.0-alpha.246",
4
4
  "description": "Toa Telemetry extension",
5
5
  "author": "temich <tema.gurtovoy@gmail.com>",
6
6
  "homepage": "https://github.com/toa-io/toa#readme",
@@ -20,7 +20,7 @@
20
20
  "transpile": "tsc"
21
21
  },
22
22
  "dependencies": {
23
- "openspan": "1.0.0-alpha.173"
23
+ "openspan": "1.0.0-alpha.246"
24
24
  },
25
- "gitHead": "4ff7c571e54e1f351795f76669f29ba79ec5a5f4"
25
+ "gitHead": "d6ee2a7246c64a44c50c28fadcfd1e27aaf137cb"
26
26
  }
package/readme.md CHANGED
@@ -1,25 +1,5 @@
1
1
  # Telemetry
2
2
 
3
- ## Ready probe
4
-
5
- Compositions expose `GET /.ready` (default port `8001`) for Kubernetes startup/readiness probes.
6
- The endpoint returns `503` until the composition has connected, then `200` after a short delay.
7
-
8
- Configure or disable via `telemetry` Context Annotation:
9
-
10
- ```yaml
11
- # context.toa.yaml
12
- telemetry:
13
- ready:
14
- port: 8001
15
- delay: 3
16
- ```
17
-
18
- ```yaml
19
- telemetry:
20
- ready: false
21
- ```
22
-
23
3
  ## Structured logs
24
4
 
25
5
  Structured logs can be written using the `logs` Context Aspect.
@@ -40,14 +20,16 @@ levels, with the following signature:
40
20
  Logs are formatted as JSON and written to stdout or stderr. The log entry format is:
41
21
 
42
22
  ```yaml
43
- time: string # ISO 8601 timestamp
44
- severity: string # DEBUG, INFO, WARN, ERROR
23
+ time: string # ISO 8601 timestamp
24
+ severity: string # TRACE, DEBUG, INFO, WARN, ERROR
45
25
  message: string
46
26
  attributes?: object
47
27
  context:
48
28
  namespace: string
49
29
  component: string
50
30
  operation: string
31
+ trace_id?: string # see Tracing
32
+ span_id?: string
51
33
  ```
52
34
 
53
35
  ### Logs configuration
@@ -55,14 +37,14 @@ context:
55
37
  Logs can be configured using `telemetry` Context Annotation.
56
38
 
57
39
  - `level`: limits the minimum log level.
58
- It can be set to `debug`, `info` (default), `warn`, or `error`.
40
+ It can be set to `trace`, `debug`, `info` (default), `warn`, or `error`.
59
41
 
60
42
  ```yaml
61
43
  # context.toa.yaml
62
44
 
63
45
  telemetry:
64
46
  logs:
65
- level: debug # debug < info < warn < error
47
+ level: debug # trace < debug < info < warn < error
66
48
  level@production: info
67
49
  ```
68
50
 
@@ -78,7 +60,151 @@ telemetry:
78
60
  level: debug
79
61
  ```
80
62
 
81
- ### Logs best practices
63
+ ## Tracing
64
+
65
+ Each operation invocation runs within a *span*.
66
+ If the incoming request carries a trace context ([W3C Trace Context](https://www.w3.org/TR/trace-context/)),
67
+ the span continues the trace, otherwise a new trace starts.
68
+ All log entries written during the invocation are automatically stamped with `trace_id` and
69
+ `span_id`, so entries belonging to one invocation can be correlated.
70
+
71
+ When a span completes, an entry with the `TRACE` severity is written with the span name as the
72
+ message and the following additional fields:
73
+
74
+ ```yaml
75
+ trace_id: string # 32 hex characters, shared by all spans and logs of the trace
76
+ span_id: string # 16 hex characters
77
+ parent_id?: string # span_id of the enclosing span
78
+ duration: number # milliseconds
79
+ kind?: string # server, client, producer, consumer; internal when omitted
80
+ status?: error # present if an exception was thrown
81
+ ```
82
+
83
+ Remote calls produce a `client`/`server` span pair: the gap between their durations
84
+ is the transport latency. Spans created with `context.span` are `internal`.
85
+
86
+ Emitting an event produces a `producer` span measuring the broker publish confirmation.
87
+ Each receiver processes the event within a `consumer` span, wrapped in a delivery span
88
+ created on behalf of the messaging destination (e.g. `default.orders.created`), so that
89
+ service graphs display event fan-out correctly: producer, the destination as a virtual
90
+ node, and each consumer. Event processing does not block the emitting operation,
91
+ so `consumer` spans may complete after the operation span ends.
92
+
93
+ Spans marked with `status: error` are those that threw an exception, operation invocations
94
+ that returned an exception, and HTTP requests that resulted in a 5xx response.
95
+ Successful spans have no status, as [recommended](https://opentelemetry.io/docs/specs/otel/trace/api/#set-status)
96
+ by the OpenTelemetry specification.
97
+
98
+ Connectors may record additional spans within the trace of the current invocation
99
+ (see the documentation of a specific connector).
100
+
101
+ Process startup can be traced as well: with `TOA_BOOT_TRACE=1`, `toa compose` and
102
+ `toa serve` produce a trace covering boot phases (manifest loading, component creation)
103
+ and connector connections, so the startup time breakdown can be explored.
104
+ Boot tracing is disabled by default.
105
+
106
+ ```shell
107
+ TOA_BOOT_TRACE=1 toa compose ./components/*
108
+ ```
109
+
110
+ Span entries are written only when the `trace` log level is enabled (the default on local
111
+ environments). Spans are executed regardless of the log level.
112
+
113
+ ### Custom spans
114
+
115
+ Sub-steps of an operation can be measured using the `span` Context Aspect:
116
+
117
+ ```javascript
118
+ async function computation (input, context) {
119
+ const rate = await context.span('fetch rate', () => fetch(RATES_URL))
120
+
121
+ return input.amount * rate
122
+ }
123
+ ```
124
+
125
+ `context.span` executes the given function and writes a span entry with its duration.
126
+ The signature is:
127
+
128
+ ```
129
+ span<T>(name: string, task: () => T | Promise<T>): Promise<T>
130
+ span<T>(name: string, attributes: object, task: () => T | Promise<T>): Promise<T>
131
+ ```
132
+
133
+ - `name`: constant span name (same rules as log messages, see best practices).
134
+ - `attributes`: optional, written to the span entry as-is — same as the `attributes`
135
+ argument of `context.logs` methods.
136
+ - `task`: the function to execute. Its result is returned as-is, and an exception is
137
+ rethrown after the span entry is written with `status: error`.
138
+
139
+ Spans can be nested: spans created and logs written inside `task` are linked to the enclosing
140
+ span.
141
+
142
+ ```javascript
143
+ async function computation (input, context) {
144
+ return context.span('convert', { currency: input.currency }, async () => {
145
+ const rate = await context.span('fetch rate', () => fetch(RATES_URL))
146
+
147
+ context.logs.info('Rate received', { rate })
148
+
149
+ return input.amount * rate
150
+ })
151
+ }
152
+ ```
153
+
154
+ ### Sampling
155
+
156
+ Whether a trace is recorded is decided once, at the trace root — by the process that starts
157
+ the trace. The decision is propagated along with the trace context, so a trace is either
158
+ recorded as a whole or not at all. Unrecorded traces still create and propagate the trace
159
+ context: log entries carry `trace_id`, only span entries are not written.
160
+
161
+ ```yaml
162
+ # context.toa.yaml
163
+
164
+ telemetry:
165
+ traces:
166
+ sample: 0.1 # probability of recording a trace, 0..1, defaults to 1
167
+ rate: 5 # maximum recorded traces per second per process, unlimited when omitted
168
+ ```
169
+
170
+ - `sample: 0` disables recording entirely, `1` records every trace.
171
+ - `rate` protects against traffic spikes: with `sample`, the recorded volume is proportional
172
+ to the traffic, while `rate` sets a hard cap (token bucket). It may be fractional:
173
+ `0.5` is one trace per 2 seconds.
174
+
175
+ When both are set, a trace is recorded if the `sample` lottery passes *and* the rate limit
176
+ is not exceeded.
177
+
178
+ ### Exporting
179
+
180
+ Recorded spans are passed to a set of *exporters*:
181
+
182
+ - `console` — writes spans as `TRACE` log entries to stdout (requires the `trace` log level,
183
+ the default on local environments)
184
+ - `otlp` — sends spans to an [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/#otlphttp)
185
+ endpoint (Grafana Tempo, OpenTelemetry Collector, etc.), batched
186
+
187
+ The OTLP `service.name` resource attribute is the logical service emitting the span:
188
+ the component id (e.g. `default.orders`) for operation spans and their outgoing calls,
189
+ or `exposition` for HTTP request spans.
190
+
191
+ ```yaml
192
+ # context.toa.yaml
193
+
194
+ telemetry:
195
+ traces:
196
+ exporters:
197
+ console: ~
198
+ otlp:
199
+ endpoint: http://tempo:4318 # POSTs to {endpoint}/v1/traces
200
+ ```
201
+
202
+ When the `exporters` key is omitted, spans are exported to the console.
203
+ When it is present, it is exhaustive: list `console` explicitly to keep it.
204
+
205
+ See [Grafana stack setup](grafana.md) for local and production wiring.
206
+
207
+ ## Logs best practices
82
208
 
83
209
  Use constant messages and attributes to facilitate log analysis.
84
210
 
@@ -154,3 +280,23 @@ context.logs.debug('Limits', {
154
280
  min: context.configuration.limits.min
155
281
  })
156
282
  ```
283
+
284
+ ## Ready probe
285
+
286
+ Compositions expose `GET /.ready` (default port `8001`) for Kubernetes startup/readiness probes.
287
+ The endpoint returns `503` until the composition has connected, then `200` after a short delay.
288
+
289
+ Configure or disable via `telemetry` Context Annotation:
290
+
291
+ ```yaml
292
+ # context.toa.yaml
293
+ telemetry:
294
+ ready:
295
+ port: 8001
296
+ delay: 3
297
+ ```
298
+
299
+ ```yaml
300
+ telemetry:
301
+ ready: false
302
+ ```
package/source/Ready.ts CHANGED
@@ -73,7 +73,12 @@ export class Ready extends Connector {
73
73
  if (this.skipped)
74
74
  return
75
75
 
76
- await setTimeout(this.options.delay)
76
+ const delay = async (): Promise<void> => await setTimeout(this.options.delay)
77
+
78
+ if (process.env.TOA_BOOT_TRACE === '1')
79
+ await console.span({ name: 'ready delay', attributes: { delay: this.options.delay } }, delay)
80
+ else
81
+ await delay()
77
82
 
78
83
  this.ready = true
79
84
 
package/source/Span.ts ADDED
@@ -0,0 +1,32 @@
1
+ import { Connector } from '@toa.io/core'
2
+ import { console } from 'openspan'
3
+ import type { Console, Task } from 'openspan'
4
+ import type { Locator, extensions } from '@toa.io/core'
5
+
6
+ export class Span extends Connector implements extensions.Aspect {
7
+ public readonly name = 'span'
8
+ private readonly locator: Locator
9
+ private readonly consoles: Record<string, Console> = {}
10
+
11
+ public constructor (locator: Locator) {
12
+ super()
13
+
14
+ this.locator = locator
15
+ }
16
+
17
+ // eslint-disable-next-line max-params
18
+ public async invoke (operation: string, name: string, attributes: object | Task<unknown>, task?: Task<unknown>): Promise<unknown> {
19
+ this.consoles[operation] ??= console.fork({
20
+ namespace: this.locator.namespace,
21
+ component: this.locator.name,
22
+ operation
23
+ })
24
+
25
+ const output = this.consoles[operation]
26
+
27
+ if (typeof attributes === 'function')
28
+ return await output.span(name, attributes as Task<unknown>)
29
+ else
30
+ return await output.span(name, attributes, task!)
31
+ }
32
+ }
package/source/aspects.ts CHANGED
@@ -4,3 +4,8 @@ export interface Logs {
4
4
  error: (message: string, ...args: any[]) => void
5
5
  debug: (message: string, ...args: any[]) => void
6
6
  }
7
+
8
+ export interface Span {
9
+ <T>(name: string, task: () => T | Promise<T>): Promise<T>
10
+ <T>(name: string, attributes: object, task: () => T | Promise<T>): Promise<T>
11
+ }
@@ -1,6 +1,8 @@
1
- import { console } from 'openspan'
1
+ import assert from 'node:assert'
2
+ import { console, traces } from 'openspan'
2
3
  import { decode, encode } from '@toa.io/generic'
3
4
  import { Logs } from './Logs'
5
+ import { Span } from './Span'
4
6
  import {
5
7
  DEFAULT_ANNOTATION,
6
8
  normalizeAnnotation,
@@ -11,7 +13,7 @@ import {
11
13
  import type { LogsOptions } from './Logs'
12
14
  import type { Connector, Locator, extensions } from '@toa.io/core'
13
15
  import type { Dependency, Probe, Variables } from '@toa.io/operations'
14
- import type { Channel } from 'openspan'
16
+ import type { ExportersConfig, LevelName } from 'openspan'
15
17
 
16
18
  export class Factory implements extensions.Factory {
17
19
  private readonly logsOptions: LogsOptions
@@ -19,20 +21,25 @@ export class Factory implements extensions.Factory {
19
21
 
20
22
  public constructor () {
21
23
  const globEnv = process.env[LOGS_PREFIX]
22
- const level = process.env.TOA_DEV === '1' ? 'debug' : 'info'
24
+ const level = process.env.TOA_DEV === '1' ? 'trace' : 'info'
23
25
 
24
26
  this.logsOptions = globEnv === undefined ? { level } : decode(globEnv)
25
27
  this.logsOptions.level ??= level
26
28
 
27
29
  console.configure({ level: this.logsOptions.level })
28
30
 
31
+ const tracesEnv = process.env[TRACES_ENV]
32
+
33
+ traces(tracesEnv === undefined ? {} : decode(tracesEnv))
34
+
29
35
  this.ready = Ready.create()
30
36
  }
31
37
 
32
38
  public aspect (locator: Locator): extensions.Aspect[] {
33
39
  const logs = this.createLogs(locator)
40
+ const span = new Span(locator)
34
41
 
35
- return [logs]
42
+ return [logs, span]
36
43
  }
37
44
 
38
45
  public manage (composition: Connector): Connector {
@@ -40,20 +47,18 @@ export class Factory implements extensions.Factory {
40
47
  return composition
41
48
 
42
49
  const ready = this.ready
50
+
51
+ // the composition manages the probe server lifecycle (listen on connect, close on disconnect)
52
+ composition.depends(ready)
53
+
43
54
  const connect = composition.connect.bind(composition)
44
- const disconnect = composition.disconnect.bind(composition)
45
55
 
56
+ // readiness is a post-connect phase, not expressible as a dependency
46
57
  composition.connect = async () => {
47
- await ready.listen()
48
58
  await connect()
49
59
  await ready.complete()
50
60
  }
51
61
 
52
- composition.disconnect = async (interrupt?: boolean) => {
53
- await ready.disconnect(interrupt)
54
- await disconnect(interrupt)
55
- }
56
-
57
62
  return composition
58
63
  }
59
64
 
@@ -73,6 +78,9 @@ export function deployment (_: unknown, annotation?: Annotation): Dependency {
73
78
  if (annotation?.logs !== undefined)
74
79
  addLogsVariables(annotation.logs, variables)
75
80
 
81
+ if (annotation?.traces !== undefined)
82
+ addTracesVariables(annotation.traces, variables)
83
+
76
84
  const ready = normalizeAnnotation(annotation?.ready)
77
85
 
78
86
  if (ready === false) {
@@ -110,15 +118,41 @@ function addLogsVariables (annotation: LogsAnnotation, variables: Variables): vo
110
118
  }
111
119
  }
112
120
 
121
+ function addTracesVariables (annotation: TracesAnnotation, variables: Variables): void {
122
+ const { sample, rate, exporters } = annotation
123
+
124
+ if (sample !== undefined)
125
+ assert.ok(typeof sample === 'number' && sample >= 0 && sample <= 1,
126
+ 'telemetry.traces.sample must be a number within [0, 1]')
127
+
128
+ if (rate !== undefined)
129
+ assert.ok(typeof rate === 'number' && rate > 0,
130
+ 'telemetry.traces.rate must be a positive number')
131
+
132
+ if (exporters?.otlp !== undefined)
133
+ assert.ok(typeof exporters.otlp.endpoint === 'string',
134
+ 'telemetry.traces.exporters.otlp.endpoint is required')
135
+
136
+ variables.global.push({ name: TRACES_ENV, value: encode({ sample, rate, exporters }) })
137
+ }
138
+
113
139
  interface Annotation {
114
140
  logs?: LogsAnnotation & Record<string, LogsAnnotation>
141
+ traces?: TracesAnnotation
115
142
  ready?: ReadyAnnotation
116
143
  }
117
144
 
118
145
  interface LogsAnnotation {
119
- level: Channel
146
+ level: LevelName
147
+ }
148
+
149
+ interface TracesAnnotation {
150
+ sample?: number
151
+ rate?: number
152
+ exporters?: ExportersConfig
120
153
  }
121
154
 
122
155
  const ENV_PREFIX = 'TOA_TELEMETRY'
123
156
  const LOGS_PREFIX = ENV_PREFIX + '_LOGS'
157
+ const TRACES_ENV = ENV_PREFIX + '_TRACES'
124
158
  export const ID = 'telemetry'
@@ -82,7 +82,11 @@ class Ready extends core_1.Connector {
82
82
  await this.listen();
83
83
  if (this.skipped)
84
84
  return;
85
- await (0, promises_1.setTimeout)(this.options.delay);
85
+ const delay = async () => await (0, promises_1.setTimeout)(this.options.delay);
86
+ if (process.env.TOA_BOOT_TRACE === '1')
87
+ await openspan_1.console.span({ name: 'ready delay', attributes: { delay: this.options.delay } }, delay);
88
+ else
89
+ await delay();
86
90
  this.ready = true;
87
91
  openspan_1.console.info('Ready');
88
92
  }
@@ -1 +1 @@
1
- {"version":3,"file":"Ready.js","sourceRoot":"","sources":["../source/Ready.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Ready.js","sourceRoot":"","sources":["../source/Ready.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,gDAAiC;AACjC,mDAAiD;AACjD,uCAAkC;AAClC,uCAAwC;AACxC,6CAAwC;AAExC,MAAa,KAAM,SAAQ,gBAAS;IAClB,IAAI,GAAG,OAAO,CAAA;IAEb,MAAM,GAAgB,IAAI,CAAC,YAAY,EAAE,CAAA;IACzC,OAAO,CAAc;IAC9B,KAAK,GAAG,KAAK,CAAA;IACb,SAAS,GAAG,CAAC,CAAA;IACb,SAAS,GAAG,KAAK,CAAA;IACjB,OAAO,GAAG,KAAK,CAAA;IAEvB,YAAoB,OAAqB;QACvC,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;IACnE,CAAC;IAEM,MAAM,CAAC,MAAM;QAClB,MAAM,OAAO,GAAG,cAAc,EAAE,CAAA;QAEhC,IAAI,OAAO,KAAK,IAAI;YAClB,OAAO,IAAI,CAAA;QAEb,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,CAAA;IAC3B,CAAC;IAEM,KAAK,CAAC,MAAM;QACjB,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO;YAChC,OAAM;QAER,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAE3B,IAAI,CAAC;YACH,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBAC1C,MAAM,OAAO,GAAG,CAAC,KAAY,EAAQ,EAAE;oBACrC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;oBACzC,MAAM,CAAC,KAAK,CAAC,CAAA;gBACf,CAAC,CAAA;gBAED,MAAM,WAAW,GAAG,GAAS,EAAE;oBAC7B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;oBACjC,OAAO,EAAE,CAAA;gBACX,CAAC,CAAA;gBAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;gBAClC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;gBAC1C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YACvC,CAAC,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,uEAAuE;YACvE,IAAI,KAAK,EAAE,IAAI,KAAK,YAAY,EAAE,CAAC;gBACjC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;gBACnB,kBAAO,CAAC,IAAI,CAAC,2CAA2C,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;gBAEtF,OAAM;YACR,CAAC;YAED,MAAM,KAAK,CAAA;QACb,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;IACvB,CAAC;IAEM,KAAK,CAAC,QAAQ;QACnB,MAAM,IAAI,CAAC,MAAM,EAAE,CAAA;QAEnB,IAAI,IAAI,CAAC,OAAO;YACd,OAAM;QAER,MAAM,KAAK,GAAG,KAAK,IAAmB,EAAE,CAAC,MAAM,IAAA,qBAAU,EAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAE7E,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,GAAG;YACpC,MAAM,kBAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,CAAC,CAAA;;YAE7F,MAAM,KAAK,EAAE,CAAA;QAEf,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QAEjB,kBAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IACvB,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,MAAM,IAAI,CAAC,MAAM,EAAE,CAAA;IACrB,CAAC;IAEkB,KAAK,CAAC,KAAK;QAC5B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAElB,IAAI,CAAC,IAAI,CAAC,SAAS;YACjB,OAAM;QAER,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;QACnB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAA;IACxB,CAAC;IAED,SAAS,CAAE,OAA6B,EAAE,QAA6B;QACrE,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACtC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAA;YAE7B,OAAM;QACR,CAAC;QAED,IAAI,IAAI,CAAC,KAAK;YACZ,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,CAAA;aAC3D,CAAC;YACJ,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAA;YAE5E,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC,CAAC,GAAG,EAAE,CAAA;QAC7D,CAAC;IACH,CAAC;CACF;AA9GD,sBA8GC;AAED,SAAgB,cAAc;IAC5B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAS,CAAC,CAAA;IAElC,IAAI,GAAG,KAAK,SAAS;QACnB,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAA;IAExB,MAAM,OAAO,GAAG,IAAA,gBAAM,EAAC,GAAG,CAAgB,CAAA;IAE1C,IAAI,OAAO,KAAK,KAAK,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK;QAChD,OAAO,IAAI,CAAA;IAEb,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI;QACnC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI;QACnC,KAAK,EAAE,CAAC,OAAO,CAAC,KAAK,IAAI,0BAAkB,CAAC,KAAK,CAAC,GAAG,IAAI;KAC1D,CAAA;AACH,CAAC;AAhBD,wCAgBC;AAED,SAAgB,mBAAmB,CAAE,KAAkC;IACrE,IAAI,KAAK,KAAK,KAAK;QACjB,OAAO,KAAK,CAAA;IAEd,IAAI,KAAK,KAAK,SAAS;QACrB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,0BAAkB,EAAE,CAAA;IAEjD,OAAO;QACL,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,0BAAkB,CAAC,IAAI;QAC3C,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,0BAAkB,CAAC,IAAI;QAC3C,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,0BAAkB,CAAC,KAAK;KAC/C,CAAA;AACH,CAAC;AAbD,kDAaC;AAEY,QAAA,SAAS,GAAG,qBAAqB,CAAA;AACjC,QAAA,kBAAkB,GAAG;IAChC,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,CAAC;CACA,CAAA;AAEV,MAAM,QAAQ,GAAiB;IAC7B,IAAI,EAAE,0BAAkB,CAAC,IAAI;IAC7B,IAAI,EAAE,0BAAkB,CAAC,IAAI;IAC7B,KAAK,EAAE,0BAAkB,CAAC,KAAK,GAAG,IAAI;CACvC,CAAA"}
@@ -0,0 +1,10 @@
1
+ import { Connector } from '@toa.io/core';
2
+ import type { Task } from 'openspan';
3
+ import type { Locator, extensions } from '@toa.io/core';
4
+ export declare class Span extends Connector implements extensions.Aspect {
5
+ readonly name = "span";
6
+ private readonly locator;
7
+ private readonly consoles;
8
+ constructor(locator: Locator);
9
+ invoke(operation: string, name: string, attributes: object | Task<unknown>, task?: Task<unknown>): Promise<unknown>;
10
+ }
@@ -0,0 +1,29 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.Span = void 0;
4
+ const core_1 = require("@toa.io/core");
5
+ const openspan_1 = require("openspan");
6
+ class Span extends core_1.Connector {
7
+ name = 'span';
8
+ locator;
9
+ consoles = {};
10
+ constructor(locator) {
11
+ super();
12
+ this.locator = locator;
13
+ }
14
+ // eslint-disable-next-line max-params
15
+ async invoke(operation, name, attributes, task) {
16
+ this.consoles[operation] ??= openspan_1.console.fork({
17
+ namespace: this.locator.namespace,
18
+ component: this.locator.name,
19
+ operation
20
+ });
21
+ const output = this.consoles[operation];
22
+ if (typeof attributes === 'function')
23
+ return await output.span(name, attributes);
24
+ else
25
+ return await output.span(name, attributes, task);
26
+ }
27
+ }
28
+ exports.Span = Span;
29
+ //# sourceMappingURL=Span.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"Span.js","sourceRoot":"","sources":["../source/Span.ts"],"names":[],"mappings":";;;AAAA,uCAAwC;AACxC,uCAAkC;AAIlC,MAAa,IAAK,SAAQ,gBAAS;IACjB,IAAI,GAAG,MAAM,CAAA;IACZ,OAAO,CAAS;IAChB,QAAQ,GAA4B,EAAE,CAAA;IAEvD,YAAoB,OAAgB;QAClC,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;IAED,sCAAsC;IAC/B,KAAK,CAAC,MAAM,CAAE,SAAiB,EAAE,IAAY,EAAE,UAAkC,EAAE,IAAoB;QAC5G,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,kBAAO,CAAC,IAAI,CAAC;YACxC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS;YACjC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI;YAC5B,SAAS;SACV,CAAC,CAAA;QAEF,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAA;QAEvC,IAAI,OAAO,UAAU,KAAK,UAAU;YAClC,OAAO,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,UAA2B,CAAC,CAAA;;YAE3D,OAAO,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,IAAK,CAAC,CAAA;IACrD,CAAC;CACF;AA1BD,oBA0BC"}
@@ -4,3 +4,7 @@ export interface Logs {
4
4
  error: (message: string, ...args: any[]) => void;
5
5
  debug: (message: string, ...args: any[]) => void;
6
6
  }
7
+ export interface Span {
8
+ <T>(name: string, task: () => T | Promise<T>): Promise<T>;
9
+ <T>(name: string, attributes: object, task: () => T | Promise<T>): Promise<T>;
10
+ }
@@ -1,7 +1,7 @@
1
1
  import { type ReadyAnnotation } from './Ready';
2
2
  import type { Connector, Locator, extensions } from '@toa.io/core';
3
3
  import type { Dependency } from '@toa.io/operations';
4
- import type { Channel } from 'openspan';
4
+ import type { ExportersConfig, LevelName } from 'openspan';
5
5
  export declare class Factory implements extensions.Factory {
6
6
  private readonly logsOptions;
7
7
  private readonly ready;
@@ -13,10 +13,16 @@ export declare class Factory implements extensions.Factory {
13
13
  export declare function deployment(_: unknown, annotation?: Annotation): Dependency;
14
14
  interface Annotation {
15
15
  logs?: LogsAnnotation & Record<string, LogsAnnotation>;
16
+ traces?: TracesAnnotation;
16
17
  ready?: ReadyAnnotation;
17
18
  }
18
19
  interface LogsAnnotation {
19
- level: Channel;
20
+ level: LevelName;
21
+ }
22
+ interface TracesAnnotation {
23
+ sample?: number;
24
+ rate?: number;
25
+ exporters?: ExportersConfig;
20
26
  }
21
27
  export declare const ID = "telemetry";
22
28
  export {};