BizFirstGO Trace Structure — Distributed Traces

Span Hierarchy

# Example trace for a workflow with 4 nodes including one HIL node

workflow.execute  [TRACE ROOT — entire execution]
  traceId: 4bf92f3577b34da6a3ce929d0e0e4736
  workflow.id: wf-8a4c2f91
  execution.id: exec-d1e2f3a4
  tenant.id: tenant-abc-123
  duration: 4h 23m 47s  ← includes HIL suspension time

  ├── node.execute  [StartNode]
  │     node.key: start-node-01
  │     node.type: StartNode
  │     duration: 3ms

  ├── node.execute  [DataFetchNode]
  │     node.key: data-fetch-01
  │     node.type: DataFetchNode
  │     duration: 4.2s
  │     └── http.client  [GET https://api.example.com/customer/data]
  │           http.url: https://api.example.com/customer/data
  │           http.method: GET
  │           http.status_code: 200
  │           duration: 4.1s   ← the slow external call

  ├── node.execute  [ApprovalNode — HIL]
  │     node.key: approval-node-01
  │     node.type: ApprovalNode
  │     hil.actor: user-xyz-789
  │     hil.outcome: approved
  │     duration: 4h 23m      ← waiting for human approval
  │     events:
  │       hil.suspended  [timestamp: 14:32:01]
  │       hil.resumed    [timestamp: 18:55:08, outcome: approved]

  └── node.execute  [EndNode]
        node.key: end-node-01
        node.type: EndNode
        duration: 2ms

Standard Span Attributes by Span Type

Span Name	Required Attributes	Optional Attributes
`workflow.execute`	workflow.id, execution.id, tenant.id, triggered_by	workflow.name, workflow.version
`node.execute`	node.key, node.type, execution.id, tenant.id	node.name, node.display_name
`node.execute` (HIL)	hil.actor, hil.outcome	hil.reason, hil.deadline
`http.client`	http.url, http.method, http.status_code	http.request.content_type
`db.query`	db.system, db.name, db.statement (sanitized)	db.operation

Span Events

Span events are timestamped log entries attached to a specific span. BizFirstGO uses them for HIL lifecycle events:

# Span events on the ApprovalNode span:
event[0]:
  name: "hil.suspended"
  timestamp: 2026-05-25T14:32:01Z
  attributes:
    hil.reason: "Manager approval required for invoices > $10,000"
    hil.assigned_to: "manager-group-finance"

event[1]:
  name: "hil.resumed"
  timestamp: 2026-05-25T18:55:08Z
  attributes:
    hil.outcome: "approved"
    hil.actor: "user-xyz-789"
    hil.comment: "Approved — within quarterly budget"
    hil.duration_seconds: 16387

Automatically Instrumented Spans

These span types are created automatically by OTel auto-instrumentation — no code changes needed in executors:

ASP.NET Core HTTP requests — GET /api/workflows/{id}/execute
HttpClient outbound calls — any HttpClient call made by an executor
Entity Framework queries — database operations with sanitized SQL
gRPC calls — inter-service gRPC communication
Redis operations — cache reads and writes (if OpenTelemetry.Instrumentation.StackExchangeRedis is enabled)

← Trace Ingestion Next: Searching Traces →