Saltar al contenido principal

Trace

Category: Monitoring
Node id: trace

Provides distributed tracing with trace/span lifecycle management, events, tags, and querying

What it does​

  • Full trace lifecycle: start, end, get, query, and export traces
  • Span management: start, end, and retrieve individual spans
  • Parent-child span relationships for nested tracing
  • Span event recording with timestamped attributes
  • Tag management for both traces and spans
  • Span kinds: client, server, producer, consumer, internal
  • Query traces/spans by service name and status filters
  • Auto-generated trace and span IDs using crypto/rand

Use cases​

  • Trace end-to-end pipeline execution across multiple node handlers
  • Monitor inter-service communication latency in healthcare workflows
  • Debug slow pipeline steps by examining span durations
  • Export traces for integration with observability platforms (Jaeger, Zipkin)
  • Correlate logs and metrics with distributed trace context

Runtime​

  • Performance tier: fast

Input ports​

NameTypeRequiredDescription
trace_idtextNoTrace ID from upstream (alternative to config)
span_idtextNoSpan ID from upstream (alternative to config)
tagsjsonNoTags to set on trace or span (key-value map)
metadatajsonNoMetadata to attach to traces
attributesjsonNoAttributes for span events

Output ports​

NameTypeRequiredDescription
resultjsonNoFull trace result object
successbooleanNoWhether the operation succeeded
countnumberNoNumber of items processed
operationtextNoOperation performed
trace_idtextNoTrace ID string (for downstream propagation)
span_idtextNoSpan ID string (for downstream propagation)
tracejsonNoTrace object (trace operations)
spanjsonNoSpan object (span operations)
spansjsonNoArray of spans (query operations)
summaryjsonNoOperation summary
processed_attextNoTimestamp of processing

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
OperationoperationenumNostart_tracestart_trace, end_trace, start_span, end_span, add_event, add_tags, get_trace, get_span, query_traces, exportTracing operation to perform
Trace IDtrace_idstringNoTrace identifier (auto-generated if empty for start_trace)
Span IDspan_idstringNoSpan identifier (auto-generated if empty for start_span)
Service Nameservice_namestringNounknownName of the service
Span NamenamestringNounknownName of the span
Span KindkindenumNointernalclient, server, producer, consumer, internalType of span

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Parent Span IDparent_idstringNoParent span ID for nested spans
StatusstatusstringNosuccessStatus to set when ending trace/span
Event Nameevent_namestringNoName of the event to add (add_event operation)
TagstagsjsonNoStatic tags to set
AttributesattributesjsonNoStatic attributes for events
Service Filterservice_filterstringNoFilter traces by service (query operation)
Status Filterstatus_filterstringNoFilter traces by status (query operation)
LimitlimitnumberNo100Maximum results for query

Errors​

CodeDescription
MISSING_TRACE_IDtrace_id is required for this operation but was not provided
MISSING_SPAN_IDspan_id is required for this operation but was not provided
TRACE_NOT_FOUNDNo trace exists with the given trace_id
SPAN_NOT_FOUNDNo span exists with the given span_id
UNSUPPORTED_OPERATIONOperation is not one of the supported tracing operations

Runtime notes​

  • Output keys are conditional: trace_id/trace appear only for trace operations, span_id/span for span operations, spans for query_traces
  • Wire trace_id output to downstream trace nodes to propagate trace context through the pipeline
  • Traces and spans are stored in-memory — data is lost on process restart; use export for persistence
  • Config values for trace_id/span_id take precedence over input port values

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

¿Algo no está claro? Envíe sus comentarios sobre la documentación por correo electrónico..