Skip to main content
When your system calls an Elementum webhook, it can pass its own trace context. Elementum then records the automation run as part of your trace, directly under the span that made the call. You see your request and the whole automation run as one tree. The run is exported only when a trace forwarding endpoint is enabled and attached to the environment.

How to do it

Send a valid W3C traceparent header with the webhook request. Most OpenTelemetry HTTP client instrumentations do this automatically.
Use the webhook URL shown on the automation’s webhook trigger. The header has four parts separated by -: version 00, the 32-character trace id, the 16-character id of your calling span, and the trace flags. If you instrument manually, inject the context from the span that makes the call. For example, in Python:

What you see

  • automation.trigger is a child of the span named in your traceparent. It is the only Elementum span whose parent is outside Elementum.
  • automation.workflow is a child of the trigger span, on your trace, with no span link.
  • Every action span of the run, and any sub-automation it starts, follows on the same trace.
  • If one webhook call starts several automation runs, each run’s workflow span is a child of the same trigger span.

Rules Elementum applies

A missing or invalid header never causes the webhook to be rejected. The response status and body are the same with or without it.

Small differences on a continued trigger span

  • The continued automation.trigger span arrives without the elementum.source attribute. Every other Elementum span keeps it. To select all Elementum spans, filter on service.name = elementum.
  • The trigger span carries your tracestate, if you sent one.

Which triggers can continue a trace

Only webhook triggers read traceparent. Other ways to start an automation do not continue a caller’s trace. That includes record events, schedules, emails, on-demand runs from the app, and the automation execution API. Those runs start a new trace. If you call another Elementum API with a traceparent, the run does not appear under your span. In some cases the Elementum spans can share your trace id without being attached to your span. Use a webhook trigger when you need a continued trace.

Runs that start a new trace

When there is no usable traceparent, or the trigger is not a webhook, the run starts a new trace:
  • automation.trigger is a root span.
  • automation.workflow is in the same trace and carries a span link to the trigger span, with the link attributes link.type = probe and link.probe.trace_id. See Span links.
  • The action spans are children of the workflow span.
In current releases, the workflow span of a run that starts a new trace can arrive without a parent, as a second top-level span in the same trace. Its span link and elementum.automation.execution_id still connect it to the trigger and to its actions.
In rare cases Elementum cannot record the trigger span on the trace, for example during an internal fault. The run then starts a trace of its own with the workflow span as its root. It keeps a span link to the trigger span when one exists. The run itself is not affected.

Calls between Elementum automations

Include Trace Header is being released. Until it reaches your environment, a Send API Request call to another automation starts a new trace.
A call from one Elementum automation to another automation’s webhook is treated like any other caller: See Send trace headers to other systems.

Verify it works

  1. Send a webhook request with a traceparent from an instrumented client.
  2. Wait a few seconds, then open the trace by its trace id in your backend.
  3. Check that automation.trigger appears directly under your calling span, and that elementum.automation.trigger_type is WEB_HOOK.
If the Elementum spans are missing or not attached, see The Elementum spans are not attached to my span.