@xylabs/telemetry 5.0.95 → 5.0.97

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.
Files changed (2) hide show
  1. package/README.md +200 -133
  2. package/package.json +8 -11
package/README.md CHANGED
@@ -1,65 +1,76 @@
1
1
  # @xylabs/telemetry
2
2
 
3
- [![logo][]](https://xylabs.com)
3
+ [![npm][npm-badge]][npm-link]
4
+ [![license][license-badge]][license-link]
4
5
 
5
- [![main-build][]][main-build-link]
6
- [![npm-badge][]][npm-link]
7
- [![npm-downloads-badge][]][npm-link]
8
- [![jsdelivr-badge][]][jsdelivr-link]
9
- [![npm-license-badge][]](LICENSE)
10
- [![codacy-badge][]][codacy-link]
11
- [![codeclimate-badge][]][codeclimate-link]
12
- [![snyk-badge][]][snyk-link]
13
- [![socket-badge][]][socket-link]
6
+ > Base functionality used throughout XY Labs TypeScript/JavaScript libraries
14
7
 
8
+ ## Install
15
9
 
16
- Base functionality used throughout XY Labs TypeScript/JavaScript libraries
10
+ Using npm:
17
11
 
12
+ ```sh
13
+ npm install {{name}}
14
+ ```
18
15
 
16
+ Using yarn:
19
17
 
20
- ## Reference
18
+ ```sh
19
+ yarn add {{name}}
20
+ ```
21
21
 
22
- **@xylabs/telemetry**
22
+ Using pnpm:
23
23
 
24
- ***
24
+ ```sh
25
+ pnpm add {{name}}
26
+ ```
27
+
28
+ Using bun:
29
+
30
+ ```sh
31
+ bun add {{name}}
32
+ ```
33
+
34
+
35
+ ## License
25
36
 
26
- ## Interfaces
37
+ See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).
27
38
 
28
- | Interface | Description |
29
- | ------ | ------ |
30
- | [SpanConfig](#interfaces/SpanConfig) | Configuration options for span creation and execution. |
39
+ ## Reference
40
+
41
+ ### packages
31
42
 
32
- ## Functions
43
+ ### telemetry
33
44
 
34
- | Function | Description |
35
- | ------ | ------ |
36
- | [cloneContextWithoutSpan](#functions/cloneContextWithoutSpan) | Creates a new OpenTelemetry context that preserves baggage and custom keys but has no active span. |
37
- | [span](#functions/span) | Executes a synchronous function within an OpenTelemetry span, recording status and exceptions. |
38
- | [spanRoot](#functions/spanRoot) | Executes a synchronous function within a new root span that has no parent, even if a span is already active. |
39
- | [spanAsync](#functions/spanAsync) | Executes an async function within an OpenTelemetry span, with optional time budget monitoring. |
40
- | [spanRootAsync](#functions/spanRootAsync) | Executes an async function within a new root span (no parent), with optional time budget monitoring. |
41
- | [timeBudget](#functions/timeBudget) | Executes an async function and logs a warning if it exceeds the given time budget. |
45
+ ### .temp-typedoc
42
46
 
43
- ### functions
47
+ ### functions
44
48
 
45
- ### <a id="cloneContextWithoutSpan"></a>cloneContextWithoutSpan
49
+ ### <a id="cloneContextWithoutSpan"></a>cloneContextWithoutSpan
46
50
 
47
51
  [**@xylabs/telemetry**](#../README)
48
52
 
49
53
  ***
50
54
 
51
55
  ```ts
52
- function cloneContextWithoutSpan(activeCtx: Context, configKeys?: symbol[]): Context;
56
+ function cloneContextWithoutSpan(activeCtx, configKeys?): Context;
53
57
  ```
54
58
 
55
59
  Creates a new OpenTelemetry context that preserves baggage and custom keys but has no active span.
56
60
 
57
61
  ## Parameters
58
62
 
59
- | Parameter | Type | Default value | Description |
60
- | ------ | ------ | ------ | ------ |
61
- | `activeCtx` | `Context` | `undefined` | The context to clone from. |
62
- | `configKeys` | `symbol`[] | `[]` | Additional context keys to copy. |
63
+ ### activeCtx
64
+
65
+ `Context`
66
+
67
+ The context to clone from.
68
+
69
+ ### configKeys?
70
+
71
+ `symbol`[] = `[]`
72
+
73
+ Additional context keys to copy.
63
74
 
64
75
  ## Returns
65
76
 
@@ -67,7 +78,7 @@ Creates a new OpenTelemetry context that preserves baggage and custom keys but h
67
78
 
68
79
  A new context with baggage but no parent span.
69
80
 
70
- ### <a id="span"></a>span
81
+ ### <a id="span"></a>span
71
82
 
72
83
  [**@xylabs/telemetry**](#../README)
73
84
 
@@ -75,26 +86,36 @@ A new context with baggage but no parent span.
75
86
 
76
87
  ```ts
77
88
  function span<T>(
78
- name: string,
79
- fn: () => T,
80
- tracer?: Tracer): T;
89
+ name,
90
+ fn,
91
+ traceProvider?): T;
81
92
  ```
82
93
 
83
94
  Executes a synchronous function within an OpenTelemetry span, recording status and exceptions.
84
95
 
85
96
  ## Type Parameters
86
97
 
87
- | Type Parameter |
88
- | ------ |
89
- | `T` |
98
+ ### T
99
+
100
+ `T`
90
101
 
91
102
  ## Parameters
92
103
 
93
- | Parameter | Type | Description |
94
- | ------ | ------ | ------ |
95
- | `name` | `string` | The span name. |
96
- | `fn` | () => `T` | The function to execute. |
97
- | `tracer?` | `Tracer` | Optional tracer to use. |
104
+ ### name
105
+
106
+ `string`
107
+
108
+ The span name.
109
+
110
+ ### fn
111
+
112
+ () => `T`
113
+
114
+ The function to execute.
115
+
116
+ ### traceProvider?
117
+
118
+ `TracerProvider` = `TRACE_API`
98
119
 
99
120
  ## Returns
100
121
 
@@ -102,7 +123,7 @@ Executes a synchronous function within an OpenTelemetry span, recording status a
102
123
 
103
124
  The return value of `fn`.
104
125
 
105
- ### <a id="spanAsync"></a>spanAsync
126
+ ### <a id="spanAsync"></a>spanAsync
106
127
 
107
128
  [**@xylabs/telemetry**](#../README)
108
129
 
@@ -110,26 +131,38 @@ The return value of `fn`.
110
131
 
111
132
  ```ts
112
133
  function spanAsync<T>(
113
- name: string,
114
- fn: () => Promise<T>,
115
- config?: SpanConfig): Promise<T>;
134
+ name,
135
+ fn,
136
+ config?): Promise<T>;
116
137
  ```
117
138
 
118
139
  Executes an async function within an OpenTelemetry span, with optional time budget monitoring.
119
140
 
120
141
  ## Type Parameters
121
142
 
122
- | Type Parameter |
123
- | ------ |
124
- | `T` |
143
+ ### T
144
+
145
+ `T`
125
146
 
126
147
  ## Parameters
127
148
 
128
- | Parameter | Type | Description |
129
- | ------ | ------ | ------ |
130
- | `name` | `string` | The span name. |
131
- | `fn` | () => `Promise`\<`T`\> | The async function to execute. |
132
- | `config` | [`SpanConfig`](#../interfaces/SpanConfig) | Optional span configuration (tracer, logger, time budget). |
149
+ ### name
150
+
151
+ `string`
152
+
153
+ The span name.
154
+
155
+ ### fn
156
+
157
+ () => `Promise`\<`T`\>
158
+
159
+ The async function to execute.
160
+
161
+ ### config?
162
+
163
+ [`SpanConfig`](#../interfaces/SpanConfig) = `{}`
164
+
165
+ Optional span configuration (tracer, logger, time budget).
133
166
 
134
167
  ## Returns
135
168
 
@@ -137,7 +170,7 @@ Executes an async function within an OpenTelemetry span, with optional time budg
137
170
 
138
171
  The resolved value of `fn`.
139
172
 
140
- ### <a id="spanRoot"></a>spanRoot
173
+ ### <a id="spanRoot"></a>spanRoot
141
174
 
142
175
  [**@xylabs/telemetry**](#../README)
143
176
 
@@ -145,26 +178,38 @@ The resolved value of `fn`.
145
178
 
146
179
  ```ts
147
180
  function spanRoot<T>(
148
- name: string,
149
- fn: () => T,
150
- tracer?: Tracer): T;
181
+ name,
182
+ fn,
183
+ tracer?): T;
151
184
  ```
152
185
 
153
186
  Executes a synchronous function within a new root span that has no parent, even if a span is already active.
154
187
 
155
188
  ## Type Parameters
156
189
 
157
- | Type Parameter |
158
- | ------ |
159
- | `T` |
190
+ ### T
191
+
192
+ `T`
160
193
 
161
194
  ## Parameters
162
195
 
163
- | Parameter | Type | Description |
164
- | ------ | ------ | ------ |
165
- | `name` | `string` | The span name. |
166
- | `fn` | () => `T` | The function to execute. |
167
- | `tracer?` | `Tracer` | Optional tracer to use. |
196
+ ### name
197
+
198
+ `string`
199
+
200
+ The span name.
201
+
202
+ ### fn
203
+
204
+ () => `T`
205
+
206
+ The function to execute.
207
+
208
+ ### tracer?
209
+
210
+ `Tracer`
211
+
212
+ Optional tracer to use.
168
213
 
169
214
  ## Returns
170
215
 
@@ -172,7 +217,7 @@ Executes a synchronous function within a new root span that has no parent, even
172
217
 
173
218
  The return value of `fn`.
174
219
 
175
- ### <a id="spanRootAsync"></a>spanRootAsync
220
+ ### <a id="spanRootAsync"></a>spanRootAsync
176
221
 
177
222
  [**@xylabs/telemetry**](#../README)
178
223
 
@@ -180,26 +225,38 @@ The return value of `fn`.
180
225
 
181
226
  ```ts
182
227
  function spanRootAsync<T>(
183
- name: string,
184
- fn: () => Promise<T>,
185
- config?: SpanConfig): Promise<T>;
228
+ name,
229
+ fn,
230
+ config?): Promise<T>;
186
231
  ```
187
232
 
188
233
  Executes an async function within a new root span (no parent), with optional time budget monitoring.
189
234
 
190
235
  ## Type Parameters
191
236
 
192
- | Type Parameter |
193
- | ------ |
194
- | `T` |
237
+ ### T
238
+
239
+ `T`
195
240
 
196
241
  ## Parameters
197
242
 
198
- | Parameter | Type | Description |
199
- | ------ | ------ | ------ |
200
- | `name` | `string` | The span name. |
201
- | `fn` | () => `Promise`\<`T`\> | The async function to execute. |
202
- | `config` | [`SpanConfig`](#../interfaces/SpanConfig) | Optional span configuration (tracer, logger, time budget). |
243
+ ### name
244
+
245
+ `string`
246
+
247
+ The span name.
248
+
249
+ ### fn
250
+
251
+ () => `Promise`\<`T`\>
252
+
253
+ The async function to execute.
254
+
255
+ ### config?
256
+
257
+ [`SpanConfig`](#../interfaces/SpanConfig) = `{}`
258
+
259
+ Optional span configuration (tracer, logger, time budget).
203
260
 
204
261
  ## Returns
205
262
 
@@ -207,7 +264,7 @@ Executes an async function within a new root span (no parent), with optional tim
207
264
 
208
265
  The resolved value of `fn`.
209
266
 
210
- ### <a id="timeBudget"></a>timeBudget
267
+ ### <a id="timeBudget"></a>timeBudget
211
268
 
212
269
  [**@xylabs/telemetry**](#../README)
213
270
 
@@ -215,30 +272,52 @@ The resolved value of `fn`.
215
272
 
216
273
  ```ts
217
274
  function timeBudget<TResult>(
218
- name: string,
219
- logger: Logger | undefined,
220
- func: () => Promise<TResult>,
221
- budget: number,
222
- status?: boolean): Promise<TResult>;
275
+ name,
276
+ logger,
277
+ func,
278
+ budget,
279
+ status?): Promise<TResult>;
223
280
  ```
224
281
 
225
282
  Executes an async function and logs a warning if it exceeds the given time budget.
226
283
 
227
284
  ## Type Parameters
228
285
 
229
- | Type Parameter |
230
- | ------ |
231
- | `TResult` |
286
+ ### TResult
287
+
288
+ `TResult`
232
289
 
233
290
  ## Parameters
234
291
 
235
- | Parameter | Type | Default value | Description |
236
- | ------ | ------ | ------ | ------ |
237
- | `name` | `string` | `undefined` | A label for the function, used in warning messages. |
238
- | `logger` | `Logger` \| `undefined` | `undefined` | The logger to use for budget-exceeded warnings. |
239
- | `func` | () => `Promise`\<`TResult`\> | `undefined` | The async function to execute. |
240
- | `budget` | `number` | `undefined` | The time budget in milliseconds. |
241
- | `status` | `boolean` | `false` | If true, logs periodic warnings while the function is still running. |
292
+ ### name
293
+
294
+ `string`
295
+
296
+ A label for the function, used in warning messages.
297
+
298
+ ### logger
299
+
300
+ `Logger` \| `undefined`
301
+
302
+ The logger to use for budget-exceeded warnings.
303
+
304
+ ### func
305
+
306
+ () => `Promise`\<`TResult`\>
307
+
308
+ The async function to execute.
309
+
310
+ ### budget
311
+
312
+ `number`
313
+
314
+ The time budget in milliseconds.
315
+
316
+ ### status?
317
+
318
+ `boolean` = `false`
319
+
320
+ If true, logs periodic warnings while the function is still running.
242
321
 
243
322
  ## Returns
244
323
 
@@ -246,9 +325,9 @@ Executes an async function and logs a warning if it exceeds the given time budge
246
325
 
247
326
  The result of the executed function.
248
327
 
249
- ### interfaces
328
+ ### interfaces
250
329
 
251
- ### <a id="SpanConfig"></a>SpanConfig
330
+ ### <a id="SpanConfig"></a>SpanConfig
252
331
 
253
332
  [**@xylabs/telemetry**](#../README)
254
333
 
@@ -258,48 +337,36 @@ Configuration options for span creation and execution.
258
337
 
259
338
  ## Properties
260
339
 
261
- | Property | Type | Description |
262
- | ------ | ------ | ------ |
263
- | <a id="logger"></a> `logger?` | `Logger` \| `null` | Optional logger for time budget warnings. Falls back to console if not provided. |
264
- | <a id="timebudgetlimit"></a> `timeBudgetLimit?` | `number` | Maximum allowed execution time in milliseconds before logging a warning. |
265
- | <a id="tracer"></a> `tracer?` | `Tracer` | OpenTelemetry tracer to use. Defaults to a tracer named after the span. |
340
+ ### logger?
266
341
 
342
+ ```ts
343
+ optional logger?: Logger | null;
344
+ ```
267
345
 
268
- Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
346
+ Optional logger for time budget warnings. Falls back to console if not provided.
269
347
 
270
- ## Maintainers
348
+ ***
271
349
 
272
- - [Arie Trouw](https://github.com/arietrouw) ([arietrouw.com](https://arietrouw.com))
273
- - [Matt Jones](https://github.com/jonesmac)
274
- - [Joel Carter](https://github.com/JoelBCarter)
275
- - [Jordan Trouw](https://github.com/jordantrouw)
350
+ ### timeBudgetLimit?
276
351
 
277
- ## License
278
-
279
- > See the [LICENSE](LICENSE) file for license details
352
+ ```ts
353
+ optional timeBudgetLimit?: number;
354
+ ```
280
355
 
281
- ## Credits
356
+ Maximum allowed execution time in milliseconds before logging a warning.
282
357
 
283
- [Made with 🔥 and ❄️ by XYLabs](https://xylabs.com)
358
+ ***
284
359
 
285
- [logo]: https://cdn.xy.company/img/brand/XYPersistentCompany_Logo_Icon_Colored.svg
360
+ ### tracer?
286
361
 
287
- [main-build]: https://github.com/xylabs/sdk-js/actions/workflows/build.yml/badge.svg
288
- [main-build-link]: https://github.com/xylabs/sdk-js/actions/workflows/build.yml
289
- [npm-badge]: https://img.shields.io/npm/v/@xylabs/telemetry.svg
290
- [npm-link]: https://www.npmjs.com/package/@xylabs/telemetry
291
- [codacy-badge]: https://app.codacy.com/project/badge/Grade/c8e15e14f37741c18cfb47ac7245c698
292
- [codacy-link]: https://www.codacy.com/gh/xylabs/sdk-js/dashboard?utm_source=github.com&utm_medium=referral&utm_content=xylabs/sdk-js&utm_campaign=Badge_Grade
293
- [codeclimate-badge]: https://api.codeclimate.com/v1/badges/c5eb068f806f0b047ea7/maintainability
294
- [codeclimate-link]: https://codeclimate.com/github/xylabs/sdk-js/maintainability
295
- [snyk-badge]: https://snyk.io/test/github/xylabs/sdk-js/badge.svg?targetFile=package.json
296
- [snyk-link]: https://snyk.io/test/github/xylabs/sdk-js?targetFile=package.json
362
+ ```ts
363
+ optional tracer?: Tracer;
364
+ ```
297
365
 
298
- [npm-downloads-badge]: https://img.shields.io/npm/dw/@xylabs/telemetry
299
- [npm-license-badge]: https://img.shields.io/npm/l/@xylabs/telemetry
366
+ OpenTelemetry tracer to use. Defaults to a tracer named after the span.
300
367
 
301
- [jsdelivr-badge]: https://data.jsdelivr.com/v1/package/npm/@xylabs/telemetry/badge
302
- [jsdelivr-link]: https://www.jsdelivr.com/package/npm/@xylabs/telemetry
303
368
 
304
- [socket-badge]: https://socket.dev/api/badge/npm/package/@xylabs/telemetry
305
- [socket-link]: https://socket.dev/npm/package/@xylabs/telemetry
369
+ [npm-badge]: https://img.shields.io/npm/v/@xylabs/telemetry.svg
370
+ [npm-link]: https://www.npmjs.com/package/@xylabs/telemetry
371
+ [license-badge]: https://img.shields.io/npm/l/@xylabs/telemetry.svg
372
+ [license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xylabs/telemetry",
3
- "version": "5.0.95",
3
+ "version": "5.0.97",
4
4
  "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
5
5
  "keywords": [
6
6
  "hex",
@@ -29,12 +29,10 @@
29
29
  "exports": {
30
30
  ".": {
31
31
  "types": "./dist/neutral/index.d.ts",
32
- "import": "./dist/neutral/index.mjs",
33
32
  "default": "./dist/neutral/index.mjs"
34
33
  },
35
34
  "./package.json": "./package.json"
36
35
  },
37
- "types": "./dist/neutral/index.d.ts",
38
36
  "files": [
39
37
  "dist",
40
38
  "!**/*.bench.*",
@@ -44,18 +42,17 @@
44
42
  ],
45
43
  "dependencies": {
46
44
  "@opentelemetry/api": "^1.9.1",
47
- "@xylabs/typeof": "~5.0.95",
48
- "@xylabs/logger": "~5.0.95"
45
+ "@xylabs/logger": "~5.0.97",
46
+ "@xylabs/typeof": "~5.0.97"
49
47
  },
50
48
  "devDependencies": {
51
- "@types/node": "^25.5.2",
52
- "@xylabs/ts-scripts-common": "~7.8.4",
53
- "@xylabs/ts-scripts-pnpm": "~7.8.4",
54
- "@xylabs/tsconfig": "~7.8.4",
49
+ "@types/node": "^25.6.0",
50
+ "@xylabs/toolchain": "~7.10.4",
51
+ "@xylabs/tsconfig": "~7.10.4",
55
52
  "esbuild": "^0.28.0",
56
53
  "typescript": "^5",
57
- "vite": "^8.0.5",
58
- "vitest": "^4.1.2"
54
+ "vite": "^8.0.8",
55
+ "vitest": "^4.1.4"
59
56
  },
60
57
  "engines": {
61
58
  "node": ">=18"