@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 +45 -0
- package/package.json +3 -3
- package/readme.md +171 -25
- package/source/Ready.ts +6 -1
- package/source/Span.ts +32 -0
- package/source/aspects.ts +5 -0
- package/source/extension.ts +46 -12
- package/transpiled/Ready.js +5 -1
- package/transpiled/Ready.js.map +1 -1
- package/transpiled/Span.d.ts +10 -0
- package/transpiled/Span.js +29 -0
- package/transpiled/Span.js.map +1 -0
- package/transpiled/aspects.d.ts +4 -0
- package/transpiled/extension.d.ts +8 -2
- package/transpiled/extension.js +26 -8
- package/transpiled/extension.js.map +1 -1
- package/transpiled/tsconfig.tsbuildinfo +1 -1
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.
|
|
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.
|
|
23
|
+
"openspan": "1.0.0-alpha.246"
|
|
24
24
|
},
|
|
25
|
-
"gitHead": "
|
|
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
|
|
44
|
-
severity: string
|
|
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
|
-
|
|
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
|
+
}
|
package/source/extension.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
|
-
import
|
|
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 {
|
|
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' ? '
|
|
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:
|
|
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'
|
package/transpiled/Ready.js
CHANGED
|
@@ -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
|
}
|
package/transpiled/Ready.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
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,IAAA,qBAAU,EAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;
|
|
1
|
+
{"version":3,"file":"Ready.js","sourceRoot":"","sources":["../source/Ready.ts"],"names":[],"mappings":"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"}
|
|
@@ -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"}
|
package/transpiled/aspects.d.ts
CHANGED
|
@@ -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 {
|
|
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:
|
|
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 {};
|