@photon-ai/otel 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# @photon-ai/otel
+
+A DX-focused OpenTelemetry wrapper for **Bun** and **Node.js**.
+
+Vanilla OTel works, but the setup is verbose, the logger plumbing is awkward, and PII scrubbing is on you. `@photon-ai/otel` wraps the OTLP/HTTP stack into a few well-named functions:
+
+- **`setupOtel()`** — idempotent one-call bootstrap for traces + logs. Honors all standard `OTEL_EXPORTER_OTLP_*` env vars.
+- **`createLogger(module)`** — structured logger that writes to both the OTel logger provider and `console`, with automatic trace correlation and exception capture.
+- **`withSpan(name, attrs?, fn)`** — wrap any sync or async function in a span; errors are recorded and PII in the error message is scrubbed before being attached to span status.
+- **`sanitizeEmail` / `sanitizePhone` / `sanitizeErrorMessage`** — PII helpers you can reuse anywhere.
+
+OTLP/HTTP only (no gRPC, no proto). Works identically on Bun and Node ≥ 20.
+
+## Install
+
+```bash
+bun add @photon-ai/otel
+# or
+npm install @photon-ai/otel
+```
+
+## Quick start
+
+```ts
+import { createLogger, setupOtel, withSpan } from "@photon-ai/otel";
+
+setupOtel({
+  serviceName: "my-service",
+  serviceVersion: "1.0.0",
+  endpoint: "https://otel.example.com", // optional; env var wins
+});
+
+const log = createLogger("server");
+
+await withSpan("handle-request", { route: "/users" }, async () => {
+  log.info("processing request", { userId: 42 });
+  // ... your work
+});
+```
+
+If `OTEL_EXPORTER_OTLP_ENDPOINT` (or the `endpoint` option) is unset, `setupOtel()` still runs but exporters are no-ops — perfect for local development with zero config.
+
+## API
+
+| Function                                      | Description                                                                                                |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `setupOtel(options): OtelHandle`              | Boots OTLP/HTTP traces + logs. Idempotent. Returns `{ shutdown(): Promise<void> }`.                        |
+| `isOtelActive(): boolean`                     | Returns `true` if `setupOtel` has already run in this process.                                             |
+| `createLogger(module): PhotonLogger`          | Returns `{ info, warn, error, debug }`. Each call emits to OTel + `console`, correlates to active span.    |
+| `withSpan(name, fn)`                          | Wraps `fn` (sync or async) in a span. Records exceptions and scrubs PII in error messages.                 |
+| `withSpan(name, attrs, fn)`                   | Same as above but attaches `attrs` to the span.                                                            |
+| `sanitizeEmail(input)`                        | Masks an email: `foo.bar@example.com` → `fo***@e***.com`.                                                  |
+| `sanitizePhone(input)`                        | Masks a phone: `+13315553374` → `+133xxxxx3374`.                                                           |
+| `sanitizeErrorMessage(input)`                 | Masks every email and phone embedded in a free-form string.                                                |
+| `PHOTON_OTEL_VERSION`                         | Constant — current package version.                                                                        |
+
+### Logger signatures
+
+```ts
+log.info(message, attrs?);
+log.warn(message, attrs?);
+log.error(message, attrs?, error?); // only error() accepts an exception
+log.debug(message, attrs?);
+```
+
+`attrs` is `Record<string, string | number | boolean | undefined>`. `undefined` values are dropped.
+
+## Configuration
+
+Standard OpenTelemetry env vars always take precedence over `SetupOtelOptions`:
+
+| Variable                                  | Effect                                                  |
+| ----------------------------------------- | ------------------------------------------------------- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`             | Base endpoint; `/v1/traces` and `/v1/logs` auto-appended. |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`      | Full traces URL (overrides the base for traces).        |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`        | Full logs URL (overrides the base for logs).            |
+| `OTEL_EXPORTER_OTLP_HEADERS`              | `key=value,key=value` headers; merged with `options.headers` (env wins). |
+| `DEPLOYMENT_ENV`                          | Attached as `deployment.environment` resource attribute. Defaults to `development`. |
+
+## Running on Node vs Bun
+
+The same code runs unmodified on both. Pick whichever you prefer:
+
+```bash
+bun run src/server.ts
+# or
+node --experimental-strip-types src/server.ts
+```
+
+The package uses `process.env` (not `Bun.env`) and `AsyncLocalStorageContextManager` (backed by `async_hooks`), both of which are supported natively by Bun and Node ≥ 20.
+
+For Bun consumers, the `exports` map points at the TypeScript source via the `bun` condition for faster cold starts during dev. Node consumers get the pre-built ESM bundle.
+
+## Why HTTP exporters only?
+
+- Bun's gRPC support is incomplete in some paths — HTTP is reliable everywhere.
+- JSON-over-HTTP is trivial to debug with `curl` and a packet sniffer.
+- One fewer transport keeps the dependency surface small.
+
+If you need gRPC, instantiate your own exporter and processor with `@opentelemetry/api` directly — `setupOtel()` is opinionated, not a wall.
+
+## Framework integration
+
+This package is framework-agnostic. For Elysia.js (Bun-native), see the [`elysiajs-otel` skill](https://github.com/anthropics/claude-code) for a recipe combining `@photon-ai/otel` with `@elysiajs/opentelemetry` auto-instrumentation. A dedicated `@photon-ai/otel-elysia` package may follow.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+type LogAttrs = Record<string, string | number | boolean | undefined>;
+interface PhotonLogger {
+    debug(message: string, attrs?: LogAttrs): void;
+    error(message: string, attrs?: LogAttrs, error?: unknown): void;
+    info(message: string, attrs?: LogAttrs): void;
+    warn(message: string, attrs?: LogAttrs): void;
+}
+declare function createLogger(module: string): PhotonLogger;
+
+/**
+ * Mask a phone number, keeping the leading `+` (if any) plus the first 3 digits
+ * and the last 4 digits visible. Example: `+13315553374` -> `+133xxxxx3374`.
+ *
+ * Inputs that don't have enough digits to safely mask are returned as
+ * `xxxx` to avoid leaking the entire short value.
+ */
+declare function sanitizePhone(input: string): string;
+/**
+ * Mask an email address, keeping the first 2 chars of the local part, the
+ * first char of the domain, and the TLD. Example:
+ * `foo.bar@example.com` -> `fo***@e***.com`.
+ */
+declare function sanitizeEmail(input: string): string;
+/**
+ * Replace every phone number and email address inside a free-form string with
+ * its sanitized form. Used to scrub `Error.message` values before attaching
+ * them to span status.
+ */
+declare function sanitizeErrorMessage(input: string): string;
+
+interface SetupOtelOptions {
+    /**
+     * Default OTLP/HTTP base endpoint (e.g. `https://otel.example.com`). The
+     * `/v1/traces` and `/v1/logs` paths are appended automatically. Standard
+     * `OTEL_EXPORTER_OTLP_*` env vars always take precedence.
+     */
+    endpoint?: string;
+    /**
+     * Default OTLP headers (e.g. `{ Authorization: "Basic ..." }`). Merged with
+     * any headers parsed from `OTEL_EXPORTER_OTLP_HEADERS`; env values win on
+     * conflicts.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Extra resource attributes attached to every span/log alongside
+     * `service.name` / `service.version`.
+     */
+    resourceAttributes?: Record<string, string | number | boolean>;
+    serviceName: string;
+    serviceVersion?: string;
+}
+interface OtelHandle {
+    shutdown(): Promise<void>;
+}
+/**
+ * Boot an OTLP/HTTP-based OpenTelemetry pipeline (traces + logs).
+ *
+ * Idempotent: calling twice in the same process is a no-op on the second
+ * call, so libraries can safely invoke this without clobbering an app-level
+ * OTel setup that ran earlier.
+ *
+ * Standard `OTEL_EXPORTER_OTLP_*` env vars override the `endpoint` and
+ * `headers` arguments — this matches the OpenTelemetry SDK config spec.
+ */
+declare function setupOtel(options: SetupOtelOptions): OtelHandle;
+/**
+ * Read-only accessor for tests / debug paths that need to know whether
+ * `setupOtel` has already run in this process.
+ */
+declare function isOtelActive(): boolean;
+
+declare const PHOTON_OTEL_VERSION = "0.1.0";
+
+declare function withSpan<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+declare function withSpan<T>(name: string, attrs: LogAttrs, fn: () => Promise<T> | T): Promise<T>;
+
+export { type LogAttrs, type OtelHandle, PHOTON_OTEL_VERSION, type PhotonLogger, type SetupOtelOptions, createLogger, isOtelActive, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, setupOtel, withSpan };

package/dist/index.js

@@ -0,0 +1,267 @@
+// src/logger.ts
+import { context as otelContext } from "@opentelemetry/api";
+import { logs, SeverityNumber } from "@opentelemetry/api-logs";
+
+// src/version.ts
+var PHOTON_OTEL_VERSION = "0.1.0";
+
+// src/logger.ts
+var scopedLogger;
+function getLogger() {
+  if (!scopedLogger) {
+    scopedLogger = logs.getLogger("@photon-ai/otel", PHOTON_OTEL_VERSION);
+  }
+  return scopedLogger;
+}
+function filterUndefined(attrs) {
+  if (!attrs) {
+    return {};
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v !== void 0) {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+function emit(severityNumber, severityText, module, message, attrs, error) {
+  const attributes = {
+    "log.module": module,
+    ...filterUndefined(attrs)
+  };
+  if (error instanceof Error) {
+    attributes["exception.type"] = error.name;
+    attributes["exception.message"] = error.message;
+    if (error.stack) {
+      attributes["exception.stacktrace"] = error.stack;
+    }
+  }
+  getLogger().emit({
+    severityNumber,
+    severityText,
+    body: message,
+    attributes,
+    context: otelContext.active()
+  });
+  const prefix = `[${module}]`;
+  if (severityNumber >= SeverityNumber.ERROR) {
+    console.error(prefix, message, ...error ? [error] : []);
+  } else {
+    console.log(prefix, message);
+  }
+}
+function createLogger(module) {
+  return {
+    info: (message, attrs) => emit(SeverityNumber.INFO, "INFO", module, message, attrs),
+    warn: (message, attrs) => emit(SeverityNumber.WARN, "WARN", module, message, attrs),
+    error: (message, attrs, error) => emit(SeverityNumber.ERROR, "ERROR", module, message, attrs, error),
+    debug: (message, attrs) => emit(SeverityNumber.DEBUG, "DEBUG", module, message, attrs)
+  };
+}
+
+// src/sanitize.ts
+var PHONE_PATTERN = /\+?\d[\d\s()\-.]{6,18}\d/g;
+var EMAIL_PATTERN = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+function sanitizePhone(input) {
+  const hasPlus = input.startsWith("+");
+  const digits = input.replace(/\D/g, "");
+  if (digits.length < 8) {
+    return hasPlus ? "+xxxx" : "xxxx";
+  }
+  const head = digits.slice(0, 3);
+  const tail = digits.slice(-4);
+  const middleLength = digits.length - head.length - tail.length;
+  return `${hasPlus ? "+" : ""}${head}${"x".repeat(middleLength)}${tail}`;
+}
+function sanitizeEmail(input) {
+  const atIndex = input.lastIndexOf("@");
+  if (atIndex < 1) {
+    return "***";
+  }
+  const local = input.slice(0, atIndex);
+  const domain = input.slice(atIndex + 1);
+  const dotIndex = domain.lastIndexOf(".");
+  if (dotIndex < 1) {
+    return "***";
+  }
+  const localHead = local.slice(0, 2);
+  const domainHead = domain.slice(0, 1);
+  const tld = domain.slice(dotIndex);
+  return `${localHead}***@${domainHead}***${tld}`;
+}
+function sanitizeErrorMessage(input) {
+  return input.replace(EMAIL_PATTERN, (match) => sanitizeEmail(match)).replace(PHONE_PATTERN, (match) => sanitizePhone(match));
+}
+
+// src/setup.ts
+import { context, trace } from "@opentelemetry/api";
+import { logs as logs2 } from "@opentelemetry/api-logs";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+  BatchLogRecordProcessor,
+  LoggerProvider
+} from "@opentelemetry/sdk-logs";
+import {
+  BasicTracerProvider,
+  BatchSpanProcessor
+} from "@opentelemetry/sdk-trace-base";
+var activeHandle;
+var TRAILING_SLASH = /\/$/;
+function parseEnvHeaders(raw) {
+  if (!raw) {
+    return {};
+  }
+  const out = {};
+  for (const pair of raw.split(",")) {
+    const eq = pair.indexOf("=");
+    if (eq <= 0) {
+      continue;
+    }
+    const key = pair.slice(0, eq).trim();
+    const value = pair.slice(eq + 1).trim();
+    if (key) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function resolveTracesEndpoint(base) {
+  const traces = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;
+  if (traces) {
+    return traces;
+  }
+  const generic = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? base;
+  return generic ? `${generic.replace(TRAILING_SLASH, "")}/v1/traces` : void 0;
+}
+function resolveLogsEndpoint(base) {
+  const logsEndpoint = process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT;
+  if (logsEndpoint) {
+    return logsEndpoint;
+  }
+  const generic = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? base;
+  return generic ? `${generic.replace(TRAILING_SLASH, "")}/v1/logs` : void 0;
+}
+function setupOtel(options) {
+  if (activeHandle) {
+    return activeHandle;
+  }
+  const tracesEndpoint = resolveTracesEndpoint(options.endpoint);
+  const logsEndpoint = resolveLogsEndpoint(options.endpoint);
+  const mergedHeaders = {
+    ...options.headers,
+    ...parseEnvHeaders(process.env.OTEL_EXPORTER_OTLP_HEADERS)
+  };
+  const hasHeaders = Object.keys(mergedHeaders).length > 0;
+  const resource = resourceFromAttributes({
+    "service.name": options.serviceName,
+    ...options.serviceVersion ? { "service.version": options.serviceVersion } : {},
+    "deployment.environment": process.env.DEPLOYMENT_ENV ?? "development",
+    ...options.resourceAttributes
+  });
+  context.setGlobalContextManager(new AsyncLocalStorageContextManager());
+  const traceProcessors = tracesEndpoint ? [
+    new BatchSpanProcessor(
+      new OTLPTraceExporter({
+        url: tracesEndpoint,
+        headers: hasHeaders ? mergedHeaders : void 0
+      })
+    )
+  ] : [];
+  const tracerProvider = new BasicTracerProvider({
+    resource,
+    spanProcessors: traceProcessors
+  });
+  trace.setGlobalTracerProvider(tracerProvider);
+  const logProcessors = logsEndpoint ? [
+    new BatchLogRecordProcessor(
+      new OTLPLogExporter({
+        url: logsEndpoint,
+        headers: hasHeaders ? mergedHeaders : void 0
+      })
+    )
+  ] : [];
+  const loggerProvider = new LoggerProvider({
+    resource,
+    processors: logProcessors
+  });
+  logs2.setGlobalLoggerProvider(loggerProvider);
+  const handle = {
+    async shutdown() {
+      await Promise.allSettled([
+        tracerProvider.shutdown(),
+        loggerProvider.shutdown()
+      ]);
+      activeHandle = void 0;
+    }
+  };
+  activeHandle = handle;
+  return handle;
+}
+function isOtelActive() {
+  return activeHandle !== void 0;
+}
+
+// src/with-span.ts
+import {
+  SpanStatusCode,
+  trace as trace2
+} from "@opentelemetry/api";
+var scopedTracer;
+function getTracer() {
+  if (!scopedTracer) {
+    scopedTracer = trace2.getTracer("@photon-ai/otel", PHOTON_OTEL_VERSION);
+  }
+  return scopedTracer;
+}
+function toAttributes(attrs) {
+  const out = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v !== void 0) {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+function withSpan(name, attrsOrFn, maybeFn) {
+  const fn = typeof attrsOrFn === "function" ? attrsOrFn : maybeFn;
+  if (!fn) {
+    throw new Error("withSpan: function argument is required");
+  }
+  const attrs = typeof attrsOrFn === "function" ? void 0 : attrsOrFn;
+  return getTracer().startActiveSpan(name, async (span) => {
+    if (attrs) {
+      span.setAttributes(toAttributes(attrs));
+    }
+    try {
+      const result = await fn();
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (err) {
+      span.recordException(err);
+      const errorObj = err instanceof Error ? err : void 0;
+      span.setAttribute("error.type", errorObj?.constructor.name ?? typeof err);
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: errorObj ? sanitizeErrorMessage(errorObj.message) : sanitizeErrorMessage(String(err))
+      });
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}
+export {
+  PHOTON_OTEL_VERSION,
+  createLogger,
+  isOtelActive,
+  sanitizeEmail,
+  sanitizeErrorMessage,
+  sanitizePhone,
+  setupOtel,
+  withSpan
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/logger.ts","../src/version.ts","../src/sanitize.ts","../src/setup.ts","../src/with-span.ts"],"sourcesContent":["import { context as otelContext } from \"@opentelemetry/api\";\nimport { type Logger, logs, SeverityNumber } from \"@opentelemetry/api-logs\";\nimport { PHOTON_OTEL_VERSION } from \"./version\";\n\nexport type LogAttrs = Record<string, string | number | boolean | undefined>;\n\nlet scopedLogger: Logger | undefined;\n\nfunction getLogger(): Logger {\n  if (!scopedLogger) {\n    scopedLogger = logs.getLogger(\"@photon-ai/otel\", PHOTON_OTEL_VERSION);\n  }\n  return scopedLogger;\n}\n\nfunction filterUndefined(\n  attrs?: LogAttrs\n): Record<string, string | number | boolean> {\n  if (!attrs) {\n    return {};\n  }\n  const out: Record<string, string | number | boolean> = {};\n  for (const [k, v] of Object.entries(attrs)) {\n    if (v !== undefined) {\n      out[k] = v;\n    }\n  }\n  return out;\n}\n\nfunction emit(\n  severityNumber: SeverityNumber,\n  severityText: string,\n  module: string,\n  message: string,\n  attrs?: LogAttrs,\n  error?: unknown\n): void {\n  const attributes: Record<string, string | number | boolean> = {\n    \"log.module\": module,\n    ...filterUndefined(attrs),\n  };\n\n  if (error instanceof Error) {\n    attributes[\"exception.type\"] = error.name;\n    attributes[\"exception.message\"] = error.message;\n    if (error.stack) {\n      attributes[\"exception.stacktrace\"] = error.stack;\n    }\n  }\n\n  getLogger().emit({\n    severityNumber,\n    severityText,\n    body: message,\n    attributes,\n    context: otelContext.active(),\n  });\n\n  const prefix = `[${module}]`;\n  if (severityNumber >= SeverityNumber.ERROR) {\n    console.error(prefix, message, ...(error ? [error] : []));\n  } else {\n    console.log(prefix, message);\n  }\n}\n\nexport interface PhotonLogger {\n  debug(message: string, attrs?: LogAttrs): void;\n  error(message: string, attrs?: LogAttrs, error?: unknown): void;\n  info(message: string, attrs?: LogAttrs): void;\n  warn(message: string, attrs?: LogAttrs): void;\n}\n\nexport function createLogger(module: string): PhotonLogger {\n  return {\n    info: (message, attrs) =>\n      emit(SeverityNumber.INFO, \"INFO\", module, message, attrs),\n    warn: (message, attrs) =>\n      emit(SeverityNumber.WARN, \"WARN\", module, message, attrs),\n    error: (message, attrs, error) =>\n      emit(SeverityNumber.ERROR, \"ERROR\", module, message, attrs, error),\n    debug: (message, attrs) =>\n      emit(SeverityNumber.DEBUG, \"DEBUG\", module, message, attrs),\n  };\n}\n","export const PHOTON_OTEL_VERSION = \"0.1.0\";\n","// E.164-ish phone match: optional `+`, 7–15 digits with optional separators.\nconst PHONE_PATTERN = /\\+?\\d[\\d\\s()\\-.]{6,18}\\d/g;\nconst EMAIL_PATTERN = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}/g;\n\n/**\n * Mask a phone number, keeping the leading `+` (if any) plus the first 3 digits\n * and the last 4 digits visible. Example: `+13315553374` -> `+133xxxxx3374`.\n *\n * Inputs that don't have enough digits to safely mask are returned as\n * `xxxx` to avoid leaking the entire short value.\n */\nexport function sanitizePhone(input: string): string {\n  const hasPlus = input.startsWith(\"+\");\n  const digits = input.replace(/\\D/g, \"\");\n  if (digits.length < 8) {\n    return hasPlus ? \"+xxxx\" : \"xxxx\";\n  }\n  const head = digits.slice(0, 3);\n  const tail = digits.slice(-4);\n  const middleLength = digits.length - head.length - tail.length;\n  return `${hasPlus ? \"+\" : \"\"}${head}${\"x\".repeat(middleLength)}${tail}`;\n}\n\n/**\n * Mask an email address, keeping the first 2 chars of the local part, the\n * first char of the domain, and the TLD. Example:\n * `foo.bar@example.com` -> `fo***@e***.com`.\n */\nexport function sanitizeEmail(input: string): string {\n  const atIndex = input.lastIndexOf(\"@\");\n  if (atIndex < 1) {\n    return \"***\";\n  }\n  const local = input.slice(0, atIndex);\n  const domain = input.slice(atIndex + 1);\n  const dotIndex = domain.lastIndexOf(\".\");\n  if (dotIndex < 1) {\n    return \"***\";\n  }\n  const localHead = local.slice(0, 2);\n  const domainHead = domain.slice(0, 1);\n  const tld = domain.slice(dotIndex);\n  return `${localHead}***@${domainHead}***${tld}`;\n}\n\n/**\n * Replace every phone number and email address inside a free-form string with\n * its sanitized form. Used to scrub `Error.message` values before attaching\n * them to span status.\n */\nexport function sanitizeErrorMessage(input: string): string {\n  return input\n    .replace(EMAIL_PATTERN, (match) => sanitizeEmail(match))\n    .replace(PHONE_PATTERN, (match) => sanitizePhone(match));\n}\n","import { context, trace } from \"@opentelemetry/api\";\nimport { logs } from \"@opentelemetry/api-logs\";\nimport { AsyncLocalStorageContextManager } from \"@opentelemetry/context-async-hooks\";\nimport { OTLPLogExporter } from \"@opentelemetry/exporter-logs-otlp-http\";\nimport { OTLPTraceExporter } from \"@opentelemetry/exporter-trace-otlp-http\";\nimport { resourceFromAttributes } from \"@opentelemetry/resources\";\nimport {\n  BatchLogRecordProcessor,\n  LoggerProvider,\n} from \"@opentelemetry/sdk-logs\";\nimport {\n  BasicTracerProvider,\n  BatchSpanProcessor,\n} from \"@opentelemetry/sdk-trace-base\";\n\nexport interface SetupOtelOptions {\n  /**\n   * Default OTLP/HTTP base endpoint (e.g. `https://otel.example.com`). The\n   * `/v1/traces` and `/v1/logs` paths are appended automatically. Standard\n   * `OTEL_EXPORTER_OTLP_*` env vars always take precedence.\n   */\n  endpoint?: string;\n  /**\n   * Default OTLP headers (e.g. `{ Authorization: \"Basic ...\" }`). Merged with\n   * any headers parsed from `OTEL_EXPORTER_OTLP_HEADERS`; env values win on\n   * conflicts.\n   */\n  headers?: Record<string, string>;\n  /**\n   * Extra resource attributes attached to every span/log alongside\n   * `service.name` / `service.version`.\n   */\n  resourceAttributes?: Record<string, string | number | boolean>;\n  serviceName: string;\n  serviceVersion?: string;\n}\n\nexport interface OtelHandle {\n  shutdown(): Promise<void>;\n}\n\nlet activeHandle: OtelHandle | undefined;\n\nconst TRAILING_SLASH = /\\/$/;\n\nfunction parseEnvHeaders(raw: string | undefined): Record<string, string> {\n  if (!raw) {\n    return {};\n  }\n  const out: Record<string, string> = {};\n  for (const pair of raw.split(\",\")) {\n    const eq = pair.indexOf(\"=\");\n    if (eq <= 0) {\n      continue;\n    }\n    const key = pair.slice(0, eq).trim();\n    const value = pair.slice(eq + 1).trim();\n    if (key) {\n      out[key] = value;\n    }\n  }\n  return out;\n}\n\nfunction resolveTracesEndpoint(base: string | undefined): string | undefined {\n  const traces = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT;\n  if (traces) {\n    return traces;\n  }\n  const generic = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? base;\n  return generic\n    ? `${generic.replace(TRAILING_SLASH, \"\")}/v1/traces`\n    : undefined;\n}\n\nfunction resolveLogsEndpoint(base: string | undefined): string | undefined {\n  const logsEndpoint = process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT;\n  if (logsEndpoint) {\n    return logsEndpoint;\n  }\n  const generic = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? base;\n  return generic ? `${generic.replace(TRAILING_SLASH, \"\")}/v1/logs` : undefined;\n}\n\n/**\n * Boot an OTLP/HTTP-based OpenTelemetry pipeline (traces + logs).\n *\n * Idempotent: calling twice in the same process is a no-op on the second\n * call, so libraries can safely invoke this without clobbering an app-level\n * OTel setup that ran earlier.\n *\n * Standard `OTEL_EXPORTER_OTLP_*` env vars override the `endpoint` and\n * `headers` arguments — this matches the OpenTelemetry SDK config spec.\n */\nexport function setupOtel(options: SetupOtelOptions): OtelHandle {\n  if (activeHandle) {\n    return activeHandle;\n  }\n\n  const tracesEndpoint = resolveTracesEndpoint(options.endpoint);\n  const logsEndpoint = resolveLogsEndpoint(options.endpoint);\n  const mergedHeaders = {\n    ...options.headers,\n    ...parseEnvHeaders(process.env.OTEL_EXPORTER_OTLP_HEADERS),\n  };\n  const hasHeaders = Object.keys(mergedHeaders).length > 0;\n\n  const resource = resourceFromAttributes({\n    \"service.name\": options.serviceName,\n    ...(options.serviceVersion\n      ? { \"service.version\": options.serviceVersion }\n      : {}),\n    \"deployment.environment\": process.env.DEPLOYMENT_ENV ?? \"development\",\n    ...options.resourceAttributes,\n  });\n\n  context.setGlobalContextManager(new AsyncLocalStorageContextManager());\n\n  const traceProcessors = tracesEndpoint\n    ? [\n        new BatchSpanProcessor(\n          new OTLPTraceExporter({\n            url: tracesEndpoint,\n            headers: hasHeaders ? mergedHeaders : undefined,\n          })\n        ),\n      ]\n    : [];\n\n  const tracerProvider = new BasicTracerProvider({\n    resource,\n    spanProcessors: traceProcessors,\n  });\n  trace.setGlobalTracerProvider(tracerProvider);\n\n  const logProcessors = logsEndpoint\n    ? [\n        new BatchLogRecordProcessor(\n          new OTLPLogExporter({\n            url: logsEndpoint,\n            headers: hasHeaders ? mergedHeaders : undefined,\n          })\n        ),\n      ]\n    : [];\n\n  const loggerProvider = new LoggerProvider({\n    resource,\n    processors: logProcessors,\n  });\n  logs.setGlobalLoggerProvider(loggerProvider);\n\n  const handle: OtelHandle = {\n    async shutdown() {\n      await Promise.allSettled([\n        tracerProvider.shutdown(),\n        loggerProvider.shutdown(),\n      ]);\n      activeHandle = undefined;\n    },\n  };\n\n  activeHandle = handle;\n  return handle;\n}\n\n/**\n * Read-only accessor for tests / debug paths that need to know whether\n * `setupOtel` has already run in this process.\n */\nexport function isOtelActive(): boolean {\n  return activeHandle !== undefined;\n}\n","import {\n  type Attributes,\n  SpanStatusCode,\n  type Tracer,\n  trace,\n} from \"@opentelemetry/api\";\nimport type { LogAttrs } from \"./logger\";\nimport { sanitizeErrorMessage } from \"./sanitize\";\nimport { PHOTON_OTEL_VERSION } from \"./version\";\n\nlet scopedTracer: Tracer | undefined;\n\nfunction getTracer(): Tracer {\n  if (!scopedTracer) {\n    scopedTracer = trace.getTracer(\"@photon-ai/otel\", PHOTON_OTEL_VERSION);\n  }\n  return scopedTracer;\n}\n\nfunction toAttributes(attrs: LogAttrs): Attributes {\n  const out: Attributes = {};\n  for (const [k, v] of Object.entries(attrs)) {\n    if (v !== undefined) {\n      out[k] = v;\n    }\n  }\n  return out;\n}\n\nexport function withSpan<T>(name: string, fn: () => Promise<T> | T): Promise<T>;\nexport function withSpan<T>(\n  name: string,\n  attrs: LogAttrs,\n  fn: () => Promise<T> | T\n): Promise<T>;\nexport function withSpan<T>(\n  name: string,\n  attrsOrFn: LogAttrs | (() => Promise<T> | T),\n  maybeFn?: () => Promise<T> | T\n): Promise<T> {\n  const fn = typeof attrsOrFn === \"function\" ? attrsOrFn : maybeFn;\n  if (!fn) {\n    throw new Error(\"withSpan: function argument is required\");\n  }\n  const attrs = typeof attrsOrFn === \"function\" ? undefined : attrsOrFn;\n\n  return getTracer().startActiveSpan(name, async (span) => {\n    if (attrs) {\n      span.setAttributes(toAttributes(attrs));\n    }\n    try {\n      const result = await fn();\n      span.setStatus({ code: SpanStatusCode.OK });\n      return result;\n    } catch (err) {\n      span.recordException(err as Error);\n      const errorObj = err instanceof Error ? err : undefined;\n      span.setAttribute(\"error.type\", errorObj?.constructor.name ?? typeof err);\n      span.setStatus({\n        code: SpanStatusCode.ERROR,\n        message: errorObj\n          ? sanitizeErrorMessage(errorObj.message)\n          : sanitizeErrorMessage(String(err)),\n      });\n      throw err;\n    } finally {\n      span.end();\n    }\n  });\n}\n"],"mappings":"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","names":["logs","trace","trace"]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@photon-ai/otel",
+  "version": "0.1.0",
+  "description": "DX-focused OpenTelemetry wrapper for Bun and Node.js: one-call setup, structured logging, span helper, and built-in PII scrubbing.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.216.0",
+    "@opentelemetry/context-async-hooks": "^2.7.1",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.216.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.216.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-logs": "^0.216.0",
+    "@opentelemetry/sdk-trace-base": "^2.7.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.15",
+    "@types/bun": "latest",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.4.0",
+    "ultracite": "7.7.0",
+    "vitest": "^2.1.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5 || ^6.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "opentelemetry",
+    "otel",
+    "tracing",
+    "logging",
+    "observability",
+    "bun",
+    "nodejs",
+    "otlp"
+  ]
+}