@opengeni/observability 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+type AttributeValue = string | number | boolean | null | undefined;
+type Attributes = Record<string, AttributeValue>;
+type ObservabilitySettings = {
+    serviceName: string;
+    environment: string;
+    observabilityStructuredLogs: boolean;
+    observabilityMetricsEnabled: boolean;
+    observabilityOtlpEndpoint?: string | undefined;
+    observabilityOtlpHeaders: string;
+};
+type ObservabilityOptions = {
+    component: string;
+    now?: () => number;
+    exporter?: (url: string, body: unknown, headers: Record<string, string>) => Promise<void>;
+};
+type Span = {
+    traceId: string;
+    spanId: string;
+    end: (input?: {
+        attributes?: Attributes;
+        error?: unknown;
+    }) => void;
+};
+declare function createObservability(settings: ObservabilitySettings, options: ObservabilityOptions): Observability;
+declare class Observability {
+    private readonly settings;
+    private readonly options;
+    private readonly metrics;
+    private readonly now;
+    private readonly exporter;
+    private readonly resourceAttributes;
+    constructor(settings: ObservabilitySettings, options: ObservabilityOptions);
+    info(message: string, attributes?: Attributes): void;
+    warn(message: string, attributes?: Attributes): void;
+    error(message: string, attributes?: Attributes): void;
+    log(level: "debug" | "info" | "warn" | "error", message: string, attributes?: Attributes): void;
+    startSpan(name: string, attributes?: Attributes): Span;
+    recordHttpRequest(input: {
+        method: string;
+        route: string;
+        status: number;
+        durationSeconds: number;
+    }): void;
+    recordWorkerActivity(input: {
+        activity: string;
+        status: string;
+        durationSeconds: number;
+    }): void;
+    prometheusMetrics(): string;
+    private exportSpan;
+}
+type StartupDependencyRetryEvent = {
+    label: string;
+    attempt: number;
+    attempts: number;
+    delayMs: number;
+    error: unknown;
+};
+declare function logStartupDependencyRetry(observability: Observability, event: StartupDependencyRetryEvent): void;
+declare function parseHeaders(value: string): Record<string, string>;
+
+export { type AttributeValue, type Attributes, Observability, type ObservabilityOptions, type ObservabilitySettings, type Span, type StartupDependencyRetryEvent, createObservability, logStartupDependencyRetry, parseHeaders };

package/dist/index.js

@@ -0,0 +1,315 @@
+// src/index.ts
+var histogramBuckets = [5e-3, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+function createObservability(settings, options) {
+  return new Observability(settings, options);
+}
+var Observability = class {
+  constructor(settings, options) {
+    this.settings = settings;
+    this.options = options;
+    this.now = options.now ?? Date.now;
+    this.exporter = options.exporter ?? defaultExporter;
+    this.resourceAttributes = {
+      "service.name": settings.serviceName,
+      "deployment.environment": settings.environment,
+      "opengeni.component": options.component
+    };
+  }
+  settings;
+  options;
+  metrics = new MetricsRegistry();
+  now;
+  exporter;
+  resourceAttributes;
+  info(message, attributes = {}) {
+    this.log("info", message, attributes);
+  }
+  warn(message, attributes = {}) {
+    this.log("warn", message, attributes);
+  }
+  error(message, attributes = {}) {
+    this.log("error", message, attributes);
+  }
+  log(level, message, attributes = {}) {
+    if (!this.settings.observabilityStructuredLogs) {
+      const line = attributes.error ? `${message}: ${String(attributes.error)}` : message;
+      if (level === "warn") {
+        console.warn(line);
+      } else if (level === "error") {
+        console.error(line);
+      } else {
+        console.log(line);
+      }
+      return;
+    }
+    const record = {
+      timestamp: new Date(this.now()).toISOString(),
+      level,
+      message,
+      service: this.settings.serviceName,
+      environment: this.settings.environment,
+      component: this.options.component,
+      ...cleanAttributes(attributes)
+    };
+    const serialized = JSON.stringify(record);
+    if (level === "warn") {
+      console.warn(serialized);
+    } else if (level === "error") {
+      console.error(serialized);
+    } else {
+      console.log(serialized);
+    }
+  }
+  startSpan(name, attributes = {}) {
+    const traceId = randomHex(16);
+    const spanId = randomHex(8);
+    const startMs = this.now();
+    let ended = false;
+    return {
+      traceId,
+      spanId,
+      end: (input = {}) => {
+        if (ended) {
+          return;
+        }
+        ended = true;
+        const errorAttributes = input.error ? errorToAttributes(input.error) : {};
+        this.exportSpan({
+          traceId,
+          spanId,
+          name,
+          startMs,
+          endMs: this.now(),
+          attributes: {
+            ...attributes,
+            ...input.attributes,
+            ...errorAttributes
+          },
+          error: input.error
+        });
+      }
+    };
+  }
+  recordHttpRequest(input) {
+    if (!this.settings.observabilityMetricsEnabled) {
+      return;
+    }
+    const labels = {
+      method: input.method,
+      route: input.route,
+      status: String(input.status),
+      component: this.options.component
+    };
+    this.metrics.increment("opengeni_http_requests_total", labels);
+    this.metrics.observe("opengeni_http_request_duration_seconds", histogramBuckets, input.durationSeconds, {
+      method: input.method,
+      route: input.route,
+      component: this.options.component
+    });
+  }
+  recordWorkerActivity(input) {
+    if (!this.settings.observabilityMetricsEnabled) {
+      return;
+    }
+    const labels = {
+      activity: input.activity,
+      status: input.status,
+      component: this.options.component
+    };
+    this.metrics.increment("opengeni_worker_activity_runs_total", labels);
+    this.metrics.observe("opengeni_worker_activity_duration_seconds", histogramBuckets, input.durationSeconds, {
+      activity: input.activity,
+      component: this.options.component
+    });
+  }
+  prometheusMetrics() {
+    return this.metrics.toPrometheus({
+      service: this.settings.serviceName,
+      environment: this.settings.environment,
+      component: this.options.component
+    });
+  }
+  exportSpan(span) {
+    if (!this.settings.observabilityOtlpEndpoint) {
+      return;
+    }
+    const endpoint = `${this.settings.observabilityOtlpEndpoint.replace(/\/$/, "")}/v1/traces`;
+    const body = {
+      resourceSpans: [{
+        resource: {
+          attributes: otlpAttributes(this.resourceAttributes)
+        },
+        scopeSpans: [{
+          scope: {
+            name: "@opengeni/observability",
+            version: "0.1.0"
+          },
+          spans: [{
+            traceId: span.traceId,
+            spanId: span.spanId,
+            name: span.name,
+            kind: 1,
+            startTimeUnixNano: millisToNanos(span.startMs),
+            endTimeUnixNano: millisToNanos(span.endMs),
+            attributes: otlpAttributes(span.attributes),
+            status: span.error ? { code: 2, message: errorMessage(span.error) } : { code: 1 }
+          }]
+        }]
+      }]
+    };
+    void this.exporter(endpoint, body, parseHeaders(this.settings.observabilityOtlpHeaders)).catch((error) => {
+      this.warn("OTLP span export failed", { error: errorMessage(error), endpoint });
+    });
+  }
+};
+function logStartupDependencyRetry(observability, event) {
+  const message = event.error instanceof Error ? event.error.message : String(event.error);
+  observability.warn("Startup dependency connection failed; retrying", {
+    dependency: event.label,
+    attempt: event.attempt,
+    attempts: event.attempts,
+    delayMs: event.delayMs,
+    error: message
+  });
+}
+var MetricsRegistry = class {
+  counters = /* @__PURE__ */ new Map();
+  histograms = /* @__PURE__ */ new Map();
+  increment(name, labels, amount = 1) {
+    const key = metricKey(name, labels);
+    this.counters.set(key, (this.counters.get(key) ?? 0) + amount);
+  }
+  observe(name, buckets, value, labels) {
+    const key = metricKey(name, labels);
+    const histogram = this.histograms.get(key) ?? {
+      buckets,
+      counts: buckets.map(() => 0),
+      sum: 0,
+      count: 0,
+      labels
+    };
+    histogram.sum += value;
+    histogram.count += 1;
+    for (let index = 0; index < buckets.length; index += 1) {
+      if (value <= buckets[index]) {
+        histogram.counts[index] = (histogram.counts[index] ?? 0) + 1;
+      }
+    }
+    this.histograms.set(key, histogram);
+  }
+  toPrometheus(resourceLabels) {
+    const lines = [
+      "# HELP opengeni_http_requests_total Total HTTP requests handled by the OpenGeni API.",
+      "# TYPE opengeni_http_requests_total counter"
+    ];
+    for (const [key, value] of this.counters) {
+      const { name, labels } = parseMetricKey(key);
+      if (name.endsWith("_total")) {
+        lines.push(`${name}${formatLabels({ ...resourceLabels, ...labels })} ${value}`);
+      }
+    }
+    lines.push(
+      "# HELP opengeni_http_request_duration_seconds HTTP request duration in seconds.",
+      "# TYPE opengeni_http_request_duration_seconds histogram",
+      "# HELP opengeni_worker_activity_runs_total Total worker activity executions.",
+      "# TYPE opengeni_worker_activity_runs_total counter",
+      "# HELP opengeni_worker_activity_duration_seconds Worker activity duration in seconds.",
+      "# TYPE opengeni_worker_activity_duration_seconds histogram"
+    );
+    for (const [key, histogram] of this.histograms) {
+      const { name, labels } = parseMetricKey(key);
+      const baseLabels = { ...resourceLabels, ...labels };
+      for (let index = 0; index < histogram.buckets.length; index += 1) {
+        lines.push(`${name}_bucket${formatLabels({ ...baseLabels, le: String(histogram.buckets[index]) })} ${histogram.counts[index]}`);
+      }
+      lines.push(`${name}_bucket${formatLabels({ ...baseLabels, le: "+Inf" })} ${histogram.count}`);
+      lines.push(`${name}_sum${formatLabels(baseLabels)} ${histogram.sum}`);
+      lines.push(`${name}_count${formatLabels(baseLabels)} ${histogram.count}`);
+    }
+    return `${lines.join("\n")}
+`;
+  }
+};
+function metricKey(name, labels) {
+  return JSON.stringify({ name, labels: Object.fromEntries(Object.entries(labels).sort(([a], [b]) => a.localeCompare(b))) });
+}
+function parseMetricKey(key) {
+  return JSON.parse(key);
+}
+function formatLabels(labels) {
+  const entries = Object.entries(labels).filter(([, value]) => value.length > 0);
+  if (entries.length === 0) {
+    return "";
+  }
+  return `{${entries.map(([key, value]) => `${key}="${escapeMetricLabel(value)}"`).join(",")}}`;
+}
+function escapeMetricLabel(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+function cleanAttributes(attributes) {
+  return Object.fromEntries(Object.entries(attributes).filter(([, value]) => value !== void 0));
+}
+function errorToAttributes(error) {
+  return {
+    "error.type": error instanceof Error ? error.name : "Error",
+    "error.message": errorMessage(error)
+  };
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function otlpAttributes(attributes) {
+  return Object.entries(cleanAttributes(attributes)).map(([key, value]) => ({
+    key,
+    value: otlpValue(value)
+  }));
+}
+function otlpValue(value) {
+  if (typeof value === "number") {
+    return Number.isInteger(value) ? { intValue: value } : { doubleValue: value };
+  }
+  if (typeof value === "boolean") {
+    return { boolValue: value };
+  }
+  return { stringValue: value === null ? "" : value };
+}
+function millisToNanos(ms) {
+  return String(BigInt(Math.round(ms)) * 1000000n);
+}
+function randomHex(bytes) {
+  const values = crypto.getRandomValues(new Uint8Array(bytes));
+  return Array.from(values, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+function parseHeaders(value) {
+  if (!value.trim()) {
+    return {};
+  }
+  const entries = value.split(",").map((pair) => {
+    const separator = pair.indexOf("=");
+    if (separator === -1) {
+      return [pair.trim(), ""];
+    }
+    return [pair.slice(0, separator).trim(), pair.slice(separator + 1).trim()];
+  }).filter(([key]) => key.length > 0);
+  return Object.fromEntries(entries);
+}
+async function defaultExporter(url, body, headers) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...headers
+    },
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) {
+    throw new Error(`OTLP endpoint returned HTTP ${response.status}`);
+  }
+}
+export {
+  Observability,
+  createObservability,
+  logStartupDependencyRetry,
+  parseHeaders
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export type AttributeValue = string | number | boolean | null | undefined;\nexport type Attributes = Record<string, AttributeValue>;\n\nexport type ObservabilitySettings = {\n  serviceName: string;\n  environment: string;\n  observabilityStructuredLogs: boolean;\n  observabilityMetricsEnabled: boolean;\n  observabilityOtlpEndpoint?: string | undefined;\n  observabilityOtlpHeaders: string;\n};\n\nexport type ObservabilityOptions = {\n  component: string;\n  now?: () => number;\n  exporter?: (url: string, body: unknown, headers: Record<string, string>) => Promise<void>;\n};\n\nexport type Span = {\n  traceId: string;\n  spanId: string;\n  end: (input?: { attributes?: Attributes; error?: unknown }) => void;\n};\n\nconst histogramBuckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];\n\nexport function createObservability(settings: ObservabilitySettings, options: ObservabilityOptions): Observability {\n  return new Observability(settings, options);\n}\n\nexport class Observability {\n  private readonly metrics = new MetricsRegistry();\n  private readonly now: () => number;\n  private readonly exporter: (url: string, body: unknown, headers: Record<string, string>) => Promise<void>;\n  private readonly resourceAttributes: Attributes;\n\n  constructor(private readonly settings: ObservabilitySettings, private readonly options: ObservabilityOptions) {\n    this.now = options.now ?? Date.now;\n    this.exporter = options.exporter ?? defaultExporter;\n    this.resourceAttributes = {\n      \"service.name\": settings.serviceName,\n      \"deployment.environment\": settings.environment,\n      \"opengeni.component\": options.component,\n    };\n  }\n\n  info(message: string, attributes: Attributes = {}): void {\n    this.log(\"info\", message, attributes);\n  }\n\n  warn(message: string, attributes: Attributes = {}): void {\n    this.log(\"warn\", message, attributes);\n  }\n\n  error(message: string, attributes: Attributes = {}): void {\n    this.log(\"error\", message, attributes);\n  }\n\n  log(level: \"debug\" | \"info\" | \"warn\" | \"error\", message: string, attributes: Attributes = {}): void {\n    if (!this.settings.observabilityStructuredLogs) {\n      const line = attributes.error ? `${message}: ${String(attributes.error)}` : message;\n      if (level === \"warn\") {\n        console.warn(line);\n      } else if (level === \"error\") {\n        console.error(line);\n      } else {\n        console.log(line);\n      }\n      return;\n    }\n    const record = {\n      timestamp: new Date(this.now()).toISOString(),\n      level,\n      message,\n      service: this.settings.serviceName,\n      environment: this.settings.environment,\n      component: this.options.component,\n      ...cleanAttributes(attributes),\n    };\n    const serialized = JSON.stringify(record);\n    if (level === \"warn\") {\n      console.warn(serialized);\n    } else if (level === \"error\") {\n      console.error(serialized);\n    } else {\n      console.log(serialized);\n    }\n  }\n\n  startSpan(name: string, attributes: Attributes = {}): Span {\n    const traceId = randomHex(16);\n    const spanId = randomHex(8);\n    const startMs = this.now();\n    let ended = false;\n    return {\n      traceId,\n      spanId,\n      end: (input = {}) => {\n        if (ended) {\n          return;\n        }\n        ended = true;\n        const errorAttributes = input.error ? errorToAttributes(input.error) : {};\n        this.exportSpan({\n          traceId,\n          spanId,\n          name,\n          startMs,\n          endMs: this.now(),\n          attributes: {\n            ...attributes,\n            ...input.attributes,\n            ...errorAttributes,\n          },\n          error: input.error,\n        });\n      },\n    };\n  }\n\n  recordHttpRequest(input: { method: string; route: string; status: number; durationSeconds: number }): void {\n    if (!this.settings.observabilityMetricsEnabled) {\n      return;\n    }\n    const labels = {\n      method: input.method,\n      route: input.route,\n      status: String(input.status),\n      component: this.options.component,\n    };\n    this.metrics.increment(\"opengeni_http_requests_total\", labels);\n    this.metrics.observe(\"opengeni_http_request_duration_seconds\", histogramBuckets, input.durationSeconds, {\n      method: input.method,\n      route: input.route,\n      component: this.options.component,\n    });\n  }\n\n  recordWorkerActivity(input: { activity: string; status: string; durationSeconds: number }): void {\n    if (!this.settings.observabilityMetricsEnabled) {\n      return;\n    }\n    const labels = {\n      activity: input.activity,\n      status: input.status,\n      component: this.options.component,\n    };\n    this.metrics.increment(\"opengeni_worker_activity_runs_total\", labels);\n    this.metrics.observe(\"opengeni_worker_activity_duration_seconds\", histogramBuckets, input.durationSeconds, {\n      activity: input.activity,\n      component: this.options.component,\n    });\n  }\n\n  prometheusMetrics(): string {\n    return this.metrics.toPrometheus({\n      service: this.settings.serviceName,\n      environment: this.settings.environment,\n      component: this.options.component,\n    });\n  }\n\n  private exportSpan(span: {\n    traceId: string;\n    spanId: string;\n    name: string;\n    startMs: number;\n    endMs: number;\n    attributes: Attributes;\n    error?: unknown;\n  }): void {\n    if (!this.settings.observabilityOtlpEndpoint) {\n      return;\n    }\n    const endpoint = `${this.settings.observabilityOtlpEndpoint.replace(/\\/$/, \"\")}/v1/traces`;\n    const body = {\n      resourceSpans: [{\n        resource: {\n          attributes: otlpAttributes(this.resourceAttributes),\n        },\n        scopeSpans: [{\n          scope: {\n            name: \"@opengeni/observability\",\n            version: \"0.1.0\",\n          },\n          spans: [{\n            traceId: span.traceId,\n            spanId: span.spanId,\n            name: span.name,\n            kind: 1,\n            startTimeUnixNano: millisToNanos(span.startMs),\n            endTimeUnixNano: millisToNanos(span.endMs),\n            attributes: otlpAttributes(span.attributes),\n            status: span.error ? { code: 2, message: errorMessage(span.error) } : { code: 1 },\n          }],\n        }],\n      }],\n    };\n    void this.exporter(endpoint, body, parseHeaders(this.settings.observabilityOtlpHeaders)).catch((error) => {\n      this.warn(\"OTLP span export failed\", { error: errorMessage(error), endpoint });\n    });\n  }\n}\n\nexport type StartupDependencyRetryEvent = {\n  label: string;\n  attempt: number;\n  attempts: number;\n  delayMs: number;\n  error: unknown;\n};\n\nexport function logStartupDependencyRetry(observability: Observability, event: StartupDependencyRetryEvent): void {\n  const message = event.error instanceof Error ? event.error.message : String(event.error);\n  observability.warn(\"Startup dependency connection failed; retrying\", {\n    dependency: event.label,\n    attempt: event.attempt,\n    attempts: event.attempts,\n    delayMs: event.delayMs,\n    error: message,\n  });\n}\n\nclass MetricsRegistry {\n  private readonly counters = new Map<string, number>();\n  private readonly histograms = new Map<string, { buckets: number[]; counts: number[]; sum: number; count: number; labels: Record<string, string> }>();\n\n  increment(name: string, labels: Record<string, string>, amount = 1): void {\n    const key = metricKey(name, labels);\n    this.counters.set(key, (this.counters.get(key) ?? 0) + amount);\n  }\n\n  observe(name: string, buckets: number[], value: number, labels: Record<string, string>): void {\n    const key = metricKey(name, labels);\n    const histogram = this.histograms.get(key) ?? {\n      buckets,\n      counts: buckets.map(() => 0),\n      sum: 0,\n      count: 0,\n      labels,\n    };\n    histogram.sum += value;\n    histogram.count += 1;\n    for (let index = 0; index < buckets.length; index += 1) {\n      if (value <= buckets[index]!) {\n        histogram.counts[index] = (histogram.counts[index] ?? 0) + 1;\n      }\n    }\n    this.histograms.set(key, histogram);\n  }\n\n  toPrometheus(resourceLabels: Record<string, string>): string {\n    const lines = [\n      \"# HELP opengeni_http_requests_total Total HTTP requests handled by the OpenGeni API.\",\n      \"# TYPE opengeni_http_requests_total counter\",\n    ];\n    for (const [key, value] of this.counters) {\n      const { name, labels } = parseMetricKey(key);\n      if (name.endsWith(\"_total\")) {\n        lines.push(`${name}${formatLabels({ ...resourceLabels, ...labels })} ${value}`);\n      }\n    }\n    lines.push(\n      \"# HELP opengeni_http_request_duration_seconds HTTP request duration in seconds.\",\n      \"# TYPE opengeni_http_request_duration_seconds histogram\",\n      \"# HELP opengeni_worker_activity_runs_total Total worker activity executions.\",\n      \"# TYPE opengeni_worker_activity_runs_total counter\",\n      \"# HELP opengeni_worker_activity_duration_seconds Worker activity duration in seconds.\",\n      \"# TYPE opengeni_worker_activity_duration_seconds histogram\",\n    );\n    for (const [key, histogram] of this.histograms) {\n      const { name, labels } = parseMetricKey(key);\n      const baseLabels = { ...resourceLabels, ...labels };\n      for (let index = 0; index < histogram.buckets.length; index += 1) {\n        lines.push(`${name}_bucket${formatLabels({ ...baseLabels, le: String(histogram.buckets[index]) })} ${histogram.counts[index]}`);\n      }\n      lines.push(`${name}_bucket${formatLabels({ ...baseLabels, le: \"+Inf\" })} ${histogram.count}`);\n      lines.push(`${name}_sum${formatLabels(baseLabels)} ${histogram.sum}`);\n      lines.push(`${name}_count${formatLabels(baseLabels)} ${histogram.count}`);\n    }\n    return `${lines.join(\"\\n\")}\\n`;\n  }\n}\n\nfunction metricKey(name: string, labels: Record<string, string>): string {\n  return JSON.stringify({ name, labels: Object.fromEntries(Object.entries(labels).sort(([a], [b]) => a.localeCompare(b))) });\n}\n\nfunction parseMetricKey(key: string): { name: string; labels: Record<string, string> } {\n  return JSON.parse(key) as { name: string; labels: Record<string, string> };\n}\n\nfunction formatLabels(labels: Record<string, string>): string {\n  const entries = Object.entries(labels).filter(([, value]) => value.length > 0);\n  if (entries.length === 0) {\n    return \"\";\n  }\n  return `{${entries.map(([key, value]) => `${key}=\"${escapeMetricLabel(value)}\"`).join(\",\")}}`;\n}\n\nfunction escapeMetricLabel(value: string): string {\n  return value.replace(/\\\\/g, \"\\\\\\\\\").replace(/\"/g, \"\\\\\\\"\").replace(/\\n/g, \"\\\\n\");\n}\n\nfunction cleanAttributes(attributes: Attributes): Record<string, string | number | boolean | null> {\n  return Object.fromEntries(Object.entries(attributes).filter(([, value]) => value !== undefined)) as Record<string, string | number | boolean | null>;\n}\n\nfunction errorToAttributes(error: unknown): Attributes {\n  return {\n    \"error.type\": error instanceof Error ? error.name : \"Error\",\n    \"error.message\": errorMessage(error),\n  };\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nfunction otlpAttributes(attributes: Attributes): Array<{ key: string; value: Record<string, string | number | boolean> }> {\n  return Object.entries(cleanAttributes(attributes)).map(([key, value]) => ({\n    key,\n    value: otlpValue(value),\n  }));\n}\n\nfunction otlpValue(value: string | number | boolean | null): Record<string, string | number | boolean> {\n  if (typeof value === \"number\") {\n    return Number.isInteger(value) ? { intValue: value } : { doubleValue: value };\n  }\n  if (typeof value === \"boolean\") {\n    return { boolValue: value };\n  }\n  return { stringValue: value === null ? \"\" : value };\n}\n\nfunction millisToNanos(ms: number): string {\n  return String(BigInt(Math.round(ms)) * 1_000_000n);\n}\n\nfunction randomHex(bytes: number): string {\n  const values = crypto.getRandomValues(new Uint8Array(bytes));\n  return Array.from(values, (value) => value.toString(16).padStart(2, \"0\")).join(\"\");\n}\n\nexport function parseHeaders(value: string): Record<string, string> {\n  if (!value.trim()) {\n    return {};\n  }\n  const entries: Array<[string, string]> = value.split(\",\").map((pair): [string, string] => {\n    const separator = pair.indexOf(\"=\");\n    if (separator === -1) {\n      return [pair.trim(), \"\"];\n    }\n    return [pair.slice(0, separator).trim(), pair.slice(separator + 1).trim()];\n  }).filter(([key]) => key.length > 0);\n  return Object.fromEntries(entries);\n}\n\nasync function defaultExporter(url: string, body: unknown, headers: Record<string, string>): Promise<void> {\n  const response = await fetch(url, {\n    method: \"POST\",\n    headers: {\n      \"content-type\": \"application/json\",\n      ...headers,\n    },\n    body: JSON.stringify(body),\n  });\n  if (!response.ok) {\n    throw new Error(`OTLP endpoint returned HTTP ${response.status}`);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@opengeni/observability",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cloudgeni-ai/opengeni.git",
+    "directory": "packages/observability"
+  }
+}

package/src/index.ts

@@ -0,0 +1,372 @@
+export type AttributeValue = string | number | boolean | null | undefined;
+export type Attributes = Record<string, AttributeValue>;
+
+export type ObservabilitySettings = {
+  serviceName: string;
+  environment: string;
+  observabilityStructuredLogs: boolean;
+  observabilityMetricsEnabled: boolean;
+  observabilityOtlpEndpoint?: string | undefined;
+  observabilityOtlpHeaders: string;
+};
+
+export type ObservabilityOptions = {
+  component: string;
+  now?: () => number;
+  exporter?: (url: string, body: unknown, headers: Record<string, string>) => Promise<void>;
+};
+
+export type Span = {
+  traceId: string;
+  spanId: string;
+  end: (input?: { attributes?: Attributes; error?: unknown }) => void;
+};
+
+const histogramBuckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+
+export function createObservability(settings: ObservabilitySettings, options: ObservabilityOptions): Observability {
+  return new Observability(settings, options);
+}
+
+export class Observability {
+  private readonly metrics = new MetricsRegistry();
+  private readonly now: () => number;
+  private readonly exporter: (url: string, body: unknown, headers: Record<string, string>) => Promise<void>;
+  private readonly resourceAttributes: Attributes;
+
+  constructor(private readonly settings: ObservabilitySettings, private readonly options: ObservabilityOptions) {
+    this.now = options.now ?? Date.now;
+    this.exporter = options.exporter ?? defaultExporter;
+    this.resourceAttributes = {
+      "service.name": settings.serviceName,
+      "deployment.environment": settings.environment,
+      "opengeni.component": options.component,
+    };
+  }
+
+  info(message: string, attributes: Attributes = {}): void {
+    this.log("info", message, attributes);
+  }
+
+  warn(message: string, attributes: Attributes = {}): void {
+    this.log("warn", message, attributes);
+  }
+
+  error(message: string, attributes: Attributes = {}): void {
+    this.log("error", message, attributes);
+  }
+
+  log(level: "debug" | "info" | "warn" | "error", message: string, attributes: Attributes = {}): void {
+    if (!this.settings.observabilityStructuredLogs) {
+      const line = attributes.error ? `${message}: ${String(attributes.error)}` : message;
+      if (level === "warn") {
+        console.warn(line);
+      } else if (level === "error") {
+        console.error(line);
+      } else {
+        console.log(line);
+      }
+      return;
+    }
+    const record = {
+      timestamp: new Date(this.now()).toISOString(),
+      level,
+      message,
+      service: this.settings.serviceName,
+      environment: this.settings.environment,
+      component: this.options.component,
+      ...cleanAttributes(attributes),
+    };
+    const serialized = JSON.stringify(record);
+    if (level === "warn") {
+      console.warn(serialized);
+    } else if (level === "error") {
+      console.error(serialized);
+    } else {
+      console.log(serialized);
+    }
+  }
+
+  startSpan(name: string, attributes: Attributes = {}): Span {
+    const traceId = randomHex(16);
+    const spanId = randomHex(8);
+    const startMs = this.now();
+    let ended = false;
+    return {
+      traceId,
+      spanId,
+      end: (input = {}) => {
+        if (ended) {
+          return;
+        }
+        ended = true;
+        const errorAttributes = input.error ? errorToAttributes(input.error) : {};
+        this.exportSpan({
+          traceId,
+          spanId,
+          name,
+          startMs,
+          endMs: this.now(),
+          attributes: {
+            ...attributes,
+            ...input.attributes,
+            ...errorAttributes,
+          },
+          error: input.error,
+        });
+      },
+    };
+  }
+
+  recordHttpRequest(input: { method: string; route: string; status: number; durationSeconds: number }): void {
+    if (!this.settings.observabilityMetricsEnabled) {
+      return;
+    }
+    const labels = {
+      method: input.method,
+      route: input.route,
+      status: String(input.status),
+      component: this.options.component,
+    };
+    this.metrics.increment("opengeni_http_requests_total", labels);
+    this.metrics.observe("opengeni_http_request_duration_seconds", histogramBuckets, input.durationSeconds, {
+      method: input.method,
+      route: input.route,
+      component: this.options.component,
+    });
+  }
+
+  recordWorkerActivity(input: { activity: string; status: string; durationSeconds: number }): void {
+    if (!this.settings.observabilityMetricsEnabled) {
+      return;
+    }
+    const labels = {
+      activity: input.activity,
+      status: input.status,
+      component: this.options.component,
+    };
+    this.metrics.increment("opengeni_worker_activity_runs_total", labels);
+    this.metrics.observe("opengeni_worker_activity_duration_seconds", histogramBuckets, input.durationSeconds, {
+      activity: input.activity,
+      component: this.options.component,
+    });
+  }
+
+  prometheusMetrics(): string {
+    return this.metrics.toPrometheus({
+      service: this.settings.serviceName,
+      environment: this.settings.environment,
+      component: this.options.component,
+    });
+  }
+
+  private exportSpan(span: {
+    traceId: string;
+    spanId: string;
+    name: string;
+    startMs: number;
+    endMs: number;
+    attributes: Attributes;
+    error?: unknown;
+  }): void {
+    if (!this.settings.observabilityOtlpEndpoint) {
+      return;
+    }
+    const endpoint = `${this.settings.observabilityOtlpEndpoint.replace(/\/$/, "")}/v1/traces`;
+    const body = {
+      resourceSpans: [{
+        resource: {
+          attributes: otlpAttributes(this.resourceAttributes),
+        },
+        scopeSpans: [{
+          scope: {
+            name: "@opengeni/observability",
+            version: "0.1.0",
+          },
+          spans: [{
+            traceId: span.traceId,
+            spanId: span.spanId,
+            name: span.name,
+            kind: 1,
+            startTimeUnixNano: millisToNanos(span.startMs),
+            endTimeUnixNano: millisToNanos(span.endMs),
+            attributes: otlpAttributes(span.attributes),
+            status: span.error ? { code: 2, message: errorMessage(span.error) } : { code: 1 },
+          }],
+        }],
+      }],
+    };
+    void this.exporter(endpoint, body, parseHeaders(this.settings.observabilityOtlpHeaders)).catch((error) => {
+      this.warn("OTLP span export failed", { error: errorMessage(error), endpoint });
+    });
+  }
+}
+
+export type StartupDependencyRetryEvent = {
+  label: string;
+  attempt: number;
+  attempts: number;
+  delayMs: number;
+  error: unknown;
+};
+
+export function logStartupDependencyRetry(observability: Observability, event: StartupDependencyRetryEvent): void {
+  const message = event.error instanceof Error ? event.error.message : String(event.error);
+  observability.warn("Startup dependency connection failed; retrying", {
+    dependency: event.label,
+    attempt: event.attempt,
+    attempts: event.attempts,
+    delayMs: event.delayMs,
+    error: message,
+  });
+}
+
+class MetricsRegistry {
+  private readonly counters = new Map<string, number>();
+  private readonly histograms = new Map<string, { buckets: number[]; counts: number[]; sum: number; count: number; labels: Record<string, string> }>();
+
+  increment(name: string, labels: Record<string, string>, amount = 1): void {
+    const key = metricKey(name, labels);
+    this.counters.set(key, (this.counters.get(key) ?? 0) + amount);
+  }
+
+  observe(name: string, buckets: number[], value: number, labels: Record<string, string>): void {
+    const key = metricKey(name, labels);
+    const histogram = this.histograms.get(key) ?? {
+      buckets,
+      counts: buckets.map(() => 0),
+      sum: 0,
+      count: 0,
+      labels,
+    };
+    histogram.sum += value;
+    histogram.count += 1;
+    for (let index = 0; index < buckets.length; index += 1) {
+      if (value <= buckets[index]!) {
+        histogram.counts[index] = (histogram.counts[index] ?? 0) + 1;
+      }
+    }
+    this.histograms.set(key, histogram);
+  }
+
+  toPrometheus(resourceLabels: Record<string, string>): string {
+    const lines = [
+      "# HELP opengeni_http_requests_total Total HTTP requests handled by the OpenGeni API.",
+      "# TYPE opengeni_http_requests_total counter",
+    ];
+    for (const [key, value] of this.counters) {
+      const { name, labels } = parseMetricKey(key);
+      if (name.endsWith("_total")) {
+        lines.push(`${name}${formatLabels({ ...resourceLabels, ...labels })} ${value}`);
+      }
+    }
+    lines.push(
+      "# HELP opengeni_http_request_duration_seconds HTTP request duration in seconds.",
+      "# TYPE opengeni_http_request_duration_seconds histogram",
+      "# HELP opengeni_worker_activity_runs_total Total worker activity executions.",
+      "# TYPE opengeni_worker_activity_runs_total counter",
+      "# HELP opengeni_worker_activity_duration_seconds Worker activity duration in seconds.",
+      "# TYPE opengeni_worker_activity_duration_seconds histogram",
+    );
+    for (const [key, histogram] of this.histograms) {
+      const { name, labels } = parseMetricKey(key);
+      const baseLabels = { ...resourceLabels, ...labels };
+      for (let index = 0; index < histogram.buckets.length; index += 1) {
+        lines.push(`${name}_bucket${formatLabels({ ...baseLabels, le: String(histogram.buckets[index]) })} ${histogram.counts[index]}`);
+      }
+      lines.push(`${name}_bucket${formatLabels({ ...baseLabels, le: "+Inf" })} ${histogram.count}`);
+      lines.push(`${name}_sum${formatLabels(baseLabels)} ${histogram.sum}`);
+      lines.push(`${name}_count${formatLabels(baseLabels)} ${histogram.count}`);
+    }
+    return `${lines.join("\n")}\n`;
+  }
+}
+
+function metricKey(name: string, labels: Record<string, string>): string {
+  return JSON.stringify({ name, labels: Object.fromEntries(Object.entries(labels).sort(([a], [b]) => a.localeCompare(b))) });
+}
+
+function parseMetricKey(key: string): { name: string; labels: Record<string, string> } {
+  return JSON.parse(key) as { name: string; labels: Record<string, string> };
+}
+
+function formatLabels(labels: Record<string, string>): string {
+  const entries = Object.entries(labels).filter(([, value]) => value.length > 0);
+  if (entries.length === 0) {
+    return "";
+  }
+  return `{${entries.map(([key, value]) => `${key}="${escapeMetricLabel(value)}"`).join(",")}}`;
+}
+
+function escapeMetricLabel(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n");
+}
+
+function cleanAttributes(attributes: Attributes): Record<string, string | number | boolean | null> {
+  return Object.fromEntries(Object.entries(attributes).filter(([, value]) => value !== undefined)) as Record<string, string | number | boolean | null>;
+}
+
+function errorToAttributes(error: unknown): Attributes {
+  return {
+    "error.type": error instanceof Error ? error.name : "Error",
+    "error.message": errorMessage(error),
+  };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function otlpAttributes(attributes: Attributes): Array<{ key: string; value: Record<string, string | number | boolean> }> {
+  return Object.entries(cleanAttributes(attributes)).map(([key, value]) => ({
+    key,
+    value: otlpValue(value),
+  }));
+}
+
+function otlpValue(value: string | number | boolean | null): Record<string, string | number | boolean> {
+  if (typeof value === "number") {
+    return Number.isInteger(value) ? { intValue: value } : { doubleValue: value };
+  }
+  if (typeof value === "boolean") {
+    return { boolValue: value };
+  }
+  return { stringValue: value === null ? "" : value };
+}
+
+function millisToNanos(ms: number): string {
+  return String(BigInt(Math.round(ms)) * 1_000_000n);
+}
+
+function randomHex(bytes: number): string {
+  const values = crypto.getRandomValues(new Uint8Array(bytes));
+  return Array.from(values, (value) => value.toString(16).padStart(2, "0")).join("");
+}
+
+export function parseHeaders(value: string): Record<string, string> {
+  if (!value.trim()) {
+    return {};
+  }
+  const entries: Array<[string, string]> = value.split(",").map((pair): [string, string] => {
+    const separator = pair.indexOf("=");
+    if (separator === -1) {
+      return [pair.trim(), ""];
+    }
+    return [pair.slice(0, separator).trim(), pair.slice(separator + 1).trim()];
+  }).filter(([key]) => key.length > 0);
+  return Object.fromEntries(entries);
+}
+
+async function defaultExporter(url: string, body: unknown, headers: Record<string, string>): Promise<void> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...headers,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok) {
+    throw new Error(`OTLP endpoint returned HTTP ${response.status}`);
+  }
+}