Use custom spans when application-specific work is not represented clearly by existing spans. Keep instrumentation close to the operation it describes and use consistent names and attributes across services.

Custom instrumentation tasks

• Create Custom Spans for meaningful operations and sub-operations.
• Add Span Attributes and Events to record searchable context and timestamped milestones.
• Record Errors and Exceptions using the SDK’s error conventions.
• Link Spans and Create Trace Links when causality is not a simple parent-child relationship.
• Instrument Async and Batch Workloads across task and batch boundaries.
• Instrument Messaging and Queues across producers, brokers, and consumers.

Design principles

• Name spans for a stable class of operation, not an individual request or entity.
• Keep attributes bounded in cardinality and avoid secrets or personal data.
• Preserve parent context where there is a direct synchronous relationship; use links for independent or many-to-one causal relationships.
• End every span when its represented operation finishes, including error and cancellation paths.
• Validate the resulting trace in a test environment before rollout.