> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Continue Your Trace into Elementum

> Pass a W3C traceparent header on a webhook call so the automation run continues your trace.

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](https://docs.elementum.io/administration/trace-forwarding/set-up.md#attach-an-endpoint-to-an-environment).

## How to do it

Send a valid W3C `traceparent` header with the webhook request. Most OpenTelemetry HTTP client instrumentations do this automatically.

```http theme={null}
POST /api/v1/webhooks/<automation-id> HTTP/1.1
Host: <your Elementum host>
Content-Type: application/json
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
tracestate: vendor1=value1

{"orderId": "ORD-1001"}
```

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:

```python theme={null}
from opentelemetry import trace
from opentelemetry.propagate import inject
import requests

tracer = trace.get_tracer("checkout")

with tracer.start_as_current_span("POST webhook", kind=trace.SpanKind.CLIENT):
    headers = {"Content-Type": "application/json"}
    inject(headers)  # adds traceparent (and tracestate if present)
    requests.post(webhook_url, json={"orderId": "ORD-1001"}, headers=headers)
```

## What you see

```text theme={null}
Your trace 4bf92f35...
checkout                                   your service
└── POST webhook                           your service, span 00f067aa0ba902b7
    └── automation.trigger                 elementum   trigger_type=WEB_HOOK
        └── automation.workflow            elementum
            ├── send_api_request           elementum
            │   └── GET                    elementum   (HTTP client span)
            └── script-runner-javascript   elementum
```

* `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

| You send | Result |
| - | - |
| A valid `traceparent` | The run continues your trace. |
| A valid `traceparent` with sampled flag `00` | The run still continues your trace, and Elementum still sends its spans. Elementum ignores the sampled flag. |
| A valid `traceparent` and a `tracestate` | The `tracestate` is kept on the trigger span's context when it is 512 characters or fewer after re-encoding, and dropped if longer. Invalid entries are dropped. |
| A `tracestate` without a valid `traceparent` | Ignored. |
| A `baggage` header | Not passed into the run. Baggage entries never reach Elementum's spans or the systems the automation calls. |
| An invalid `traceparent` (wrong length, bad separators, upper-case or non-hex characters, version `ff`, an all-zero trace id or span id) | Treated as if no header was sent. |
| No `traceparent` | The run starts a new trace. See [Runs that start a new trace](#runs-that-start-a-new-trace). |

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:

```text theme={null}
New trace
automation.trigger                         elementum   (root span)
automation.workflow                        elementum   link → automation.trigger
├── send_api_request                       elementum
└── ...
```

* `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](https://docs.elementum.io/administration/trace-forwarding/span-reference.md#span-links).
* The action spans are children of the workflow span.

> [!NOTE]
>
> 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

> [!NOTE]
>
> **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:

| Calling step | Result in the called run |
| - | - |
| Send API Request with **Include Trace Header** on | Continues the caller's trace under the calling step's HTTP client span. |
| Send API Request with **Include Trace Header** off | Starts a new trace, with no link to the caller. |

See [Send trace headers to other systems](https://docs.elementum.io/administration/trace-forwarding/send-trace-headers.md).

## 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](https://docs.elementum.io/administration/trace-forwarding/troubleshooting.md#the-elementum-spans-are-not-attached-to-my-span).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.