feat(trace): add --span-id and --parent-id to trace span

rodrigo-roca · claude · rodrigo-roca · commit e583ac4f5ed0 · 2026-07-06T10:02:48.000+02:00
Let callers assign an explicit span ID and nest a custom span under another
custom span, instead of every span being flat under the job. --span-id
defaults to a generated ID when omitted; --parent-id references another
span's ID and attaches to the job/step as before when omitted. Both are
validated as hexadecimal.

This makes it possible to assemble arbitrary span trees (e.g. from an
OpenTelemetry dump) via repeated `trace span` calls.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/base/src/commands/span/__tests__/span.test.ts b/packages/base/src/commands/span/__tests__/span.test.ts
@@ -120,6 +120,48 @@ describe('span', () => {
       expect(context.stdout.toString()).toContain('"life":42')
       expect(context.stdout.toString()).toContain('"golden":1.618')
     })
+
+    test('span-id', async () => {
+      const env = {GITLAB_CI: '1'}
+      const {context, code} = await runCLI(
+        ['--name', 'mytestname', '--duration', '10000', '--span-id', '0a1b2c3d4e'],
+        env
+      )
+      expect(code).toBe(0)
+      expect(context.stdout.toString()).toContain('"span_id":"0a1b2c3d4e"')
+    })
+
+    test('parent-id', async () => {
+      const env = {GITLAB_CI: '1'}
+      const {context, code} = await runCLI(
+        ['--name', 'mytestname', '--duration', '10000', '--span-id', '0a1b2c3d4e', '--parent-id', '5f6a7b8c9d'],
+        env
+      )
+      expect(code).toBe(0)
+      expect(context.stdout.toString()).toContain('"span_id":"0a1b2c3d4e"')
+      expect(context.stdout.toString()).toContain('"parent_id":"5f6a7b8c9d"')
+    })
+
+    test('no-parent-id-by-default', async () => {
+      const env = {GITLAB_CI: '1'}
+      const {context, code} = await runCLI(['--name', 'mytestname', '--duration', '10000'], env)
+      expect(code).toBe(0)
+      expect(context.stdout.toString()).not.toContain('"parent_id"')
+    })
+
+    test('span-id-invalid', async () => {
+      const env = {GITLAB_CI: '1'}
+      const {context, code} = await runCLI(['--name', 'mytestname', '--duration', '10000', '--span-id', 'xyz'], env)
+      expect(code).toBe(1)
+      expect(context.stderr.toString()).toContain('The span ID must be a hexadecimal string.')
+    })
+
+    test('parent-id-invalid', async () => {
+      const env = {GITLAB_CI: '1'}
+      const {context, code} = await runCLI(['--name', 'mytestname', '--duration', '10000', '--parent-id', 'xyz'], env)
+      expect(code).toBe(1)
+      expect(context.stderr.toString()).toContain('The parent ID must be a hexadecimal string.')
+    })
   })
 
   makeCIProviderTests(runCLI, ['--name', 'mytestname', '--duration', '10000'])
diff --git a/packages/base/src/commands/span/span.ts b/packages/base/src/commands/span/span.ts
@@ -27,6 +27,10 @@ export class SpanCommand extends CustomSpanCommand {
         'Create span with name "Get Dependencies" and duration of 10s and report to Datadog with tags and measures',
         'datadog-ci trace span --name "Get Dependencies" --duration 10000 --tags "dependency-set:notify" --measures "n-dependencies:42"',
       ],
+      [
+        'Create a span nested under another custom span by referencing its span ID',
+        'datadog-ci trace span --name "Plan" --duration 10000 --span-id 0a1b2c3d4e --parent-id 5f6a7b8c9d',
+      ],
     ],
   })
 
@@ -40,6 +44,9 @@ export class SpanCommand extends CustomSpanCommand {
   private endTimeInMs: number | undefined = Option.String('--end-time', {
     validator: validation.isInteger(),
   })
+  // Optional explicit IDs so callers can assemble a span tree.
+  private spanId = Option.String('--span-id')
+  private parentId = Option.String('--parent-id')
 
   public async execute() {
     this.tryEnableFips()
@@ -76,14 +83,32 @@ export class SpanCommand extends CustomSpanCommand {
       return 1
     }
 
+    const hexPattern = /^[0-9a-f]+$/i
+    if (this.spanId !== undefined && !hexPattern.test(this.spanId)) {
+      this.context.stderr.write(`The span ID must be a hexadecimal string.\n`)
+
+      return 1
+    }
+    if (this.parentId !== undefined && !hexPattern.test(this.parentId)) {
+      this.context.stderr.write(`The parent ID must be a hexadecimal string.\n`)
+
+      return 1
+    }
+
     const endTime = this.endTimeInMs ? new Date(this.endTimeInMs) : new Date()
     const startTime = new Date(endTime.getTime() - this.durationInMs)
 
-    return this.executeReportCustomSpan(this.generateSpanId(), startTime, endTime, {
-      name: this.name,
-      error_message: '',
-      exit_code: 0,
-      command: 'datadog-ci trace span',
-    })
+    return this.executeReportCustomSpan(
+      this.spanId ?? this.generateSpanId(),
+      startTime,
+      endTime,
+      {
+        name: this.name,
+        error_message: '',
+        exit_code: 0,
+        command: 'datadog-ci trace span',
+      },
+      this.parentId
+    )
   }
 }
diff --git a/packages/base/src/commands/trace/helper.ts b/packages/base/src/commands/trace/helper.ts
@@ -53,7 +53,8 @@ export abstract class CustomSpanCommand extends BaseCommand {
     id: string,
     startTime: Date,
     endTime: Date,
-    extraTags: Record<string, any>
+    extraTags: Record<string, any>,
+    parentId?: string
   ): Promise<number> {
     const provider = getCIProvider()
     if (!SUPPORTED_PROVIDERS.includes(provider)) {
@@ -87,6 +88,7 @@ export abstract class CustomSpanCommand extends BaseCommand {
       end_time: endTime.toISOString(),
       ci_provider: provider,
       span_id: id,
+      ...(parentId ? {parent_id: parentId} : {}),
       tags: {...gitSpanTags, ...ciSpanTags, ...userGitSpanTags, ...cliTags, ...envVarTags},
       measures,
       command: extraTags.command,
diff --git a/packages/base/src/commands/trace/interfaces.ts b/packages/base/src/commands/trace/interfaces.ts
@@ -16,6 +16,7 @@ export type Provider = (typeof SUPPORTED_PROVIDERS)[number]
 export interface Payload {
   ci_provider: string
   span_id: string
+  parent_id?: string
   command: string
   name: string
   start_time: string
