@lokalise/opentelemetry-fastify-bootstrap 1.1.0

package/LICENSE.md

@@ -0,0 +1,13 @@
+Copyright 2024 Lokalise, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,77 @@
+# OpenTelemetry Fastify Bootstrap
+
+This package provides a pre-configured OpenTelemetry setup for Fastify applications with automatic instrumentation.
+
+**Important:** OpenTelemetry must be initialized before importing any modules you want to instrument (fastify, http, etc.), because it works by patching module exports at import time. This requires using dynamic imports to control the loading order.
+
+## Installation
+
+```bash
+npm install @lokalise/opentelemetry-fastify-bootstrap
+```
+
+## Usage
+
+Your application entry point must use dynamic `await import()` to ensure OpenTelemetry initializes before other modules are loaded:
+
+```ts
+// index.ts (entry point)
+
+// This MUST be first - initializes OpenTelemetry before anything else
+const { initOpenTelemetry } = await import('@lokalise/opentelemetry-fastify-bootstrap')
+initOpenTelemetry({
+  skippedPaths: ['/health', '/ready', '/live', '/metrics', '/'],
+})
+
+// Now dynamically import your actual server code
+const server = await import('./server.ts')
+await server.start()
+```
+
+**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.
+
+### Using defaults
+
+If you don't need custom skipped paths:
+
+```ts
+const { initOpenTelemetry } = await import('@lokalise/opentelemetry-fastify-bootstrap')
+initOpenTelemetry()
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NODE_ENV` | When set to `test`, OpenTelemetry is disabled | - |
+| `OPEN_TELEMETRY_ENABLED` | Set to `true` to enable OpenTelemetry | `false` |
+| `OPEN_TELEMETRY_EXPORTER_URL` | OTLP gRPC exporter URL | `grpc://localhost:4317` |
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `skippedPaths` | `string[]` | `['/health', '/metrics', '/']` | Paths to exclude from tracing |
+
+## Features
+
+- Automatic instrumentation for Node.js applications via `@opentelemetry/auto-instrumentations-node`
+- Fastify-specific instrumentation via `@fastify/otel`
+- OTLP gRPC trace exporter
+- Configurable path filtering
+- Graceful shutdown support
+
+## Graceful Shutdown
+
+To properly shutdown the OpenTelemetry SDK when your application exits:
+
+```ts
+import { gracefulOtelShutdown } from '@lokalise/opentelemetry-fastify-bootstrap'
+
+process.on('SIGTERM', async () => {
+  await gracefulOtelShutdown()
+  process.exit(0)
+})
+```

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export interface OpenTelemetryOptions {
+    /**
+     * Paths to exclude from tracing.
+     * @default ['/health', '/metrics', '/']
+     */
+    skippedPaths?: string[];
+}
+/**
+ * Initialize OpenTelemetry instrumentation.
+ *
+ * IMPORTANT: This function must be called BEFORE importing any other modules
+ * that you want to instrument (fastify, http, etc.).
+ *
+ * @example
+ * ```ts
+ * // At the very top of your entry point
+ * import { initOpenTelemetry } from '@lokalise/opentelemetry-fastify-bootstrap'
+ * initOpenTelemetry({ skippedPaths: ['/health', '/ready', '/live'] })
+ *
+ * // Only import other modules AFTER initialization
+ * import fastify from 'fastify'
+ * ```
+ */
+export declare function initOpenTelemetry(options?: OpenTelemetryOptions): void;
+export declare function gracefulOtelShutdown(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,124 @@
+import { FastifyOtelInstrumentation } from '@fastify/otel';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter as OTLPTraceExporterGrpc } from '@opentelemetry/exporter-trace-otlp-grpc';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+function createLogEntry(level, msg, data) {
+    return {
+        level,
+        time: Date.now(),
+        ...data,
+        msg,
+    };
+}
+function log(level, msgOrData, msg) {
+    let logEntry;
+    if (typeof msgOrData === 'string') {
+        logEntry = createLogEntry(level, msgOrData);
+    }
+    else {
+        logEntry = createLogEntry(level, msg ?? '', msgOrData);
+    }
+    const output = JSON.stringify(logEntry);
+    if (level === 'error') {
+        // biome-ignore lint/suspicious/noConsole: this is the logger implementation
+        console.error(output);
+    }
+    else if (level === 'warn') {
+        // biome-ignore lint/suspicious/noConsole: this is the logger implementation
+        console.warn(output);
+    }
+    else {
+        // biome-ignore lint/suspicious/noConsole: this is the logger implementation
+        console.log(output);
+    }
+}
+const logger = {
+    info: (msgOrData, msg) => log('info', msgOrData, msg),
+    error: (msgOrData, msg) => log('error', msgOrData, msg),
+    warn: (msgOrData, msg) => log('warn', msgOrData, msg),
+    debug: (msgOrData, msg) => log('debug', msgOrData, msg),
+};
+const DEFAULT_SKIPPED_PATHS = ['/health', '/metrics', '/'];
+let isInstrumentationRegistered = false;
+let sdk;
+/**
+ * Initialize OpenTelemetry instrumentation.
+ *
+ * IMPORTANT: This function must be called BEFORE importing any other modules
+ * that you want to instrument (fastify, http, etc.).
+ *
+ * @example
+ * ```ts
+ * // At the very top of your entry point
+ * import { initOpenTelemetry } from '@lokalise/opentelemetry-fastify-bootstrap'
+ * initOpenTelemetry({ skippedPaths: ['/health', '/ready', '/live'] })
+ *
+ * // Only import other modules AFTER initialization
+ * import fastify from 'fastify'
+ * ```
+ */
+export function initOpenTelemetry(options = {}) {
+    const { skippedPaths = DEFAULT_SKIPPED_PATHS } = options;
+    logger.info('[OTEL] initOpenTelemetry called');
+    const isOpenTelemetryEnabled = process.env.NODE_ENV !== 'test' && process.env.OPEN_TELEMETRY_ENABLED?.toLowerCase() === 'true';
+    logger.info({
+        nodeEnv: process.env.NODE_ENV,
+        openTelemetryEnabled: process.env.OPEN_TELEMETRY_ENABLED,
+        isOpenTelemetryEnabled,
+        skippedPaths,
+    }, '[OTEL] Configuration');
+    if (isOpenTelemetryEnabled && !isInstrumentationRegistered) {
+        logger.info('[OTEL] Initializing OpenTelemetry SDK...');
+        // Configure the OTLP trace exporter
+        const exporterUrl = process.env.OPEN_TELEMETRY_EXPORTER_URL || 'grpc://localhost:4317';
+        logger.info({ exporterUrl }, '[OTEL] Configuring trace exporter');
+        const traceExporter = new OTLPTraceExporterGrpc({
+            // optional - url default value is http://localhost:4318/v1/traces (http)
+            // or grpc://localhost:4317/opentelemetry.proto.collector.trace.v1.TraceService/Export (grpc)
+            url: exporterUrl,
+        });
+        // Setup SDK
+        sdk = new NodeSDK({
+            traceExporter,
+            instrumentations: [
+                getNodeAutoInstrumentations({
+                    '@opentelemetry/instrumentation-fastify': {
+                        enabled: false,
+                    },
+                }),
+                new FastifyOtelInstrumentation({
+                    registerOnInitialization: true,
+                    ignorePaths: (req) => {
+                        if (!req.url)
+                            return false;
+                        // Extract path without query string, normalize empty to '/'
+                        const path = req.url.split('?')[0] || '/';
+                        return skippedPaths.includes(path);
+                    },
+                }),
+            ],
+        });
+        sdk.start();
+        isInstrumentationRegistered = true;
+        logger.info('[OTEL] SDK started successfully - ready to send traces');
+    }
+    else {
+        logger.info('[OTEL] OpenTelemetry is disabled or already registered');
+    }
+}
+export async function gracefulOtelShutdown() {
+    logger.info('[OTEL] Shutdown requested');
+    if (!sdk) {
+        logger.info('[OTEL] No SDK instance to shutdown');
+        return;
+    }
+    try {
+        await sdk.shutdown();
+        isInstrumentationRegistered = false;
+        logger.info('[OTEL] SDK shutdown completed successfully');
+    }
+    catch (error) {
+        logger.error({ error }, '[OTEL] Error during SDK shutdown');
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+    "name": "@lokalise/opentelemetry-fastify-bootstrap",
+    "version": "1.1.0",
+    "type": "module",
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE.md"
+    ],
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": "./dist/index.js",
+        "./package.json": "./package.json"
+    },
+    "keywords": [
+        "opentelemetry",
+        "otel",
+        "fastify",
+        "tracing",
+        "instrumentation",
+        "bootstrap"
+    ],
+    "homepage": "https://github.com/lokalise/shared-ts-libs",
+    "repository": {
+        "type": "git",
+        "url": "git://github.com/lokalise/shared-ts-libs.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "rimraf dist && tsc --project tsconfig.build.json",
+        "lint": "biome check . && tsc",
+        "lint:fix": "biome check --write",
+        "prepublishOnly": "npm run build",
+        "package-version": "echo $npm_package_version",
+        "postversion": "biome check --write package.json"
+    },
+    "dependencies": {},
+    "peerDependencies": {
+        "fastify": ">=5.0.0",
+        "@fastify/otel": ">=0.16.0",
+        "@opentelemetry/auto-instrumentations-node": ">=0.67.3",
+        "@opentelemetry/exporter-trace-otlp-grpc": ">=0.208.0",
+        "@opentelemetry/sdk-node": ">=0.208.0"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.3.7",
+        "@lokalise/biome-config": "^3.1.0",
+        "@lokalise/tsconfig": "~1.2.0",
+        "rimraf": "^6.1.2",
+        "typescript": "5.9.3"
+    }
+}