@vzn/vx-otel 0.0.523 → 0.0.524

package/README.md

@@ -152,26 +152,30 @@ secrets, and this sends it to the collector; `logs: false` or
 
 **One run, three signals, linked.** Every request's resource names the run
 (`service.instance.id` and `cicd.pipeline.run.id`, its id), the host
-(`host.name`, `host.arch`, `os.type`) and the commit (`vcs.ref.head.*`),
-under `OTEL_RESOURCE_ATTRIBUTES`, which wins. Each task metric point carries
+(`host.name`, `host.arch`, `os.type`), the commit (`vcs.ref.head.*`) and
+the repository (`vcs.repository.url.full`, `vcs.repository.name`,
+`vcs.owner.name`, `vcs.provider.name`, from the `origin` remote) with
+`vx.workspace.path`, the workspace root inside it (`.` at the top), under `OTEL_RESOURCE_ATTRIBUTES`, which wins. Each task metric point carries
 its task's span as an exemplar, and each log record its span, so a chart
 opens the trace and a span opens its output.
 
 ## Live export
 
-```ts
-otel({ live: process.env.CI === 'true' })
-```
-
-With `live: true` each task's span, metrics and output tail are sent as the
+On by default; `otel({ live: false })` sends everything at the end instead.
+Each task's span, metrics and output tail are sent as the
 task ends, its process samples as they are taken, and a log record
 (`event.name` `vx.run.start` or `vx.task.start`, linked to the trace) as the
 run and each task start; the `vx.run` span, the stage spans and the run's
-metrics follow at the end. A dashboard follows a CI run while it runs. One
-send is in flight at a time and takes everything that ended meanwhile; a
-refused send warns once per signal for the run. Cost on 60 tasks against a
-local collector: within the noise of run-to-run wall time (min of 6: 1,101 ms
-off, 1,108 ms on). Off by default.
+metrics follow at the end. A dashboard follows a CI run while it runs.
+Sends are batched: one per second at most, one in flight at a time, each
+taking everything that ended meanwhile; a refused send warns once per
+signal for the run. On 60 tasks against a local collector the run burns the
+same CPU live as with one send at the end (median of 10: 815 ms both).
+
+No send ever holds a task: a task's end only queues its records. A collector
+that never answers holds nothing either: at the end of the run every send
+still in flight is cut at core's teardown deadline (3 s,
+`VX_TEARDOWN_TIMEOUT_MS`), and the process exits.
 
 ## Behavior note
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx-otel",
-  "version": "0.0.523",
+  "version": "0.0.524",
   "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.523"
+    "@vzn/vx": "^0.0.524"
   },
   "repository": {
     "type": "git",

package/src/otlp.ts

@@ -55,6 +55,10 @@ const SEMCONV = {
   taskRunResult: 'cicd.pipeline.task.run.result',
   vcsHeadRevision: 'vcs.ref.head.revision',
   vcsHeadName: 'vcs.ref.head.name',
+  vcsRepositoryUrl: 'vcs.repository.url.full',
+  vcsRepositoryName: 'vcs.repository.name',
+  vcsOwnerName: 'vcs.owner.name',
+  vcsProviderName: 'vcs.provider.name',
   serviceName: 'service.name',
   serviceVersion: 'service.version',
   serviceInstanceId: 'service.instance.id',
@@ -84,6 +88,7 @@ const VX_ATTR = {
   schema: 'vx.telemetry.schema',
   workspaceId: 'vx.workspace.id',
   workspaceName: 'vx.workspace.name',
+  workspacePath: 'vx.workspace.path',
   command: 'vx.command',
   requestedTasks: 'vx.requested_tasks',
   cachePolicy: 'vx.cache_policy',
@@ -282,8 +287,9 @@ function resourceAttributes(
 
 /**
  * The run as resource attributes, so every signal it sends (spans, metric
- * points, log records) names the same run and host: a backend joins them on
- * `service.instance.id`. Under `OTEL_RESOURCE_ATTRIBUTES`, which wins.
+ * points, log records) names the same run, host, repository and workspace: a
+ * backend joins them on `service.instance.id`. Under `OTEL_RESOURCE_ATTRIBUTES`,
+ * which wins.
  */
 export function runResource(run: RunContextRecord): Record<string, string> {
   const r: Record<string, string> = {
@@ -293,11 +299,39 @@ export function runResource(run: RunContextRecord): Record<string, string> {
     [SEMCONV.hostArch]: run.arch === 'x64' ? 'amd64' : run.arch,
   }
   if (run.host !== null) r[SEMCONV.hostName] = run.host
+  for (const [k, v] of repositoryFields(run)) r[k] = v
   if (run.commitSha !== null) r[SEMCONV.vcsHeadRevision] = run.commitSha
   if (run.branch !== null) r[SEMCONV.vcsHeadName] = run.branch
   return r
 }
 
+const VCS_PROVIDERS: Readonly<Record<string, string>> = {
+  'github.com': 'github',
+  'gitlab.com': 'gitlab',
+  'bitbucket.org': 'bitbucket',
+  'codeberg.org': 'gitea',
+}
+
+/**
+ * The repository (from the normalized origin remote, `host/owner/name`) as
+ * the VCS conventions name it, and where in it the workspace sits.
+ */
+function repositoryFields(run: RunContextRecord): [key: string, value: string][] {
+  const fields: [string, string][] = []
+  if (run.repository !== undefined) {
+    const parts = run.repository.split('/')
+    fields.push(
+      [SEMCONV.vcsRepositoryUrl, `https://${run.repository}`],
+      [SEMCONV.vcsRepositoryName, parts.at(-1)!],
+    )
+    if (parts.length >= 3) fields.push([SEMCONV.vcsOwnerName, parts.at(-2)!])
+    const provider = VCS_PROVIDERS[parts[0]!]
+    if (provider !== undefined) fields.push([SEMCONV.vcsProviderName, provider])
+  }
+  if (run.workspacePath !== undefined) fields.push([VX_ATTR.workspacePath, run.workspacePath])
+  return fields
+}
+
 /**
  * Attributes for the root `vx.run` span.
  *
@@ -318,6 +352,7 @@ export function runSpanAttributes(run: RunContextRecord, summary?: RunSummaryRec
     intAttr(VX_ATTR.schema, TELEMETRY_SCHEMA_VERSION),
     strAttr(VX_ATTR.workspaceId, run.workspaceId),
     strAttr(VX_ATTR.workspaceName, run.workspaceName),
+    ...repositoryFields(run).map(([k, v]) => strAttr(k, v)),
     strAttr(VX_ATTR.command, run.command),
     strAttr(VX_ATTR.requestedTasks, run.requestedTasks.join(',')),
     strAttr(VX_ATTR.cachePolicy, run.cachePolicy),

package/src/plugin.ts

@@ -43,7 +43,8 @@ export interface OtelPluginOptions {
   /**
    * Send each task's span, metrics and log as it ends, and a log record as
    * the run and each task start, instead of everything at the run's end: a
-   * dashboard follows the run while it runs. Default: false.
+   * dashboard follows the run while it runs. Default: true; `false` sends
+   * everything at the run's end.
    */
   live?: boolean
   /** Per-request timeout (ms). Falls back to `OTEL_EXPORTER_OTLP_TIMEOUT`, else 15000. */
@@ -360,7 +361,7 @@ export function resolveOtelConfig(
     ...(tracesWanted && tracesUrl !== undefined ? {} : { tracesEnabled: false }),
     metricsEnabled: metricsWanted && metricsUrl !== undefined,
     logsEnabled: logsWanted && logsUrl !== undefined,
-    ...(opts.live === true ? { live: true } : {}),
+    live: opts.live !== false,
     timeoutMs,
     // A signal's own `OTEL_EXPORTER_OTLP_<SIGNAL>_TIMEOUT` wins over the
     // shared one; it was not read (F-49). The option tops both.

package/src/sink.ts

@@ -71,6 +71,8 @@ export interface OtelSinkConfig {
   tls?: Partial<Record<OtelSignal, OtlpTls>>
   /** Send each task's span, metrics and log as it ends, not all at the run's end. */
   live?: boolean
+  /** Live mode's batch window (ms): what ends within it goes in one send. Default 1000. */
+  liveBatchMs?: number
   /** False under `OTEL_TRACES_EXPORTER=none`; absent is true. */
   tracesEnabled?: boolean
   metricsEnabled: boolean
@@ -119,6 +121,7 @@ function isCertificateRefusal(err: unknown): boolean {
 }
 
 const RETRY_DELAYS_MS = [200, 800] as const
+const LIVE_BATCH_MS = 1000
 const MAX_TIMER_MS = 2 ** 31 - 1
 const MAX_RETRY_AFTER_MS = 2000
 const RETRYABLE_STATUS = new Set([429, 502, 503, 504])
@@ -294,7 +297,8 @@ export class OtelSink implements TelemetrySink {
   private readonly liveLogs: TaskLogEntry[] = []
   private readonly liveEvents: LiveEvent[] = []
   private pumping: Promise<void> | undefined
-  private readonly warnedLive = new Set<OtelSignal>()
+  private window: ReturnType<typeof setTimeout> | undefined
+  private readonly warned = new Set<OtelSignal>()
   private summary: RunSummaryRecord | undefined
   private uploaded = false
   // Core's own bounded capture buffer, so which task's output survives a
@@ -318,6 +322,7 @@ export class OtelSink implements TelemetrySink {
       headers: config.headers,
       signalHeaders: config.signalHeaders ?? {},
       live: config.live === true,
+      liveBatchMs: config.liveBatchMs ?? LIVE_BATCH_MS,
       tracesEnabled: config.tracesEnabled !== false,
       metricsEnabled: config.metricsEnabled,
       logsEnabled: config.logsEnabled,
@@ -467,8 +472,13 @@ export class OtelSink implements TelemetrySink {
     }
   }
 
-  /** Core's flush deadline, passed to every POST. */
-  private deadline: AbortSignal | undefined
+  /**
+   * Every POST's signal, live ones included: core's flush deadline aborts
+   * it, so a send still hanging on a slow collector when the run ends is
+   * cut there, not left holding the process open (item 1055).
+   */
+  private readonly lifetime = new AbortController()
+  private readonly deadline = this.lifetime.signal
 
   /** The task's span, for its metric points' exemplars; none with traces off. */
   private spanOf(taskId: string): { span?: { traceId: string; spanId: string } } {
@@ -482,31 +492,42 @@ export class OtelSink implements TelemetrySink {
     if (this.cfg.live && this.cfg.logsEnabled) this.liveEvents.push(event)
   }
 
-  /** Live mode: send what is waiting, unless a send is already on its way (it takes it next). */
+  /**
+   * Live mode: send what is waiting once the batch window has passed, unless
+   * a window or a send is already open (it takes this too). A request per
+   * task cost the run a millisecond of CPU each; a window holds them to a
+   * few a second.
+   */
   private kick(): void {
-    if (!this.cfg.live || this.pumping !== undefined || this.uploaded) return
-    this.pumping = Promise.resolve()
-      .then(() => this.pump())
-      .finally(() => {
+    if (!this.cfg.live || this.uploaded || this.window !== undefined) return
+    if (this.pumping !== undefined) return
+    this.window = setTimeout(() => {
+      this.window = undefined
+      this.pumping = this.pump().finally(() => {
         this.pumping = undefined
+        if (this.waiting()) this.kick()
       })
+    }, this.cfg.liveBatchMs)
+    this.window.unref()
+  }
+
+  private waiting(): boolean {
+    return (
+      this.spans.length + this.taskPoints.length + this.liveLogs.length + this.liveEvents.length > 0
+    )
   }
 
+  /** Sends everything waiting now, as one request per signal (or a few, when large). */
   private async pump(): Promise<void> {
-    while (
-      this.spans.length + this.taskPoints.length + this.liveLogs.length + this.liveEvents.length >
-      0
-    ) {
-      const spans = this.spans.splice(0)
-      const points = this.taskPoints.splice(0)
-      const logs = this.liveLogs.splice(0)
-      const events = this.liveEvents.splice(0)
-      await Promise.all([
-        this.shipSpans(spans, true),
-        this.shipPoints(points),
-        this.shipLiveLogs(logs, events),
-      ])
-    }
+    const spans = this.spans.splice(0)
+    const points = this.taskPoints.splice(0)
+    const logs = this.liveLogs.splice(0)
+    const events = this.liveEvents.splice(0)
+    await Promise.all([
+      this.shipSpans(spans),
+      this.shipPoints(points),
+      this.shipLiveLogs(logs, events),
+    ])
   }
 
   private async shipPoints(points: TaskMetricPoint[]): Promise<void> {
@@ -517,7 +538,7 @@ export class OtelSink implements TelemetrySink {
         buildTaskMetricsRequest(this.cfg.serviceName, vxVersion, group, this.resource),
       ),
     )
-    await this.send('metrics', this.cfg.metricsUrl, bodies, true)
+    await this.send('metrics', this.cfg.metricsUrl, bodies)
   }
 
   private async shipLiveLogs(logs: TaskLogEntry[], events: LiveEvent[]): Promise<void> {
@@ -540,7 +561,7 @@ export class OtelSink implements TelemetrySink {
           )
         : []),
     ]
-    if (bodies.length > 0) await this.send('logs', this.cfg.logsUrl, bodies, true)
+    if (bodies.length > 0) await this.send('logs', this.cfg.logsUrl, bodies)
   }
 
   onRunSummary(summary: RunSummaryRecord): void {
@@ -550,11 +571,11 @@ export class OtelSink implements TelemetrySink {
   async flush(signal?: AbortSignal): Promise<void> {
     if (this.uploaded) return
     this.uploaded = true
-    this.deadline = signal
-    // Live: what is on its way lands before the rest, which the run's end sends.
-    if (this.cfg.live) {
-      await this.pumping
-      await this.pump()
+    clearTimeout(this.window)
+    if (signal !== undefined) {
+      if (signal.aborted) this.lifetime.abort(signal.reason)
+      else
+        signal.addEventListener('abort', () => this.lifetime.abort(signal.reason), { once: true })
     }
     // Finalize the root span now that the run is over (run.end set the end).
     if (this.run !== undefined && this.traceId) {
@@ -583,20 +604,29 @@ export class OtelSink implements TelemetrySink {
       )
       this.spans.splice(1, 0, ...stages)
     }
-    await Promise.all([this.shipTraces(), this.shipMetrics(), this.shipLogs()])
+    // Live: a send still on its way is not waited for before the rest; the
+    // pump takes what is left (the root span included) beside it, and the
+    // run's metrics go with no task point left to carry.
+    await Promise.all([
+      this.pumping,
+      this.cfg.live ? this.pump() : undefined,
+      this.shipTraces(),
+      this.shipMetrics(),
+      this.shipLogs(),
+    ])
   }
 
   private async shipTraces(): Promise<void> {
-    await this.shipSpans(this.spans, false)
+    await this.shipSpans(this.spans)
   }
 
-  private async shipSpans(spans: OtlpSpan[], live: boolean): Promise<void> {
+  private async shipSpans(spans: OtlpSpan[]): Promise<void> {
     if (this.cfg.tracesEnabled === false || spans.length === 0) return
     const vxVersion = this.run?.vxVersion ?? '0.0.0'
     const bodies = requestBodies(spans, (group) =>
       JSON.stringify(buildTraceRequest(this.cfg.serviceName, vxVersion, group, this.resource)),
     )
-    await this.send('traces', this.cfg.tracesUrl, bodies, live)
+    await this.send('traces', this.cfg.tracesUrl, bodies)
   }
 
   private async shipMetrics(): Promise<void> {
@@ -667,16 +697,8 @@ export class OtelSink implements TelemetrySink {
     return own === undefined || this.injected ? this.cfg.post : defaultPost(own)
   }
 
-  /**
-   * POSTs every body at once; one warning per signal, however many fail, and
-   * live sends (`once`) one per signal for the whole run.
-   */
-  private async send(
-    signal: OtelSignal,
-    url: string,
-    bodies: readonly string[],
-    once = false,
-  ): Promise<void> {
+  /** POSTs every body at once; one warning per signal for the run, however many fail. */
+  private async send(signal: OtelSignal, url: string, bodies: readonly string[]): Promise<void> {
     const gzip = this.cfg.gzip.includes(signal)
     const headers: Record<string, string> = {
       'content-type': 'application/json',
@@ -700,11 +722,8 @@ export class OtelSink implements TelemetrySink {
       )
     ).filter((m) => m !== undefined)
     // export is fully optional — a down collector never affects a run
-    if (failed.length === 0) return
-    if (once) {
-      if (this.warnedLive.has(signal)) return
-      this.warnedLive.add(signal)
-    }
+    if (failed.length === 0 || this.warned.has(signal)) return
+    this.warned.add(signal)
     // Name the URL: three signals ship concurrently and each is caught
     // here on its own, so a bare "export failed" cannot tell a down
     // collector from one misconfigured signal endpoint.