A span link relates one span to another span context without making either span the other’s parent. Use links when work is causally related but does not fit a single parent-child tree.

  • A worker processes a message created in a separate trace.
  • One batch operation depends on several independently created messages or requests.
  • A new operation is associated with prior work but should remain a separate trace.
  • A span has an existing parent context and also needs to retain another causal relationship.

For ordinary synchronous calls, preserve the active context and use parent-child spans instead. A link does not change the linked span’s parent or merge trace IDs.

Use the SDK’s span-link API and provide the source span context. When the context is known before the new span starts, add the link during span creation; a sampler may use creation-time links when deciding whether to record the span. Add bounded, non-sensitive link attributes only when they explain the relationship, such as a message role or batch position.
Inspect traces with a representative single-message and batch workflow to confirm the links are present and useful.