@lokalise/opentelemetry-fastify-bootstrap 2.1.0 → 2.1.2
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/README.md +29 -18
- package/dist/index.d.ts +8 -6
- package/dist/index.js +14 -11
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,7 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
This package provides a pre-configured OpenTelemetry setup for Fastify applications with automatic instrumentation.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
Your application **must** be started with the `--import=@opentelemetry/instrumentation/hook.mjs` Node.js flag. This flag registers the OpenTelemetry instrumentation hook before any application code runs, enabling automatic patching of all imported modules.
|
|
8
|
+
|
|
9
|
+
In your Dockerfile:
|
|
10
|
+
|
|
11
|
+
```dockerfile
|
|
12
|
+
CMD ["dumb-init", "node", "--import=@opentelemetry/instrumentation/hook.mjs", "/home/node/app/server.js"]
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
When the `--import` hook is used, strict import sequencing is **not** required — you can use regular static imports in your application code. This is the recommended approach for performance reasons, as dynamic imports can cause significantly slower module loading (synchronous module resolution can add 20+ seconds to startup in large applications).
|
|
6
16
|
|
|
7
17
|
## Installation
|
|
8
18
|
|
|
@@ -12,30 +22,30 @@ npm install @lokalise/opentelemetry-fastify-bootstrap
|
|
|
12
22
|
|
|
13
23
|
## Usage
|
|
14
24
|
|
|
15
|
-
|
|
25
|
+
With the `--import` hook in place, use regular static imports and call `initOpenTelemetry` before starting your server:
|
|
16
26
|
|
|
17
27
|
```ts
|
|
18
|
-
//
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
28
|
+
// server.ts (entry point)
|
|
29
|
+
import { initOpenTelemetry } from '@lokalise/opentelemetry-fastify-bootstrap'
|
|
30
|
+
import { startServer } from './serverInternal.ts'
|
|
31
|
+
|
|
32
|
+
// Call this before starting the server
|
|
33
|
+
if (process.env.OTEL_ENABLED !== 'false') {
|
|
34
|
+
initOpenTelemetry({
|
|
35
|
+
skippedPaths: ['/health', '/ready', '/live', '/metrics', '/'],
|
|
36
|
+
})
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
await startServer()
|
|
29
40
|
```
|
|
30
41
|
|
|
31
|
-
**Why dynamic imports?** Static imports in ESM are hoisted and resolved together before any code executes. Dynamic `await import()` ensures sequential loading - the package fully initializes before server.ts is even parsed.
|
|
32
|
-
|
|
33
42
|
### Using defaults
|
|
34
43
|
|
|
35
44
|
If you don't need custom skipped paths:
|
|
36
45
|
|
|
37
46
|
```ts
|
|
38
|
-
|
|
47
|
+
import { initOpenTelemetry } from '@lokalise/opentelemetry-fastify-bootstrap'
|
|
48
|
+
|
|
39
49
|
initOpenTelemetry()
|
|
40
50
|
```
|
|
41
51
|
|
|
@@ -62,7 +72,8 @@ initOpenTelemetry()
|
|
|
62
72
|
For local development and debugging, you can enable console span output to see traces printed directly to the console:
|
|
63
73
|
|
|
64
74
|
```ts
|
|
65
|
-
|
|
75
|
+
import { initOpenTelemetry } from '@lokalise/opentelemetry-fastify-bootstrap'
|
|
76
|
+
|
|
66
77
|
initOpenTelemetry({
|
|
67
78
|
consoleSpans: true, // Prints spans to console for debugging
|
|
68
79
|
})
|
|
@@ -78,8 +89,8 @@ Multiple span processors work alongside the OTLP exporter and optional console s
|
|
|
78
89
|
|
|
79
90
|
```ts
|
|
80
91
|
import { MyCustomSpanProcessor } from './custom-processor'
|
|
92
|
+
import { initOpenTelemetry } from '@lokalise/opentelemetry-fastify-bootstrap'
|
|
81
93
|
|
|
82
|
-
const { initOpenTelemetry } = await import('@lokalise/opentelemetry-fastify-bootstrap')
|
|
83
94
|
initOpenTelemetry({
|
|
84
95
|
consoleSpans: true, // Enable console debugging
|
|
85
96
|
spanProcessors: [
|
package/dist/index.d.ts
CHANGED
|
@@ -19,17 +19,19 @@ export interface OpenTelemetryOptions {
|
|
|
19
19
|
/**
|
|
20
20
|
* Initialize OpenTelemetry instrumentation.
|
|
21
21
|
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
22
|
+
* The application must be started with the `--import=@opentelemetry/instrumentation/hook.mjs`
|
|
23
|
+
* Node.js flag to enable automatic module patching. When using this flag, strict import
|
|
24
|
+
* sequencing is not required — regular static imports are recommended for better performance.
|
|
25
|
+
*
|
|
26
|
+
* Call this function before starting the server.
|
|
24
27
|
*
|
|
25
28
|
* @example
|
|
26
29
|
* ```ts
|
|
27
|
-
* // At the very top of your entry point
|
|
28
30
|
* import { initOpenTelemetry } from '@lokalise/opentelemetry-fastify-bootstrap'
|
|
29
|
-
*
|
|
31
|
+
* import { startServer } from './serverInternal.ts'
|
|
30
32
|
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
+
* initOpenTelemetry({ skippedPaths: ['/health', '/ready', '/live'] })
|
|
34
|
+
* await startServer()
|
|
33
35
|
* ```
|
|
34
36
|
*/
|
|
35
37
|
export declare function initOpenTelemetry(options?: OpenTelemetryOptions): void;
|
package/dist/index.js
CHANGED
|
@@ -2,7 +2,7 @@ import { FastifyOtelInstrumentation } from '@fastify/otel';
|
|
|
2
2
|
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
|
|
3
3
|
import { OTLPTraceExporter as OTLPTraceExporterGrpc } from '@opentelemetry/exporter-trace-otlp-grpc';
|
|
4
4
|
import { NodeSDK } from '@opentelemetry/sdk-node';
|
|
5
|
-
import { ConsoleSpanExporter, SimpleSpanProcessor, } from '@opentelemetry/sdk-trace-base';
|
|
5
|
+
import { BatchSpanProcessor, ConsoleSpanExporter, SimpleSpanProcessor, } from '@opentelemetry/sdk-trace-base';
|
|
6
6
|
function createLogEntry(level, msg, data) {
|
|
7
7
|
return {
|
|
8
8
|
level,
|
|
@@ -45,17 +45,19 @@ let sdk;
|
|
|
45
45
|
/**
|
|
46
46
|
* Initialize OpenTelemetry instrumentation.
|
|
47
47
|
*
|
|
48
|
-
*
|
|
49
|
-
*
|
|
48
|
+
* The application must be started with the `--import=@opentelemetry/instrumentation/hook.mjs`
|
|
49
|
+
* Node.js flag to enable automatic module patching. When using this flag, strict import
|
|
50
|
+
* sequencing is not required — regular static imports are recommended for better performance.
|
|
51
|
+
*
|
|
52
|
+
* Call this function before starting the server.
|
|
50
53
|
*
|
|
51
54
|
* @example
|
|
52
55
|
* ```ts
|
|
53
|
-
* // At the very top of your entry point
|
|
54
56
|
* import { initOpenTelemetry } from '@lokalise/opentelemetry-fastify-bootstrap'
|
|
55
|
-
*
|
|
57
|
+
* import { startServer } from './serverInternal.ts'
|
|
56
58
|
*
|
|
57
|
-
*
|
|
58
|
-
*
|
|
59
|
+
* initOpenTelemetry({ skippedPaths: ['/health', '/ready', '/live'] })
|
|
60
|
+
* await startServer()
|
|
59
61
|
* ```
|
|
60
62
|
*/
|
|
61
63
|
export function initOpenTelemetry(options = {}) {
|
|
@@ -80,15 +82,16 @@ export function initOpenTelemetry(options = {}) {
|
|
|
80
82
|
// or grpc://localhost:4317/opentelemetry.proto.collector.trace.v1.TraceService/Export (grpc)
|
|
81
83
|
url: exporterUrl,
|
|
82
84
|
});
|
|
83
|
-
|
|
84
|
-
|
|
85
|
+
const allSpanProcessors = [
|
|
86
|
+
new BatchSpanProcessor(traceExporter),
|
|
87
|
+
...spanProcessors,
|
|
88
|
+
];
|
|
85
89
|
if (consoleSpans) {
|
|
86
90
|
allSpanProcessors.push(new SimpleSpanProcessor(new ConsoleSpanExporter()));
|
|
87
91
|
}
|
|
88
92
|
// Setup SDK
|
|
89
93
|
sdk = new NodeSDK({
|
|
90
|
-
|
|
91
|
-
spanProcessors: allSpanProcessors.length > 0 ? allSpanProcessors : undefined,
|
|
94
|
+
spanProcessors: allSpanProcessors,
|
|
92
95
|
instrumentations: [
|
|
93
96
|
getNodeAutoInstrumentations({
|
|
94
97
|
'@opentelemetry/instrumentation-fastify': {
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAE,2BAA2B,EAAE,MAAM,2CAA2C,CAAA;AACvF,OAAO,EAAE,iBAAiB,IAAI,qBAAqB,EAAE,MAAM,yCAAyC,CAAA;AACpG,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AACjD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,GAEpB,MAAM,+BAA+B,CAAA;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|