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

# Span Metrics

> Convert tracing spans into aggregated metrics in the Odigos VM Agent

[Span metrics](./overview#span-metrics) is a processor that turns tracing spans into aggregated metrics (e.g., request counts, latency histograms), reducing export volume and making it easier to build dashboards and alerts.

There are two ways to add a span metrics action: using `odictl` or using YAML files.

<Tabs>
  <Tab title="odictl">
    <Steps>
      <Step title="Launch odictl">
        ```shell theme={null}
        odictl
        ```
      </Step>

      <Step title="Select the actions menu">
        Use `Tab` to focus on the Actions pane or press `a`, then press `Enter` or click `+ Add Action` with your mouse.

        <img
          src="https://mintcdn.com/odigos/plx_nD0F6Hp-pnSU/images/vmagent/actions/odictl-action-select.png?fit=max&auto=format&n=plx_nD0F6Hp-pnSU&q=85&s=7b2dca2c2364ea7e632ddc02e3701b26"
          alt="Select Actions menu"
          style={{    
        width: "700px",
        height: "auto",
        display: "block",
        margin: "0 auto"
      }}
          width="3378"
          height="1690"
          data-path="images/vmagent/actions/odictl-action-select.png"
        />
      </Step>

      <Step title="Select Span metrics">
        Use the arrow keys to move through the list of action types. When **Span metrics** is highlighted, press `Enter`.

        <img
          src="https://mintcdn.com/odigos/plx_nD0F6Hp-pnSU/images/vmagent/actions/odictl-action-type-span.png?fit=max&auto=format&n=plx_nD0F6Hp-pnSU&q=85&s=e11b06bb2ea2de1f42f31c682cfceb89"
          alt="Select Span metrics action"
          style={{    
        width: "700px",
        height: "auto",
        display: "block",
        margin: "0 auto"
      }}
          width="1912"
          height="1714"
          data-path="images/vmagent/actions/odictl-action-type-span.png"
        />
      </Step>

      <Step title="Configure span metrics">
        1. Press `i` to enter INSERT mode.
        2. Adjust options such as `interval`, `metricsExpiration`, and histogram settings as needed.
        3. When finished, press `Esc`, then type `:wq` to save and exit.

        <img
          src="https://mintcdn.com/odigos/plx_nD0F6Hp-pnSU/images/vmagent/actions/odictl-action-edit-span.png?fit=max&auto=format&n=plx_nD0F6Hp-pnSU&q=85&s=e761d133cf9a0fff1f6de29c207b20e0"
          alt="Configure Span metrics action"
          style={{    
        width: "700px",
        height: "auto",
        display: "block",
        margin: "0 auto"
      }}
          width="1912"
          height="798"
          data-path="images/vmagent/actions/odictl-action-edit-span.png"
        />

        <Note>To cancel creating the action, press `Esc` if you are in INSERT mode, then type `:q!` to exit without saving.</Note>
      </Step>

      <Step title="Complete adding the action">
        Select `OK`. The action appears in the **Actions** section in `odictl`.

        <img
          src="https://mintcdn.com/odigos/plx_nD0F6Hp-pnSU/images/vmagent/actions/odictl-action-span-finish.png?fit=max&auto=format&n=plx_nD0F6Hp-pnSU&q=85&s=6cd61299b538a3cff367ee7d14a8569c"
          alt="Complete adding the action"
          style={{    
        width: "700px",
        height: "auto",
        display: "block",
        margin: "0 auto"
      }}
          width="1214"
          height="340"
          data-path="images/vmagent/actions/odictl-action-span-finish.png"
        />
      </Step>

      <Step title="Verify the action has been created">
        <img
          src="https://mintcdn.com/odigos/plx_nD0F6Hp-pnSU/images/vmagent/actions/odictl-action-span-end.png?fit=max&auto=format&n=plx_nD0F6Hp-pnSU&q=85&s=7f9b890cbbf363514d5a4cc63199cdc5"
          alt="Verify the action has been created"
          style={{    
        width: "700px",
        height: "auto",
        display: "block",
        margin: "0 auto"
      }}
          width="3378"
          height="1690"
          data-path="images/vmagent/actions/odictl-action-span-end.png"
        />
      </Step>
    </Steps>
  </Tab>

  <Tab title="YAML">
    <Steps>
      <Step title="Navigate to the actions configuration folder">
        ```shell theme={null}
        cd /etc/odigos-vmagent/actions.d
        ```
      </Step>

      <Step title="Create an action YAML file">
        Create a YAML file for your action using the editor of your choice. The example below uses [vi](https://en.wikipedia.org/wiki/Vi).

        ```shell theme={null}
        sudo vi span-metrics.yaml
        ```
      </Step>

      <Step title="Add the span metrics configuration">
        Add a span metrics action. You can adjust `interval`, `metricsExpiration`, `additionalDimensions`, and other resource attributes to match your needs.

        For example:

        ```yaml theme={null}
        name: span-metrics
        actionName: span-metrics
        signals:
          - TRACES
          - METRICS
        # pipelines: []  # optional: target specific pipelines
        type: spanMetrics
        config:
          disabled: false
          interval: "60s"
          metricsExpiration: "5m"
          additionalDimensions: []
          histogramDisabled: false
          explicitHistogramBuckets: []
          resourceMetricsKeyAttributes: []
          includedProcessInDimensions: false
          excludedResourceAttributes: []
        ```
      </Step>

      <Step title="Save the file">
        ```shell theme={null}
        :wq!
        ```
      </Step>

      <Step title="Verify the action has been created">
        ```shell theme={null}
        sudo journalctl -u odigos-vmagent | grep 'Action created'
        ```

        ```
        Mar 11 21:59:43 ip-10-0-1-51 odigos-vmagent[611]: time=2026-03-11T21:59:43.580Z level=INFO source=/go/src/github.com/keyval/odigos-vmagent/pkg/components/controller/tower/mutations/create_action_handler.go:41 msg="Action created" name=span-metrics
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>