@toa.io/extensions.telemetry 1.0.0-alpha.283 → 1.0.0-alpha.289

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/CHANGELOG.md CHANGED
@@ -3,80 +3,12 @@
3
3
  All notable changes to this project will be documented in this file.
4
4
  See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
5
5
 
6
- # [1.0.0-alpha.283](https://github.com/toa-io/toa/compare/v1.0.0-alpha.282...v1.0.0-alpha.283) (2026-09-04)
7
-
8
- ### Features
9
-
10
- * **extensions:** an extension declares what it puts on a component's context ([133bc2a](https://github.com/toa-io/toa/commit/133bc2aad1e45a2d4aa68a08a5e44ca48d3b7414))
11
-
12
-
13
- # [1.0.0-alpha.277](https://github.com/toa-io/toa/compare/v1.0.0-alpha.276...v1.0.0-alpha.277) (2026-09-03)
14
-
15
- ### Bug Fixes
16
-
17
- * drop the build output that landed beside the sources ([a724f69](https://github.com/toa-io/toa/commit/a724f6921190e5c9d945e33c6035bb12d832e5c8))
18
-
19
-
20
- # [1.0.0-alpha.273](https://github.com/toa-io/toa/compare/v1.0.0-alpha.272...v1.0.0-alpha.273) (2026-09-02)
21
-
22
- **Note:** Version bump only for package @toa.io/extensions.telemetry
23
-
24
-
25
-
26
-
27
-
28
- # [1.0.0-alpha.272](https://github.com/toa-io/toa/compare/v1.0.0-alpha.271...v1.0.0-alpha.272) (2026-09-01)
29
-
30
-
31
- * feat(openspan)!: make trace a log channel ([b107944](https://github.com/toa-io/toa/commit/b10794473ee442b28fa6b9b1c48ef9fc1d4471e5))
6
+ # [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
32
7
 
8
+ * A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
33
9
 
34
10
  ### BREAKING CHANGES
35
11
 
36
- * `Console.trace(span)` is gone. `trace` is a log channel taking
37
- `(message, attributes)`, and a span is written with `Console.entry` instead.
38
-
39
- Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
40
-
41
-
42
-
43
-
44
-
45
- # [1.0.0-alpha.270](https://github.com/toa-io/toa/compare/v1.0.0-alpha.269...v1.0.0-alpha.270) (2026-08-31)
46
-
47
-
48
- ### Bug Fixes
49
-
50
- * **telemetry:** keep the ready probe from holding the process open ([1cb180b](https://github.com/toa-io/toa/commit/1cb180be2a0d13f61fc6d78ceecd18b339a94cf0))
51
-
52
-
53
- ### Performance Improvements
54
-
55
- * **openspan:** create a span only when something records it ([a6efb0e](https://github.com/toa-io/toa/commit/a6efb0eed38393f4c169b067f23d7447f0169bca))
56
-
57
-
58
-
59
-
60
-
61
- # [1.0.0-alpha.265](https://github.com/toa-io/toa/compare/v1.0.0-alpha.264...v1.0.0-alpha.265) (2026-08-29)
62
-
63
-
64
- ### Bug Fixes
65
-
66
- * **telemetry:** signal readiness when the probe port is taken ([19722b8](https://github.com/toa-io/toa/commit/19722b8b2f3b9af969fc66c3c67e4d9cd87b952f))
67
-
68
-
69
-
70
-
71
-
72
- # [1.0.0-alpha.264](https://github.com/toa-io/toa/compare/v1.0.0-alpha.263...v1.0.0-alpha.264) (2026-08-29)
73
-
74
-
75
- ### Bug Fixes
76
-
77
- * **openspan:** stop an unavailable OTLP endpoint delaying the shutdown ([e5f0d52](https://github.com/toa-io/toa/commit/e5f0d52805c150cd127f27d1cd39553da7c82aef))
78
-
79
-
80
- ### Performance Improvements
81
-
82
- * **telemetry:** release the ready probe connections on shutdown ([5242f12](https://github.com/toa-io/toa/commit/5242f122cb0ccb01b16c48ef10f49cd0a603f15e))
12
+ * a component that read `process.env.TOA_*` reads `context` instead;
13
+ `echo(input)` no longer substitutes from the environment; a bash operation sees no
14
+ `TOA_*`; images no longer set `USER node` — see migrations/289.md.
package/grafana.md CHANGED
@@ -50,7 +50,7 @@ Toa stamps `trace_id` and `span_id` into every log entry written within a span
50
50
  (including unsampled traces), so once pod logs are shipped to Loki,
51
51
  traces and logs link up with two datasource settings:
52
52
 
53
- - Tempo datasource, *Trace to logs*: select the Loki datasource,
53
+ - Tempo datasource, _Trace to logs_: select the Loki datasource,
54
54
  set time shifts (e.g. `-5m`/`+5m`) and a custom query:
55
55
 
56
56
  ```logql
@@ -58,7 +58,8 @@ traces and logs link up with two datasource settings:
58
58
  ```
59
59
 
60
60
  Append `` | span_id = `${__span.spanId}` `` to narrow down to a single span.
61
- - Loki datasource, *Derived fields*: regex `"trace_id":"([0-9a-f]+)"`,
61
+
62
+ - Loki datasource, _Derived fields_: regex `"trace_id":"([0-9a-f]+)"`,
62
63
  query `${__value.raw}`, internal link to the Tempo datasource.
63
64
 
64
65
  Logs of unsampled traces carry a `trace_id` that does not exist in Tempo.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@toa.io/extensions.telemetry",
3
- "version": "1.0.0-alpha.283",
3
+ "version": "1.0.0-alpha.289",
4
4
  "type": "module",
5
5
  "description": "Toa Telemetry extension",
6
6
  "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,7 +21,8 @@
21
21
  "transpile": "tsc"
22
22
  },
23
23
  "dependencies": {
24
- "openspan": "1.0.0-alpha.277"
24
+ "@toa.io/generic": "1.0.0-alpha.289",
25
+ "openspan": "1.0.0-alpha.286"
25
26
  },
26
- "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
27
+ "gitHead": "4fcb482beac5896305d8084cdbc1d5fcf372d108"
27
28
  }
package/readme.md CHANGED
@@ -5,7 +5,7 @@
5
5
  Structured logs can be written using the `logs` Context Aspect.
6
6
 
7
7
  ```javascript
8
- async function computation (input, context) {
8
+ async function computation(input, context) {
9
9
  context.logs.info('Hello, world', { foo: 'bar' })
10
10
  }
11
11
  ```
@@ -20,15 +20,15 @@ severity levels, with the following signature:
20
20
  Logs are formatted as JSON and written to stdout or stderr. The log entry format is:
21
21
 
22
22
  ```yaml
23
- time: string # ISO 8601 timestamp
24
- severity: string # TRACE, DEBUG, INFO, WARN, ERROR
23
+ time: string # ISO 8601 timestamp
24
+ severity: string # TRACE, DEBUG, INFO, WARN, ERROR
25
25
  message: string
26
26
  attributes?: object
27
27
  context:
28
28
  namespace: string
29
29
  component: string
30
30
  operation: string
31
- trace_id?: string # see Tracing
31
+ trace_id?: string # see Tracing
32
32
  span_id?: string
33
33
  ```
34
34
 
@@ -44,7 +44,7 @@ Logs can be configured using `telemetry` Context Annotation.
44
44
 
45
45
  telemetry:
46
46
  logs:
47
- level: debug # trace < debug < info < warn < error
47
+ level: debug # trace < debug < info < warn < error
48
48
  level@production: info
49
49
  ```
50
50
 
@@ -62,7 +62,7 @@ telemetry:
62
62
 
63
63
  ## Tracing
64
64
 
65
- Each operation invocation runs within a *span*.
65
+ Each operation invocation runs within a _span_.
66
66
  If the incoming request carries a trace context ([W3C Trace Context](https://www.w3.org/TR/trace-context/)),
67
67
  the span continues the trace, otherwise a new trace starts.
68
68
  All log entries written during the invocation are automatically stamped with `trace_id` and
@@ -72,12 +72,12 @@ When a span completes, an entry with the `TRACE` severity is written with the sp
72
72
  message and the following additional fields:
73
73
 
74
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
75
+ trace_id: string # 32 hex characters, shared by all spans and logs of the trace
76
+ span_id: string # 16 hex characters
77
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
78
+ duration: number # milliseconds
79
+ kind?: string # server, client, producer, consumer; internal when omitted
80
+ status?: error # present if an exception was thrown
81
81
  ```
82
82
 
83
83
  Remote calls produce a `client`/`server` span pair: the gap between their durations
@@ -115,7 +115,7 @@ environments). Spans are executed regardless of the log level.
115
115
  Sub-steps of an operation can be measured using the `span` Context Aspect:
116
116
 
117
117
  ```javascript
118
- async function computation (input, context) {
118
+ async function computation(input, context) {
119
119
  const rate = await context.span('fetch rate', () => fetch(RATES_URL))
120
120
 
121
121
  return input.amount * rate
@@ -140,7 +140,7 @@ Spans can be nested: spans created and logs written inside `task` are linked to
140
140
  span.
141
141
 
142
142
  ```javascript
143
- async function computation (input, context) {
143
+ async function computation(input, context) {
144
144
  return context.span('convert', { currency: input.currency }, async () => {
145
145
  const rate = await context.span('fetch rate', () => fetch(RATES_URL))
146
146
 
@@ -163,8 +163,8 @@ context: log entries carry `trace_id`, only span entries are not written.
163
163
 
164
164
  telemetry:
165
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
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
168
  ```
169
169
 
170
170
  - `sample: 0` disables recording entirely, `1` records every trace.
@@ -172,12 +172,12 @@ telemetry:
172
172
  to the traffic, while `rate` sets a hard cap (token bucket). It may be fractional:
173
173
  `0.5` is one trace per 2 seconds.
174
174
 
175
- When both are set, a trace is recorded if the `sample` lottery passes *and* the rate limit
175
+ When both are set, a trace is recorded if the `sample` lottery passes _and_ the rate limit
176
176
  is not exceeded.
177
177
 
178
178
  ### Exporting
179
179
 
180
- Recorded spans are passed to a set of *exporters*:
180
+ Recorded spans are passed to a set of _exporters_:
181
181
 
182
182
  - `console` — writes spans as `TRACE` log entries to stdout (requires the `trace` log level,
183
183
  the default on local environments)
@@ -196,9 +196,9 @@ telemetry:
196
196
  exporters:
197
197
  console: ~
198
198
  otlp:
199
- endpoint: http://tempo:4318 # POSTs to {endpoint}/v1/traces
200
- timeout: 5000 # request timeout, milliseconds
201
- cooldown: 30000 # how long to drop spans for after a failed export
199
+ endpoint: http://tempo:4318 # POSTs to {endpoint}/v1/traces
200
+ timeout: 5000 # request timeout, milliseconds
201
+ cooldown: 30000 # how long to drop spans for after a failed export
202
202
  ```
203
203
 
204
204
  When the `exporters` key is omitted, spans are exported to the console.
@@ -234,7 +234,9 @@ Logs are not comments or documentation, nor are they a replacement for them.
234
234
  :-1: Don't:
235
235
 
236
236
  ```javascript
237
- context.logs.error('Failed to send the email, please check the email server configuration')
237
+ context.logs.error(
238
+ 'Failed to send the email, please check the email server configuration'
239
+ )
238
240
  ```
239
241
 
240
242
  :+1: Do:
package/source/Logs.ts CHANGED
@@ -1,7 +1,8 @@
1
1
  import { Connector } from '@toa.io/core'
2
2
  import { console } from 'openspan'
3
3
  import type { Channel, Console, ConsoleOptions } from 'openspan'
4
- import type { Locator, extensions } from '@toa.io/core'
4
+ import type { Locator } from '@toa.io/core'
5
+ import type { extensions } from '@toa.io/core/types'
5
6
 
6
7
  export class Logs extends Connector implements extensions.Aspect {
7
8
  public readonly name = 'logs'
@@ -9,7 +10,7 @@ export class Logs extends Connector implements extensions.Aspect {
9
10
  private readonly console: Console
10
11
  private readonly consoles: Record<string, Console> = {}
11
12
 
12
- public constructor (locator: Locator, options: LogsOptions) {
13
+ public constructor(locator: Locator, options: LogsOptions) {
13
14
  super()
14
15
 
15
16
  this.locator = locator
@@ -17,9 +18,14 @@ export class Logs extends Connector implements extensions.Aspect {
17
18
  this.console.configure(options)
18
19
  }
19
20
 
20
- public invoke (operation: string, fork: 'fork', context: object): Console
21
+ public invoke(operation: string, fork: 'fork', context: object): Console
21
22
  // eslint-disable-next-line max-params
22
- public invoke (operation: string, severity: Channel | 'fork', message: string | object, attributes?: object): Console | undefined {
23
+ public invoke(
24
+ operation: string,
25
+ severity: Channel | 'fork',
26
+ message: string | object,
27
+ attributes?: object
28
+ ): Console | undefined {
23
29
  if (!(operation in this.consoles))
24
30
  this.consoles[operation] = this.console.fork({
25
31
  namespace: this.locator.namespace,
@@ -30,7 +36,10 @@ export class Logs extends Connector implements extensions.Aspect {
30
36
  if (severity === 'fork')
31
37
  return this.consoles[operation].fork(message as Record<string, unknown>)
32
38
  else
33
- this.consoles[operation][severity](message as string, attributes as Record<string, unknown>)
39
+ this.consoles[operation][severity](
40
+ message as string,
41
+ attributes as Record<string, unknown>
42
+ )
34
43
  }
35
44
  }
36
45
 
@@ -24,7 +24,12 @@ it('should signal readiness', async () => {
24
24
  await ready.connect()
25
25
  await ready.complete()
26
26
 
27
- assert.ok(send.mock.calls.some((call: any) => call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], 'ready')))
27
+ assert.ok(
28
+ send.mock.calls.some(
29
+ (call: any) =>
30
+ call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], 'ready')
31
+ )
32
+ )
28
33
 
29
34
  await ready.disconnect()
30
35
  })
@@ -40,7 +45,12 @@ it('should signal readiness when the probe port is taken', async () => {
40
45
 
41
46
  await second.complete()
42
47
 
43
- assert.ok(send.mock.calls.some((call: any) => call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], 'ready')))
48
+ assert.ok(
49
+ send.mock.calls.some(
50
+ (call: any) =>
51
+ call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], 'ready')
52
+ )
53
+ )
44
54
 
45
55
  await first.disconnect()
46
56
  await second.disconnect()
package/source/Ready.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import * as http from 'node:http'
2
2
  import { console } from 'openspan'
3
3
  import { Connector } from '@toa.io/core'
4
+ import { environment } from '@toa.io/generic'
4
5
 
5
6
  export class Ready extends Connector {
6
7
  public readonly name = 'ready'
@@ -12,25 +13,23 @@ export class Ready extends Connector {
12
13
  private listening = false
13
14
  private skipped = false
14
15
 
15
- public constructor (options: ReadyOptions) {
16
+ public constructor(options: ReadyOptions) {
16
17
  super()
17
18
 
18
19
  this.options = options
19
20
  this.server.on('request', (req, res) => this.#listener(req, res))
20
21
  }
21
22
 
22
- public static create (): Ready | null {
23
+ public static create(): Ready | null {
23
24
  const options = resolveOptions()
24
25
 
25
- if (options === null)
26
- return null
26
+ if (options === null) return null
27
27
 
28
28
  return new Ready(options)
29
29
  }
30
30
 
31
- public async listen (): Promise<void> {
32
- if (this.listening || this.skipped)
33
- return
31
+ public async listen(): Promise<void> {
32
+ if (this.listening || this.skipped) return
34
33
 
35
34
  this.startedAt = Date.now()
36
35
 
@@ -54,7 +53,9 @@ export class Ready extends Connector {
54
53
  // Local multi-process (pm2 + features) shares a host; k8s pods do not.
55
54
  if (error?.code === 'EADDRINUSE') {
56
55
  this.skipped = true
57
- console.warn('Ready probe port already in use, skipping', { port: this.options.port })
56
+ console.warn('Ready probe port already in use, skipping', {
57
+ port: this.options.port
58
+ })
58
59
 
59
60
  return
60
61
  }
@@ -68,7 +69,7 @@ export class Ready extends Connector {
68
69
  this.server.unref()
69
70
  }
70
71
 
71
- public async complete (): Promise<void> {
72
+ public async complete(): Promise<void> {
72
73
  await this.listen()
73
74
 
74
75
  this.ready = true
@@ -80,15 +81,14 @@ export class Ready extends Connector {
80
81
  process.send?.('ready')
81
82
  }
82
83
 
83
- protected override async open (): Promise<void> {
84
+ protected override async open(): Promise<void> {
84
85
  await this.listen()
85
86
  }
86
87
 
87
- protected override async close (): Promise<void> {
88
+ protected override async close(): Promise<void> {
88
89
  this.ready = false
89
90
 
90
- if (!this.listening)
91
- return
91
+ if (!this.listening) return
92
92
 
93
93
  this.listening = false
94
94
 
@@ -98,15 +98,14 @@ export class Ready extends Connector {
98
98
  await new Promise<void>((resolve) => this.server.close(() => resolve()))
99
99
  }
100
100
 
101
- #listener (request: http.IncomingMessage, response: http.ServerResponse): void {
101
+ #listener(request: http.IncomingMessage, response: http.ServerResponse): void {
102
102
  if (request.url !== this.options.path) {
103
103
  response.writeHead(404).end()
104
104
 
105
105
  return
106
106
  }
107
107
 
108
- if (this.ready)
109
- response.writeHead(200, { 'cache-control': 'no-store' }).end()
108
+ if (this.ready) response.writeHead(200, { 'cache-control': 'no-store' }).end()
110
109
  else {
111
110
  const remaining = Math.ceil((Date.now() - this.startedAt) / 1000).toString()
112
111
 
@@ -115,16 +114,14 @@ export class Ready extends Connector {
115
114
  }
116
115
  }
117
116
 
118
- export function resolveOptions (): ReadyOptions | null {
119
- const env = process.env[READY_ENV]
117
+ export function resolveOptions(): ReadyOptions | null {
118
+ const env = environment.get(READY_ENV)
120
119
 
121
- if (env === undefined)
122
- return { ...DEFAULTS }
120
+ if (env === undefined) return { ...DEFAULTS }
123
121
 
124
122
  const decoded = JSON.parse(env) as ReadyConfig
125
123
 
126
- if (decoded === false || decoded.enabled === false)
127
- return null
124
+ if (decoded === false || decoded.enabled === false) return null
128
125
 
129
126
  return {
130
127
  path: decoded.path ?? DEFAULTS.path,
@@ -132,12 +129,12 @@ export function resolveOptions (): ReadyOptions | null {
132
129
  }
133
130
  }
134
131
 
135
- export function normalizeAnnotation (ready: ReadyAnnotation | undefined): ReadyConfig | false {
136
- if (ready === false)
137
- return false
132
+ export function normalizeAnnotation(
133
+ ready: ReadyAnnotation | undefined
134
+ ): ReadyConfig | false {
135
+ if (ready === false) return false
138
136
 
139
- if (ready === undefined)
140
- return { enabled: true, ...DEFAULT_ANNOTATION }
137
+ if (ready === undefined) return { enabled: true, ...DEFAULT_ANNOTATION }
141
138
 
142
139
  return {
143
140
  enabled: true,
@@ -159,13 +156,17 @@ export interface ReadyOptions {
159
156
  port: number
160
157
  }
161
158
 
162
- export type ReadyAnnotation = false | {
163
- path?: string
164
- port?: number
165
- }
159
+ export type ReadyAnnotation =
160
+ | false
161
+ | {
162
+ path?: string
163
+ port?: number
164
+ }
166
165
 
167
- export type ReadyConfig = false | {
168
- enabled?: boolean
169
- path?: string
170
- port?: number
171
- }
166
+ export type ReadyConfig =
167
+ | false
168
+ | {
169
+ enabled?: boolean
170
+ path?: string
171
+ port?: number
172
+ }
package/source/Span.ts CHANGED
@@ -1,21 +1,27 @@
1
1
  import { Connector } from '@toa.io/core'
2
2
  import { console } from 'openspan'
3
3
  import type { Console, Task } from 'openspan'
4
- import type { Locator, extensions } from '@toa.io/core'
4
+ import type { Locator } from '@toa.io/core'
5
+ import type { extensions } from '@toa.io/core/types'
5
6
 
6
7
  export class Span extends Connector implements extensions.Aspect {
7
8
  public readonly name = 'span'
8
9
  private readonly locator: Locator
9
10
  private readonly consoles: Record<string, Console> = {}
10
11
 
11
- public constructor (locator: Locator) {
12
+ public constructor(locator: Locator) {
12
13
  super()
13
14
 
14
15
  this.locator = locator
15
16
  }
16
17
 
17
18
  // eslint-disable-next-line max-params
18
- public async invoke (operation: string, name: string, attributes: object | Task<unknown>, task?: Task<unknown>): Promise<unknown> {
19
+ public async invoke(
20
+ operation: string,
21
+ name: string,
22
+ attributes: object | Task<unknown>,
23
+ task?: Task<unknown>
24
+ ): Promise<unknown> {
19
25
  this.consoles[operation] ??= console.fork({
20
26
  namespace: this.locator.namespace,
21
27
  component: this.locator.name,
@@ -26,7 +32,6 @@ export class Span extends Connector implements extensions.Aspect {
26
32
 
27
33
  if (typeof attributes === 'function')
28
34
  return await output.span(name, attributes as Task<unknown>)
29
- else
30
- return await output.span(name, attributes, task!)
35
+ else return await output.span(name, attributes, task!)
31
36
  }
32
37
  }
package/source/context.ts CHANGED
@@ -1,7 +1,7 @@
1
- import type { Contribution } from '@toa.io/core'
1
+ import type { Contribution } from '@toa.io/core/types'
2
2
 
3
3
  /** What this extension puts on the context of every component, being declared for all. */
4
- export function context (): Contribution[] {
4
+ export function context(): Contribution[] {
5
5
  const imports = { '@toa.io/extensions.telemetry': ['Logs', 'Span'] }
6
6
 
7
7
  return [