@vzn/vx-otel 0.0.519 → 0.0.520

package/README.md

@@ -105,7 +105,17 @@ otel({
   a sandboxed one its violation count (`vx.task.sandbox_violations`), on a
   persistent one that never became ready why (`vx.task.not_ready`). A
   failed task sets span status
-  `ERROR`.
+  `ERROR`. A task span links to the spans of the tasks it waited on (a
+  group seen through to the tasks behind it), and carries an event per
+  attempt that failed and was run again (`vx.task.retry`, with
+  `vx.task.attempt` and `vx.task.exit_code`) and one when vx's own
+  timeout killed it (`vx.task.timeout`);
+- a child span per stage of the run, named by the stage (`startup`,
+  `load configs`, `git enumeration`, `classify + probe`, `run graph`,
+  `record history`, …, the stages `VX_TIMING` prints), with
+  `vx.stage.name`: where the time before the first task and after the
+  last went. The stages ahead of the run lock end before the `vx.run`
+  span starts.
 
 **Metrics per run**: `vx.tasks.total`, `vx.tasks.failed`,
 `vx.tasks.cache_hits{source=local|remote}`, what those hits did to the disk as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-otel",
-  "version": "0.0.519",
+  "version": "0.0.520",
   "license": "MIT",
   "description": "OpenTelemetry exporter for vx — a telemetry plugin mapping runs to OTLP traces + metrics (CI/CD + VCS semantic conventions).",
   "keywords": [
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@vzn/vx": "^0.0.519"
+    "@vzn/vx": "^0.0.520"
   },
   "repository": {
     "type": "git",

package/src/otlp.ts

@@ -126,6 +126,8 @@ const VX_ATTR = {
   taskOutputs: 'vx.task.outputs',
   peakRssBytes: 'vx.peak_rss_bytes',
   taskAttempts: 'vx.task.attempts',
+  taskAttempt: 'vx.task.attempt',
+  stageName: 'vx.stage.name',
   wallclockStartNs: 'vx.task.wallclock_start_ns',
   wallclockEndNs: 'vx.task.wallclock_end_ns',
   // task log records (the OTel Logs signal)
@@ -151,6 +153,76 @@ export interface OtlpSpan {
   endTimeUnixNano: string
   attributes: KeyValue[]
   status: { code: number }
+  events?: OtlpSpanEvent[]
+  links?: OtlpSpanLink[]
+}
+
+export interface OtlpSpanEvent {
+  timeUnixNano: string
+  name: string
+  attributes: KeyValue[]
+}
+
+export interface OtlpSpanLink {
+  traceId: string
+  spanId: string
+  attributes: KeyValue[]
+}
+
+/**
+ * A task span's events: each attempt that failed and was run again
+ * (`vx.task.retry`, at its end), and vx's own deadline killing the task
+ * (`vx.task.timeout`, at the span's end).
+ */
+export function taskSpanEvents(t: TaskTelemetry, endUnixNano: string): OtlpSpanEvent[] {
+  const events: OtlpSpanEvent[] = (t.failedAttempts ?? []).map((a, i) => ({
+    timeUnixNano: String(Math.trunc(a.endedAt) * 1_000_000),
+    name: 'vx.task.retry',
+    attributes: [
+      intAttr(VX_ATTR.taskAttempt, i + 1),
+      intAttr(VX_ATTR.taskExitCode, a.exitCode),
+      ...(a.timedOut === true ? [boolAttr(VX_ATTR.taskTimedOut, true)] : []),
+    ],
+  }))
+  if (t.timedOut === true) {
+    events.push({ timeUnixNano: endUnixNano, name: 'vx.task.timeout', attributes: [] })
+  }
+  return events
+}
+
+/**
+ * A child span of the run for one of its stages (`VX_TIMING`'s marks):
+ * where the time before the first task and after the last one went. Named
+ * by the stage, a fixed set. The stages ahead of the run lock end before
+ * the run span starts.
+ */
+export function stageSpan(
+  traceId: string,
+  parentSpanId: string,
+  stage: { name: string; startedAt: number; endedAt: number },
+  spanId: string,
+): OtlpSpan {
+  return {
+    traceId,
+    spanId,
+    parentSpanId,
+    name: stage.name,
+    kind: SPAN_KIND_INTERNAL,
+    startTimeUnixNano: exactNanos(stage.startedAt),
+    endTimeUnixNano: exactNanos(stage.endedAt),
+    attributes: [strAttr(VX_ATTR.stageName, stage.name)],
+    status: { code: STATUS_UNSET },
+  }
+}
+
+/** Epoch ms with a fraction, as OTLP's int64 nanoseconds: a stage can be under 1 ms. */
+function exactNanos(ms: number): string {
+  return String(BigInt(Math.round(ms * 1000)) * 1000n)
+}
+
+/** A link from a task span to the span of a task it waited on. */
+export function dependencyLink(traceId: string, spanId: string, taskId: string): OtlpSpanLink {
+  return { traceId, spanId, attributes: [strAttr(SEMCONV.taskName, taskId)] }
 }
 
 // --- attribute mapping (pure) ------------------------------------------

package/src/sink.ts

@@ -22,6 +22,9 @@ import {
   type TaskMetricPoint,
   runSpanAttributes,
   SPAN_KIND_INTERNAL,
+  dependencyLink,
+  stageSpan,
+  taskSpanEvents,
   runStatusCode,
   taskSpanAttributes,
   taskStatusCode,
@@ -276,6 +279,7 @@ export class OtelSink implements TelemetrySink {
   private readonly lastSample = new Map<string, { ts: number; cpuMs: number }>()
   private readonly taskSpanId = new Map<string, string>()
   private readonly taskStartNano = new Map<string, string>()
+  private readonly taskDeps = new Map<string, readonly string[]>()
   private summary: RunSummaryRecord | undefined
   private uploaded = false
   // Core's own bounded capture buffer, so which task's output survives a
@@ -331,6 +335,7 @@ export class OtelSink implements TelemetrySink {
       case 'task.start':
         this.taskSpanId.set(record.taskId, genId(8))
         this.taskStartNano.set(record.taskId, nanos(record.ts))
+        if (record.dependsOn !== undefined) this.taskDeps.set(record.taskId, record.dependsOn)
         this.taskNames.set(record.taskId, {
           project: record.project,
           task: record.task,
@@ -362,7 +367,18 @@ export class OtelSink implements TelemetrySink {
         this.logs.append(record.taskId, record.chunk)
         return
       case 'task.end': {
-        const spanId = this.taskSpanId.get(record.taskId) ?? genId(8)
+        // A task that never started (a skip) still gets a span, and a later
+        // task that waited on it links to it.
+        let spanId = this.taskSpanId.get(record.taskId)
+        if (spanId === undefined) {
+          spanId = genId(8)
+          this.taskSpanId.set(record.taskId, spanId)
+        }
+        const links = (this.taskDeps.get(record.taskId) ?? []).flatMap((dep) => {
+          const depSpan = this.taskSpanId.get(dep)
+          return depSpan === undefined ? [] : [dependencyLink(this.traceId, depSpan, dep)]
+        })
+        const events = taskSpanEvents(record, nanos(record.ts))
         const startNano =
           this.taskStartNano.get(record.taskId) ?? nanos(record.ts - record.durationMs)
         const t: TaskTelemetry = record
@@ -380,6 +396,8 @@ export class OtelSink implements TelemetrySink {
             startedAt: this.runStartedAt,
           }),
           status: { code: taskStatusCode(t) },
+          ...(events.length > 0 ? { events } : {}),
+          ...(links.length > 0 ? { links } : {}),
         })
         // A skipped task never ran: a zero duration would read as a fast one.
         if (record.status !== 'skipped') {
@@ -437,6 +455,10 @@ export class OtelSink implements TelemetrySink {
         attributes: runSpanAttributes(this.run, this.summary),
         status: { code: runStatusCode(this.summary) },
       })
+      const stages = (this.summary?.stages ?? []).map((stage) =>
+        stageSpan(this.traceId, this.rootSpanId, stage, genId(8)),
+      )
+      this.spans.splice(1, 0, ...stages)
     }
     const vxVersion = this.run?.vxVersion ?? '0.0.0'
     await Promise.all([this.shipTraces(vxVersion), this.shipMetrics(), this.shipLogs(vxVersion)])