> ## 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.

# Send Trace Headers to Other Systems

> Use Include Trace Header on Send API Request so the systems an automation calls can continue the trace.

The Send API Request action can pass the automation's trace on to the system it calls. If that system is traced and sends its spans to the same backend, its spans appear under the Elementum call in one trace.

> [!NOTE]
>
> The HTTP client span and the **Include Trace Header** option are being released. If you do not see the option on the Send API Request step, or `GET` and `POST` client spans under `send_api_request`, the release has not reached your environment yet.

## Turn it on

1. Open the automation and select the **Send API Request** step.
2. Turn on **Include Trace Header**.
3. Publish the workflow.

The option is off by default. It is set per step, so you choose which calls carry trace context.

The step describes the option this way: "Adds a W3C traceparent header so the receiving system can continue this automation's trace. Trace headers you add above (traceparent, tracestate, b3) are replaced."

## What Elementum sends

With **Include Trace Header** on, each request carries one header:

```http theme={null}
traceparent: 00-<trace id>-<span id of the Elementum HTTP client span>-01
```

* The trace id is the run's trace id. If the run [continued your trace](https://docs.elementum.io/administration/trace-forwarding/continue-your-trace.md), it is your trace id.
* The span id names the Elementum HTTP client span for this call. The receiving system's server span becomes a child of that client span.
* No `tracestate` and no `baggage` are sent.

```text theme={null}
automation.workflow                        elementum
└── send_api_request                       elementum   task_label="Call partner API"
    └── GET                                elementum   client span, url.full=https://partner.example.com/orders
        └── GET /orders                    partner-api (server span, continued from traceparent)
            └── partner.lookup             partner-api
```

The receiving system must be instrumented to read `traceparent`. Most OpenTelemetry HTTP server instrumentations do this by default.

## Trace headers you set on the step

You can add trace headers yourself in the step's headers list, for example to pass a fixed trace context to a partner. What is sent depends on the option:

| Include Trace Header | Trace headers you added on the step | What the server receives |
| - | - | - |
| Off (default) | none | No trace headers. |
| Off | yes | Your headers exactly as you wrote them. |
| On | none | Elementum's `traceparent`. |
| On | yes | Only Elementum's `traceparent`. Your trace headers are not sent. |

When the option is on and the step already lists a trace header, the builder shows this warning: "Trace Headers Will Be Replaced. With Include Trace Header on, the trace headers listed above are not sent. Elementum adds its own traceparent instead."

Header names treated as trace headers, matched without regard to case:

* `traceparent`, `tracestate`, `baggage`
* `b3`, `x-b3-traceid`, `x-b3-spanid`, `x-b3-parentspanid`, `x-b3-sampled`, `x-b3-flags`
* `uber-trace-id`, `x-amzn-trace-id`
* Any header starting with `uberctx-`, `ot-tracer-`, or `x-datadog-`

## When the header is not sent

Even with the option on, Elementum sends no `traceparent` in these cases:

| Case | Behavior |
| - | - |
| **Redirect to another host.** The server answers with a redirect to a different host, scheme, or port. | The redirected request carries no trace header. A redirect to another path on the same host, scheme, and port keeps the same `traceparent`. |
| **OAuth token requests.** The step uses OAuth and fetches or refreshes a token. | The token request carries no trace header and has no span. Only the API call itself is traced. |
| **The action has no span.** For example, the step ran outside a traced automation run. | No `traceparent` is sent, and any trace headers you added on the step are also removed. |

## Elementum internal trace headers are never sent

Elementum traces its own infrastructure separately. Those internal trace headers are removed from every Send API Request call, whether **Include Trace Header** is on or off. The systems you call never receive Elementum's internal trace ids or baggage.

## The HTTP client span

Every Send API Request call that runs inside a traced action produces an HTTP client span, whether or not **Include Trace Header** is on. The span is named after the HTTP method, for example `GET` or `POST`, and has kind `CLIENT`. Its parent is the `send_api_request` action span.

| Attribute | Example | Notes |
| - | - | - |
| `http.request.method` | `GET` | |
| `url.full` | `https://partner.example.com/orders?key=REDACTED` | Query values, user name, password, and fragment removed. See below. |
| `server.address` | `partner.example.com` | |
| `server.port` | `443` | Always set. The scheme's default port when the URL has none. |
| `http.response.status_code` | `200` | Absent when no response arrived. |
| `error.type` | `404`, `timeout`, `java.net.ConnectException` | Only on failed calls. |
| `elementum.automation.trace_header` | `true` | Whether **Include Trace Header** was on for this call. |
| `elementum.automation.http.resend_count` | `1` | Only on a call resent after an OAuth rejection. |

The span is marked as an error for a 4xx or 5xx response, a timeout, a connection failure, or a failure while reading the response body. The span ends when the response has been read, so its duration includes the body download. Full definitions are in the [attribute reference](https://docs.elementum.io/administration/trace-forwarding/attribute-reference.md#http-client-span).

### URL redaction

`url.full` never contains query values or credentials:

| Request URL | `url.full` on the span |
| - | - |
| `https://user:pass@api.example.com/a/b?x=1&x=2&flag#section` | `https://api.example.com/a/b?x=REDACTED&x=REDACTED&REDACTED` |
| `https://api.example.com/orders?customer=acme&page=2` | `https://api.example.com/orders?customer=REDACTED&page=REDACTED` |

Query parameter names and the URL path are kept. If an API puts a secret or personal data in the path, that value appears in `url.full`. Put those values in query parameters or headers.

### OAuth resends

When a call using OAuth is rejected with 401 or 403, Elementum refreshes the token and sends the call once more. You then see two client spans under the same action span: the first with status code `401` or `403` and error status, the second with `elementum.automation.http.resend_count = 1`.

## Check that it works

1. Turn on **Include Trace Header** on a step that calls an instrumented service, and publish.
2. Run the automation.
3. In your backend, open the run's trace. Under `send_api_request` you should see the client span, and under it the receiving service's server span.
4. If the receiving service's span is a separate trace, check that it reads `traceparent`, and that the call did not redirect to another host.

Calling another Elementum automation's webhook with the option on continues the trace into that automation. See [Calls between Elementum automations](https://docs.elementum.io/administration/trace-forwarding/continue-your-trace.md#calls-between-elementum-automations).


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