@odla-ai/o11y 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# @odla-ai/o11y
+
+Official observability client for [odla](https://github.com/) Cloudflare Workers.
+Wrap your Worker once and get OpenTelemetry **traces**, **metrics**, structured
+**errors**, and **LLM cost** — exported over OTLP to the odla-o11y collector.
+
+- Traces via [`@microlabs/otel-cf-workers`](https://github.com/evanderkoogh/otel-cf-workers) (auto-instruments incoming/outgoing fetch, Durable Objects, and bindings).
+- Metrics + logs via lightweight OTLP/JSON emitters (the traces-only otel library doesn't cover them, and the Node metrics SDK doesn't fit the isolate model).
+- Targets the Cloudflare Workers runtime; requires the `nodejs_compat` flag.
+
+## Install
+
+```sh
+npm i @odla-ai/o11y
+```
+
+## Use
+
+```ts
+import { withObservability, span, count, recordError, recordLlmUsage } from "@odla-ai/o11y";
+
+const handler = {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    count("http.requests", 1, { "http.route": new URL(req.url).pathname });
+    return span("handle", async () => new Response("ok"), { kind: "server" });
+  },
+} satisfies ExportedHandler<Env>;
+
+export default withObservability(handler);
+```
+
+Wrap a Durable Object class with `instrumentDurableObject(MyDO)`.
+
+## Configuration
+
+Config is read from env vars (override per call via the second `withObservability` arg):
+
+| Var | Meaning |
+| --- | --- |
+| `ODLA_O11Y_ENDPOINT` | Collector base URL (e.g. `https://odla-o11y.workers.dev`) |
+| `ODLA_O11Y_SERVICE` | This service's name |
+| `ODLA_O11Y_TOKEN` | Per-service bearer token (secret) |
+| `ODLA_O11Y_VERSION` | Release tag (optional) |
+
+`wrangler.jsonc` needs `"compatibility_flags": ["nodejs_compat"]` (for AsyncLocalStorage).
+
+## API
+
+- `withObservability(handler, opts?)` — wrap a Worker handler (fetch/scheduled).
+- `instrumentDurableObject(cls, opts?)` — wrap a Durable Object class.
+- `span(name, fn, opts?)` — run `fn` inside an active span.
+- `count(name, by?, attrs?)` / `metrics()` — counters, gauges, histograms.
+- `recordError(err, report?)` — structured error; message/stack go only to the
+  collector's R2 artifact bundle, never to metrics.
+- `recordLlmUsage(usage, opts)` — turn `{calls, inputTokens, outputTokens}` into
+  cost + token metrics and GenAI span attributes.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,352 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  count: () => count,
+  instrumentDurableObject: () => instrumentDurableObject,
+  metrics: () => metrics,
+  recordError: () => recordError,
+  recordLlmUsage: () => recordLlmUsage,
+  span: () => span,
+  withObservability: () => withObservability
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/instrument.ts
+var import_otel_cf_workers = require("@microlabs/otel-cf-workers");
+
+// src/context.ts
+var import_node_async_hooks = require("async_hooks");
+
+// ../o11y-core/src/encode.ts
+function attrsToKvList(attrs) {
+  const out = [];
+  for (const [key, value] of Object.entries(attrs)) {
+    if (typeof value === "string") out.push({ key, value: { stringValue: value } });
+    else if (typeof value === "boolean") out.push({ key, value: { boolValue: value } });
+    else if (Number.isInteger(value)) out.push({ key, value: { intValue: String(value) } });
+    else out.push({ key, value: { doubleValue: value } });
+  }
+  return out;
+}
+var DELTA = 1;
+function encodeMetricsRequest(resource, scopeName, points) {
+  const metrics2 = points.map((p) => {
+    const dp = {
+      attributes: attrsToKvList(p.attrs),
+      startTimeUnixNano: p.startUnixNano,
+      timeUnixNano: p.timeUnixNano,
+      asDouble: p.value
+    };
+    return p.kind === "gauge" ? { name: p.name, unit: p.unit, gauge: { dataPoints: [dp] } } : { name: p.name, unit: p.unit, sum: { aggregationTemporality: DELTA, isMonotonic: true, dataPoints: [dp] } };
+  });
+  return {
+    resourceMetrics: [
+      { resource: { attributes: attrsToKvList(resource) }, scopeMetrics: [{ scope: { name: scopeName }, metrics: metrics2 }] }
+    ]
+  };
+}
+function encodeLogsRequest(resource, scopeName, records) {
+  return {
+    resourceLogs: [
+      {
+        resource: { attributes: attrsToKvList(resource) },
+        scopeLogs: [
+          {
+            scope: { name: scopeName },
+            logRecords: records.map((r) => ({
+              timeUnixNano: r.timeUnixNano,
+              observedTimeUnixNano: r.timeUnixNano,
+              severityNumber: r.severityNumber,
+              severityText: r.severityText,
+              body: { stringValue: r.body },
+              attributes: attrsToKvList(r.attrs),
+              ...r.traceId ? { traceId: r.traceId } : {},
+              ...r.spanId ? { spanId: r.spanId } : {}
+            }))
+          }
+        ]
+      }
+    ]
+  };
+}
+
+// ../o11y-core/src/pricing.ts
+var MODEL_PRICING = {
+  "claude-haiku-4-5": { inputPerMTok: 1, outputPerMTok: 5 },
+  "claude-sonnet-4-6": { inputPerMTok: 3, outputPerMTok: 15 },
+  "claude-sonnet-5": { inputPerMTok: 3, outputPerMTok: 15 },
+  "claude-opus-4-6": { inputPerMTok: 5, outputPerMTok: 25 },
+  "claude-opus-4-7": { inputPerMTok: 5, outputPerMTok: 25 },
+  "claude-opus-4-8": { inputPerMTok: 5, outputPerMTok: 25 },
+  "claude-fable-5": { inputPerMTok: 10, outputPerMTok: 50 }
+};
+function costUsd(model, inputTokens, outputTokens, override) {
+  const price = override ?? MODEL_PRICING[model];
+  if (!price) return 0;
+  return inputTokens / 1e6 * price.inputPerMTok + outputTokens / 1e6 * price.outputPerMTok;
+}
+
+// src/context.ts
+var SCOPE = "@odla-ai/o11y";
+function evalOpts(opts, env) {
+  return typeof opts === "function" ? opts(env) : opts ?? {};
+}
+function resolveConfig(env, opts) {
+  const o = evalOpts(opts, env);
+  const e = env;
+  return {
+    service: o.service ?? e["ODLA_O11Y_SERVICE"] ?? "unknown",
+    endpoint: (o.endpoint ?? e["ODLA_O11Y_ENDPOINT"] ?? "").replace(/\/$/, ""),
+    token: o.token ?? e["ODLA_O11Y_TOKEN"],
+    version: o.version ?? e["ODLA_O11Y_VERSION"] ?? "0.0.0",
+    attributes: o.attributes ?? {},
+    sampleRatio: o.sampleRatio
+  };
+}
+function nowNano() {
+  return `${Date.now()}000000`;
+}
+var als = new import_node_async_hooks.AsyncLocalStorage();
+function currentSink() {
+  return als.getStore();
+}
+function runWithSink(sink, fn) {
+  return als.run(sink, fn);
+}
+function resourceAttrs(config) {
+  return { "service.name": config.service, "service.version": config.version, ...config.attributes };
+}
+async function post(url, body, token) {
+  try {
+    await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...token ? { authorization: `Bearer ${token}` } : {}
+      },
+      body: JSON.stringify(body)
+    });
+  } catch {
+  }
+}
+function createSink(config) {
+  return {
+    config,
+    metrics: [],
+    logs: [],
+    async flush() {
+      if (!this.config.endpoint) {
+        this.metrics = [];
+        this.logs = [];
+        return;
+      }
+      const resource = resourceAttrs(this.config);
+      const jobs = [];
+      if (this.metrics.length) {
+        jobs.push(
+          post(`${this.config.endpoint}/v1/metrics`, encodeMetricsRequest(resource, SCOPE, this.metrics), this.config.token)
+        );
+        this.metrics = [];
+      }
+      if (this.logs.length) {
+        jobs.push(
+          post(`${this.config.endpoint}/v1/logs`, encodeLogsRequest(resource, SCOPE, this.logs), this.config.token)
+        );
+        this.logs = [];
+      }
+      await Promise.all(jobs);
+    }
+  };
+}
+
+// src/instrument.ts
+function traceConfig(env, opts) {
+  const c = resolveConfig(env, opts);
+  const headers = {};
+  if (c.token) headers.authorization = `Bearer ${c.token}`;
+  const config = {
+    exporter: { url: `${c.endpoint}/v1/traces`, headers },
+    service: { name: c.service, version: c.version }
+  };
+  if (c.sampleRatio != null) config.sampling = { headSampler: { ratio: c.sampleRatio } };
+  return config;
+}
+function wrapHandler(handler, opts) {
+  const wrapped = { ...handler };
+  const fetchImpl = handler.fetch;
+  if (fetchImpl) {
+    wrapped.fetch = (req, env, ctx) => {
+      const sink = createSink(resolveConfig(env, opts));
+      return runWithSink(sink, async () => {
+        try {
+          return await fetchImpl(req, env, ctx);
+        } finally {
+          ctx.waitUntil(sink.flush());
+        }
+      });
+    };
+  }
+  const scheduledImpl = handler.scheduled;
+  if (scheduledImpl) {
+    wrapped.scheduled = (controller, env, ctx) => {
+      const sink = createSink(resolveConfig(env, opts));
+      return runWithSink(sink, async () => {
+        try {
+          return await scheduledImpl(controller, env, ctx);
+        } finally {
+          ctx.waitUntil(sink.flush());
+        }
+      });
+    };
+  }
+  return wrapped;
+}
+function withObservability(handler, opts) {
+  const configFn = (env, _trigger) => traceConfig(env, opts);
+  return (0, import_otel_cf_workers.instrument)(wrapHandler(handler, opts), configFn);
+}
+function instrumentDurableObject(cls, opts) {
+  const configFn = (env, _trigger) => traceConfig(env, opts);
+  return (0, import_otel_cf_workers.instrumentDO)(cls, configFn);
+}
+
+// src/span.ts
+var import_api = require("@opentelemetry/api");
+var KIND = {
+  internal: import_api.SpanKind.INTERNAL,
+  server: import_api.SpanKind.SERVER,
+  client: import_api.SpanKind.CLIENT,
+  producer: import_api.SpanKind.PRODUCER,
+  consumer: import_api.SpanKind.CONSUMER
+};
+async function span(name, fn, opts) {
+  const tracer = import_api.trace.getTracer(SCOPE);
+  return tracer.startActiveSpan(
+    name,
+    { attributes: opts?.attributes, kind: opts?.kind ? KIND[opts.kind] : void 0 },
+    async (s) => {
+      try {
+        const result = await fn(s);
+        s.setStatus({ code: import_api.SpanStatusCode.OK });
+        return result;
+      } catch (err) {
+        s.setStatus({ code: import_api.SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
+        throw err;
+      } finally {
+        s.end();
+      }
+    }
+  );
+}
+
+// src/metrics.ts
+function record(kind, name, value, attrs, unit) {
+  const sink = currentSink();
+  if (!sink) return;
+  const ts = nowNano();
+  sink.metrics.push({ name, unit, kind, value, attrs: attrs ?? {}, startUnixNano: ts, timeUnixNano: ts });
+}
+function metrics() {
+  return {
+    count: (name, by = 1, attrs) => record("sum", name, by, attrs),
+    gauge: (name, value, attrs) => record("gauge", name, value, attrs),
+    histogram: (name, value, attrs, unit) => record("sum", name, value, attrs, unit)
+  };
+}
+function count(name, by = 1, attrs) {
+  record("sum", name, by, attrs);
+}
+
+// src/logs.ts
+var import_api2 = require("@opentelemetry/api");
+var SEVERITY_ERROR = 17;
+function recordError(err, report) {
+  const error = err instanceof Error ? err : new Error(String(err));
+  const artifactId = `${Date.now().toString(16)}${crypto.randomUUID().replace(/-/g, "")}`;
+  const span2 = import_api2.trace.getActiveSpan();
+  const attrs = {
+    "error.type": error.name,
+    "odla.artifact_id": artifactId,
+    ...report?.code ? { "error.code": report.code } : {},
+    ...report?.route ? { "odla.route": report.route } : {},
+    ...report?.fingerprint ? { "odla.fingerprint": report.fingerprint } : {},
+    ...report?.attributes ?? {}
+  };
+  if (span2) {
+    span2.recordException(error);
+    span2.setStatus({ code: import_api2.SpanStatusCode.ERROR, message: error.message });
+    span2.setAttributes(attrs);
+  }
+  const sink = currentSink();
+  if (sink) {
+    const ctx = span2?.spanContext();
+    sink.logs.push({
+      timeUnixNano: nowNano(),
+      severityNumber: SEVERITY_ERROR,
+      severityText: "ERROR",
+      body: error.message,
+      // full message → R2 bundle only (collector-enforced)
+      attrs: {
+        ...attrs,
+        // Denied keys: stripped from metrics/index, retained in the R2 bundle.
+        ...error.stack ? { "exception.stacktrace": error.stack } : {},
+        ...report?.artifacts ? { "odla.artifacts": JSON.stringify(report.artifacts) } : {}
+      },
+      ...ctx ? { traceId: ctx.traceId, spanId: ctx.spanId } : {}
+    });
+  }
+  return artifactId;
+}
+
+// src/llm.ts
+var import_api3 = require("@opentelemetry/api");
+function recordLlmUsage(usage, opts) {
+  const cost = costUsd(opts.model, usage.inputTokens, usage.outputTokens, opts.price);
+  const base = {
+    "gen_ai.provider.name": opts.provider,
+    "gen_ai.request.model": opts.model,
+    ...opts.operation ? { "gen_ai.operation.name": opts.operation } : {},
+    ...opts.attributes ?? {}
+  };
+  count("odla.llm.cost.usd", cost, base);
+  count("odla.llm.calls", usage.calls, base);
+  count("odla.llm.tokens", usage.inputTokens, { ...base, "gen_ai.token.type": "input" });
+  count("odla.llm.tokens", usage.outputTokens, { ...base, "gen_ai.token.type": "output" });
+  import_api3.trace.getActiveSpan()?.setAttributes({
+    ...base,
+    "gen_ai.usage.input_tokens": usage.inputTokens,
+    "gen_ai.usage.output_tokens": usage.outputTokens,
+    "odla.llm.cost.usd": cost
+  });
+  return { costUsd: cost };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  count,
+  instrumentDurableObject,
+  metrics,
+  recordError,
+  recordLlmUsage,
+  span,
+  withObservability
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/instrument.ts","../src/context.ts","../../o11y-core/src/encode.ts","../../o11y-core/src/pricing.ts","../src/span.ts","../src/metrics.ts","../src/logs.ts","../src/llm.ts"],"sourcesContent":["export { instrumentDurableObject, withObservability } from \"./instrument.js\";\nexport { span } from \"./span.js\";\nexport { count, metrics } from \"./metrics.js\";\nexport { recordError } from \"./logs.js\";\nexport { recordLlmUsage } from \"./llm.js\";\n\nexport type { ObservabilityOptions, OptsFn } from \"./context.js\";\nexport type { SpanKindName, SpanOpts } from \"./span.js\";\nexport type { Metrics } from \"./metrics.js\";\nexport type { ErrorReport } from \"./logs.js\";\nexport type { LlmCostOpts, LlmUsage } from \"./llm.js\";\nexport type { Attrs } from \"@odla/o11y-core\";\n","import { instrument, instrumentDO, type ResolveConfigFn, type TraceConfig } from \"@microlabs/otel-cf-workers\";\nimport { createSink, resolveConfig, runWithSink, type OptsFn } from \"./context.js\";\n\n/** Build the otel-cf-workers trace config (exporter + service) from env/opts. */\nfunction traceConfig<E>(env: E, opts?: OptsFn<E>): TraceConfig {\n  const c = resolveConfig(env, opts);\n  const headers: Record<string, string> = {};\n  if (c.token) headers.authorization = `Bearer ${c.token}`;\n  const config: TraceConfig = {\n    exporter: { url: `${c.endpoint}/v1/traces`, headers },\n    service: { name: c.service, version: c.version },\n  };\n  if (c.sampleRatio != null) config.sampling = { headSampler: { ratio: c.sampleRatio } };\n  return config;\n}\n\n/** Wrap each handler entrypoint so an ALS metrics/logs sink is live for the\n *  duration of the invocation and flushed via ctx.waitUntil at the end. */\nfunction wrapHandler<E>(handler: ExportedHandler<E>, opts?: OptsFn<E>): ExportedHandler<E> {\n  const wrapped: ExportedHandler<E> = { ...handler };\n\n  const fetchImpl = handler.fetch;\n  if (fetchImpl) {\n    wrapped.fetch = (req, env, ctx) => {\n      const sink = createSink(resolveConfig(env, opts));\n      return runWithSink(sink, async () => {\n        try {\n          return await fetchImpl(req, env, ctx);\n        } finally {\n          ctx.waitUntil(sink.flush());\n        }\n      });\n    };\n  }\n\n  const scheduledImpl = handler.scheduled;\n  if (scheduledImpl) {\n    wrapped.scheduled = (controller, env, ctx) => {\n      const sink = createSink(resolveConfig(env, opts));\n      return runWithSink(sink, async () => {\n        try {\n          return await scheduledImpl(controller, env, ctx);\n        } finally {\n          ctx.waitUntil(sink.flush());\n        }\n      });\n    };\n  }\n\n  return wrapped;\n}\n\n/** Wrap a Worker handler with tracing (otel-cf-workers) + the metrics/logs sink.\n *  Config is read from env vars ODLA_O11Y_{ENDPOINT,SERVICE,TOKEN,VERSION} unless\n *  overridden by `opts`. */\nexport function withObservability<E = unknown>(\n  handler: ExportedHandler<E>,\n  opts?: OptsFn<E>,\n): ExportedHandler<E> {\n  const configFn: ResolveConfigFn = (env, _trigger) => traceConfig(env as E, opts);\n  // instrument constrains E to its own Env type; we support any service env, so\n  // cross the boundary with `any` and restore the caller's E on the way out.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return instrument(wrapHandler(handler, opts) as ExportedHandler<any>, configFn) as ExportedHandler<E>;\n}\n\n/** Wrap a Durable Object class with tracing. (Establishing the metrics/logs sink\n *  inside DO methods is added in P1 when odla-db's usage counters are bridged.) */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function instrumentDurableObject<T extends abstract new (...args: any[]) => object>(\n  cls: T,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  opts?: OptsFn<any>,\n): T {\n  const configFn: ResolveConfigFn = (env, _trigger) => traceConfig(env, opts);\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return instrumentDO(cls as any, configFn) as unknown as T;\n}\n","import { AsyncLocalStorage } from \"node:async_hooks\";\nimport {\n  encodeLogsRequest,\n  encodeMetricsRequest,\n  type Attrs,\n  type LogRecord,\n  type MetricPoint,\n} from \"@odla/o11y-core\";\n\n/** The instrumentation scope name stamped on every signal. */\nexport const SCOPE = \"@odla-ai/o11y\";\n\nexport interface ObservabilityOptions {\n  /** Service name (default: env.ODLA_O11Y_SERVICE). */\n  service?: string;\n  /** Collector base URL (default: env.ODLA_O11Y_ENDPOINT). */\n  endpoint?: string;\n  /** Per-service bearer token (default: env.ODLA_O11Y_TOKEN). */\n  token?: string;\n  /** Release/version tag (default: env.ODLA_O11Y_VERSION ?? \"0.0.0\"). */\n  version?: string;\n  /** Head-sampling ratio 0..1 for traces (default: 1). */\n  sampleRatio?: number;\n  /** Static resource attributes merged onto every signal. */\n  attributes?: Attrs;\n}\n\nexport type OptsFn<E> = ObservabilityOptions | ((env: E) => ObservabilityOptions);\n\nexport interface ResolvedConfig {\n  service: string;\n  endpoint: string;\n  token?: string;\n  version: string;\n  attributes: Attrs;\n  sampleRatio?: number;\n}\n\nfunction evalOpts<E>(opts: OptsFn<E> | undefined, env: E): ObservabilityOptions {\n  return typeof opts === \"function\" ? opts(env) : (opts ?? {});\n}\n\n/** Resolve options against the service's env vars. */\nexport function resolveConfig<E>(env: E, opts?: OptsFn<E>): ResolvedConfig {\n  const o = evalOpts(opts, env);\n  const e = env as Record<string, string | undefined>;\n  return {\n    service: o.service ?? e[\"ODLA_O11Y_SERVICE\"] ?? \"unknown\",\n    endpoint: (o.endpoint ?? e[\"ODLA_O11Y_ENDPOINT\"] ?? \"\").replace(/\\/$/, \"\"),\n    token: o.token ?? e[\"ODLA_O11Y_TOKEN\"],\n    version: o.version ?? e[\"ODLA_O11Y_VERSION\"] ?? \"0.0.0\",\n    attributes: o.attributes ?? {},\n    sampleRatio: o.sampleRatio,\n  };\n}\n\n/** Nanoseconds since epoch as a decimal string (OTLP timestamp format). */\nexport function nowNano(): string {\n  return `${Date.now()}000000`;\n}\n\nexport interface Sink {\n  config: ResolvedConfig;\n  metrics: MetricPoint[];\n  logs: LogRecord[];\n  flush(): Promise<void>;\n}\n\nconst als = new AsyncLocalStorage<Sink>();\n\nexport function currentSink(): Sink | undefined {\n  return als.getStore();\n}\n\nexport function runWithSink<T>(sink: Sink, fn: () => Promise<T>): Promise<T> {\n  return als.run(sink, fn);\n}\n\nfunction resourceAttrs(config: ResolvedConfig): Attrs {\n  return { \"service.name\": config.service, \"service.version\": config.version, ...config.attributes };\n}\n\nasync function post(url: string, body: unknown, token?: string): Promise<void> {\n  try {\n    await fetch(url, {\n      method: \"POST\",\n      headers: {\n        \"content-type\": \"application/json\",\n        ...(token ? { authorization: `Bearer ${token}` } : {}),\n      },\n      body: JSON.stringify(body),\n    });\n  } catch {\n    // Telemetry export is best-effort — never surface into the app.\n  }\n}\n\n/** A per-invocation sink: accumulates metric/log records and flushes them to the\n *  collector as OTLP/JSON (traces are exported separately by otel-cf-workers). */\nexport function createSink(config: ResolvedConfig): Sink {\n  return {\n    config,\n    metrics: [],\n    logs: [],\n    async flush(): Promise<void> {\n      if (!this.config.endpoint) {\n        this.metrics = [];\n        this.logs = [];\n        return;\n      }\n      const resource = resourceAttrs(this.config);\n      const jobs: Promise<void>[] = [];\n      if (this.metrics.length) {\n        jobs.push(\n          post(`${this.config.endpoint}/v1/metrics`, encodeMetricsRequest(resource, SCOPE, this.metrics), this.config.token),\n        );\n        this.metrics = [];\n      }\n      if (this.logs.length) {\n        jobs.push(\n          post(`${this.config.endpoint}/v1/logs`, encodeLogsRequest(resource, SCOPE, this.logs), this.config.token),\n        );\n        this.logs = [];\n      }\n      await Promise.all(jobs);\n    },\n  };\n}\n","// OTLP/JSON encoders — the emit side of the wire contract (the SDK produces\n// these; the collector decodes them in later phases). Traces are produced by\n// @microlabs/otel-cf-workers; metrics and logs are hand-rolled here because that\n// library is traces-only and the Node OTel metrics SDK doesn't fit the isolate\n// model.\n\nimport type { Attrs, OtlpKeyValue, OtlpResource, OtlpScope } from \"./otlp.js\";\n\n/** Inverse of kvListToAttrs: a flat attr map → OTLP KeyValue[]. */\nexport function attrsToKvList(attrs: Attrs): OtlpKeyValue[] {\n  const out: OtlpKeyValue[] = [];\n  for (const [key, value] of Object.entries(attrs)) {\n    if (typeof value === \"string\") out.push({ key, value: { stringValue: value } });\n    else if (typeof value === \"boolean\") out.push({ key, value: { boolValue: value } });\n    else if (Number.isInteger(value)) out.push({ key, value: { intValue: String(value) } });\n    else out.push({ key, value: { doubleValue: value } });\n  }\n  return out;\n}\n\n// ---- Metrics ----\n\nexport type MetricKind = \"sum\" | \"gauge\";\n\nexport interface MetricPoint {\n  name: string;\n  unit?: string;\n  kind: MetricKind;\n  value: number;\n  attrs: Attrs;\n  startUnixNano: string;\n  timeUnixNano: string;\n}\n\ninterface OtlpNumberDataPoint {\n  attributes?: OtlpKeyValue[];\n  startTimeUnixNano?: string;\n  timeUnixNano: string;\n  asDouble: number;\n}\n\ninterface OtlpMetric {\n  name: string;\n  unit?: string;\n  sum?: { aggregationTemporality: number; isMonotonic: boolean; dataPoints: OtlpNumberDataPoint[] };\n  gauge?: { dataPoints: OtlpNumberDataPoint[] };\n}\n\nexport interface ExportMetricsServiceRequest {\n  resourceMetrics: Array<{\n    resource: OtlpResource;\n    scopeMetrics: Array<{ scope: OtlpScope; metrics: OtlpMetric[] }>;\n  }>;\n}\n\n// OTLP AggregationTemporality: 1 = DELTA. Each ephemeral isolate reports its own\n// delta; the collector aggregates across invocations into Analytics Engine.\nconst DELTA = 1;\n\nexport function encodeMetricsRequest(\n  resource: Attrs,\n  scopeName: string,\n  points: MetricPoint[],\n): ExportMetricsServiceRequest {\n  const metrics: OtlpMetric[] = points.map((p) => {\n    const dp: OtlpNumberDataPoint = {\n      attributes: attrsToKvList(p.attrs),\n      startTimeUnixNano: p.startUnixNano,\n      timeUnixNano: p.timeUnixNano,\n      asDouble: p.value,\n    };\n    return p.kind === \"gauge\"\n      ? { name: p.name, unit: p.unit, gauge: { dataPoints: [dp] } }\n      : { name: p.name, unit: p.unit, sum: { aggregationTemporality: DELTA, isMonotonic: true, dataPoints: [dp] } };\n  });\n  return {\n    resourceMetrics: [\n      { resource: { attributes: attrsToKvList(resource) }, scopeMetrics: [{ scope: { name: scopeName }, metrics }] },\n    ],\n  };\n}\n\n// ---- Logs (errors ride the logs signal) ----\n\nexport interface LogRecord {\n  timeUnixNano: string;\n  severityNumber: number; // OTel: 17 = ERROR, 9 = INFO\n  severityText: string;\n  body: string;\n  attrs: Attrs;\n  traceId?: string;\n  spanId?: string;\n}\n\nexport interface ExportLogsServiceRequest {\n  resourceLogs: Array<{\n    resource: OtlpResource;\n    scopeLogs: Array<{\n      scope: OtlpScope;\n      logRecords: Array<{\n        timeUnixNano: string;\n        observedTimeUnixNano: string;\n        severityNumber: number;\n        severityText: string;\n        body: { stringValue: string };\n        attributes: OtlpKeyValue[];\n        traceId?: string;\n        spanId?: string;\n      }>;\n    }>;\n  }>;\n}\n\nexport function encodeLogsRequest(\n  resource: Attrs,\n  scopeName: string,\n  records: LogRecord[],\n): ExportLogsServiceRequest {\n  return {\n    resourceLogs: [\n      {\n        resource: { attributes: attrsToKvList(resource) },\n        scopeLogs: [\n          {\n            scope: { name: scopeName },\n            logRecords: records.map((r) => ({\n              timeUnixNano: r.timeUnixNano,\n              observedTimeUnixNano: r.timeUnixNano,\n              severityNumber: r.severityNumber,\n              severityText: r.severityText,\n              body: { stringValue: r.body },\n              attributes: attrsToKvList(r.attrs),\n              ...(r.traceId ? { traceId: r.traceId } : {}),\n              ...(r.spanId ? { spanId: r.spanId } : {}),\n            })),\n          },\n        ],\n      },\n    ],\n  };\n}\n","// LLM price table + cost computation. OTel GenAI semconv has no cost attribute,\n// so we compute cost downstream from raw token counts × model price. Keep this\n// table in sync with current model pricing (verify against the claude-api\n// reference); unknown models cost 0 and should be added here.\n\nexport interface ModelPrice {\n  /** USD per million input tokens. */\n  inputPerMTok: number;\n  /** USD per million output tokens. */\n  outputPerMTok: number;\n}\n\n/** Prices in USD per million tokens (MTok). */\nexport const MODEL_PRICING: Record<string, ModelPrice> = {\n  \"claude-haiku-4-5\": { inputPerMTok: 1, outputPerMTok: 5 },\n  \"claude-sonnet-4-6\": { inputPerMTok: 3, outputPerMTok: 15 },\n  \"claude-sonnet-5\": { inputPerMTok: 3, outputPerMTok: 15 },\n  \"claude-opus-4-6\": { inputPerMTok: 5, outputPerMTok: 25 },\n  \"claude-opus-4-7\": { inputPerMTok: 5, outputPerMTok: 25 },\n  \"claude-opus-4-8\": { inputPerMTok: 5, outputPerMTok: 25 },\n  \"claude-fable-5\": { inputPerMTok: 10, outputPerMTok: 50 },\n};\n\n/** Compute USD cost for a call. Pass `override` to price a model not in the\n *  table (or to apply promotional pricing). Returns 0 for unknown models. */\nexport function costUsd(\n  model: string,\n  inputTokens: number,\n  outputTokens: number,\n  override?: ModelPrice,\n): number {\n  const price = override ?? MODEL_PRICING[model];\n  if (!price) return 0;\n  return (inputTokens / 1_000_000) * price.inputPerMTok + (outputTokens / 1_000_000) * price.outputPerMTok;\n}\n","import { SpanKind, SpanStatusCode, trace, type Span } from \"@opentelemetry/api\";\nimport type { Attrs } from \"@odla/o11y-core\";\nimport { SCOPE } from \"./context.js\";\n\nexport type SpanKindName = \"internal\" | \"server\" | \"client\" | \"producer\" | \"consumer\";\n\nexport interface SpanOpts {\n  attributes?: Attrs;\n  kind?: SpanKindName;\n}\n\nconst KIND: Record<SpanKindName, SpanKind> = {\n  internal: SpanKind.INTERNAL,\n  server: SpanKind.SERVER,\n  client: SpanKind.CLIENT,\n  producer: SpanKind.PRODUCER,\n  consumer: SpanKind.CONSUMER,\n};\n\n/** Run `fn` inside a new active span. The span is ended automatically and its\n *  status set from success/throw. Works whether or not tracing is exporting —\n *  falls back to a no-op span if no tracer is installed. */\nexport async function span<T>(\n  name: string,\n  fn: (span: Span) => Promise<T> | T,\n  opts?: SpanOpts,\n): Promise<T> {\n  const tracer = trace.getTracer(SCOPE);\n  return tracer.startActiveSpan(\n    name,\n    { attributes: opts?.attributes, kind: opts?.kind ? KIND[opts.kind] : undefined },\n    async (s) => {\n      try {\n        const result = await fn(s);\n        s.setStatus({ code: SpanStatusCode.OK });\n        return result;\n      } catch (err) {\n        s.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });\n        throw err;\n      } finally {\n        s.end();\n      }\n    },\n  );\n}\n","import type { Attrs } from \"@odla/o11y-core\";\nimport { currentSink, nowNano } from \"./context.js\";\n\nexport interface Metrics {\n  /** Monotonic counter (delta). Formalizes odla-db's usage counters. */\n  count(name: string, by?: number, attrs?: Attrs): void;\n  /** Last-value gauge. */\n  gauge(name: string, value: number, attrs?: Attrs): void;\n  /** A single observation (recorded as a delta sum for now; histograms later). */\n  histogram(name: string, value: number, attrs?: Attrs, unit?: string): void;\n}\n\nfunction record(kind: \"sum\" | \"gauge\", name: string, value: number, attrs?: Attrs, unit?: string): void {\n  const sink = currentSink();\n  if (!sink) return; // outside an instrumented invocation — no-op\n  const ts = nowNano();\n  sink.metrics.push({ name, unit, kind, value, attrs: attrs ?? {}, startUnixNano: ts, timeUnixNano: ts });\n}\n\n/** The ambient metrics API for the current invocation. */\nexport function metrics(): Metrics {\n  return {\n    count: (name, by = 1, attrs) => record(\"sum\", name, by, attrs),\n    gauge: (name, value, attrs) => record(\"gauge\", name, value, attrs),\n    histogram: (name, value, attrs, unit) => record(\"sum\", name, value, attrs, unit),\n  };\n}\n\n/** Convenience: increment a monotonic counter by `by` (default 1). */\nexport function count(name: string, by = 1, attrs?: Attrs): void {\n  record(\"sum\", name, by, attrs);\n}\n","import { SpanStatusCode, trace } from \"@opentelemetry/api\";\nimport type { Attrs } from \"@odla/o11y-core\";\nimport { currentSink, nowNano } from \"./context.js\";\n\nexport interface ErrorReport {\n  /** Stable, low-cardinality error code (e.g. \"unique_violation\"). */\n  code?: string;\n  /** Low-cardinality route/step where it happened. */\n  route?: string;\n  /** Extra low-cardinality attributes for the index. */\n  attributes?: Attrs;\n  /** Rich context for triage — kept only in the R2 artifact bundle. */\n  artifacts?: Record<string, unknown>;\n  /** Dedup key; the collector fingerprints by (type+code+route) if absent. */\n  fingerprint?: string;\n}\n\n// OTel severity number for ERROR.\nconst SEVERITY_ERROR = 17;\n\n/** Record a structured error. Returns an artifact id. The message and stack ride\n *  the log body + a denied attribute so the collector persists them ONLY in the\n *  R2 artifact bundle, never in metrics or the queryable index. */\nexport function recordError(err: unknown, report?: ErrorReport): string {\n  const error = err instanceof Error ? err : new Error(String(err));\n  const artifactId = `${Date.now().toString(16)}${crypto.randomUUID().replace(/-/g, \"\")}`;\n  const span = trace.getActiveSpan();\n\n  const attrs: Attrs = {\n    \"error.type\": error.name,\n    \"odla.artifact_id\": artifactId,\n    ...(report?.code ? { \"error.code\": report.code } : {}),\n    ...(report?.route ? { \"odla.route\": report.route } : {}),\n    ...(report?.fingerprint ? { \"odla.fingerprint\": report.fingerprint } : {}),\n    ...(report?.attributes ?? {}),\n  };\n\n  if (span) {\n    span.recordException(error);\n    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });\n    span.setAttributes(attrs);\n  }\n\n  const sink = currentSink();\n  if (sink) {\n    const ctx = span?.spanContext();\n    sink.logs.push({\n      timeUnixNano: nowNano(),\n      severityNumber: SEVERITY_ERROR,\n      severityText: \"ERROR\",\n      body: error.message, // full message → R2 bundle only (collector-enforced)\n      attrs: {\n        ...attrs,\n        // Denied keys: stripped from metrics/index, retained in the R2 bundle.\n        ...(error.stack ? { \"exception.stacktrace\": error.stack } : {}),\n        ...(report?.artifacts ? { \"odla.artifacts\": JSON.stringify(report.artifacts) } : {}),\n      },\n      ...(ctx ? { traceId: ctx.traceId, spanId: ctx.spanId } : {}),\n    });\n  }\n\n  return artifactId;\n}\n","import { trace } from \"@opentelemetry/api\";\nimport { costUsd, type Attrs, type ModelPrice } from \"@odla/o11y-core\";\nimport { count } from \"./metrics.js\";\n\n/** The token accounting odla-kg's Provider already returns (and drops today). */\nexport interface LlmUsage {\n  calls: number;\n  inputTokens: number;\n  outputTokens: number;\n}\n\nexport interface LlmCostOpts {\n  provider: string; // \"claude\" | \"openai\" | ...\n  model: string; // e.g. \"claude-sonnet-4-6\"\n  operation?: string; // \"extract\" | \"search\" | ...\n  attributes?: Attrs;\n  /** Override the built-in price table for this call. */\n  price?: ModelPrice;\n}\n\n/** Turn LLM token usage into first-class cost. Emits cost/token/call counters\n *  and stamps the active span with GenAI semconv attributes. */\nexport function recordLlmUsage(usage: LlmUsage, opts: LlmCostOpts): { costUsd: number } {\n  const cost = costUsd(opts.model, usage.inputTokens, usage.outputTokens, opts.price);\n  const base: Attrs = {\n    \"gen_ai.provider.name\": opts.provider,\n    \"gen_ai.request.model\": opts.model,\n    ...(opts.operation ? { \"gen_ai.operation.name\": opts.operation } : {}),\n    ...(opts.attributes ?? {}),\n  };\n\n  count(\"odla.llm.cost.usd\", cost, base);\n  count(\"odla.llm.calls\", usage.calls, base);\n  count(\"odla.llm.tokens\", usage.inputTokens, { ...base, \"gen_ai.token.type\": \"input\" });\n  count(\"odla.llm.tokens\", usage.outputTokens, { ...base, \"gen_ai.token.type\": \"output\" });\n\n  trace.getActiveSpan()?.setAttributes({\n    ...base,\n    \"gen_ai.usage.input_tokens\": usage.inputTokens,\n    \"gen_ai.usage.output_tokens\": usage.outputTokens,\n    \"odla.llm.cost.usd\": cost,\n  });\n\n  return { costUsd: cost };\n}\n"],"mappings":"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","names":["metrics","import_api","span","import_api"]}

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+import { Attrs, ModelPrice } from '@odla/o11y-core';
+export { Attrs } from '@odla/o11y-core';
+import { Span } from '@opentelemetry/api';
+
+interface ObservabilityOptions {
+    /** Service name (default: env.ODLA_O11Y_SERVICE). */
+    service?: string;
+    /** Collector base URL (default: env.ODLA_O11Y_ENDPOINT). */
+    endpoint?: string;
+    /** Per-service bearer token (default: env.ODLA_O11Y_TOKEN). */
+    token?: string;
+    /** Release/version tag (default: env.ODLA_O11Y_VERSION ?? "0.0.0"). */
+    version?: string;
+    /** Head-sampling ratio 0..1 for traces (default: 1). */
+    sampleRatio?: number;
+    /** Static resource attributes merged onto every signal. */
+    attributes?: Attrs;
+}
+type OptsFn<E> = ObservabilityOptions | ((env: E) => ObservabilityOptions);
+
+/** Wrap a Worker handler with tracing (otel-cf-workers) + the metrics/logs sink.
+ *  Config is read from env vars ODLA_O11Y_{ENDPOINT,SERVICE,TOKEN,VERSION} unless
+ *  overridden by `opts`. */
+declare function withObservability<E = unknown>(handler: ExportedHandler<E>, opts?: OptsFn<E>): ExportedHandler<E>;
+/** Wrap a Durable Object class with tracing. (Establishing the metrics/logs sink
+ *  inside DO methods is added in P1 when odla-db's usage counters are bridged.) */
+declare function instrumentDurableObject<T extends abstract new (...args: any[]) => object>(cls: T, opts?: OptsFn<any>): T;
+
+type SpanKindName = "internal" | "server" | "client" | "producer" | "consumer";
+interface SpanOpts {
+    attributes?: Attrs;
+    kind?: SpanKindName;
+}
+/** Run `fn` inside a new active span. The span is ended automatically and its
+ *  status set from success/throw. Works whether or not tracing is exporting —
+ *  falls back to a no-op span if no tracer is installed. */
+declare function span<T>(name: string, fn: (span: Span) => Promise<T> | T, opts?: SpanOpts): Promise<T>;
+
+interface Metrics {
+    /** Monotonic counter (delta). Formalizes odla-db's usage counters. */
+    count(name: string, by?: number, attrs?: Attrs): void;
+    /** Last-value gauge. */
+    gauge(name: string, value: number, attrs?: Attrs): void;
+    /** A single observation (recorded as a delta sum for now; histograms later). */
+    histogram(name: string, value: number, attrs?: Attrs, unit?: string): void;
+}
+/** The ambient metrics API for the current invocation. */
+declare function metrics(): Metrics;
+/** Convenience: increment a monotonic counter by `by` (default 1). */
+declare function count(name: string, by?: number, attrs?: Attrs): void;
+
+interface ErrorReport {
+    /** Stable, low-cardinality error code (e.g. "unique_violation"). */
+    code?: string;
+    /** Low-cardinality route/step where it happened. */
+    route?: string;
+    /** Extra low-cardinality attributes for the index. */
+    attributes?: Attrs;
+    /** Rich context for triage — kept only in the R2 artifact bundle. */
+    artifacts?: Record<string, unknown>;
+    /** Dedup key; the collector fingerprints by (type+code+route) if absent. */
+    fingerprint?: string;
+}
+/** Record a structured error. Returns an artifact id. The message and stack ride
+ *  the log body + a denied attribute so the collector persists them ONLY in the
+ *  R2 artifact bundle, never in metrics or the queryable index. */
+declare function recordError(err: unknown, report?: ErrorReport): string;
+
+/** The token accounting odla-kg's Provider already returns (and drops today). */
+interface LlmUsage {
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+interface LlmCostOpts {
+    provider: string;
+    model: string;
+    operation?: string;
+    attributes?: Attrs;
+    /** Override the built-in price table for this call. */
+    price?: ModelPrice;
+}
+/** Turn LLM token usage into first-class cost. Emits cost/token/call counters
+ *  and stamps the active span with GenAI semconv attributes. */
+declare function recordLlmUsage(usage: LlmUsage, opts: LlmCostOpts): {
+    costUsd: number;
+};
+
+export { type ErrorReport, type LlmCostOpts, type LlmUsage, type Metrics, type ObservabilityOptions, type OptsFn, type SpanKindName, type SpanOpts, count, instrumentDurableObject, metrics, recordError, recordLlmUsage, span, withObservability };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { Attrs, ModelPrice } from '@odla/o11y-core';
+export { Attrs } from '@odla/o11y-core';
+import { Span } from '@opentelemetry/api';
+
+interface ObservabilityOptions {
+    /** Service name (default: env.ODLA_O11Y_SERVICE). */
+    service?: string;
+    /** Collector base URL (default: env.ODLA_O11Y_ENDPOINT). */
+    endpoint?: string;
+    /** Per-service bearer token (default: env.ODLA_O11Y_TOKEN). */
+    token?: string;
+    /** Release/version tag (default: env.ODLA_O11Y_VERSION ?? "0.0.0"). */
+    version?: string;
+    /** Head-sampling ratio 0..1 for traces (default: 1). */
+    sampleRatio?: number;
+    /** Static resource attributes merged onto every signal. */
+    attributes?: Attrs;
+}
+type OptsFn<E> = ObservabilityOptions | ((env: E) => ObservabilityOptions);
+
+/** Wrap a Worker handler with tracing (otel-cf-workers) + the metrics/logs sink.
+ *  Config is read from env vars ODLA_O11Y_{ENDPOINT,SERVICE,TOKEN,VERSION} unless
+ *  overridden by `opts`. */
+declare function withObservability<E = unknown>(handler: ExportedHandler<E>, opts?: OptsFn<E>): ExportedHandler<E>;
+/** Wrap a Durable Object class with tracing. (Establishing the metrics/logs sink
+ *  inside DO methods is added in P1 when odla-db's usage counters are bridged.) */
+declare function instrumentDurableObject<T extends abstract new (...args: any[]) => object>(cls: T, opts?: OptsFn<any>): T;
+
+type SpanKindName = "internal" | "server" | "client" | "producer" | "consumer";
+interface SpanOpts {
+    attributes?: Attrs;
+    kind?: SpanKindName;
+}
+/** Run `fn` inside a new active span. The span is ended automatically and its
+ *  status set from success/throw. Works whether or not tracing is exporting —
+ *  falls back to a no-op span if no tracer is installed. */
+declare function span<T>(name: string, fn: (span: Span) => Promise<T> | T, opts?: SpanOpts): Promise<T>;
+
+interface Metrics {
+    /** Monotonic counter (delta). Formalizes odla-db's usage counters. */
+    count(name: string, by?: number, attrs?: Attrs): void;
+    /** Last-value gauge. */
+    gauge(name: string, value: number, attrs?: Attrs): void;
+    /** A single observation (recorded as a delta sum for now; histograms later). */
+    histogram(name: string, value: number, attrs?: Attrs, unit?: string): void;
+}
+/** The ambient metrics API for the current invocation. */
+declare function metrics(): Metrics;
+/** Convenience: increment a monotonic counter by `by` (default 1). */
+declare function count(name: string, by?: number, attrs?: Attrs): void;
+
+interface ErrorReport {
+    /** Stable, low-cardinality error code (e.g. "unique_violation"). */
+    code?: string;
+    /** Low-cardinality route/step where it happened. */
+    route?: string;
+    /** Extra low-cardinality attributes for the index. */
+    attributes?: Attrs;
+    /** Rich context for triage — kept only in the R2 artifact bundle. */
+    artifacts?: Record<string, unknown>;
+    /** Dedup key; the collector fingerprints by (type+code+route) if absent. */
+    fingerprint?: string;
+}
+/** Record a structured error. Returns an artifact id. The message and stack ride
+ *  the log body + a denied attribute so the collector persists them ONLY in the
+ *  R2 artifact bundle, never in metrics or the queryable index. */
+declare function recordError(err: unknown, report?: ErrorReport): string;
+
+/** The token accounting odla-kg's Provider already returns (and drops today). */
+interface LlmUsage {
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+interface LlmCostOpts {
+    provider: string;
+    model: string;
+    operation?: string;
+    attributes?: Attrs;
+    /** Override the built-in price table for this call. */
+    price?: ModelPrice;
+}
+/** Turn LLM token usage into first-class cost. Emits cost/token/call counters
+ *  and stamps the active span with GenAI semconv attributes. */
+declare function recordLlmUsage(usage: LlmUsage, opts: LlmCostOpts): {
+    costUsd: number;
+};
+
+export { type ErrorReport, type LlmCostOpts, type LlmUsage, type Metrics, type ObservabilityOptions, type OptsFn, type SpanKindName, type SpanOpts, count, instrumentDurableObject, metrics, recordError, recordLlmUsage, span, withObservability };

package/dist/index.js

@@ -0,0 +1,319 @@
+// src/instrument.ts
+import { instrument, instrumentDO } from "@microlabs/otel-cf-workers";
+
+// src/context.ts
+import { AsyncLocalStorage } from "async_hooks";
+
+// ../o11y-core/src/encode.ts
+function attrsToKvList(attrs) {
+  const out = [];
+  for (const [key, value] of Object.entries(attrs)) {
+    if (typeof value === "string") out.push({ key, value: { stringValue: value } });
+    else if (typeof value === "boolean") out.push({ key, value: { boolValue: value } });
+    else if (Number.isInteger(value)) out.push({ key, value: { intValue: String(value) } });
+    else out.push({ key, value: { doubleValue: value } });
+  }
+  return out;
+}
+var DELTA = 1;
+function encodeMetricsRequest(resource, scopeName, points) {
+  const metrics2 = points.map((p) => {
+    const dp = {
+      attributes: attrsToKvList(p.attrs),
+      startTimeUnixNano: p.startUnixNano,
+      timeUnixNano: p.timeUnixNano,
+      asDouble: p.value
+    };
+    return p.kind === "gauge" ? { name: p.name, unit: p.unit, gauge: { dataPoints: [dp] } } : { name: p.name, unit: p.unit, sum: { aggregationTemporality: DELTA, isMonotonic: true, dataPoints: [dp] } };
+  });
+  return {
+    resourceMetrics: [
+      { resource: { attributes: attrsToKvList(resource) }, scopeMetrics: [{ scope: { name: scopeName }, metrics: metrics2 }] }
+    ]
+  };
+}
+function encodeLogsRequest(resource, scopeName, records) {
+  return {
+    resourceLogs: [
+      {
+        resource: { attributes: attrsToKvList(resource) },
+        scopeLogs: [
+          {
+            scope: { name: scopeName },
+            logRecords: records.map((r) => ({
+              timeUnixNano: r.timeUnixNano,
+              observedTimeUnixNano: r.timeUnixNano,
+              severityNumber: r.severityNumber,
+              severityText: r.severityText,
+              body: { stringValue: r.body },
+              attributes: attrsToKvList(r.attrs),
+              ...r.traceId ? { traceId: r.traceId } : {},
+              ...r.spanId ? { spanId: r.spanId } : {}
+            }))
+          }
+        ]
+      }
+    ]
+  };
+}
+
+// ../o11y-core/src/pricing.ts
+var MODEL_PRICING = {
+  "claude-haiku-4-5": { inputPerMTok: 1, outputPerMTok: 5 },
+  "claude-sonnet-4-6": { inputPerMTok: 3, outputPerMTok: 15 },
+  "claude-sonnet-5": { inputPerMTok: 3, outputPerMTok: 15 },
+  "claude-opus-4-6": { inputPerMTok: 5, outputPerMTok: 25 },
+  "claude-opus-4-7": { inputPerMTok: 5, outputPerMTok: 25 },
+  "claude-opus-4-8": { inputPerMTok: 5, outputPerMTok: 25 },
+  "claude-fable-5": { inputPerMTok: 10, outputPerMTok: 50 }
+};
+function costUsd(model, inputTokens, outputTokens, override) {
+  const price = override ?? MODEL_PRICING[model];
+  if (!price) return 0;
+  return inputTokens / 1e6 * price.inputPerMTok + outputTokens / 1e6 * price.outputPerMTok;
+}
+
+// src/context.ts
+var SCOPE = "@odla-ai/o11y";
+function evalOpts(opts, env) {
+  return typeof opts === "function" ? opts(env) : opts ?? {};
+}
+function resolveConfig(env, opts) {
+  const o = evalOpts(opts, env);
+  const e = env;
+  return {
+    service: o.service ?? e["ODLA_O11Y_SERVICE"] ?? "unknown",
+    endpoint: (o.endpoint ?? e["ODLA_O11Y_ENDPOINT"] ?? "").replace(/\/$/, ""),
+    token: o.token ?? e["ODLA_O11Y_TOKEN"],
+    version: o.version ?? e["ODLA_O11Y_VERSION"] ?? "0.0.0",
+    attributes: o.attributes ?? {},
+    sampleRatio: o.sampleRatio
+  };
+}
+function nowNano() {
+  return `${Date.now()}000000`;
+}
+var als = new AsyncLocalStorage();
+function currentSink() {
+  return als.getStore();
+}
+function runWithSink(sink, fn) {
+  return als.run(sink, fn);
+}
+function resourceAttrs(config) {
+  return { "service.name": config.service, "service.version": config.version, ...config.attributes };
+}
+async function post(url, body, token) {
+  try {
+    await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...token ? { authorization: `Bearer ${token}` } : {}
+      },
+      body: JSON.stringify(body)
+    });
+  } catch {
+  }
+}
+function createSink(config) {
+  return {
+    config,
+    metrics: [],
+    logs: [],
+    async flush() {
+      if (!this.config.endpoint) {
+        this.metrics = [];
+        this.logs = [];
+        return;
+      }
+      const resource = resourceAttrs(this.config);
+      const jobs = [];
+      if (this.metrics.length) {
+        jobs.push(
+          post(`${this.config.endpoint}/v1/metrics`, encodeMetricsRequest(resource, SCOPE, this.metrics), this.config.token)
+        );
+        this.metrics = [];
+      }
+      if (this.logs.length) {
+        jobs.push(
+          post(`${this.config.endpoint}/v1/logs`, encodeLogsRequest(resource, SCOPE, this.logs), this.config.token)
+        );
+        this.logs = [];
+      }
+      await Promise.all(jobs);
+    }
+  };
+}
+
+// src/instrument.ts
+function traceConfig(env, opts) {
+  const c = resolveConfig(env, opts);
+  const headers = {};
+  if (c.token) headers.authorization = `Bearer ${c.token}`;
+  const config = {
+    exporter: { url: `${c.endpoint}/v1/traces`, headers },
+    service: { name: c.service, version: c.version }
+  };
+  if (c.sampleRatio != null) config.sampling = { headSampler: { ratio: c.sampleRatio } };
+  return config;
+}
+function wrapHandler(handler, opts) {
+  const wrapped = { ...handler };
+  const fetchImpl = handler.fetch;
+  if (fetchImpl) {
+    wrapped.fetch = (req, env, ctx) => {
+      const sink = createSink(resolveConfig(env, opts));
+      return runWithSink(sink, async () => {
+        try {
+          return await fetchImpl(req, env, ctx);
+        } finally {
+          ctx.waitUntil(sink.flush());
+        }
+      });
+    };
+  }
+  const scheduledImpl = handler.scheduled;
+  if (scheduledImpl) {
+    wrapped.scheduled = (controller, env, ctx) => {
+      const sink = createSink(resolveConfig(env, opts));
+      return runWithSink(sink, async () => {
+        try {
+          return await scheduledImpl(controller, env, ctx);
+        } finally {
+          ctx.waitUntil(sink.flush());
+        }
+      });
+    };
+  }
+  return wrapped;
+}
+function withObservability(handler, opts) {
+  const configFn = (env, _trigger) => traceConfig(env, opts);
+  return instrument(wrapHandler(handler, opts), configFn);
+}
+function instrumentDurableObject(cls, opts) {
+  const configFn = (env, _trigger) => traceConfig(env, opts);
+  return instrumentDO(cls, configFn);
+}
+
+// src/span.ts
+import { SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+var KIND = {
+  internal: SpanKind.INTERNAL,
+  server: SpanKind.SERVER,
+  client: SpanKind.CLIENT,
+  producer: SpanKind.PRODUCER,
+  consumer: SpanKind.CONSUMER
+};
+async function span(name, fn, opts) {
+  const tracer = trace.getTracer(SCOPE);
+  return tracer.startActiveSpan(
+    name,
+    { attributes: opts?.attributes, kind: opts?.kind ? KIND[opts.kind] : void 0 },
+    async (s) => {
+      try {
+        const result = await fn(s);
+        s.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (err) {
+        s.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });
+        throw err;
+      } finally {
+        s.end();
+      }
+    }
+  );
+}
+
+// src/metrics.ts
+function record(kind, name, value, attrs, unit) {
+  const sink = currentSink();
+  if (!sink) return;
+  const ts = nowNano();
+  sink.metrics.push({ name, unit, kind, value, attrs: attrs ?? {}, startUnixNano: ts, timeUnixNano: ts });
+}
+function metrics() {
+  return {
+    count: (name, by = 1, attrs) => record("sum", name, by, attrs),
+    gauge: (name, value, attrs) => record("gauge", name, value, attrs),
+    histogram: (name, value, attrs, unit) => record("sum", name, value, attrs, unit)
+  };
+}
+function count(name, by = 1, attrs) {
+  record("sum", name, by, attrs);
+}
+
+// src/logs.ts
+import { SpanStatusCode as SpanStatusCode2, trace as trace2 } from "@opentelemetry/api";
+var SEVERITY_ERROR = 17;
+function recordError(err, report) {
+  const error = err instanceof Error ? err : new Error(String(err));
+  const artifactId = `${Date.now().toString(16)}${crypto.randomUUID().replace(/-/g, "")}`;
+  const span2 = trace2.getActiveSpan();
+  const attrs = {
+    "error.type": error.name,
+    "odla.artifact_id": artifactId,
+    ...report?.code ? { "error.code": report.code } : {},
+    ...report?.route ? { "odla.route": report.route } : {},
+    ...report?.fingerprint ? { "odla.fingerprint": report.fingerprint } : {},
+    ...report?.attributes ?? {}
+  };
+  if (span2) {
+    span2.recordException(error);
+    span2.setStatus({ code: SpanStatusCode2.ERROR, message: error.message });
+    span2.setAttributes(attrs);
+  }
+  const sink = currentSink();
+  if (sink) {
+    const ctx = span2?.spanContext();
+    sink.logs.push({
+      timeUnixNano: nowNano(),
+      severityNumber: SEVERITY_ERROR,
+      severityText: "ERROR",
+      body: error.message,
+      // full message → R2 bundle only (collector-enforced)
+      attrs: {
+        ...attrs,
+        // Denied keys: stripped from metrics/index, retained in the R2 bundle.
+        ...error.stack ? { "exception.stacktrace": error.stack } : {},
+        ...report?.artifacts ? { "odla.artifacts": JSON.stringify(report.artifacts) } : {}
+      },
+      ...ctx ? { traceId: ctx.traceId, spanId: ctx.spanId } : {}
+    });
+  }
+  return artifactId;
+}
+
+// src/llm.ts
+import { trace as trace3 } from "@opentelemetry/api";
+function recordLlmUsage(usage, opts) {
+  const cost = costUsd(opts.model, usage.inputTokens, usage.outputTokens, opts.price);
+  const base = {
+    "gen_ai.provider.name": opts.provider,
+    "gen_ai.request.model": opts.model,
+    ...opts.operation ? { "gen_ai.operation.name": opts.operation } : {},
+    ...opts.attributes ?? {}
+  };
+  count("odla.llm.cost.usd", cost, base);
+  count("odla.llm.calls", usage.calls, base);
+  count("odla.llm.tokens", usage.inputTokens, { ...base, "gen_ai.token.type": "input" });
+  count("odla.llm.tokens", usage.outputTokens, { ...base, "gen_ai.token.type": "output" });
+  trace3.getActiveSpan()?.setAttributes({
+    ...base,
+    "gen_ai.usage.input_tokens": usage.inputTokens,
+    "gen_ai.usage.output_tokens": usage.outputTokens,
+    "odla.llm.cost.usd": cost
+  });
+  return { costUsd: cost };
+}
+export {
+  count,
+  instrumentDurableObject,
+  metrics,
+  recordError,
+  recordLlmUsage,
+  span,
+  withObservability
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/instrument.ts","../src/context.ts","../../o11y-core/src/encode.ts","../../o11y-core/src/pricing.ts","../src/span.ts","../src/metrics.ts","../src/logs.ts","../src/llm.ts"],"sourcesContent":["import { instrument, instrumentDO, type ResolveConfigFn, type TraceConfig } from \"@microlabs/otel-cf-workers\";\nimport { createSink, resolveConfig, runWithSink, type OptsFn } from \"./context.js\";\n\n/** Build the otel-cf-workers trace config (exporter + service) from env/opts. */\nfunction traceConfig<E>(env: E, opts?: OptsFn<E>): TraceConfig {\n  const c = resolveConfig(env, opts);\n  const headers: Record<string, string> = {};\n  if (c.token) headers.authorization = `Bearer ${c.token}`;\n  const config: TraceConfig = {\n    exporter: { url: `${c.endpoint}/v1/traces`, headers },\n    service: { name: c.service, version: c.version },\n  };\n  if (c.sampleRatio != null) config.sampling = { headSampler: { ratio: c.sampleRatio } };\n  return config;\n}\n\n/** Wrap each handler entrypoint so an ALS metrics/logs sink is live for the\n *  duration of the invocation and flushed via ctx.waitUntil at the end. */\nfunction wrapHandler<E>(handler: ExportedHandler<E>, opts?: OptsFn<E>): ExportedHandler<E> {\n  const wrapped: ExportedHandler<E> = { ...handler };\n\n  const fetchImpl = handler.fetch;\n  if (fetchImpl) {\n    wrapped.fetch = (req, env, ctx) => {\n      const sink = createSink(resolveConfig(env, opts));\n      return runWithSink(sink, async () => {\n        try {\n          return await fetchImpl(req, env, ctx);\n        } finally {\n          ctx.waitUntil(sink.flush());\n        }\n      });\n    };\n  }\n\n  const scheduledImpl = handler.scheduled;\n  if (scheduledImpl) {\n    wrapped.scheduled = (controller, env, ctx) => {\n      const sink = createSink(resolveConfig(env, opts));\n      return runWithSink(sink, async () => {\n        try {\n          return await scheduledImpl(controller, env, ctx);\n        } finally {\n          ctx.waitUntil(sink.flush());\n        }\n      });\n    };\n  }\n\n  return wrapped;\n}\n\n/** Wrap a Worker handler with tracing (otel-cf-workers) + the metrics/logs sink.\n *  Config is read from env vars ODLA_O11Y_{ENDPOINT,SERVICE,TOKEN,VERSION} unless\n *  overridden by `opts`. */\nexport function withObservability<E = unknown>(\n  handler: ExportedHandler<E>,\n  opts?: OptsFn<E>,\n): ExportedHandler<E> {\n  const configFn: ResolveConfigFn = (env, _trigger) => traceConfig(env as E, opts);\n  // instrument constrains E to its own Env type; we support any service env, so\n  // cross the boundary with `any` and restore the caller's E on the way out.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return instrument(wrapHandler(handler, opts) as ExportedHandler<any>, configFn) as ExportedHandler<E>;\n}\n\n/** Wrap a Durable Object class with tracing. (Establishing the metrics/logs sink\n *  inside DO methods is added in P1 when odla-db's usage counters are bridged.) */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport function instrumentDurableObject<T extends abstract new (...args: any[]) => object>(\n  cls: T,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  opts?: OptsFn<any>,\n): T {\n  const configFn: ResolveConfigFn = (env, _trigger) => traceConfig(env, opts);\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  return instrumentDO(cls as any, configFn) as unknown as T;\n}\n","import { AsyncLocalStorage } from \"node:async_hooks\";\nimport {\n  encodeLogsRequest,\n  encodeMetricsRequest,\n  type Attrs,\n  type LogRecord,\n  type MetricPoint,\n} from \"@odla/o11y-core\";\n\n/** The instrumentation scope name stamped on every signal. */\nexport const SCOPE = \"@odla-ai/o11y\";\n\nexport interface ObservabilityOptions {\n  /** Service name (default: env.ODLA_O11Y_SERVICE). */\n  service?: string;\n  /** Collector base URL (default: env.ODLA_O11Y_ENDPOINT). */\n  endpoint?: string;\n  /** Per-service bearer token (default: env.ODLA_O11Y_TOKEN). */\n  token?: string;\n  /** Release/version tag (default: env.ODLA_O11Y_VERSION ?? \"0.0.0\"). */\n  version?: string;\n  /** Head-sampling ratio 0..1 for traces (default: 1). */\n  sampleRatio?: number;\n  /** Static resource attributes merged onto every signal. */\n  attributes?: Attrs;\n}\n\nexport type OptsFn<E> = ObservabilityOptions | ((env: E) => ObservabilityOptions);\n\nexport interface ResolvedConfig {\n  service: string;\n  endpoint: string;\n  token?: string;\n  version: string;\n  attributes: Attrs;\n  sampleRatio?: number;\n}\n\nfunction evalOpts<E>(opts: OptsFn<E> | undefined, env: E): ObservabilityOptions {\n  return typeof opts === \"function\" ? opts(env) : (opts ?? {});\n}\n\n/** Resolve options against the service's env vars. */\nexport function resolveConfig<E>(env: E, opts?: OptsFn<E>): ResolvedConfig {\n  const o = evalOpts(opts, env);\n  const e = env as Record<string, string | undefined>;\n  return {\n    service: o.service ?? e[\"ODLA_O11Y_SERVICE\"] ?? \"unknown\",\n    endpoint: (o.endpoint ?? e[\"ODLA_O11Y_ENDPOINT\"] ?? \"\").replace(/\\/$/, \"\"),\n    token: o.token ?? e[\"ODLA_O11Y_TOKEN\"],\n    version: o.version ?? e[\"ODLA_O11Y_VERSION\"] ?? \"0.0.0\",\n    attributes: o.attributes ?? {},\n    sampleRatio: o.sampleRatio,\n  };\n}\n\n/** Nanoseconds since epoch as a decimal string (OTLP timestamp format). */\nexport function nowNano(): string {\n  return `${Date.now()}000000`;\n}\n\nexport interface Sink {\n  config: ResolvedConfig;\n  metrics: MetricPoint[];\n  logs: LogRecord[];\n  flush(): Promise<void>;\n}\n\nconst als = new AsyncLocalStorage<Sink>();\n\nexport function currentSink(): Sink | undefined {\n  return als.getStore();\n}\n\nexport function runWithSink<T>(sink: Sink, fn: () => Promise<T>): Promise<T> {\n  return als.run(sink, fn);\n}\n\nfunction resourceAttrs(config: ResolvedConfig): Attrs {\n  return { \"service.name\": config.service, \"service.version\": config.version, ...config.attributes };\n}\n\nasync function post(url: string, body: unknown, token?: string): Promise<void> {\n  try {\n    await fetch(url, {\n      method: \"POST\",\n      headers: {\n        \"content-type\": \"application/json\",\n        ...(token ? { authorization: `Bearer ${token}` } : {}),\n      },\n      body: JSON.stringify(body),\n    });\n  } catch {\n    // Telemetry export is best-effort — never surface into the app.\n  }\n}\n\n/** A per-invocation sink: accumulates metric/log records and flushes them to the\n *  collector as OTLP/JSON (traces are exported separately by otel-cf-workers). */\nexport function createSink(config: ResolvedConfig): Sink {\n  return {\n    config,\n    metrics: [],\n    logs: [],\n    async flush(): Promise<void> {\n      if (!this.config.endpoint) {\n        this.metrics = [];\n        this.logs = [];\n        return;\n      }\n      const resource = resourceAttrs(this.config);\n      const jobs: Promise<void>[] = [];\n      if (this.metrics.length) {\n        jobs.push(\n          post(`${this.config.endpoint}/v1/metrics`, encodeMetricsRequest(resource, SCOPE, this.metrics), this.config.token),\n        );\n        this.metrics = [];\n      }\n      if (this.logs.length) {\n        jobs.push(\n          post(`${this.config.endpoint}/v1/logs`, encodeLogsRequest(resource, SCOPE, this.logs), this.config.token),\n        );\n        this.logs = [];\n      }\n      await Promise.all(jobs);\n    },\n  };\n}\n","// OTLP/JSON encoders — the emit side of the wire contract (the SDK produces\n// these; the collector decodes them in later phases). Traces are produced by\n// @microlabs/otel-cf-workers; metrics and logs are hand-rolled here because that\n// library is traces-only and the Node OTel metrics SDK doesn't fit the isolate\n// model.\n\nimport type { Attrs, OtlpKeyValue, OtlpResource, OtlpScope } from \"./otlp.js\";\n\n/** Inverse of kvListToAttrs: a flat attr map → OTLP KeyValue[]. */\nexport function attrsToKvList(attrs: Attrs): OtlpKeyValue[] {\n  const out: OtlpKeyValue[] = [];\n  for (const [key, value] of Object.entries(attrs)) {\n    if (typeof value === \"string\") out.push({ key, value: { stringValue: value } });\n    else if (typeof value === \"boolean\") out.push({ key, value: { boolValue: value } });\n    else if (Number.isInteger(value)) out.push({ key, value: { intValue: String(value) } });\n    else out.push({ key, value: { doubleValue: value } });\n  }\n  return out;\n}\n\n// ---- Metrics ----\n\nexport type MetricKind = \"sum\" | \"gauge\";\n\nexport interface MetricPoint {\n  name: string;\n  unit?: string;\n  kind: MetricKind;\n  value: number;\n  attrs: Attrs;\n  startUnixNano: string;\n  timeUnixNano: string;\n}\n\ninterface OtlpNumberDataPoint {\n  attributes?: OtlpKeyValue[];\n  startTimeUnixNano?: string;\n  timeUnixNano: string;\n  asDouble: number;\n}\n\ninterface OtlpMetric {\n  name: string;\n  unit?: string;\n  sum?: { aggregationTemporality: number; isMonotonic: boolean; dataPoints: OtlpNumberDataPoint[] };\n  gauge?: { dataPoints: OtlpNumberDataPoint[] };\n}\n\nexport interface ExportMetricsServiceRequest {\n  resourceMetrics: Array<{\n    resource: OtlpResource;\n    scopeMetrics: Array<{ scope: OtlpScope; metrics: OtlpMetric[] }>;\n  }>;\n}\n\n// OTLP AggregationTemporality: 1 = DELTA. Each ephemeral isolate reports its own\n// delta; the collector aggregates across invocations into Analytics Engine.\nconst DELTA = 1;\n\nexport function encodeMetricsRequest(\n  resource: Attrs,\n  scopeName: string,\n  points: MetricPoint[],\n): ExportMetricsServiceRequest {\n  const metrics: OtlpMetric[] = points.map((p) => {\n    const dp: OtlpNumberDataPoint = {\n      attributes: attrsToKvList(p.attrs),\n      startTimeUnixNano: p.startUnixNano,\n      timeUnixNano: p.timeUnixNano,\n      asDouble: p.value,\n    };\n    return p.kind === \"gauge\"\n      ? { name: p.name, unit: p.unit, gauge: { dataPoints: [dp] } }\n      : { name: p.name, unit: p.unit, sum: { aggregationTemporality: DELTA, isMonotonic: true, dataPoints: [dp] } };\n  });\n  return {\n    resourceMetrics: [\n      { resource: { attributes: attrsToKvList(resource) }, scopeMetrics: [{ scope: { name: scopeName }, metrics }] },\n    ],\n  };\n}\n\n// ---- Logs (errors ride the logs signal) ----\n\nexport interface LogRecord {\n  timeUnixNano: string;\n  severityNumber: number; // OTel: 17 = ERROR, 9 = INFO\n  severityText: string;\n  body: string;\n  attrs: Attrs;\n  traceId?: string;\n  spanId?: string;\n}\n\nexport interface ExportLogsServiceRequest {\n  resourceLogs: Array<{\n    resource: OtlpResource;\n    scopeLogs: Array<{\n      scope: OtlpScope;\n      logRecords: Array<{\n        timeUnixNano: string;\n        observedTimeUnixNano: string;\n        severityNumber: number;\n        severityText: string;\n        body: { stringValue: string };\n        attributes: OtlpKeyValue[];\n        traceId?: string;\n        spanId?: string;\n      }>;\n    }>;\n  }>;\n}\n\nexport function encodeLogsRequest(\n  resource: Attrs,\n  scopeName: string,\n  records: LogRecord[],\n): ExportLogsServiceRequest {\n  return {\n    resourceLogs: [\n      {\n        resource: { attributes: attrsToKvList(resource) },\n        scopeLogs: [\n          {\n            scope: { name: scopeName },\n            logRecords: records.map((r) => ({\n              timeUnixNano: r.timeUnixNano,\n              observedTimeUnixNano: r.timeUnixNano,\n              severityNumber: r.severityNumber,\n              severityText: r.severityText,\n              body: { stringValue: r.body },\n              attributes: attrsToKvList(r.attrs),\n              ...(r.traceId ? { traceId: r.traceId } : {}),\n              ...(r.spanId ? { spanId: r.spanId } : {}),\n            })),\n          },\n        ],\n      },\n    ],\n  };\n}\n","// LLM price table + cost computation. OTel GenAI semconv has no cost attribute,\n// so we compute cost downstream from raw token counts × model price. Keep this\n// table in sync with current model pricing (verify against the claude-api\n// reference); unknown models cost 0 and should be added here.\n\nexport interface ModelPrice {\n  /** USD per million input tokens. */\n  inputPerMTok: number;\n  /** USD per million output tokens. */\n  outputPerMTok: number;\n}\n\n/** Prices in USD per million tokens (MTok). */\nexport const MODEL_PRICING: Record<string, ModelPrice> = {\n  \"claude-haiku-4-5\": { inputPerMTok: 1, outputPerMTok: 5 },\n  \"claude-sonnet-4-6\": { inputPerMTok: 3, outputPerMTok: 15 },\n  \"claude-sonnet-5\": { inputPerMTok: 3, outputPerMTok: 15 },\n  \"claude-opus-4-6\": { inputPerMTok: 5, outputPerMTok: 25 },\n  \"claude-opus-4-7\": { inputPerMTok: 5, outputPerMTok: 25 },\n  \"claude-opus-4-8\": { inputPerMTok: 5, outputPerMTok: 25 },\n  \"claude-fable-5\": { inputPerMTok: 10, outputPerMTok: 50 },\n};\n\n/** Compute USD cost for a call. Pass `override` to price a model not in the\n *  table (or to apply promotional pricing). Returns 0 for unknown models. */\nexport function costUsd(\n  model: string,\n  inputTokens: number,\n  outputTokens: number,\n  override?: ModelPrice,\n): number {\n  const price = override ?? MODEL_PRICING[model];\n  if (!price) return 0;\n  return (inputTokens / 1_000_000) * price.inputPerMTok + (outputTokens / 1_000_000) * price.outputPerMTok;\n}\n","import { SpanKind, SpanStatusCode, trace, type Span } from \"@opentelemetry/api\";\nimport type { Attrs } from \"@odla/o11y-core\";\nimport { SCOPE } from \"./context.js\";\n\nexport type SpanKindName = \"internal\" | \"server\" | \"client\" | \"producer\" | \"consumer\";\n\nexport interface SpanOpts {\n  attributes?: Attrs;\n  kind?: SpanKindName;\n}\n\nconst KIND: Record<SpanKindName, SpanKind> = {\n  internal: SpanKind.INTERNAL,\n  server: SpanKind.SERVER,\n  client: SpanKind.CLIENT,\n  producer: SpanKind.PRODUCER,\n  consumer: SpanKind.CONSUMER,\n};\n\n/** Run `fn` inside a new active span. The span is ended automatically and its\n *  status set from success/throw. Works whether or not tracing is exporting —\n *  falls back to a no-op span if no tracer is installed. */\nexport async function span<T>(\n  name: string,\n  fn: (span: Span) => Promise<T> | T,\n  opts?: SpanOpts,\n): Promise<T> {\n  const tracer = trace.getTracer(SCOPE);\n  return tracer.startActiveSpan(\n    name,\n    { attributes: opts?.attributes, kind: opts?.kind ? KIND[opts.kind] : undefined },\n    async (s) => {\n      try {\n        const result = await fn(s);\n        s.setStatus({ code: SpanStatusCode.OK });\n        return result;\n      } catch (err) {\n        s.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) });\n        throw err;\n      } finally {\n        s.end();\n      }\n    },\n  );\n}\n","import type { Attrs } from \"@odla/o11y-core\";\nimport { currentSink, nowNano } from \"./context.js\";\n\nexport interface Metrics {\n  /** Monotonic counter (delta). Formalizes odla-db's usage counters. */\n  count(name: string, by?: number, attrs?: Attrs): void;\n  /** Last-value gauge. */\n  gauge(name: string, value: number, attrs?: Attrs): void;\n  /** A single observation (recorded as a delta sum for now; histograms later). */\n  histogram(name: string, value: number, attrs?: Attrs, unit?: string): void;\n}\n\nfunction record(kind: \"sum\" | \"gauge\", name: string, value: number, attrs?: Attrs, unit?: string): void {\n  const sink = currentSink();\n  if (!sink) return; // outside an instrumented invocation — no-op\n  const ts = nowNano();\n  sink.metrics.push({ name, unit, kind, value, attrs: attrs ?? {}, startUnixNano: ts, timeUnixNano: ts });\n}\n\n/** The ambient metrics API for the current invocation. */\nexport function metrics(): Metrics {\n  return {\n    count: (name, by = 1, attrs) => record(\"sum\", name, by, attrs),\n    gauge: (name, value, attrs) => record(\"gauge\", name, value, attrs),\n    histogram: (name, value, attrs, unit) => record(\"sum\", name, value, attrs, unit),\n  };\n}\n\n/** Convenience: increment a monotonic counter by `by` (default 1). */\nexport function count(name: string, by = 1, attrs?: Attrs): void {\n  record(\"sum\", name, by, attrs);\n}\n","import { SpanStatusCode, trace } from \"@opentelemetry/api\";\nimport type { Attrs } from \"@odla/o11y-core\";\nimport { currentSink, nowNano } from \"./context.js\";\n\nexport interface ErrorReport {\n  /** Stable, low-cardinality error code (e.g. \"unique_violation\"). */\n  code?: string;\n  /** Low-cardinality route/step where it happened. */\n  route?: string;\n  /** Extra low-cardinality attributes for the index. */\n  attributes?: Attrs;\n  /** Rich context for triage — kept only in the R2 artifact bundle. */\n  artifacts?: Record<string, unknown>;\n  /** Dedup key; the collector fingerprints by (type+code+route) if absent. */\n  fingerprint?: string;\n}\n\n// OTel severity number for ERROR.\nconst SEVERITY_ERROR = 17;\n\n/** Record a structured error. Returns an artifact id. The message and stack ride\n *  the log body + a denied attribute so the collector persists them ONLY in the\n *  R2 artifact bundle, never in metrics or the queryable index. */\nexport function recordError(err: unknown, report?: ErrorReport): string {\n  const error = err instanceof Error ? err : new Error(String(err));\n  const artifactId = `${Date.now().toString(16)}${crypto.randomUUID().replace(/-/g, \"\")}`;\n  const span = trace.getActiveSpan();\n\n  const attrs: Attrs = {\n    \"error.type\": error.name,\n    \"odla.artifact_id\": artifactId,\n    ...(report?.code ? { \"error.code\": report.code } : {}),\n    ...(report?.route ? { \"odla.route\": report.route } : {}),\n    ...(report?.fingerprint ? { \"odla.fingerprint\": report.fingerprint } : {}),\n    ...(report?.attributes ?? {}),\n  };\n\n  if (span) {\n    span.recordException(error);\n    span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });\n    span.setAttributes(attrs);\n  }\n\n  const sink = currentSink();\n  if (sink) {\n    const ctx = span?.spanContext();\n    sink.logs.push({\n      timeUnixNano: nowNano(),\n      severityNumber: SEVERITY_ERROR,\n      severityText: \"ERROR\",\n      body: error.message, // full message → R2 bundle only (collector-enforced)\n      attrs: {\n        ...attrs,\n        // Denied keys: stripped from metrics/index, retained in the R2 bundle.\n        ...(error.stack ? { \"exception.stacktrace\": error.stack } : {}),\n        ...(report?.artifacts ? { \"odla.artifacts\": JSON.stringify(report.artifacts) } : {}),\n      },\n      ...(ctx ? { traceId: ctx.traceId, spanId: ctx.spanId } : {}),\n    });\n  }\n\n  return artifactId;\n}\n","import { trace } from \"@opentelemetry/api\";\nimport { costUsd, type Attrs, type ModelPrice } from \"@odla/o11y-core\";\nimport { count } from \"./metrics.js\";\n\n/** The token accounting odla-kg's Provider already returns (and drops today). */\nexport interface LlmUsage {\n  calls: number;\n  inputTokens: number;\n  outputTokens: number;\n}\n\nexport interface LlmCostOpts {\n  provider: string; // \"claude\" | \"openai\" | ...\n  model: string; // e.g. \"claude-sonnet-4-6\"\n  operation?: string; // \"extract\" | \"search\" | ...\n  attributes?: Attrs;\n  /** Override the built-in price table for this call. */\n  price?: ModelPrice;\n}\n\n/** Turn LLM token usage into first-class cost. Emits cost/token/call counters\n *  and stamps the active span with GenAI semconv attributes. */\nexport function recordLlmUsage(usage: LlmUsage, opts: LlmCostOpts): { costUsd: number } {\n  const cost = costUsd(opts.model, usage.inputTokens, usage.outputTokens, opts.price);\n  const base: Attrs = {\n    \"gen_ai.provider.name\": opts.provider,\n    \"gen_ai.request.model\": opts.model,\n    ...(opts.operation ? { \"gen_ai.operation.name\": opts.operation } : {}),\n    ...(opts.attributes ?? {}),\n  };\n\n  count(\"odla.llm.cost.usd\", cost, base);\n  count(\"odla.llm.calls\", usage.calls, base);\n  count(\"odla.llm.tokens\", usage.inputTokens, { ...base, \"gen_ai.token.type\": \"input\" });\n  count(\"odla.llm.tokens\", usage.outputTokens, { ...base, \"gen_ai.token.type\": \"output\" });\n\n  trace.getActiveSpan()?.setAttributes({\n    ...base,\n    \"gen_ai.usage.input_tokens\": usage.inputTokens,\n    \"gen_ai.usage.output_tokens\": usage.outputTokens,\n    \"odla.llm.cost.usd\": cost,\n  });\n\n  return { costUsd: cost };\n}\n"],"mappings":"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","names":["metrics","SpanStatusCode","trace","span","trace","SpanStatusCode","trace","trace"]}

package/llms.txt

@@ -0,0 +1,156 @@
+# @odla-ai/o11y — LLM context
+
+> Official observability client for odla Cloudflare Workers — OpenTelemetry traces, metrics, structured errors, and LLM cost, exported over OTLP to the odla-o11y collector.
+
+Official observability client for [odla](https://github.com/) Cloudflare Workers.
+Wrap your Worker once and get OpenTelemetry **traces**, **metrics**, structured
+**errors**, and **LLM cost** — exported over OTLP to the odla-o11y collector.
+
+- Traces via [`@microlabs/otel-cf-workers`](https://github.com/evanderkoogh/otel-cf-workers) (auto-instruments incoming/outgoing fetch, Durable Objects, and bindings).
+- Metrics + logs via lightweight OTLP/JSON emitters (the traces-only otel library doesn't cover them, and the Node metrics SDK doesn't fit the isolate model).
+- Targets the Cloudflare Workers runtime; requires the `nodejs_compat` flag.
+
+## Install
+
+```sh
+npm i @odla-ai/o11y
+```
+
+## Use
+
+```ts
+import { withObservability, span, count, recordError, recordLlmUsage } from "@odla-ai/o11y";
+
+const handler = {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    count("http.requests", 1, { "http.route": new URL(req.url).pathname });
+    return span("handle", async () => new Response("ok"), { kind: "server" });
+  },
+} satisfies ExportedHandler<Env>;
+
+export default withObservability(handler);
+```
+
+Wrap a Durable Object class with `instrumentDurableObject(MyDO)`.
+
+## Configuration
+
+Config is read from env vars (override per call via the second `withObservability` arg):
+
+| Var | Meaning |
+| --- | --- |
+| `ODLA_O11Y_ENDPOINT` | Collector base URL (e.g. `https://odla-o11y.workers.dev`) |
+| `ODLA_O11Y_SERVICE` | This service's name |
+| `ODLA_O11Y_TOKEN` | Per-service bearer token (secret) |
+| `ODLA_O11Y_VERSION` | Release tag (optional) |
+
+`wrangler.jsonc` needs `"compatibility_flags": ["nodejs_compat"]` (for AsyncLocalStorage).
+
+## API
+
+- `withObservability(handler, opts?)` — wrap a Worker handler (fetch/scheduled).
+- `instrumentDurableObject(cls, opts?)` — wrap a Durable Object class.
+- `span(name, fn, opts?)` — run `fn` inside an active span.
+- `count(name, by?, attrs?)` / `metrics()` — counters, gauges, histograms.
+- `recordError(err, report?)` — structured error; message/stack go only to the
+  collector's R2 artifact bundle, never to metrics.
+- `recordLlmUsage(usage, opts)` — turn `{calls, inputTokens, outputTokens}` into
+  cost + token metrics and GenAI span attributes.
+
+## License
+
+MIT
+
+## API reference (generated from dist/index.d.ts, v1.0.0)
+
+```ts
+import { Attrs, ModelPrice } from '@odla/o11y-core';
+export { Attrs } from '@odla/o11y-core';
+import { Span } from '@opentelemetry/api';
+
+interface ObservabilityOptions {
+    /** Service name (default: env.ODLA_O11Y_SERVICE). */
+    service?: string;
+    /** Collector base URL (default: env.ODLA_O11Y_ENDPOINT). */
+    endpoint?: string;
+    /** Per-service bearer token (default: env.ODLA_O11Y_TOKEN). */
+    token?: string;
+    /** Release/version tag (default: env.ODLA_O11Y_VERSION ?? "0.0.0"). */
+    version?: string;
+    /** Head-sampling ratio 0..1 for traces (default: 1). */
+    sampleRatio?: number;
+    /** Static resource attributes merged onto every signal. */
+    attributes?: Attrs;
+}
+type OptsFn<E> = ObservabilityOptions | ((env: E) => ObservabilityOptions);
+
+/** Wrap a Worker handler with tracing (otel-cf-workers) + the metrics/logs sink.
+ *  Config is read from env vars ODLA_O11Y_{ENDPOINT,SERVICE,TOKEN,VERSION} unless
+ *  overridden by `opts`. */
+declare function withObservability<E = unknown>(handler: ExportedHandler<E>, opts?: OptsFn<E>): ExportedHandler<E>;
+/** Wrap a Durable Object class with tracing. (Establishing the metrics/logs sink
+ *  inside DO methods is added in P1 when odla-db's usage counters are bridged.) */
+declare function instrumentDurableObject<T extends abstract new (...args: any[]) => object>(cls: T, opts?: OptsFn<any>): T;
+
+type SpanKindName = "internal" | "server" | "client" | "producer" | "consumer";
+interface SpanOpts {
+    attributes?: Attrs;
+    kind?: SpanKindName;
+}
+/** Run `fn` inside a new active span. The span is ended automatically and its
+ *  status set from success/throw. Works whether or not tracing is exporting —
+ *  falls back to a no-op span if no tracer is installed. */
+declare function span<T>(name: string, fn: (span: Span) => Promise<T> | T, opts?: SpanOpts): Promise<T>;
+
+interface Metrics {
+    /** Monotonic counter (delta). Formalizes odla-db's usage counters. */
+    count(name: string, by?: number, attrs?: Attrs): void;
+    /** Last-value gauge. */
+    gauge(name: string, value: number, attrs?: Attrs): void;
+    /** A single observation (recorded as a delta sum for now; histograms later). */
+    histogram(name: string, value: number, attrs?: Attrs, unit?: string): void;
+}
+/** The ambient metrics API for the current invocation. */
+declare function metrics(): Metrics;
+/** Convenience: increment a monotonic counter by `by` (default 1). */
+declare function count(name: string, by?: number, attrs?: Attrs): void;
+
+interface ErrorReport {
+    /** Stable, low-cardinality error code (e.g. "unique_violation"). */
+    code?: string;
+    /** Low-cardinality route/step where it happened. */
+    route?: string;
+    /** Extra low-cardinality attributes for the index. */
+    attributes?: Attrs;
+    /** Rich context for triage — kept only in the R2 artifact bundle. */
+    artifacts?: Record<string, unknown>;
+    /** Dedup key; the collector fingerprints by (type+code+route) if absent. */
+    fingerprint?: string;
+}
+/** Record a structured error. Returns an artifact id. The message and stack ride
+ *  the log body + a denied attribute so the collector persists them ONLY in the
+ *  R2 artifact bundle, never in metrics or the queryable index. */
+declare function recordError(err: unknown, report?: ErrorReport): string;
+
+/** The token accounting odla-kg's Provider already returns (and drops today). */
+interface LlmUsage {
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+interface LlmCostOpts {
+    provider: string;
+    model: string;
+    operation?: string;
+    attributes?: Attrs;
+    /** Override the built-in price table for this call. */
+    price?: ModelPrice;
+}
+/** Turn LLM token usage into first-class cost. Emits cost/token/call counters
+ *  and stamps the active span with GenAI semconv attributes. */
+declare function recordLlmUsage(usage: LlmUsage, opts: LlmCostOpts): {
+    costUsd: number;
+};
+
+export { type ErrorReport, type LlmCostOpts, type LlmUsage, type Metrics, type ObservabilityOptions, type OptsFn, type SpanKindName, type SpanOpts, count, instrumentDurableObject, metrics, recordError, recordLlmUsage, span, withObservability };
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@odla-ai/o11y",
+  "version": "1.0.0",
+  "description": "Official observability client for odla Cloudflare Workers — OpenTelemetry traces, metrics, structured errors, and LLM cost, exported over OTLP to the odla-o11y collector.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md", "llms.txt"],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["odla", "odla-o11y", "observability", "opentelemetry", "otlp", "tracing", "metrics", "llm-cost", "cloudflare", "workers"],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "test": "vitest run --passWithNoTests",
+    "gen:llms": "node ../../scripts/gen-llms.mjs",
+    "prepublishOnly": "npm run build && npm run gen:llms"
+  },
+  "dependencies": {
+    "@microlabs/otel-cf-workers": "^1.0.0-rc.52",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "devDependencies": {
+    "@odla/o11y-core": "*",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}