@lunora/container 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/otel.d.mts

@@ -61,6 +61,20 @@ interface ContainerLogInput {
  * @experimental
  */
 interface ContainerTelemetryOptions {
+  /**
+   * Value of the `deployment.environment` resource attribute. Falls back to
+   * the `DEPLOYMENT_ENVIRONMENT` / `ENVIRONMENT` / `NODE_ENV` env vars **only
+   * when {@link ContainerTelemetryOptions.detectResources} is `true`** —
+   * unlike `serviceName`, env detection here is opt-in so a stray `NODE_ENV`
+   * never silently labels a deployment.
+   */
+  deploymentEnvironment?: string;
+  /**
+   * When `true`, auto-detect OTLP resource attributes from the container
+   * environment (`HOSTNAME`, `KUBERNETES_*`, `SERVICE_VERSION`, etc.).
+   * Explicit options and `resourceAttributes` win on collision.
+   */
+  detectResources?: boolean;
   /** Base OTLP collector endpoint; defaults to the `LUNORA_OTLP_ENDPOINT` env var. */
   endpoint?: string;
   /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
@@ -69,8 +83,17 @@ interface ContainerTelemetryOptions {
   headers?: Record<string, string>;
   /** Called with any send failure so the caller can surface it; the export itself always swallows. */
   onError?: (error: unknown) => void;
+  /** Additional resource attributes merged onto every signal. */
+  resourceAttributes?: Record<string, ContainerAttributeValue>;
   /** `service.name` resource attribute; defaults to the `LUNORA_SERVICE_NAME` env var then `"lunora-container"`. */
   serviceName?: string;
+  /**
+   * `service.version` resource attribute. Falls back to `SERVICE_VERSION` /
+   * `CF_VERSION_METADATA` / `VERCEL_GIT_COMMIT_SHA` / `GITHUB_SHA` /
+   * `COMMIT_SHA` env vars **only when
+   * {@link ContainerTelemetryOptions.detectResources} is `true`**.
+   */
+  serviceVersion?: string;
   /** Per-POST timeout in ms; a collector that never responds aborts after this so a stuck send can't stall `flush()`. Defaults to {@link DEFAULT_TIMEOUT_MS} (10s). */
   timeoutMs?: number;
   /** Bearer token sent as an `Authorization: Bearer` header; defaults to the `LUNORA_OTLP_TOKEN` env var. */
@@ -128,7 +151,10 @@ interface ContainerTelemetry {
  * With no endpoint resolvable the returned exporter is disabled (`enabled ===
  * false`): `emitSpan`/`emitLog` no-op and `trace` still runs its work but records
  * nothing — so the same code runs unchanged locally and in the cloud.
- * @param options Exporter options; every field falls back to a `LUNORA_*` env var.
+ * @param options Exporter options. Connection fields (`endpoint`, `token`,
+ * `serviceName`, `traceparent`) always fall back to their `LUNORA_*` env var;
+ * resource fields (`serviceVersion`, `deploymentEnvironment`) only do so under
+ * `detectResources: true`.
  * @experimental
  */
 declare const createContainerTelemetry: (options?: ContainerTelemetryOptions) => ContainerTelemetry;

package/dist/otel.d.ts

@@ -61,6 +61,20 @@ interface ContainerLogInput {
  * @experimental
  */
 interface ContainerTelemetryOptions {
+  /**
+   * Value of the `deployment.environment` resource attribute. Falls back to
+   * the `DEPLOYMENT_ENVIRONMENT` / `ENVIRONMENT` / `NODE_ENV` env vars **only
+   * when {@link ContainerTelemetryOptions.detectResources} is `true`** —
+   * unlike `serviceName`, env detection here is opt-in so a stray `NODE_ENV`
+   * never silently labels a deployment.
+   */
+  deploymentEnvironment?: string;
+  /**
+   * When `true`, auto-detect OTLP resource attributes from the container
+   * environment (`HOSTNAME`, `KUBERNETES_*`, `SERVICE_VERSION`, etc.).
+   * Explicit options and `resourceAttributes` win on collision.
+   */
+  detectResources?: boolean;
   /** Base OTLP collector endpoint; defaults to the `LUNORA_OTLP_ENDPOINT` env var. */
   endpoint?: string;
   /** Injectable `fetch` (tests / non-global runtimes). Defaults to `globalThis.fetch`. */
@@ -69,8 +83,17 @@ interface ContainerTelemetryOptions {
   headers?: Record<string, string>;
   /** Called with any send failure so the caller can surface it; the export itself always swallows. */
   onError?: (error: unknown) => void;
+  /** Additional resource attributes merged onto every signal. */
+  resourceAttributes?: Record<string, ContainerAttributeValue>;
   /** `service.name` resource attribute; defaults to the `LUNORA_SERVICE_NAME` env var then `"lunora-container"`. */
   serviceName?: string;
+  /**
+   * `service.version` resource attribute. Falls back to `SERVICE_VERSION` /
+   * `CF_VERSION_METADATA` / `VERCEL_GIT_COMMIT_SHA` / `GITHUB_SHA` /
+   * `COMMIT_SHA` env vars **only when
+   * {@link ContainerTelemetryOptions.detectResources} is `true`**.
+   */
+  serviceVersion?: string;
   /** Per-POST timeout in ms; a collector that never responds aborts after this so a stuck send can't stall `flush()`. Defaults to {@link DEFAULT_TIMEOUT_MS} (10s). */
   timeoutMs?: number;
   /** Bearer token sent as an `Authorization: Bearer` header; defaults to the `LUNORA_OTLP_TOKEN` env var. */
@@ -128,7 +151,10 @@ interface ContainerTelemetry {
  * With no endpoint resolvable the returned exporter is disabled (`enabled ===
  * false`): `emitSpan`/`emitLog` no-op and `trace` still runs its work but records
  * nothing — so the same code runs unchanged locally and in the cloud.
- * @param options Exporter options; every field falls back to a `LUNORA_*` env var.
+ * @param options Exporter options. Connection fields (`endpoint`, `token`,
+ * `serviceName`, `traceparent`) always fall back to their `LUNORA_*` env var;
+ * resource fields (`serviceVersion`, `deploymentEnvironment`) only do so under
+ * `detectResources: true`.
  * @experimental
  */
 declare const createContainerTelemetry: (options?: ContainerTelemetryOptions) => ContainerTelemetry;

package/dist/otel.mjs

@@ -35,7 +35,7 @@ const parseTraceparent = (header) => {
   version === "00" && parts.length !== 4 || traceId === void 0 || parentSpanId === void 0 || flags === void 0 || flags.length !== 2 || !HEX_ONLY.test(flags) || traceId.length !== 32 || parentSpanId.length !== 16 || !HEX_ONLY.test(traceId) || !HEX_ONLY.test(parentSpanId) || traceId === "00000000000000000000000000000000" || parentSpanId === "0000000000000000") {
     return void 0;
   }
-  return { parentSpanId, traceId };
+  return { parentSpanId, sampled: (Number.parseInt(flags, 16) & 1) === 1, traceId };
 };
 const encodeAttribute = (key, value) => {
   if (typeof value === "boolean") {
@@ -79,31 +79,82 @@ const mergeHeaders = (defaults, overrides, token) => {
   }
   return merged;
 };
-const wrapResourceSpans = (span, scopeName, serviceName) => {
+const buildResourceAttributes = (serviceName, extra) => {
+  const merged = { "service.name": serviceName };
+  for (const [key, value] of Object.entries(extra ?? {})) {
+    merged[key] = value;
+  }
+  return Object.entries(merged).map(([key, value]) => encodeAttribute(key, value));
+};
+const wrapResourceSpans = (span, scopeName, serviceName, resourceAttributes) => {
   return {
     resourceSpans: [
       {
-        resource: { attributes: [encodeAttribute("service.name", serviceName)] },
+        resource: { attributes: buildResourceAttributes(serviceName, resourceAttributes) },
         scopeSpans: [{ scope: { name: scopeName }, spans: [span] }]
       }
     ]
   };
 };
-const wrapResourceLogs = (logRecord, scopeName, serviceName) => {
+const wrapResourceLogs = (logRecord, scopeName, serviceName, resourceAttributes) => {
   return {
     resourceLogs: [
       {
-        resource: { attributes: [encodeAttribute("service.name", serviceName)] },
+        resource: { attributes: buildResourceAttributes(serviceName, resourceAttributes) },
         scopeLogs: [{ logRecords: [logRecord], scope: { name: scopeName } }]
       }
     ]
   };
 };
 
+const detectServiceResource = (read) => {
+  const detected = {};
+  const serviceVersion = read("SERVICE_VERSION") ?? read("CF_VERSION_METADATA") ?? read("VERCEL_GIT_COMMIT_SHA") ?? read("GITHUB_SHA") ?? read("COMMIT_SHA");
+  if (serviceVersion !== void 0) {
+    detected["service.version"] = serviceVersion;
+  }
+  const deploymentEnvironment = read("DEPLOYMENT_ENVIRONMENT") ?? read("ENVIRONMENT") ?? read("NODE_ENV");
+  if (deploymentEnvironment !== void 0) {
+    detected["deployment.environment"] = deploymentEnvironment;
+  }
+  return detected;
+};
+const detectHostResource = (read, pid) => {
+  const detected = {};
+  const hostName = read("HOSTNAME") ?? read("COMPUTERNAME");
+  if (hostName !== void 0) {
+    detected["host.name"] = hostName;
+  }
+  const podName = read("KUBERNETES_POD_NAME") ?? read("HOSTNAME");
+  if (podName !== void 0 && read("KUBERNETES_SERVICE_HOST") !== void 0) {
+    detected["k8s.pod.name"] = podName;
+  }
+  if (pid !== void 0 && Number.isFinite(pid)) {
+    detected["process.pid"] = pid;
+  }
+  return detected;
+};
+const mergeResourceAttributes = (...bags) => {
+  const merged = {};
+  for (const bag of bags) {
+    if (bag === void 0) {
+      continue;
+    }
+    for (const [key, value] of Object.entries(bag)) {
+      merged[key] = value;
+    }
+  }
+  return merged;
+};
+
 const DEFAULT_TIMEOUT_MS = 1e4;
 const readEnv = (name) => {
   return process.env[name];
 };
+const detectContainerResource = () => {
+  const pid = typeof process.pid !== "number" ? void 0 : process.pid;
+  return mergeResourceAttributes(detectServiceResource(readEnv), detectHostResource(readEnv, pid));
+};
 const resolveFetch = (injected) => {
   if (injected !== void 0) {
     return injected;
@@ -113,7 +164,7 @@ const resolveFetch = (injected) => {
   }
   return void 0;
 };
-const traceBody = (span, serviceName, parent) => {
+const traceBody = (span, serviceName, parent, resource) => {
   const attributes = encodeAttributes(span.attributes);
   if (span.error?.type !== void 0) {
     attributes.push(encodeAttribute("error.type", span.error.type));
@@ -133,9 +184,18 @@ const traceBody = (span, serviceName, parent) => {
     status: span.error === void 0 ? { code: 1 } : { code: 2, message: span.error.message },
     traceId: parent?.traceId ?? otlpRandomHex(16)
   };
-  return wrapResourceSpans(otlpSpan, "@lunora/container", serviceName);
+  if (span.error) {
+    otlpSpan.events = [
+      {
+        attributes: [encodeAttribute("exception.type", span.error.type ?? "Error"), encodeAttribute("exception.message", span.error.message)],
+        name: "exception",
+        timeUnixNano: otlpUnixNano(span.endMs)
+      }
+    ];
+  }
+  return wrapResourceSpans(otlpSpan, "@lunora/container", serviceName, resource);
 };
-const logBody = (log, serviceName, nowMs) => {
+const logBody = (log, serviceName, nowMs, resource) => {
   const level = log.level ?? "info";
   const record = {
     attributes: encodeAttributes(log.attributes),
@@ -144,7 +204,7 @@ const logBody = (log, serviceName, nowMs) => {
     severityText: level.toUpperCase(),
     timeUnixNano: otlpUnixNano(log.ts ?? nowMs)
   };
-  return wrapResourceLogs(record, "@lunora/container", serviceName);
+  return wrapResourceLogs(record, "@lunora/container", serviceName, resource);
 };
 const createContainerTelemetry = (options = {}) => {
   const endpoint = options.endpoint ?? readEnv("LUNORA_OTLP_ENDPOINT");
@@ -155,6 +215,18 @@ const createContainerTelemetry = (options = {}) => {
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const fetchImpl = resolveFetch(options.fetch);
   const headers = mergeHeaders({ "content-type": "application/json" }, options.headers, token);
+  const detectedAttributes = options.detectResources === true ? detectContainerResource() : void 0;
+  const staticAttributes = {};
+  if (options.serviceVersion !== void 0) {
+    staticAttributes["service.version"] = options.serviceVersion;
+  }
+  if (options.deploymentEnvironment !== void 0) {
+    staticAttributes["deployment.environment"] = options.deploymentEnvironment;
+  }
+  if (options.resourceAttributes !== void 0) {
+    Object.assign(staticAttributes, options.resourceAttributes);
+  }
+  const resource = mergeResourceAttributes(detectedAttributes, staticAttributes);
   let base = endpoint ?? "";
   while (base.endsWith("/")) {
     base = base.slice(0, -1);
@@ -190,13 +262,13 @@ const createContainerTelemetry = (options = {}) => {
     if (!enabled) {
       return;
     }
-    send(tracesUrl, traceBody(span, serviceName, parent));
+    send(tracesUrl, traceBody(span, serviceName, parent, resource));
   };
   const emitLog = (log) => {
     if (!enabled) {
       return;
     }
-    send(logsUrl, logBody(log, serviceName, Date.now()));
+    send(logsUrl, logBody(log, serviceName, Date.now(), resource));
   };
   const trace = async (name, run, attributes) => {
     const startMs = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/container",
-  "version": "1.0.0-alpha.13",
+  "version": "1.0.0-alpha.15",
   "description": "Cloudflare Containers for Lunora: defineContainer, generated Container DO classes, and the ctx.containers action surface",
   "keywords": [
     "cloudflare",
@@ -56,7 +56,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.6"
+    "@lunora/errors": "1.0.0-alpha.7"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"