@devopsplaybook.io/otel-utils-fastify 0.0.1-beta1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 devopsplaybook.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# otel-utils-fastify

package/index.ts

@@ -0,0 +1,7 @@
+// Entry point for the otel-utils npm package
+// Export all modules from src
+
+export * from "./src/Logger";
+export * from "./src/StandardMeter";
+export * from "./src/StandardTracer";
+export * from "./src/models/ConfigInterfaceOTel";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@devopsplaybook.io/otel-utils-fastify",
+  "version": "0.0.1-beta1",
+  "description": "Utility to simplify integration with Open Telemetry for Fastify API Server",
+  "keywords": [
+    "Open",
+    "Telemetry",
+    "Traces",
+    "Logs",
+    "Metrics"
+  ],
+  "license": "ISC",
+  "author": "",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "fastify": "^5.5.0",
+    "@devopsplaybook.io/otel-utils": "1.0.1-beta3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "@types/sqlite3": "^5.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Logger.ts

@@ -0,0 +1,120 @@
+import type { Logger as OTelLogger } from "@opentelemetry/api-logs";
+import { SeverityNumber } from "@opentelemetry/api-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+  BatchLogRecordProcessor,
+  LoggerProvider,
+} from "@opentelemetry/sdk-logs";
+import { Span } from "@opentelemetry/sdk-trace-base";
+import {
+  ATTR_NETWORK_LOCAL_ADDRESS,
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+} from "@opentelemetry/semantic-conventions";
+import * as os from "os";
+import { ConfigInterfaceOTel } from "./models/ConfigInterfaceOTel";
+import { StandardTracerStartSpan } from "./StandardTracer";
+
+let loggerOTel: OTelLogger;
+
+export function LoggerInit(context: Span, config: ConfigInterfaceOTel) {
+  const span = StandardTracerStartSpan("LoggerInit", context);
+
+  if (config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS) {
+    const exporterHeaders: Record<string, string> = {};
+    if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
+      exporterHeaders[
+        "Authorization"
+      ] = `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
+    }
+    const exporter = new OTLPLogExporter({
+      url: config.OPENTELEMETRY_COLLECTOR_HTTP_LOGS,
+      headers: exporterHeaders,
+    });
+
+    const loggerProvider = new LoggerProvider({
+      processors: [
+        new BatchLogRecordProcessor(exporter, {
+          maxQueueSize: 100,
+          scheduledDelayMillis:
+            config.OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS * 1000,
+        }),
+      ],
+      resource: resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: `${config.SERVICE_ID}`,
+        [ATTR_SERVICE_VERSION]: `${config.VERSION}`,
+        [ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
+      }),
+    });
+
+    loggerOTel = loggerProvider.getLogger(
+      `${config.SERVICE_ID}:${config.VERSION}`
+    );
+  }
+  span.end();
+}
+
+const DEV_MODE = (() => {
+  if (process.env.NODE_ENV === "dev") {
+    return true;
+  }
+  return false;
+})();
+
+export class Logger {
+  private module: string;
+
+  constructor(module: string) {
+    this.module = `${module}`;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public debug(message: Error | string | any): void {
+    if (DEV_MODE) {
+      this.display("debug", message, SeverityNumber.DEBUG);
+    }
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public info(message: Error | string | any): void {
+    this.display("info", message, SeverityNumber.WARN);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public warn(message: Error | string | any): void {
+    this.display("warn", message, SeverityNumber.WARN);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public error(message: Error | string | any): void {
+    this.display("error", message, SeverityNumber.ERROR);
+  }
+
+  private display(
+    level: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    message: any,
+    severityNumber = SeverityNumber.INFO
+  ): void {
+    if (typeof message === "string") {
+      // eslint:disable-next-line:no-console
+      console.log(`[${level}] [${this.module}] ${message}`);
+    } else if (message instanceof Error) {
+      // eslint:disable-next-line:no-console
+      console.log(`${level} [${this.module}] ${message}`);
+      // eslint:disable-next-line:no-console
+      console.log((message as Error).stack);
+    } else if (typeof message === "object") {
+      // eslint:disable-next-line:no-console
+      console.log(`${level} [${this.module}] ${JSON.stringify(message)}`);
+    }
+    if (loggerOTel) {
+      {
+        loggerOTel.emit({
+          severityNumber,
+          severityText: level,
+          body: message,
+          attributes: { "log.type": "custom" },
+        });
+      }
+    }
+  }
+}

package/src/StandardMeter.ts

@@ -0,0 +1,91 @@
+import { Counter, Histogram, ObservableGauge } from "@opentelemetry/api";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+  MeterProvider,
+  PeriodicExportingMetricReader,
+} from "@opentelemetry/sdk-metrics";
+import {
+  ATTR_NETWORK_LOCAL_ADDRESS,
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+} from "@opentelemetry/semantic-conventions";
+import * as os from "os";
+import { ConfigInterfaceOTel } from "./models/ConfigInterfaceOTel";
+
+let meterProvider: MeterProvider;
+let config: ConfigInterfaceOTel;
+const METER_NAME = "default";
+
+//
+export function StandardMeterInitTelemetry(initConfig: ConfigInterfaceOTel) {
+  config = initConfig;
+
+  // Metrics
+  if (config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS) {
+    const collectorOptions = {
+      url: config.OPENTELEMETRY_COLLECTOR_HTTP_METRICS,
+      headers: {} as Record<string, string>,
+      concurrencyLimit: 1,
+    };
+    if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
+      collectorOptions.headers[
+        "Authorization"
+      ] = `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
+    }
+    const metricExporter = new OTLPMetricExporter(collectorOptions);
+    meterProvider = new MeterProvider({
+      resource: resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: `${config.SERVICE_ID}`,
+        [ATTR_SERVICE_VERSION]: `${config.VERSION}`,
+        [ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
+      }),
+      readers: [
+        new PeriodicExportingMetricReader({
+          exporter: metricExporter,
+          exportIntervalMillis:
+            config.OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS *
+            1000,
+        }),
+      ],
+    });
+  } else {
+    meterProvider = new MeterProvider({
+      resource: resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: `${config.SERVICE_ID}`,
+        [ATTR_SERVICE_VERSION]: `${config.VERSION}`,
+        [ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
+      }),
+    });
+  }
+}
+
+export function StandardMeterCreateCounter(key: string): Counter {
+  const meter = meterProvider.getMeter(METER_NAME);
+  return meter.createCounter(`${config.SERVICE_ID}.${key}`);
+}
+
+export function StandardMeterCreateUpDownCounter(key: string): Counter {
+  const meter = meterProvider.getMeter(METER_NAME);
+  return meter.createUpDownCounter(`${config.SERVICE_ID}.${key}`);
+}
+
+export function StandardMeterCreateHistorgram(key: string): Histogram {
+  const meter = meterProvider.getMeter(METER_NAME);
+  return meter.createHistogram(`${config.SERVICE_ID}.${key}`);
+}
+
+export function StandardMeterCreateObservableGauge(
+  key: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  callback: (observableResult: any) => void,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  description: any = null
+): ObservableGauge {
+  const meter = meterProvider.getMeter(METER_NAME);
+  const observableGauge = meter.createObservableGauge(key, description);
+
+  observableGauge.addCallback(callback);
+
+  return observableGauge;
+}

package/src/StandardTracer.ts

@@ -0,0 +1,105 @@
+import opentelemetry, {
+  defaultTextMapSetter,
+  ROOT_CONTEXT,
+  trace,
+  Tracer,
+} from "@opentelemetry/api";
+import { AsyncHooksContextManager } from "@opentelemetry/context-async-hooks";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BatchSpanProcessor, Span } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import {
+  ATTR_HTTP_REQUEST_METHOD,
+  ATTR_HTTP_ROUTE,
+  ATTR_NETWORK_LOCAL_ADDRESS,
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+} from "@opentelemetry/semantic-conventions";
+import * as os from "os";
+import { ConfigInterfaceOTel } from "./models/ConfigInterfaceOTel";
+
+let tracerInstance: Tracer;
+const propagator = new W3CTraceContextPropagator();
+let config: ConfigInterfaceOTel;
+
+//
+export function StandardTracerInitTelemetry(initConfig: ConfigInterfaceOTel) {
+  config = initConfig;
+  const spanProcessors = [];
+
+  if (config.OPENTELEMETRY_COLLECTOR_HTTP_TRACES) {
+    const exporterHeaders: Record<string, string> = {};
+    if (config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER) {
+      exporterHeaders[
+        "Authorization"
+      ] = `Bearer ${config.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER}`;
+    }
+    const exporter = new OTLPTraceExporter({
+      url: config.OPENTELEMETRY_COLLECTOR_HTTP_TRACES,
+      headers: exporterHeaders,
+    });
+    spanProcessors.push(new BatchSpanProcessor(exporter));
+  }
+  const traceProvider = new NodeTracerProvider({
+    idGenerator: new AWSXRayIdGenerator(),
+    resource: resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: `${config.SERVICE_ID}`,
+      [ATTR_SERVICE_VERSION]: `${config.VERSION}`,
+      [ATTR_NETWORK_LOCAL_ADDRESS]: os.hostname(),
+    }),
+    spanProcessors,
+  });
+  traceProvider.register();
+  const contextManager = new AsyncHooksContextManager();
+  contextManager.enable();
+  opentelemetry.context.setGlobalContextManager(contextManager);
+}
+
+export function StandardTracerStartSpan(name: string, parentSpan?: Span): Span {
+  const sanitizedName = String(name).replace(/[^a-zA-Z0-9-_/]/g, "_");
+  const tracer = StandardTracerGetTracer();
+
+  if (parentSpan) {
+    return tracer.startSpan(
+      sanitizedName,
+      undefined,
+      opentelemetry.trace.setSpan(opentelemetry.context.active(), parentSpan)
+    ) as Span;
+  }
+
+  const span = tracer.startSpan(sanitizedName) as Span;
+
+  span.setAttribute(ATTR_HTTP_REQUEST_METHOD, `BACKEND`);
+  span.setAttribute(
+    ATTR_HTTP_ROUTE,
+    `${config.SERVICE_ID}-${config.VERSION}-${sanitizedName}`
+  );
+  return span;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function StandardTracerGetTracer(): any {
+  if (!tracerInstance) {
+    tracerInstance = opentelemetry.trace.getTracer(
+      `${config.SERVICE_ID}:${config.VERSION}`
+    );
+  }
+  return tracerInstance;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function StandardTracerAppendHeader(context: Span, headers = {}): any {
+  if (!headers) {
+    headers = {};
+  }
+  propagator.inject(
+    trace.setSpanContext(ROOT_CONTEXT, context.spanContext()),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    headers as any,
+    defaultTextMapSetter
+  );
+  return headers;
+}

package/src/models/ConfigInterfaceOTel.ts

@@ -0,0 +1,11 @@
+export interface ConfigInterfaceOTel {
+  SERVICE_ID: string;
+  VERSION: number;
+  OPENTELEMETRY_COLLECTOR_HTTP_TRACES: string;
+  OPENTELEMETRY_COLLECTOR_HTTP_METRICS: string;
+  OPENTELEMETRY_COLLECTOR_HTTP_LOGS: string;
+  OPENTELEMETRY_COLLECTOR_EXPORT_LOGS_INTERVAL_SECONDS: number;
+  OPENTELEMETRY_COLLECTOR_EXPORT_METRICS_INTERVAL_SECONDS: number;
+  OPENTELEMETRY_COLLECTOR_AWS: boolean;
+  OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER: string;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["index.ts", "src/**/*"]
+}