chore(config): invoke key-value parsing directly in config

chore(instrumentation): use cached singleton vs. global metrics

Author: kschelonka

src/config.test.ts

@@ -3,7 +3,13 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 import { describe, it, expect } from "@jest/globals";
-import { getEnvEnum, getEnvInt, getEnvString, parseKVList } from "./config";
+import {
+  getEnvEnum,
+  getEnvInt,
+  getEnvKVList,
+  getEnvString,
+  parseKVList,
+} from "./config";
 
 describe("getEnvString", () => {
   it("throws an error when attempting to access an undefined environment variable", () => {
@@ -116,6 +122,27 @@ describe("getEnvEnum", () => {
   });
 });
 
+describe("getEnvKVList", () => {
+  it("returns the parsed record when defined", () => {
+    process.env.TEST_KEYV_VAR = "key=value";
+
+    expect(getEnvKVList("TEST_KEYV_VAR")).toStrictEqual({ key: "value" });
+
+    delete process.env.TEST_KEYV_VAR;
+  });
+  it("throws an error when attempting to access an undefined environment variable", () => {
+    expect(() => getEnvKVList("UNDEFINED_ENV_VAR")).toThrow(
+      "Variable $UNDEFINED_ENV_VAR is not defined in `.env`, `.env.test`, `.env.local` and `.env.test.local`, nor as an environment variable.",
+    );
+  });
+
+  it("returns the fallback value when attempting to access an undefined environment variable and one is given", () => {
+    expect(
+      getEnvKVList("UNDEFINED_ENV_VAR", { fallbackValue: { key: "value" } }),
+    ).toStrictEqual({ key: "value" });
+  });
+});
+
 describe("parseKVList", () => {
   it("returns empty object for undefined", () => {
     expect(parseKVList(undefined)).toEqual({});

src/config.ts

@@ -131,7 +131,9 @@ export const config = {
         fallbackValue: "http/protobuf",
       },
     ),
-    resourceAttributes: process.env.OTEL_RESOURCE_ATTRIBUTES,
+    resourceAttributes: getEnvKVList("OTEL_RESOURCE_ATTRIBUTES", {
+      fallbackValue: {},
+    }),
     serviceName: getEnvString("OTEL_SERVICE_NAME", {
       fallbackValue: "monitor",
     }),
@@ -228,9 +230,28 @@ export function getEnvString(
 
   return value;
 }
+/**
+ * Parse comma-separated key=value list from env var into dictionary.
+ * */
+export function getEnvKVList(
+  key: string,
+  options: Partial<{ fallbackValue: Record<string, string> }> = {},
+): Record<string, string> {
+  const value = process.env[key];
+  if (typeof value !== "string" || value === "") {
+    if ("fallbackValue" in options && options.fallbackValue !== undefined) {
+      return options.fallbackValue;
+    }
+    throw new Error(
+      `Variable $${key} is not defined in \`.env\`, \`.env.${process.env.NODE_ENV}\`, \`.env.local\` and \`.env.${process.env.NODE_ENV}.local\`, nor as an environment variable.`,
+    );
+  }
+  return parseKVList(value);
+}
 
 /**
  * Parse comma-separated key=value list into dictionary.
+ * Undefined or empty values will return an empty record.
  * Segments without '=' are ignored (a=1,b,c=2 -> {a: 1, c: 2}
  * (e.g. used by OTEL_RESOURCE_ATTRIBUTES env var:
  * 'k8s.container.name=monitor-api-endpoint,k8s.namespace.name=monitor-stage...')

src/instrumentation.node.ts

@@ -10,8 +10,6 @@ import {
   ConsoleMetricExporter,
   PeriodicExportingMetricReader,
 } from "@opentelemetry/sdk-metrics";
-import { detectResources } from "@opentelemetry/resources";
-import { gcpDetector } from "@opentelemetry/resource-detector-gcp";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import {
@@ -42,7 +40,7 @@ import {
 } from "@sentry/opentelemetry";
 import * as Sentry from "@sentry/nextjs";
 import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
-import { config as appConfig, parseKVList } from "./config";
+import { config as appConfig } from "./config";
 
 // Note: console.log use is intentional because this step is done as early
 // as possible, before setting up winston logging
@@ -101,7 +99,7 @@ export async function nodeSDKBuilder() {
   const sdk = new NodeSDK({
     resource: resourceFromAttributes({
       [ATTR_SERVICE_NAME]: appConfig.otel.serviceName,
-      ...parseKVList(appConfig.otel.resourceAttributes),
+      ...appConfig.otel.resourceAttributes,
     }),
     metricReaders: [
       new PeriodicExportingMetricReader({
@@ -170,21 +168,18 @@ export async function nodeSDKBuilder() {
   console.log("[INSTRUMENTATION] Otel setup is valid");
 }
 
-// Prometheus setup
 type MetricsState = {
   hibpNotifyRequestsTotal: Counter<Attributes>;
   hibpNotifyRequestFailuresTotal: Counter<Attributes>;
 };
 
-declare global {
-  var __metrics: Readonly<MetricsState> | undefined;
-}
+let metricsState: MetricsState | undefined;
 
 // NOTE: OTEL must be initialized before calling any metrics
 // or else it will be a No-Op metric
-function getOrInitMetrics(): MetricsState {
+export function getOrInitMetrics(): MetricsState {
   // Return cached state
-  if (globalThis.__metrics !== undefined) return globalThis.__metrics;
+  if (metricsState !== undefined) return metricsState;
   // Get the pre-registered metrics provider
   // Will be a no-op if otel has not been initialized
   const meter = metrics.getMeter(appConfig.otel.serviceName);
@@ -204,14 +199,6 @@ function getOrInitMetrics(): MetricsState {
     hibpNotifyRequestFailuresTotal,
     hibpNotifyRequestsTotal,
   };
-
-  // Make it readonly
-  Object.defineProperty(globalThis, "__metrics", {
-    value: state,
-    writable: false,
-    configurable: false,
-    enumerable: false,
-  });
   return state;
 }
 

src/instrumentation.ts

@@ -31,9 +31,13 @@ export async function register() {
       // Disable Sentry's automatic OTEL instrumentation since we're managing it ourselves
       skipOpenTelemetrySetup: true,
     });
-    const { nodeSDKBuilder } = await import("./instrumentation.node");
+    const { nodeSDKBuilder, getOrInitMetrics } = await import(
+      "./instrumentation.node"
+    );
     console.log("[INSTRUMENTATION] Initializing OTEL...");
     await nodeSDKBuilder();
+    // Ensure metrics are initialized after OTEL
+    getOrInitMetrics();
   }
 }