@pepys/source-telemetry 0.0.0-stage → 0.0.1

package/src/otlp/read-otlp-facts.ts

@@ -0,0 +1,226 @@
+import { createHash } from 'node:crypto';
+import { parseEntityID } from '@pepys/kit';
+import type { LogRecordPayload } from '../log-record-family.ts';
+import type { TelemetryProduct } from '../products/types.ts';
+import { formatCanonicalJSON } from './format-canonical-json.ts';
+import { toAttributeMap } from './to-attribute-map.ts';
+import type { AttributeValue, LogRecord, LogsExport, OtlpLogRecord } from './types.ts';
+
+export interface OtlpReadOptions {
+  products: readonly TelemetryProduct[];
+
+  // the attribute that holds the session, read from the resource first and from the record second
+  sessionAttribute: string;
+}
+
+// One fact as a fact batch sender writes it. The read of the route adds the proven sender as the
+// payload's `origin`.
+export interface TelemetryFact {
+  type: string;
+  event: string;
+  entity: `telemetry:session:${string}`;
+  at: string;
+  payload: Omit<LogRecordPayload, 'origin'>;
+}
+
+// Why a record made no fact. A dropped record never refuses the export it came in.
+export type DroppedRecord =
+  | { reason: 'unknown-product' }
+
+  // neither the session attribute nor the product's own session attribute has a value
+  | { reason: 'no-session'; product: string; event: string }
+  | { reason: 'no-time'; product: string; event: string };
+
+export interface OtlpFacts {
+  facts: readonly TelemetryFact[];
+  dropped: readonly DroppedRecord[];
+}
+
+// Pure: one fact per log record of a known product, with an ID that depends on the record alone.
+export function readOtlpFacts(body: LogsExport, options: OtlpReadOptions): OtlpFacts {
+  const facts: TelemetryFact[] = [];
+  const dropped: DroppedRecord[] = [];
+
+  for (const resourceLogs of body.resourceLogs) {
+    const resource = toAttributeMap(resourceLogs.resource.attributes);
+
+    for (const scopeLogs of resourceLogs.scopeLogs) {
+      for (const raw of scopeLogs.logRecords) {
+        const record: LogRecord = {
+          scope: { name: scopeLogs.scope.name },
+          resource,
+          attributes: toAttributeMap(raw.attributes ?? []),
+          raw,
+        };
+
+        const built = buildFact(record, options);
+
+        if ('reason' in built) {
+          dropped.push(built);
+        } else {
+          facts.push({
+            ...built,
+            payload: {
+              resource: { attributes: [...resourceLogs.resource.attributes] },
+              scope: scopeLogs.scope,
+              logRecord: raw,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return { facts, dropped };
+}
+
+function buildFact(
+  record: LogRecord,
+  options: OtlpReadOptions,
+): Omit<TelemetryFact, 'payload'> | DroppedRecord {
+  const owner = findOwner(record, options.products);
+
+  if (owner === undefined) {
+    return { reason: 'unknown-product' };
+  }
+
+  const product = owner.product;
+  const event = owner.event;
+  const attribute = product.agentSessionAttribute;
+  const agentSession = toText(record.attributes[attribute]) ?? toText(record.resource[attribute]);
+
+  const session =
+    toText(record.resource[options.sessionAttribute]) ??
+    toText(record.attributes[options.sessionAttribute]) ??
+    agentSession;
+
+  const entity = session === undefined ? undefined : toSessionEntity(session);
+
+  if (entity === undefined) {
+    return { reason: 'no-session', product: product.name, event };
+  }
+
+  const at = pickTime(record, product.timeAttribute);
+
+  if (at === undefined) {
+    return { reason: 'no-time', product: product.name, event };
+  }
+
+  const isListed = Object.hasOwn(product.events, event);
+  const eventName = `${product.name}.${event}`;
+  const key = isListed ? product.events[event]?.key?.(record) : undefined;
+
+  return {
+    type: `telemetry.${product.name}.${isListed ? event : 'unlisted'}`,
+    event: `${eventName}:${key ?? `h-${buildRecordHash(record.raw, eventName, agentSession)}`}`,
+    entity,
+    at,
+  };
+}
+
+function findOwner(
+  record: LogRecord,
+  list: readonly TelemetryProduct[],
+): { product: TelemetryProduct; event: string } | undefined {
+  for (const product of list) {
+    const event = product.readEvent(record);
+
+    if (event !== undefined) {
+      return { product, event };
+    }
+  }
+
+  return undefined;
+}
+
+function toText(value: AttributeValue | undefined): string | undefined {
+  if (typeof value === 'number') {
+    return String(value);
+  }
+
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+function toSessionEntity(session: string): `telemetry:session:${string}` | undefined {
+  const entity = `telemetry:session:${session}` as const;
+
+  return parseEntityID(entity).ok ? entity : undefined;
+}
+
+// The time the product wrote, as ISO text in UTC; never the time ingest read the record.
+function pickTime(record: LogRecord, timeAttribute: string): string | undefined {
+  const written = record.attributes[timeAttribute];
+  const writtenMs = typeof written === 'string' ? Date.parse(written) : Number.NaN;
+
+  if (Number.isFinite(writtenMs)) {
+    return toISOTime(writtenMs);
+  }
+
+  return toTimeFromNanoseconds(record.raw['timeUnixNano']);
+}
+
+// A fact's time is ISO text with a four-digit year, which the envelope check takes.
+function toISOTime(timeMs: number): string | undefined {
+  const date = new Date(timeMs);
+
+  if (!Number.isFinite(date.getTime())) {
+    return undefined;
+  }
+
+  const text = date.toISOString();
+
+  return /^\d{4}-/u.test(text) ? text : undefined;
+}
+
+const nanosecondsPerMillisecond = 1_000_000n;
+
+// OTLP JSON writes the time as decimal text, and an exporter may write a number; 0 means the time
+// is unknown.
+function toTimeFromNanoseconds(value: unknown): string | undefined {
+  const nanoseconds = toNanoseconds(value);
+
+  if (nanoseconds === undefined || nanoseconds === 0n) {
+    return undefined;
+  }
+
+  return toISOTime(Number(nanoseconds / nanosecondsPerMillisecond));
+}
+
+function toNanoseconds(value: unknown): bigint | undefined {
+  if (typeof value === 'number') {
+    return Number.isInteger(value) && value >= 0 ? BigInt(value) : undefined;
+  }
+
+  return typeof value === 'string' && /^\d+$/u.test(value) ? BigInt(value) : undefined;
+}
+
+// What the product wrote: its own session ID, the event name, the time, the body, and the
+// attributes sorted by name. The resource and the observed time stay out, because a sink that
+// forwards a record may set both again.
+function buildRecordHash(
+  raw: OtlpLogRecord,
+  eventName: string,
+  agentSession: string | undefined,
+): string {
+  const attributes = (raw.attributes ?? []).toSorted((left, right) =>
+    compareText(left.key, right.key),
+  );
+
+  const hashed = formatCanonicalJSON([
+    agentSession ?? null,
+    eventName,
+    raw['timeUnixNano'] ?? null,
+    raw['body'] ?? null,
+    attributes,
+  ]);
+
+  return createHash('sha256').update(hashed).digest('hex');
+}
+
+function compareText(left: string, right: string): number {
+  if (left === right) {
+    return 0;
+  }
+
+  return left < right ? -1 : 1;
+}

package/src/otlp/receive-otlp-logs.ts

@@ -0,0 +1,130 @@
+import { buildEventFactID } from '@pepys/kit';
+import type {
+  DeliveryCheck,
+  EntityID,
+  FactFamily,
+  PendingFact,
+  ReceivePath,
+  Received,
+  Sender,
+  SourceContext,
+  StreamName,
+} from '@pepys/kit';
+import { toTagged } from '@zgeoff/std';
+import invariant from 'tiny-invariant';
+import { parseLogsExport } from './parse-logs-export.ts';
+import { readOtlpFacts } from './read-otlp-facts.ts';
+import type { DroppedRecord, OtlpReadOptions, TelemetryFact } from './read-otlp-facts.ts';
+
+type OtlpLogsReceiver = Pick<
+  ReceivePath,
+  | 'route'
+  | 'ignoredRoutes'
+  | 'bodyByteLimit'
+  | 'factLimit'
+  | 'encodings'
+  | 'answer'
+  | 'reach'
+  | 'sender'
+> &
+  OtlpReadOptions & { check: DeliveryCheck };
+
+// The receive path of OTLP/HTTP logs in JSON. Ingest has checked the method, the size, the token
+// and the sender, and has unpacked a gzip body, before `read` sees the export.
+export function receiveOtlpLogs(receiver: OtlpLogsReceiver): ReceivePath {
+  const { products, sessionAttribute, ...path } = receiver;
+
+  return {
+    ...path,
+    kind: 'receive',
+    read: (delivery, source) => {
+      if (!isJSONContentType(delivery.headers.get('content-type'))) {
+        return {
+          kind: 'refused',
+          status: 400,
+          reason: 'the body must be OTLP JSON, with the content type application/json',
+        };
+      }
+
+      const body = parseLogsExport(parseJSON(new TextDecoder().decode(delivery.body)));
+
+      if (body === undefined) {
+        return { kind: 'refused', status: 400, reason: 'the body is no OTLP logs export' };
+      }
+
+      // ingest calls `read` on a path with a `sender` only once a sender is proven
+      invariant(delivery.sender !== undefined, 'a telemetry export always has a proven sender');
+
+      const read = readOtlpFacts(body, { products, sessionAttribute });
+
+      if (read.dropped.length > 0) {
+        console.warn(`the source ${source.name} dropped log records`, formatDropped(read.dropped));
+      }
+
+      return buildReceived(read.facts, delivery.sender, source);
+    },
+  };
+}
+
+function isJSONContentType(contentType: string | null): boolean {
+  return contentType?.split(';')[0]?.trim().toLowerCase() === 'application/json';
+}
+
+function parseJSON(text: string): unknown {
+  try {
+    const value: unknown = JSON.parse(text);
+
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+// One line per export: the count of each reason, never the records.
+function formatDropped(dropped: readonly DroppedRecord[]): string {
+  const counts = new Map<string, number>();
+
+  for (const record of dropped) {
+    counts.set(record.reason, (counts.get(record.reason) ?? 0) + 1);
+  }
+
+  return JSON.stringify(Object.fromEntries(counts));
+}
+
+function buildReceived(
+  facts: readonly TelemetryFact[],
+  sender: Sender,
+  source: SourceContext,
+): Received {
+  if (facts.length === 0) {
+    return { kind: 'ignored' };
+  }
+
+  const pending: PendingFact[] = [];
+
+  for (const fact of facts) {
+    const family = findFamily(source.families, fact.type);
+
+    invariant(family !== undefined, `the source has a family for ${fact.type}`);
+
+    pending.push({
+      stream: toTagged<StreamName>(family.stream),
+      fact: {
+        id: buildEventFactID({ source: source.name, event: fact.event }),
+        type: fact.type,
+        v: 1,
+        api: family.api,
+        entity: toTagged<EntityID>(fact.entity),
+        at: fact.at,
+        payload: { ...fact.payload, origin: { issuer: sender.issuer, subject: sender.subject } },
+      },
+      blobs: [],
+    });
+  }
+
+  return { kind: 'batch', batch: { facts: pending } };
+}
+
+function findFamily(families: readonly FactFamily[], type: string): FactFamily | undefined {
+  return families.find((family) => Object.hasOwn(family.types, type));
+}

package/src/otlp/to-attribute-map.ts

@@ -0,0 +1,63 @@
+import { isRecord } from '@zgeoff/std';
+import type { AttributeValue, OtlpKeyValue } from './types.ts';
+
+// The scalar attributes as a plain map. OTLP JSON writes a 64-bit integer as text, and an exporter
+// may write any number as text, so an `intValue` that is a safe integer becomes a number. A list or
+// a map value has no entry.
+export function toAttributeMap(
+  attributes: readonly OtlpKeyValue[],
+): Readonly<Record<string, AttributeValue>> {
+  return Object.fromEntries(
+    attributes.flatMap((attribute) => {
+      const value = toAttributeValue(attribute.value);
+
+      return value === undefined ? [] : [[attribute.key, value] as const];
+    }),
+  );
+}
+
+function toAttributeValue(value: unknown): AttributeValue | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const text = value['stringValue'];
+  const integer = value['intValue'];
+  const double = value['doubleValue'];
+  const flag = value['boolValue'];
+
+  if (typeof text === 'string') {
+    return text;
+  }
+
+  if (typeof integer === 'number' || typeof integer === 'string') {
+    return toInteger(integer);
+  }
+
+  if (typeof double === 'number' || typeof double === 'string') {
+    return toDouble(double);
+  }
+
+  return typeof flag === 'boolean' ? flag : undefined;
+}
+
+function toInteger(value: number | string): AttributeValue {
+  if (typeof value === 'string' && !/^-?\d+$/u.test(value)) {
+    return value;
+  }
+
+  const number = Number(value);
+
+  return Number.isSafeInteger(number) ? number : String(value);
+}
+
+// OTLP JSON writes NaN and the infinities as text.
+function toDouble(value: number | string): AttributeValue | undefined {
+  if (typeof value === 'string' && value.trim() === '') {
+    return undefined;
+  }
+
+  const number = Number(value);
+
+  return Number.isFinite(number) ? number : undefined;
+}

package/src/otlp/types.ts

@@ -0,0 +1,36 @@
+// The body of an OTLP/HTTP logs export in its JSON form. Only the fields ingest reads are typed.
+export interface LogsExport {
+  resourceLogs: readonly ResourceLogs[];
+}
+
+export interface ResourceLogs {
+  resource: { attributes: readonly OtlpKeyValue[] };
+  scopeLogs: readonly ScopeLogs[];
+}
+
+export interface ScopeLogs {
+  scope: { name: string; version?: string | undefined };
+  logRecords: readonly OtlpLogRecord[];
+}
+
+export interface OtlpKeyValue {
+  key: string;
+  value: unknown;
+}
+
+// A record as the exporter wrote it. OTLP JSON writes a 64-bit integer as text, and an exporter
+// may write it as a number, so each field the exporter owns stays as it came.
+export interface OtlpLogRecord {
+  readonly [field: string]: unknown;
+  attributes?: OtlpKeyValue[] | undefined;
+}
+
+export type AttributeValue = string | number | boolean;
+
+// What a product's functions get: one record with its attributes as plain maps. Never stored.
+export interface LogRecord {
+  scope: { name: string };
+  resource: Readonly<Record<string, AttributeValue>>;
+  attributes: Readonly<Record<string, AttributeValue>>;
+  raw: OtlpLogRecord;
+}

package/src/products/claude-code/claude-code-product.ts

@@ -0,0 +1,45 @@
+import type { LogRecord } from '../../otlp/types.ts';
+import { defineTelemetryProduct } from '../define-telemetry-product.ts';
+import { findAttributeText } from '../find-attribute-text.ts';
+
+const scopePrefix = 'com.anthropic.claude_code';
+const eventPrefix = 'claude_code.';
+
+export const claudeCodeProduct = defineTelemetryProduct({
+  name: 'claude_code',
+  readEvent: findClaudeCodeEvent,
+  agentSessionAttribute: 'session.id',
+  timeAttribute: 'event.timestamp',
+  events: {
+    // `api_request` and `api_error` can share a request ID; the event name is in the fact ID
+    api_request: { key: findRequestKey },
+    api_error: { key: findRequestKey },
+    api_refusal: { key: (record) => findAttributeText(record, 'request_id') },
+    user_prompt: {},
+    assistant_response: {},
+    tool_result: {},
+    tool_decision: {},
+  },
+});
+
+// Neither the scope name nor the event name's prefix on the wire is checked against a capture, so
+// either one marks a record as Claude Code's, and the event is the name without the prefix.
+function findClaudeCodeEvent(record: LogRecord): string | undefined {
+  const name = findAttributeText(record, 'event.name');
+
+  if (name === undefined) {
+    return undefined;
+  }
+
+  if (name.startsWith(eventPrefix)) {
+    const event = name.slice(eventPrefix.length);
+
+    return event === '' ? undefined : event;
+  }
+
+  return record.scope.name.startsWith(scopePrefix) ? name : undefined;
+}
+
+function findRequestKey(record: LogRecord): string | undefined {
+  return findAttributeText(record, 'request_id') ?? findAttributeText(record, 'client_request_id');
+}

package/src/products/codex/codex-product.ts

@@ -0,0 +1,37 @@
+import type { LogRecord } from '../../otlp/types.ts';
+import { defineTelemetryProduct } from '../define-telemetry-product.ts';
+import { findAttributeText } from '../find-attribute-text.ts';
+
+const eventPrefix = 'codex.';
+
+export const codexProduct = defineTelemetryProduct({
+  name: 'codex',
+  readEvent: findCodexEvent,
+  agentSessionAttribute: 'conversation.id',
+  timeAttribute: 'event.timestamp',
+
+  // Any other `codex.*` event is stored as `telemetry.codex.unlisted`. With no `key`, the fact ID
+  // holds a hash of what Codex wrote.
+  events: {
+    sse_event: {},
+    api_request: {},
+    turn_cost: { key: (record) => findAttributeText(record, 'turn.id') },
+    conversation_starts: {},
+    user_prompt: {},
+    tool_decision: {},
+    tool_result: {},
+  },
+});
+
+// Codex puts the full name in `event.name`, such as `codex.sse_event`.
+function findCodexEvent(record: LogRecord): string | undefined {
+  const name = findAttributeText(record, 'event.name');
+
+  if (name === undefined || !name.startsWith(eventPrefix)) {
+    return undefined;
+  }
+
+  const event = name.slice(eventPrefix.length);
+
+  return event === '' ? undefined : event;
+}

package/src/products/define-telemetry-product.ts

@@ -0,0 +1,7 @@
+import type { TelemetryProduct } from './types.ts';
+
+export function defineTelemetryProduct<const Name extends string, const Event extends string>(
+  product: TelemetryProduct<Name, Event>,
+): TelemetryProduct<Name, Event> {
+  return product;
+}

package/src/products/find-attribute-text.ts

@@ -0,0 +1,12 @@
+import type { LogRecord } from '../otlp/types.ts';
+
+// The record's attribute as text: a number counts, since an exporter may write an ID either way.
+export function findAttributeText(record: LogRecord, name: string): string | undefined {
+  const value = record.attributes[name];
+
+  if (typeof value === 'string') {
+    return value === '' ? undefined : value;
+  }
+
+  return typeof value === 'number' ? String(value) : undefined;
+}

package/src/products/products.ts

@@ -0,0 +1,8 @@
+import { claudeCodeProduct } from './claude-code/claude-code-product.ts';
+import { codexProduct } from './codex/codex-product.ts';
+
+// The one list of products. A third product is one more entry here, and one more case in each
+// consumer, which does not compile until the case is there.
+export const products = [claudeCodeProduct, codexProduct] as const;
+
+export type ProductName = (typeof products)[number]['name'];

package/src/products/types.ts

@@ -0,0 +1,21 @@
+import type { LogRecord } from '../otlp/types.ts';
+
+// The ingest half of a product. It holds no row shape.
+export interface TelemetryProduct<Name extends string = string, Event extends string = string> {
+  // the `product` column, and the middle part of every fact type
+  readonly name: Name;
+
+  // the short event name when the record is this product's; the first product that answers owns it
+  readonly readEvent: (record: LogRecord) => string | undefined;
+
+  // the attribute that holds the agent's own session ID
+  readonly agentSessionAttribute: string;
+
+  // the attribute that holds the time the product wrote; `timeUnixNano` when it is absent
+  readonly timeAttribute: string;
+
+  // the events with a fact type of their own; `key` gives the event's own key for the fact ID
+  readonly events: Readonly<
+    Record<Event, { readonly key?: ((record: LogRecord) => string | undefined) | undefined }>
+  >;
+}

package/src/telemetry-model-request-consumer.ts

@@ -0,0 +1,59 @@
+import { defineConsumer, defineTable } from '@pepys/kit';
+import { logRecordFamily } from './log-record-family.ts';
+
+// Fact mode: one row comes from exactly one fact, and the row's key comes from the fact's ID, so
+// the order of the facts changes nothing.
+export const telemetryModelRequestConsumer = defineConsumer({
+  name: 'telemetry_model_request',
+  entry: new URL('consumers/telemetry-model-request.ts', import.meta.url),
+  input: { mode: 'fact', streams: [logRecordFamily.stream] },
+  tables: {
+    telemetry_model_request: defineTable({
+      columns: {
+        // `telemetry:model_request:<product>.<event>:<key>`
+        id: { kind: 'entityID' },
+
+        // The join key: `telemetry:session:<atc session ID>`, or the agent's own session ID when
+        // the record has no atc session ID.
+        session_id: { kind: 'entityID' },
+
+        // The agent's own session ID. It changes inside one atc session, so nothing joins on it.
+        agent_session: { kind: 'text', nullable: true },
+        product: { kind: 'text' },
+        model: { kind: 'text' },
+
+        // never holds a token that the cache read or wrote, for every product
+        input_tokens: { kind: 'integer' },
+        cache_read_tokens: { kind: 'integer' },
+        cache_creation_tokens: { kind: 'integer' },
+        output_tokens: { kind: 'integer' },
+
+        // null when the product reports no cost for one request; 0 never stands for unknown
+        cost_usd: { kind: 'real', nullable: true },
+        cost_basis: { kind: 'text' },
+        duration_ms: { kind: 'integer', nullable: true },
+        agent: { kind: 'text', nullable: true },
+
+        // the proven sender of the export that carried the record
+        origin_issuer: { kind: 'text' },
+        origin_subject: { kind: 'text' },
+        at: { kind: 'timestamp' },
+      },
+      primaryKey: ['id'],
+      indexes: [{ columns: ['session_id'] }, { columns: ['at'] }],
+    }),
+  },
+  entityViews: [
+    {
+      table: 'telemetry_model_request',
+      kind: 'telemetry:model_request',
+      id: 'id',
+      title: 'model',
+      url: null,
+      actor: null,
+      updatedAt: 'at',
+    },
+  ],
+  reads: [],
+  links: [],
+});