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

# Span Reference

> Every automation span Elementum sends, how the spans nest, and which steps have no span.

This page lists every kind of span Elementum sends for automations, how they nest, and when each one appears. For the attributes on each span, see the [attribute reference](https://docs.elementum.io/administration/trace-forwarding/attribute-reference.md).

## Span types at a glance

| Span name | Kind | One per | Parent |
| - | - | - | - |
| `automation.trigger` | `INTERNAL` | Trigger firing | None, your calling span, or a `run_automation` action span |
| `automation.workflow` | `INTERNAL` | Automation run | The trigger span. See [Parenting of the workflow span](#parenting-of-the-workflow-span). |
| Action span, named after the action type, for example `send_api_request` | `INTERNAL` | Action attempt | The workflow span of the run |
| HTTP client span, named after the method, for example `GET` | `CLIENT` | Outbound HTTP call of a Send API Request | The `send_api_request` action span |

Every span has resource `service.name = elementum` and instrumentation scope `elementum`.

> [!NOTE]
>
> The HTTP client span is being released. See [Send trace headers to other systems](https://docs.elementum.io/administration/trace-forwarding/send-trace-headers.md).

## Span tree

```mermaid theme={null}
flowchart TD
    C["Your span, continued webhook only"] --> T["automation.trigger"]
    T --> W["automation.workflow"]
    W --> A1["send_api_request"]
    A1 --> H["GET or POST, CLIENT"]
    H --> P["Partner server span, if it continues the trace"]
    W --> A2["script-runner-javascript"]
    W --> A3["create_aspect_record_and_relate"]
    W --> RA["run_automation"]
    RA --> T2["Sub-automation trigger"]
    T2 --> W2["Sub-automation workflow"]
    W2 --> A4["Action spans"]
```

The same tree as indented text, from a real run that continued the caller's trace:

```text theme={null}
checkout                                   customer-app
└── POST webhook                           customer-app
    └── automation.trigger                 elementum   WEB_HOOK
        └── automation.workflow            elementum   workflow_version=8
            ├── send_api_request           elementum   task_label="Call partner API"
            │   └── GET                    elementum   CLIENT  url.full=http://partner-api:8080/orders
            │       └── GET /orders        partner-api
            ├── send_api_request           elementum   task_label="Create shipment"
            │   └── POST                   elementum   CLIENT
            │       └── POST /shipments    shipping-api
            ├── send_api_request           elementum   task_label="Check stock"
            │   └── GET                    elementum   CLIENT
            │       └── GET /stock         inventory-api
            ├── script-runner-javascript   elementum   task_label="Summarize order"
            ├── create_aspect_record_and_relate        task_label="Create incident"
            └── send_tagged_message        elementum   task_label="Post shipment update"
```

## `automation.trigger`

One span each time a trigger fires. That covers record events, approvals, comments, schedules, time-relative triggers, emails, webhooks, on-demand runs, and sub-automations started by a Run Automation action.

| Property | Value |
| - | - |
| Parent | None for most triggers. Your calling span for a [continued webhook](https://docs.elementum.io/administration/trace-forwarding/continue-your-trace.md). The calling `run_automation` action span for a sub-automation. |
| Children | The workflow span of each run it starts. One trigger can start several runs. |
| Duration | Short. It covers the trigger firing and the start of the run, not the run itself. |
| Key attributes | `elementum.automation.trigger_type`, `elementum.automation.trigger_category` |

The trigger span carries no automation or run id. To find the runs it started, look at its child or linked workflow spans.

## `automation.workflow`

One span per automation run, created when the run starts.

| Property | Value |
| - | - |
| Parent | The trigger span that started the run, in the same trace. See the note below. |
| Links | One link to the trigger span, except for a run that continued your webhook trace. |
| Children | The run's action spans. |
| Duration | Short. The span marks the start of the run and ends before the actions run. Do not use it as the run's duration. Exception: for a run started by a synchronous execution request, which waits for the run's result, the trigger and workflow spans stay open until the run finishes. |
| Key attributes | `elementum.automation.execution_id`, `elementum.automation.id`, `elementum.automation.workflow_id`, `elementum.automation.workflow_version` |

### Parenting of the workflow span

| Run | Trace | Parent | Link to trigger |
| - | - | - | - |
| Continued your webhook trace | Your trace | `automation.trigger` | No |
| Any other run | The trigger's trace | See note | Yes |
| Trigger not recorded (rare) | A new trace | None | Yes, when the trigger exists |

> [!NOTE]
>
> For runs that do not continue your trace, the workflow span is intended to be a child of the trigger. In current releases it can arrive without a parent, as a second top-level span in the same trace. Use the span link or `elementum.automation.execution_id` to connect it to its trigger and actions.

### Span links

The link from a workflow span to its trigger span carries two attributes:

| Link attribute | Value |
| - | - |
| `link.type` | `probe`. Marks the link back to the trigger that started the run. |
| `link.probe.trace_id` | The trigger span's trace id. Usually the same as the workflow span's own trace id. |

Some tracing UIs, including Jaeger, show links as references the span follows from, and do not display link attributes.

## Action spans

One span per attempt of each action. The span name is the action type, for example `send_api_request`. Each retry is a separate span with a higher `elementum.automation.retry_count`.

| Property | Value |
| - | - |
| Parent | The workflow span of the run. Actions inside parallel branches are siblings under the same workflow span. |
| Children | The HTTP client span for `send_api_request`. The sub-automation's trigger span for some `run_automation` steps. Otherwise none. |
| Duration | The time the action took to execute. An action that starts asynchronous work and returns while it continues reports success, and its span covers only the call, not the wait. |
| Key attributes | `elementum.automation.task_label`, `elementum.automation.executor`, `elementum.automation.retry_count`, and the run's ids |

### Action type to span name

The span name is the action type. The label in the first column is the action as it appears when you build the automation.

| Action | Span name |
| - | - |
| Send API Request | `send_api_request` |
| Execute Script | `script-runner-javascript` |
| Create Record | `create_aspect_record_and_relate` |
| Post Update, Send Message | `send_tagged_message` |
| Run Automation | `run_automation` |
| Send Email | `send_email` |
| Send Survey | `send_survey` |
| Send Slack Message | `send_slack_message` |
| Post Teams Message | `post_teams_message` |
| Search Records | `aspect_records_search` |
| Search Table Records | `table_records_search` |
| Relate Records | `relate_aspect_records` |
| Delete Records | `delete_records` |
| Add Watcher | `add_watcher_to_record` |
| Save Attachment | `save_attachment` |
| Create Approval Chain | `create_approval_chain` |
| Calculation | `calculation` |
| AI Classify, AI Summarize, AI Transform | `ai_classify_completion`, `ai_summarize_completion`, `ai_transform_completion` |
| AI Agent | `ai_agent_run` |

The span name always equals the `elementum.automation.executor` attribute, so you can group by either.

### Elementum bookkeeping actions

Some runs include steps that Elementum adds itself. They appear as action spans with `elementum.automation.system_task = true`:

`async_automation_task_start`, `async_automation_task_complete`, `async_automation_task_failure`, `automation_workflow_completion`, `execute_workflow_callbacks`.

Filter them out with `elementum.automation.system_task != true` when you only want the steps you built.

### Batched actions

Elementum can group the same action from many runs and execute them together. Update Field is commonly batched. Assign User and Assign Group use the same action and are batched the same way. A batched action still gets its own span, under its own run's workflow span and on its own trace, with its own status. Its span differs in two ways:

* `elementum.automation.mode` is `batch`, and `elementum.automation.batch.size` and `elementum.automation.batch.index` say how many actions ran together and where this one sat in the group.
* The span covers the whole batch, not only this action's share of it. Actions in the same batch therefore have almost the same duration. Small differences between them reflect their position in the batch, not the work done.

### Actions without a span

Some steps have no span of their own:

* **Structural steps**, such as parallel branches and their joins. The actions inside them have spans.
* **Platform jobs** that are not automation runs.

A run can have fewer action spans than steps. The Elementum run history lists every step.

## Run Automation and sub-automations

A Run Automation step produces one of two shapes. Which shape you get depends on how the step is configured and how Elementum runs it.

| Shape | What you see |
| - | - |
| Sub-automation with its own run | A `run_automation` action span. Under it, the sub-automation's `automation.trigger` (with `trigger_type = ON_DEMAND`), then its `automation.workflow` and action spans, in the same trace. Nesting continues at any depth. |
| Sub-automation run inside the calling run | No trigger or workflow span for the sub-automation. Its action spans appear directly under the calling run's workflow span, next to bookkeeping steps such as `async_automation_task_start` and `async_automation_task_complete`. |

## HTTP client span

One span per outbound HTTP call of a Send API Request, named after the method (`GET`, `POST`, `PUT`, `DELETE`). Kind `CLIENT`, parent `send_api_request`. A call resent after an OAuth rejection produces a second client span. Details are in [The HTTP client span](https://docs.elementum.io/administration/trace-forwarding/send-trace-headers.md#the-http-client-span).

## Span status

| Status | When |
| - | - |
| `OK` | The trigger, run start, or action completed. |
| `ERROR` | It failed. Action spans also carry `elementum.error.type` and `elementum.error.message`. HTTP client spans carry `error.type`. |
| `UNSET` | An HTTP client span that completed without an error status. |

The error status has no description. Span events, including exception events, are not sent on automation spans.

## Other spans you may see

| Span name | What it is |
| - | - |
| `elementum.connection-test` | The test span sent when you test an endpoint. Not an automation span. |
| `invoke_agent <agent name>`, `chat <model>`, `execute_tool <tool name>` | An AI agent turn, its LLM calls, and its tool runs. See [GenAI tracing](https://docs.elementum.io/administration/trace-forwarding/genai-tracing.md). |
| `voice.realtime.*`, `voice.tool.call`, `voice.authentication` | Voice agent calls. See [Voice calls](https://docs.elementum.io/administration/trace-forwarding/genai-tracing.md#voice-calls). |
| Other AI activity spans, such as conversation and message handling | Sent to General endpoints only. These pages do not describe them span by span. |

A General endpoint receives AI agent spans next to automation spans, from the same environments. They have `service.name = elementum` too. To separate them, filter on `gen_ai.operation.name`. Agent, LLM call, and tool spans carry it. Automation spans never do.


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