@celerity-sdk/telemetry 0.2.0

package/dist/setup.js

@@ -0,0 +1,138 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/init.ts
+import createDebug2 from "debug";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-grpc";
+import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
+import { CompositePropagator, W3CTraceContextPropagator } from "@opentelemetry/core";
+import { AWSXRayPropagator } from "@opentelemetry/propagator-aws-xray";
+import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";
+
+// src/env.ts
+var VALID_LOG_LEVELS = /* @__PURE__ */ new Set([
+  "debug",
+  "info",
+  "warn",
+  "error"
+]);
+var VALID_LOG_FORMATS = /* @__PURE__ */ new Set([
+  "json",
+  "human",
+  "auto"
+]);
+function readTelemetryEnv() {
+  const rawLevel = process.env.CELERITY_LOG_LEVEL;
+  const rawFormat = process.env.CELERITY_LOG_FORMAT;
+  return {
+    tracingEnabled: process.env.CELERITY_TELEMETRY_ENABLED === "true",
+    otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? process.env.CELERITY_TRACE_OTLP_COLLECTOR_ENDPOINT ?? "http://otelcollector:4317",
+    serviceName: process.env.OTEL_SERVICE_NAME ?? "celerity-app",
+    serviceVersion: process.env.OTEL_SERVICE_VERSION ?? "0.0.0",
+    logLevel: rawLevel && VALID_LOG_LEVELS.has(rawLevel) ? rawLevel : "info",
+    logFormat: rawFormat && VALID_LOG_FORMATS.has(rawFormat) ? rawFormat : "auto",
+    logFilePath: process.env.CELERITY_LOG_FILE_PATH ?? null
+  };
+}
+__name(readTelemetryEnv, "readTelemetryEnv");
+
+// src/instrumentations.ts
+import createDebug from "debug";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import { UndiciInstrumentation } from "@opentelemetry/instrumentation-undici";
+var debug = createDebug("celerity:telemetry");
+async function buildInstrumentations() {
+  const instrumentations = [
+    new HttpInstrumentation(),
+    new UndiciInstrumentation()
+  ];
+  const optionalPackages = [
+    "@opentelemetry/instrumentation-aws-sdk",
+    "@opentelemetry/instrumentation-ioredis",
+    "@opentelemetry/instrumentation-pg",
+    "@opentelemetry/instrumentation-mysql2"
+  ];
+  for (const name of optionalPackages) {
+    try {
+      const pkg = name;
+      const mod = await import(pkg);
+      const InstrumentationClass = findInstrumentationExport(mod);
+      if (InstrumentationClass) {
+        debug("instrumentation: loaded %s", name);
+        instrumentations.push(new InstrumentationClass());
+      }
+    } catch (err) {
+      const code = err.code;
+      if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") {
+        debug("instrumentation: failed to load %s: %O", name, err);
+      }
+    }
+  }
+  return instrumentations;
+}
+__name(buildInstrumentations, "buildInstrumentations");
+function findInstrumentationExport(mod) {
+  for (const value of Object.values(mod)) {
+    if (typeof value === "function" && value.prototype && "enable" in value.prototype) {
+      return value;
+    }
+  }
+  return null;
+}
+__name(findInstrumentationExport, "findInstrumentationExport");
+
+// src/init.ts
+var debug2 = createDebug2("celerity:telemetry");
+var initialized = false;
+var sdk = null;
+async function initTelemetry() {
+  if (initialized) {
+    debug2("initTelemetry: already initialized, skipping");
+    return;
+  }
+  const config = readTelemetryEnv();
+  if (!config.tracingEnabled) {
+    debug2("initTelemetry: tracing disabled, skipping");
+    return;
+  }
+  const platform = process.env.CELERITY_RUNTIME_PLATFORM ?? "local";
+  const isAws = platform === "aws";
+  debug2("initTelemetry: platform=%s endpoint=%s service=%s", platform, config.otlpEndpoint, config.serviceName);
+  const instrumentations = await buildInstrumentations();
+  sdk = new NodeSDK({
+    resource: resourceFromAttributes({
+      [ATTR_SERVICE_NAME]: config.serviceName,
+      [ATTR_SERVICE_VERSION]: config.serviceVersion
+    }),
+    traceExporter: new OTLPTraceExporter({
+      url: config.otlpEndpoint
+    }),
+    logRecordProcessors: [
+      new BatchLogRecordProcessor(new OTLPLogExporter({
+        url: config.otlpEndpoint
+      }))
+    ],
+    textMapPropagator: new CompositePropagator({
+      propagators: [
+        new W3CTraceContextPropagator(),
+        new AWSXRayPropagator()
+      ]
+    }),
+    ...isAws ? {
+      idGenerator: new AWSXRayIdGenerator()
+    } : {},
+    instrumentations
+  });
+  sdk.start();
+  initialized = true;
+  debug2("initTelemetry: SDK started");
+}
+__name(initTelemetry, "initTelemetry");
+
+// src/setup.ts
+await initTelemetry();
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/init.ts","../src/env.ts","../src/instrumentations.ts","../src/setup.ts"],"sourcesContent":["import createDebug from \"debug\";\nimport { NodeSDK } from \"@opentelemetry/sdk-node\";\nimport { resourceFromAttributes } from \"@opentelemetry/resources\";\nimport { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from \"@opentelemetry/semantic-conventions\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-grpc\";\nimport { OTLPLogExporter } from \"@opentelemetry/exporter-logs-otlp-grpc\";\nimport { BatchLogRecordProcessor } from \"@opentelemetry/sdk-logs\";\nimport { CompositePropagator, W3CTraceContextPropagator } from \"@opentelemetry/core\";\nimport { AWSXRayPropagator } from \"@opentelemetry/propagator-aws-xray\";\nimport { AWSXRayIdGenerator } from \"@opentelemetry/id-generator-aws-xray\";\nimport { readTelemetryEnv } from \"./env\";\nimport { buildInstrumentations } from \"./instrumentations\";\n\nconst debug = createDebug(\"celerity:telemetry\");\n\nlet initialized = false;\nlet sdk: NodeSDK | null = null;\n\nexport function isInitialized(): boolean {\n  return initialized;\n}\n\nexport async function initTelemetry(): Promise<void> {\n  if (initialized) {\n    debug(\"initTelemetry: already initialized, skipping\");\n    return;\n  }\n\n  const config = readTelemetryEnv();\n  if (!config.tracingEnabled) {\n    debug(\"initTelemetry: tracing disabled, skipping\");\n    return;\n  }\n\n  const platform = process.env.CELERITY_RUNTIME_PLATFORM ?? \"local\";\n  const isAws = platform === \"aws\";\n  debug(\n    \"initTelemetry: platform=%s endpoint=%s service=%s\",\n    platform,\n    config.otlpEndpoint,\n    config.serviceName,\n  );\n\n  const instrumentations = await buildInstrumentations();\n\n  sdk = new NodeSDK({\n    resource: resourceFromAttributes({\n      [ATTR_SERVICE_NAME]: config.serviceName,\n      [ATTR_SERVICE_VERSION]: config.serviceVersion,\n    }),\n    traceExporter: new OTLPTraceExporter({ url: config.otlpEndpoint }),\n    logRecordProcessors: [\n      new BatchLogRecordProcessor(new OTLPLogExporter({ url: config.otlpEndpoint })),\n    ],\n    textMapPropagator: new CompositePropagator({\n      propagators: [new W3CTraceContextPropagator(), new AWSXRayPropagator()],\n    }),\n    ...(isAws ? { idGenerator: new AWSXRayIdGenerator() } : {}),\n    instrumentations,\n  });\n\n  sdk.start();\n  initialized = true;\n  debug(\"initTelemetry: SDK started\");\n}\n\nexport async function shutdownTelemetry(): Promise<void> {\n  if (sdk) {\n    debug(\"shutdownTelemetry: shutting down SDK\");\n    await sdk.shutdown();\n    sdk = null;\n    initialized = false;\n  }\n}\n","import type { LogLevel } from \"@celerity-sdk/types\";\n\nexport type TelemetryConfig = {\n  tracingEnabled: boolean;\n  otlpEndpoint: string;\n  serviceName: string;\n  serviceVersion: string;\n  logLevel: LogLevel;\n  logFormat: \"json\" | \"human\" | \"auto\";\n  logFilePath: string | null;\n};\n\nconst VALID_LOG_LEVELS = new Set<string>([\"debug\", \"info\", \"warn\", \"error\"]);\nconst VALID_LOG_FORMATS = new Set<string>([\"json\", \"human\", \"auto\"]);\n\nexport function readTelemetryEnv(): TelemetryConfig {\n  const rawLevel = process.env.CELERITY_LOG_LEVEL;\n  const rawFormat = process.env.CELERITY_LOG_FORMAT;\n\n  return {\n    tracingEnabled: process.env.CELERITY_TELEMETRY_ENABLED === \"true\",\n    otlpEndpoint:\n      process.env.OTEL_EXPORTER_OTLP_ENDPOINT ??\n      process.env.CELERITY_TRACE_OTLP_COLLECTOR_ENDPOINT ??\n      \"http://otelcollector:4317\",\n    serviceName: process.env.OTEL_SERVICE_NAME ?? \"celerity-app\",\n    serviceVersion: process.env.OTEL_SERVICE_VERSION ?? \"0.0.0\",\n    logLevel: rawLevel && VALID_LOG_LEVELS.has(rawLevel) ? (rawLevel as LogLevel) : \"info\",\n    logFormat:\n      rawFormat && VALID_LOG_FORMATS.has(rawFormat)\n        ? (rawFormat as \"json\" | \"human\" | \"auto\")\n        : \"auto\",\n    logFilePath: process.env.CELERITY_LOG_FILE_PATH ?? null,\n  };\n}\n","import createDebug from \"debug\";\nimport { HttpInstrumentation } from \"@opentelemetry/instrumentation-http\";\nimport { UndiciInstrumentation } from \"@opentelemetry/instrumentation-undici\";\nimport type { Instrumentation } from \"@opentelemetry/instrumentation\";\n\nconst debug = createDebug(\"celerity:telemetry\");\n\nexport async function buildInstrumentations(): Promise<Instrumentation[]> {\n  // Core instrumentation: always active — covers all HTTP/HTTPS and fetch() calls\n  const instrumentations: Instrumentation[] = [\n    new HttpInstrumentation() as Instrumentation,\n    new UndiciInstrumentation() as Instrumentation,\n  ];\n\n  // Dynamically load optional instrumentation packages.\n  // Each targets a specific library and silently no-ops if the library isn't installed.\n  const optionalPackages = [\n    \"@opentelemetry/instrumentation-aws-sdk\",\n    \"@opentelemetry/instrumentation-ioredis\",\n    \"@opentelemetry/instrumentation-pg\",\n    \"@opentelemetry/instrumentation-mysql2\",\n  ];\n\n  for (const name of optionalPackages) {\n    try {\n      const pkg = name;\n      const mod = (await import(pkg)) as Record<string, unknown>;\n      const InstrumentationClass = findInstrumentationExport(mod);\n      if (InstrumentationClass) {\n        debug(\"instrumentation: loaded %s\", name);\n        instrumentations.push(new InstrumentationClass() as Instrumentation);\n      }\n    } catch (err) {\n      const code = (err as { code?: string }).code;\n      if (code !== \"ERR_MODULE_NOT_FOUND\" && code !== \"MODULE_NOT_FOUND\") {\n        debug(\"instrumentation: failed to load %s: %O\", name, err);\n      }\n    }\n  }\n\n  return instrumentations;\n}\n\nfunction findInstrumentationExport(mod: Record<string, unknown>): (new () => unknown) | null {\n  for (const value of Object.values(mod)) {\n    if (typeof value === \"function\" && value.prototype && \"enable\" in value.prototype) {\n      return value as new () => unknown;\n    }\n  }\n  return null;\n}\n","// Early initialization entry point for: node --import @celerity-sdk/telemetry/setup app.js\n// Registers OTel auto-instrumentations before any user code loads.\n// Only activates when CELERITY_TELEMETRY_ENABLED=true.\nimport { initTelemetry } from \"./init\";\n\nawait initTelemetry();\n"],"mappings":"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","names":["createDebug","NodeSDK","resourceFromAttributes","ATTR_SERVICE_NAME","ATTR_SERVICE_VERSION","OTLPTraceExporter","OTLPLogExporter","BatchLogRecordProcessor","CompositePropagator","W3CTraceContextPropagator","AWSXRayPropagator","AWSXRayIdGenerator","VALID_LOG_LEVELS","Set","VALID_LOG_FORMATS","readTelemetryEnv","rawLevel","process","env","CELERITY_LOG_LEVEL","rawFormat","CELERITY_LOG_FORMAT","tracingEnabled","CELERITY_TELEMETRY_ENABLED","otlpEndpoint","OTEL_EXPORTER_OTLP_ENDPOINT","CELERITY_TRACE_OTLP_COLLECTOR_ENDPOINT","serviceName","OTEL_SERVICE_NAME","serviceVersion","OTEL_SERVICE_VERSION","logLevel","has","logFormat","logFilePath","CELERITY_LOG_FILE_PATH","createDebug","HttpInstrumentation","UndiciInstrumentation","debug","createDebug","buildInstrumentations","instrumentations","HttpInstrumentation","UndiciInstrumentation","optionalPackages","name","pkg","mod","InstrumentationClass","findInstrumentationExport","push","err","code","value","Object","values","prototype","debug","createDebug","initialized","sdk","initTelemetry","initialized","debug","config","readTelemetryEnv","tracingEnabled","platform","process","env","CELERITY_RUNTIME_PLATFORM","isAws","otlpEndpoint","serviceName","instrumentations","buildInstrumentations","sdk","NodeSDK","resource","resourceFromAttributes","ATTR_SERVICE_NAME","ATTR_SERVICE_VERSION","serviceVersion","traceExporter","OTLPTraceExporter","url","logRecordProcessors","BatchLogRecordProcessor","OTLPLogExporter","textMapPropagator","CompositePropagator","propagators","W3CTraceContextPropagator","AWSXRayPropagator","idGenerator","AWSXRayIdGenerator","start","initTelemetry"]}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@celerity-sdk/telemetry",
+  "version": "0.2.0",
+  "description": "Observability layer for the Celerity Node SDK — pino-based logger and OTel-based tracing",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/newstack-cloud/celerity-node-sdk.git",
+    "directory": "packages/telemetry"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./setup": {
+      "import": "./dist/setup.js"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "debug": "^4.4.0",
+    "pino": "^10.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.200.0",
+    "@opentelemetry/sdk-node": "^0.200.0",
+    "@opentelemetry/sdk-trace-node": "^2.0.0",
+    "@opentelemetry/sdk-logs": "^0.200.0",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/semantic-conventions": "^1.25.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.200.0",
+    "@opentelemetry/exporter-logs-otlp-grpc": "^0.200.0",
+    "@opentelemetry/core": "^2.0.0",
+    "@opentelemetry/propagator-aws-xray": "^2.0.0",
+    "@opentelemetry/id-generator-aws-xray": "^2.0.0",
+    "@opentelemetry/instrumentation": "^0.200.0",
+    "@opentelemetry/instrumentation-http": "^0.200.0",
+    "@opentelemetry/instrumentation-undici": "^0.14.0",
+    "@celerity-sdk/common": "^0.2.0",
+    "@celerity-sdk/types": "^0.2.0"
+  },
+  "devDependencies": {
+    "pino-pretty": "^13.0.0"
+  },
+  "peerDependencies": {
+    "@opentelemetry/instrumentation-aws-sdk": "^0.50.0",
+    "@opentelemetry/instrumentation-ioredis": "^0.50.0",
+    "@opentelemetry/instrumentation-pg": "^0.50.0",
+    "@opentelemetry/instrumentation-mysql2": "^0.50.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/instrumentation-aws-sdk": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-ioredis": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-pg": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-mysql2": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}