@pepys/source-telemetry 0.0.0-stage → 0.1.0

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: [],
+});

package/src/telemetry-plugin.ts

@@ -0,0 +1,44 @@
+import { definePlugin, defineSource } from '@pepys/kit';
+import { logRecordFamily } from './log-record-family.ts';
+import { receiveOtlpLogs } from './otlp/receive-otlp-logs.ts';
+import { products } from './products/products.ts';
+import { sessionModelRequestsQuery } from './queries/session-model-requests-query.ts';
+import { telemetryModelRequestConsumer } from './telemetry-model-request-consumer.ts';
+import { telemetryTurnCostConsumer } from './telemetry-turn-cost-consumer.ts';
+
+export const telemetrySource = defineSource({
+  name: 'telemetry',
+  families: [logRecordFamily],
+
+  // Push only. An OTLP exporter cannot sign a body, so the check is a token, and the route needs a
+  // proven sender, whom each fact then holds as its `origin`.
+  live: receiveOtlpLogs({
+    route: '/v1/logs',
+
+    // An exporter that gets a bare origin adds these paths itself, and retries a refusal for ever.
+    ignoredRoutes: ['/v1/metrics', '/v1/traces'],
+    check: { kind: 'token', header: 'authorization', secretEnv: 'PEPYS_TELEMETRY_TOKEN' },
+    sender: {
+      kind: 'imp-identity',
+      audienceEnv: 'PEPYS_IMP_IDENTITY_AUDIENCE',
+      issuersEnv: 'PEPYS_IMP_IDENTITY_ISSUERS',
+    },
+    products,
+
+    // atc stamps it on every record of a session it runs
+    sessionAttribute: 'atc.session.id',
+    factLimit: 1000,
+    bodyByteLimit: 4_194_304,
+    encodings: ['gzip'],
+    answer: 'empty',
+  }),
+});
+
+// `telemetry:session` is a kind of this plug-in, from the family, with no table: a link may point
+// at a session, and no entity view finds one.
+export const telemetryPlugin = definePlugin({
+  name: 'telemetry',
+  sources: [telemetrySource],
+  consumers: [telemetryModelRequestConsumer, telemetryTurnCostConsumer],
+  queries: [sessionModelRequestsQuery],
+});

package/src/telemetry-turn-cost-consumer.ts

@@ -0,0 +1,42 @@
+import { defineConsumer, defineTable } from '@pepys/kit';
+import { logRecordFamily } from './log-record-family.ts';
+
+// The cost a product reports per turn: a second consumer on the same stream.
+export const telemetryTurnCostConsumer = defineConsumer({
+  name: 'telemetry_turn_cost',
+  entry: new URL('consumers/telemetry-turn-cost.ts', import.meta.url),
+  input: { mode: 'fact', streams: [logRecordFamily.stream] },
+  tables: {
+    telemetry_turn_cost: defineTable({
+      columns: {
+        // `telemetry:turn_cost:<product>.<event>:<key>`
+        id: { kind: 'entityID' },
+        session_id: { kind: 'entityID' },
+        agent_session: { kind: 'text', nullable: true },
+        product: { kind: 'text' },
+
+        // the model the record names, so a report can group turn costs by model; null when absent
+        model: { kind: 'text', nullable: true },
+        cost_usd: { kind: 'real' },
+        origin_issuer: { kind: 'text' },
+        origin_subject: { kind: 'text' },
+        at: { kind: 'timestamp' },
+      },
+      primaryKey: ['id'],
+      indexes: [{ columns: ['session_id'] }],
+    }),
+  },
+  entityViews: [
+    {
+      table: 'telemetry_turn_cost',
+      kind: 'telemetry:turn_cost',
+      id: 'id',
+      title: 'product',
+      url: null,
+      actor: null,
+      updatedAt: 'at',
+    },
+  ],
+  reads: [],
+  links: [],
+});