@vzn/vx-otel 0.0.0 → 0.0.485

package/src/otlp.ts

@@ -0,0 +1,482 @@
+// OTLP/HTTP JSON payload builders — pure functions, no SDK.
+//
+// vx-otel speaks the OTLP/HTTP JSON protocol directly rather than pulling the
+// OpenTelemetry SDK closure. The protocol is a stable wire spec; building the
+// payloads by hand keeps the package zero-dependency, fully testable, and free
+// of SDK-version drift. Maps a vx run to:
+//   - a TRACE: one root `vx.run` span + one child `vx.task` span per task,
+//     with CI/CD + VCS semantic-convention attributes;
+//   - METRICS: task/run counters + a run-duration gauge;
+//   - LOGS: one record per executed task carrying its captured output tail.
+//
+// References: OpenTelemetry CI/CD + VCS semantic conventions; OTLP/JSON
+// protobuf-JSON mapping (int64 fields are decimal STRINGS).
+
+import { TELEMETRY_SCHEMA_VERSION } from '@vzn/vx'
+import type { RunContextRecord, RunSummaryRecord, TaskLogEntry, TaskTelemetry } from '@vzn/vx'
+
+// --- OTLP value + attribute primitives ---------------------------------
+
+type AnyValue =
+  | { stringValue: string }
+  | { intValue: string }
+  | { boolValue: boolean }
+  | { doubleValue: number }
+
+export interface KeyValue {
+  key: string
+  value: AnyValue
+}
+
+function strAttr(key: string, v: string): KeyValue {
+  return { key, value: { stringValue: v } }
+}
+function intAttr(key: string, v: number): KeyValue {
+  return { key, value: { intValue: String(Math.trunc(v)) } }
+}
+function boolAttr(key: string, v: boolean): KeyValue {
+  return { key, value: { boolValue: v } }
+}
+/** An int64 that is ALREADY a decimal string — OTLP's own encoding for the
+ *  type. Passing it through untouched is the point: routing a nanosecond
+ *  count through a JS number would round it. */
+function int64Attr(key: string, v: string): KeyValue {
+  return { key, value: { intValue: v } }
+}
+
+// --- semantic-convention keys ------------------------------------------
+
+const SEMCONV = {
+  pipelineRunId: 'cicd.pipeline.run.id',
+  pipelineResult: 'cicd.pipeline.result',
+  taskName: 'cicd.pipeline.task.name',
+  taskRunResult: 'cicd.pipeline.task.run.result',
+  vcsHeadRevision: 'vcs.ref.head.revision',
+  vcsHeadName: 'vcs.ref.head.name',
+  serviceName: 'service.name',
+  serviceVersion: 'service.version',
+} as const
+
+/**
+ * Every vx-specific attribute key, in ONE place.
+ *
+ * These keys are the wire: a trace is only a lossless description of a run if
+ * a reader can find every field again, and the only thing standing between an
+ * encoder and a decoder is agreement on these strings. Naming them once means
+ * a rename is a compile error here rather than a field that silently stops
+ * arriving. Anything with a real OTel semantic convention uses it instead (see
+ * SEMCONV above) — these cover what the conventions have no word for.
+ *
+ * `vx.default_branch` deliberately does NOT reuse `vcs.ref.base.name`: that
+ * convention means the base ref of a specific change, which is not the same
+ * question as "what is this repo's trunk", and a decoder reading the wrong
+ * one would quietly mis-classify every run's trust scope.
+ */
+const VX_ATTR = {
+  // run
+  schema: 'vx.telemetry.schema',
+  workspaceId: 'vx.workspace.id',
+  workspaceName: 'vx.workspace.name',
+  command: 'vx.command',
+  requestedTasks: 'vx.requested_tasks',
+  cachePolicy: 'vx.cache_policy',
+  concurrency: 'vx.concurrency',
+  flow: 'vx.flow',
+  ci: 'vx.ci',
+  ciProvider: 'vx.ci.provider',
+  host: 'vx.host',
+  os: 'vx.os',
+  arch: 'vx.arch',
+  version: 'vx.version',
+  dirty: 'vx.dirty',
+  defaultBranch: 'vx.default_branch',
+  tagPrefix: 'vx.tag.',
+  // run summary (root span only)
+  runStartedAt: 'vx.run.started_at',
+  runEndedAt: 'vx.run.ended_at',
+  runDurationMs: 'vx.run.duration_ms',
+  runTaskCount: 'vx.run.task_count',
+  runFailedCount: 'vx.run.failed_count',
+  runAbortedCount: 'vx.run.aborted_count',
+  runHitCount: 'vx.run.hit_count',
+  runHitLocalCount: 'vx.run.hit_local_count',
+  runHitRemoteCount: 'vx.run.hit_remote_count',
+  runExitOk: 'vx.run.exit_ok',
+  // task
+  taskProject: 'vx.task.project',
+  taskRunStartedAt: 'vx.task.run_started_at',
+  taskTask: 'vx.task.task',
+  cacheSource: 'vx.cache.source',
+  taskExitCode: 'vx.task.exit_code',
+  taskStatus: 'vx.task.status',
+  taskDurationMs: 'vx.task.duration_ms',
+  taskHash: 'vx.task.hash',
+  cpuMs: 'vx.cpu_ms',
+  taskWhere: 'vx.task.where',
+  taskBlockedBy: 'vx.task.blocked_by',
+  taskTimedOut: 'vx.task.timed_out',
+  taskSandboxViolations: 'vx.task.sandbox_violations',
+  taskNotReady: 'vx.task.not_ready',
+  taskOutputs: 'vx.task.outputs',
+  peakRssBytes: 'vx.peak_rss_bytes',
+  taskAttempts: 'vx.task.attempts',
+  wallclockStartNs: 'vx.task.wallclock_start_ns',
+  wallclockEndNs: 'vx.task.wallclock_end_ns',
+  // task log records (the OTel Logs signal)
+  logCharsFull: 'vx.log.chars_full',
+  logTruncatedHead: 'vx.log.truncated_head',
+  logStatus: 'vx.log.status',
+} as const
+
+// OTLP status codes: 0 UNSET, 1 OK, 2 ERROR. Span kind: 1 INTERNAL.
+const STATUS_UNSET = 0
+const STATUS_ERROR = 2
+export const SPAN_KIND_INTERNAL = 1
+// Metric aggregation temporality: 1 = DELTA.
+const AGG_DELTA = 1
+
+export interface OtlpSpan {
+  traceId: string
+  spanId: string
+  parentSpanId?: string
+  name: string
+  kind: number
+  startTimeUnixNano: string
+  endTimeUnixNano: string
+  attributes: KeyValue[]
+  status: { code: number }
+}
+
+// --- attribute mapping (pure) ------------------------------------------
+
+/**
+ * Resource attributes — service identity, after `OTEL_RESOURCE_ATTRIBUTES`'
+ * own (`extra`), whose `service.name` / `service.version` vx's replace.
+ * Run/VCS context rides span attrs.
+ */
+function resourceAttributes(
+  serviceName: string,
+  vxVersion: string,
+  extra: Readonly<Record<string, string>> = {},
+): KeyValue[] {
+  const own = new Set<string>([SEMCONV.serviceName, SEMCONV.serviceVersion])
+  return [
+    ...Object.entries(extra)
+      .filter(([k]) => !own.has(k))
+      .map(([k, v]) => strAttr(k, v)),
+    strAttr(SEMCONV.serviceName, serviceName),
+    strAttr(SEMCONV.serviceVersion, vxVersion),
+  ]
+}
+
+/**
+ * Attributes for the root `vx.run` span.
+ *
+ * With `summary` supplied this is a COMPLETE description of the run — every
+ * `RunContextRecord` field plus the run-level tallies — so a receiver can
+ * rebuild the invocation header from the trace alone. The summary is absent
+ * only when a run died before it was assembled; the context half still ships.
+ *
+ * `started_at` / `ended_at` ride as millisecond attributes even though the
+ * span already carries times, because the span's are unix-NANOS: decoding
+ * them costs a BigInt (epoch-ms × 1e6 is past Number.MAX_SAFE_INTEGER), and
+ * these two values are a storage partition key — silently losing precision on
+ * them is not a rounding error, it is a row in the wrong partition.
+ */
+export function runSpanAttributes(run: RunContextRecord, summary?: RunSummaryRecord): KeyValue[] {
+  const attrs: KeyValue[] = [
+    strAttr(SEMCONV.pipelineRunId, run.runId),
+    intAttr(VX_ATTR.schema, TELEMETRY_SCHEMA_VERSION),
+    strAttr(VX_ATTR.workspaceId, run.workspaceId),
+    strAttr(VX_ATTR.workspaceName, run.workspaceName),
+    strAttr(VX_ATTR.command, run.command),
+    strAttr(VX_ATTR.requestedTasks, run.requestedTasks.join(',')),
+    strAttr(VX_ATTR.cachePolicy, run.cachePolicy),
+    intAttr(VX_ATTR.concurrency, run.concurrency),
+    boolAttr(VX_ATTR.ci, run.ci),
+    strAttr(VX_ATTR.os, run.os),
+    strAttr(VX_ATTR.arch, run.arch),
+    strAttr(VX_ATTR.version, run.vxVersion),
+  ]
+  if (run.flow !== null) attrs.push(strAttr(VX_ATTR.flow, run.flow))
+  if (run.commitSha !== null) attrs.push(strAttr(SEMCONV.vcsHeadRevision, run.commitSha))
+  if (run.branch !== null) attrs.push(strAttr(SEMCONV.vcsHeadName, run.branch))
+  if (run.defaultBranch !== null) attrs.push(strAttr(VX_ATTR.defaultBranch, run.defaultBranch))
+  if (run.dirty !== null) attrs.push(boolAttr(VX_ATTR.dirty, run.dirty))
+  if (run.ciProvider !== null) attrs.push(strAttr(VX_ATTR.ciProvider, run.ciProvider))
+  if (run.host !== null) attrs.push(strAttr(VX_ATTR.host, run.host))
+  for (const [k, v] of Object.entries(run.tags)) attrs.push(strAttr(`${VX_ATTR.tagPrefix}${k}`, v))
+  if (summary !== undefined) {
+    attrs.push(
+      intAttr(VX_ATTR.runStartedAt, summary.startedAt),
+      intAttr(VX_ATTR.runEndedAt, summary.endedAt),
+      intAttr(VX_ATTR.runDurationMs, summary.totalDurationMs),
+      intAttr(VX_ATTR.runTaskCount, summary.taskCount),
+      intAttr(VX_ATTR.runFailedCount, summary.failedCount),
+      intAttr(VX_ATTR.runAbortedCount, summary.abortedCount),
+      intAttr(VX_ATTR.runHitCount, summary.hitCount),
+      intAttr(VX_ATTR.runHitLocalCount, summary.hitLocalCount),
+      intAttr(VX_ATTR.runHitRemoteCount, summary.hitRemoteCount),
+      boolAttr(VX_ATTR.runExitOk, summary.exitOk),
+      strAttr(SEMCONV.pipelineResult, pipelineResult(summary)),
+    )
+  }
+  return attrs
+}
+
+/**
+ * `cicd.pipeline.result`, the task enum's run-level twin. A red run with
+ * nothing failed and something aborted is a stopped one.
+ */
+function pipelineResult(s: RunSummaryRecord): string {
+  if (s.exitOk) return 'success'
+  return s.failedCount === 0 && s.abortedCount > 0 ? 'cancellation' : 'failure'
+}
+
+/** The root span is ERROR when the run is red: UNSET read as a clean run. */
+export function runStatusCode(summary?: RunSummaryRecord): number {
+  return summary?.exitOk === false ? STATUS_ERROR : STATUS_UNSET
+}
+
+/** What a task span needs to identify its run without its root span. */
+interface TaskSpanRunContext {
+  runId: string
+  workspaceId: string
+  /** The run's canonical start (epoch ms) — the storage key's base. */
+  startedAt: number
+}
+
+/**
+ * `cicd.pipeline.task.run.result` is an enum (success, failure, error,
+ * timeout, cancellation, skip). vx's own status went out verbatim, so
+ * `failed`, `skipped`, `aborted` and the two hit statuses matched none of it
+ * and a conventions-aware backend counted no task as failed (F-12). The
+ * exact status still rides `vx.task.status`.
+ */
+function runResult(t: TaskTelemetry): string {
+  switch (t.status) {
+    case 'failed':
+      return t.timedOut === true ? 'timeout' : 'failure'
+    case 'skipped':
+      return 'skip'
+    case 'aborted':
+      return 'cancellation'
+    default:
+      return 'success'
+  }
+}
+
+/**
+ * Attributes for a child `vx.task` span — every `TaskTelemetry` field.
+ *
+ * The wallclock offsets ride as int64 STRINGS (OTLP's own int64 encoding), not
+ * numbers: they are nanoseconds, and a receiver reconstructing a task's
+ * `started_at` from them is computing a dedup key that must match the value
+ * the native ingest path derives, to the millisecond.
+ *
+ * Nothing here is unbounded: every value is an id, an enum or a number, so a
+ * collector's attribute-value limit cannot cut one. The largest thing this
+ * exporter ships is a task's captured tail, which travels as a LOG record
+ * (`vx.log.*`) carrying its own full length, so a cut there is visible.
+ */
+export function taskSpanAttributes(t: TaskTelemetry, run: TaskSpanRunContext): KeyValue[] {
+  const attrs: KeyValue[] = [
+    strAttr(SEMCONV.taskName, t.taskId),
+    strAttr(SEMCONV.taskRunResult, runResult(t)),
+    strAttr(VX_ATTR.taskStatus, t.status),
+    // Which run, which workspace, and when that run began. Required, not
+    // optional: OTLP is re-batched in transit, so a task span can arrive in a
+    // payload its root span is not in, and a span that can only be read
+    // alongside its parent is a span a collector can silently strand. These
+    // three make it attributable on its own — and `run_started_at` is what
+    // lets a receiver derive the SAME storage key it would have derived from
+    // the complete trace, so the two arrival orders converge instead of
+    // duplicating.
+    strAttr(SEMCONV.pipelineRunId, run.runId),
+    strAttr(VX_ATTR.workspaceId, run.workspaceId),
+    intAttr(VX_ATTR.taskRunStartedAt, run.startedAt),
+    strAttr(VX_ATTR.taskProject, t.project),
+    strAttr(VX_ATTR.taskTask, t.task),
+    strAttr(VX_ATTR.cacheSource, t.cacheSource),
+    intAttr(VX_ATTR.taskExitCode, t.exitCode),
+    intAttr(VX_ATTR.taskDurationMs, t.durationMs),
+  ]
+  if (t.hash !== undefined) attrs.push(strAttr(VX_ATTR.taskHash, t.hash))
+  if (t.cpuMs !== undefined) attrs.push(intAttr(VX_ATTR.cpuMs, t.cpuMs))
+  if (t.where !== undefined) attrs.push(strAttr(VX_ATTR.taskWhere, t.where))
+  // A skipped task's root blocker (a task id, as the record carries it).
+  if (t.blockedBy !== undefined) attrs.push(strAttr(VX_ATTR.taskBlockedBy, t.blockedBy))
+  // vx's own deadline killed the task: the 143 is a timeout, not a signal.
+  if (t.timedOut === true) attrs.push(boolAttr(VX_ATTR.taskTimedOut, true))
+  if (t.sandboxViolations !== undefined)
+    attrs.push(intAttr(VX_ATTR.taskSandboxViolations, t.sandboxViolations))
+  // Why a persistent task never became ready ('timeout' | 'exited' | 'spawn').
+  if (t.notReady !== undefined) attrs.push(strAttr(VX_ATTR.taskNotReady, t.notReady))
+  if (t.outputs !== undefined) attrs.push(strAttr(VX_ATTR.taskOutputs, t.outputs))
+  if (t.peakRssBytes !== undefined) attrs.push(intAttr(VX_ATTR.peakRssBytes, t.peakRssBytes))
+  if (t.attempts !== undefined) attrs.push(intAttr(VX_ATTR.taskAttempts, t.attempts))
+  if (t.wallclockStartNs !== undefined)
+    attrs.push(int64Attr(VX_ATTR.wallclockStartNs, t.wallclockStartNs))
+  if (t.wallclockEndNs !== undefined)
+    attrs.push(int64Attr(VX_ATTR.wallclockEndNs, t.wallclockEndNs))
+  return attrs
+}
+
+/** A failed task maps to span status ERROR. Everything else stays UNSET. */
+export function taskStatusCode(t: TaskTelemetry): number {
+  if (t.status === 'failed') return STATUS_ERROR
+  return STATUS_UNSET
+}
+
+// --- envelope builders -------------------------------------------------
+
+/** Wrap spans in an ExportTraceServiceRequest. */
+export function buildTraceRequest(
+  serviceName: string,
+  vxVersion: string,
+  spans: OtlpSpan[],
+  resource?: Readonly<Record<string, string>>,
+): unknown {
+  return {
+    resourceSpans: [
+      {
+        resource: { attributes: resourceAttributes(serviceName, vxVersion, resource) },
+        scopeSpans: [{ scope: { name: 'vx', version: vxVersion }, spans }],
+      },
+    ],
+  }
+}
+
+/**
+ * Build an ExportMetricsServiceRequest from a run summary. Each count is the
+ * RUN's, so it is a DELTA over the run's own interval: sent CUMULATIVE with
+ * no start time, two runs of 10 tasks read as a series that never rose, and
+ * parallel jobs interleaved on one series (item 927).
+ */
+export function buildMetricsRequest(
+  serviceName: string,
+  summary: RunSummaryRecord,
+  nowUnixNano: string,
+  startUnixNano: string,
+  resource?: Readonly<Record<string, string>>,
+): unknown {
+  const point = (value: number, attrs: KeyValue[] = []) => ({
+    asInt: String(value),
+    startTimeUnixNano: startUnixNano,
+    timeUnixNano: nowUnixNano,
+    attributes: attrs,
+  })
+  const sum = (name: string, dataPoints: ReturnType<typeof point>[]) => ({
+    name,
+    sum: { dataPoints, aggregationTemporality: AGG_DELTA, isMonotonic: true },
+  })
+  const gauge = (name: string, value: number) => ({
+    name,
+    gauge: {
+      dataPoints: [{ asDouble: value, timeUnixNano: nowUnixNano, attributes: [] }],
+    },
+  })
+  return {
+    resourceMetrics: [
+      {
+        resource: { attributes: resourceAttributes(serviceName, summary.run.vxVersion, resource) },
+        scopeMetrics: [
+          {
+            scope: { name: 'vx', version: summary.run.vxVersion },
+            metrics: [
+              sum('vx.tasks.total', [point(summary.taskCount)]),
+              sum('vx.tasks.failed', [point(summary.failedCount)]),
+              // One metric, a point per source: two entries of one name
+              // are two metrics a backend may keep only one of.
+              sum('vx.tasks.cache_hits', [
+                point(summary.hitLocalCount, [strAttr('source', 'local')]),
+                point(summary.hitRemoteCount, [strAttr('source', 'remote')]),
+              ]),
+              gauge('vx.run.duration_ms', summary.totalDurationMs),
+            ],
+          },
+        ],
+      },
+    ],
+  }
+}
+
+// --- logs ---------------------------------------------------------------
+
+// OTLP severity numbers: 9 INFO, 17 ERROR.
+const SEVERITY_INFO = 9
+const SEVERITY_ERROR = 17
+
+export interface OtlpLogRecord {
+  timeUnixNano: string
+  observedTimeUnixNano: string
+  severityNumber: number
+  severityText: string
+  body: { stringValue: string }
+  attributes: KeyValue[]
+  traceId?: string
+  spanId?: string
+}
+
+/**
+ * One log record per EXECUTED task, carrying its captured output tail.
+ *
+ * Per task, not per chunk. A chunk-level stream is the conventional shape for
+ * application logs, but a build task's output arrives as thousands of tiny
+ * writes and the thing anyone reads is the tail — so a record per chunk would
+ * multiply the payload by orders of magnitude to deliver the same bytes, and
+ * force every receiver to reassemble them in order before it could show
+ * anything. The capture buffer already bounds and orders the tail; this ships
+ * what it drained.
+ *
+ * `traceId`/`spanId` link each record to its task span, so a viewer opens the
+ * output from the span rather than by correlating ids by hand. The truncation
+ * counters ride along because a capped tail that reads as complete is worse
+ * than one that says what it lost.
+ */
+export function buildLogsRequest(args: {
+  serviceName: string
+  vxVersion: string
+  runId: string
+  /** The run's workspace — a receiver has no other way to route the record. */
+  workspaceId: string
+  entries: readonly TaskLogEntry[]
+  timeUnixNano: string
+  traceId?: string
+  spanIdFor?: (taskId: string) => string | undefined
+  resource?: Readonly<Record<string, string>>
+}): unknown {
+  const logRecords: OtlpLogRecord[] = args.entries.map((e) => {
+    const failed = e.status === 'failed'
+    const attrs: KeyValue[] = [
+      strAttr(SEMCONV.pipelineRunId, args.runId),
+      strAttr(VX_ATTR.workspaceId, args.workspaceId),
+      strAttr(SEMCONV.taskName, e.taskId),
+      strAttr(VX_ATTR.logStatus, e.status),
+      intAttr(VX_ATTR.logCharsFull, e.charsFull),
+      intAttr(VX_ATTR.logTruncatedHead, e.truncatedHeadChars),
+    ]
+    if (e.hash !== undefined) attrs.push(strAttr(VX_ATTR.taskHash, e.hash))
+    const spanId = args.spanIdFor?.(e.taskId)
+    return {
+      timeUnixNano: args.timeUnixNano,
+      observedTimeUnixNano: args.timeUnixNano,
+      severityNumber: failed ? SEVERITY_ERROR : SEVERITY_INFO,
+      severityText: failed ? 'ERROR' : 'INFO',
+      body: { stringValue: e.content },
+      attributes: attrs,
+      ...(args.traceId ? { traceId: args.traceId } : {}),
+      ...(spanId ? { spanId } : {}),
+    }
+  })
+  return {
+    resourceLogs: [
+      {
+        resource: {
+          attributes: resourceAttributes(args.serviceName, args.vxVersion, args.resource),
+        },
+        scopeLogs: [{ scope: { name: 'vx', version: args.vxVersion }, logRecords }],
+      },
+    ],
+  }
+}