> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/traces.md).

# ThousandEyes for OpenTelemetry Data Model v2 - Traces

Trace support depends on the test type and configuration:

* **HAR application traces:** Page load, web transaction, and API tests export application trace data based on HTTP Archive (HAR).
* **Network Path traces:** Agent-to-server and agent-to-agent tests export Network Path trace data. For HTTP server, page load, web transaction, API, FTP server, DNS server, SIP server, and RTP stream tests, enable **Perform Network Measurements** to collect [Path Visualization](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/path-visualization) data for export as Network Path traces.

## HAR Application Traces

### Supported Test Types

#### Network & App Synthetics Tests

{% hint style="info" %}
In the context of this page, a layer refers to the specific category of trace data generated by a ThousandEyes test that is available for export through OpenTelemetry.
{% endhint %}

HAR application traces are supported for page load, web transaction, and API tests. Web transaction tests use the `transaction` layer. Page load and API tests use the `page-load` and `API` layers, respectively.

### HAR Attributes by Test Type

| **Test type**   | **Resource attributes**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | **Span attributes**                                                                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page load       | <ul><li><code>service.name</code></li><li><code>thousandeyes.account.id</code></li><li><code>thousandeyes.data.version</code></li><li><code>thousandeyes.permalink</code></li><li><code>thousandeyes.source.agent.id</code></li><li><code>thousandeyes.source.agent.location</code></li><li><code>thousandeyes.source.agent.name</code></li><li><code>thousandeyes.source.agent.geoname.id</code></li><li><code>thousandeyes.source.agent.geo.region.iso\_code</code></li><li><code>thousandeyes.source.agent.geo.country.iso\_code</code></li><li><code>thousandeyes.stream.id</code></li><li><code>thousandeyes.stream.name</code></li><li><code>thousandeyes.test.domain</code></li><li><code>thousandeyes.test.id</code></li><li><code>thousandeyes.test.name</code></li><li><code>thousandeyes.test.type</code></li></ul> | <ul><li><code>http.request.method</code></li><li><code>http.response.code</code></li><li><code>server.address</code></li><li><code>server.port</code></li><li><code>url.full</code></li></ul>                           |
| Web transaction | <ul><li><code>service.name</code></li><li><code>thousandeyes.account.id</code></li><li><code>thousandeyes.data.version</code></li><li><code>thousandeyes.permalink</code></li><li><code>thousandeyes.source.agent.id</code></li><li><code>thousandeyes.source.agent.location</code></li><li><code>thousandeyes.source.agent.name</code></li><li><code>thousandeyes.source.agent.geoname.id</code></li><li><code>thousandeyes.source.agent.geo.region.iso\_code</code></li><li><code>thousandeyes.source.agent.geo.country.iso\_code</code></li><li><code>thousandeyes.stream.id</code></li><li><code>thousandeyes.stream.name</code></li><li><code>thousandeyes.test.domain</code></li><li><code>thousandeyes.test.id</code></li><li><code>thousandeyes.test.name</code></li><li><code>thousandeyes.test.type</code></li></ul> | <ul><li><code>http.request.method</code></li><li><code>http.response.code</code></li><li><code>server.address</code></li><li><code>server.port</code></li><li><code>url.full</code></li></ul>                           |
| API             | <ul><li><code>service.name</code></li><li><code>thousandeyes.account.id</code></li><li><code>thousandeyes.data.version</code></li><li><code>thousandeyes.permalink</code></li><li><code>thousandeyes.source.agent.id</code></li><li><code>thousandeyes.source.agent.location</code></li><li><code>thousandeyes.source.agent.name</code></li><li><code>thousandeyes.source.agent.geoname.id</code></li><li><code>thousandeyes.source.agent.geo.region.iso\_code</code></li><li><code>thousandeyes.source.agent.geo.country.iso\_code</code></li><li><code>thousandeyes.stream.id</code></li><li><code>thousandeyes.stream.name</code></li><li><code>thousandeyes.test.domain</code></li><li><code>thousandeyes.test.id</code></li><li><code>thousandeyes.test.name</code></li><li><code>thousandeyes.test.type</code></li></ul> | <ul><li><code>http.request.method</code></li><li><code>http.response.code</code></li><li><code>server.address</code></li><li><code>server.port</code></li><li><code>url.full</code></li><li><code>step</code></li></ul> |

### HAR Resource Attributes

| **Attribute**                                    | **Type** | **Description**                                                                                                                                    |
| ------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `service.name`                                   | String   | Name of the service                                                                                                                                |
| `thousandeyes.account.id`                        | String   | The ID of the account that the telemetry data is associated with.                                                                                  |
| `thousandeyes.data.version`                      | String   | <p>Specifies the version of the data model. Possible values:</p><ul><li><code>v1</code></li><li><code>v2</code></li></ul>                          |
| `thousandeyes.permalink`                         | String   | ThousandEyes test permalink                                                                                                                        |
| `thousandeyes.source.agent.id`                   | String   | Identifies the ThousandEyes agent that ran the test                                                                                                |
| `thousandeyes.source.agent.location`             | String   | Location of the ThousandEyes source agent                                                                                                          |
| `thousandeyes.source.agent.name`                 | String   | Name of the ThousandEyes source agent                                                                                                              |
| `thousandeyes.source.agent.geoname.id`           | String   | The GeoNames ID of the ThousandEyes source agent that ran the test. For more information, see \[GeoNames]\(<https://www.geonames.org/about.html>). |
| `thousandeyes.source.agent.geo.region.iso_code`  | String   | ISO code for the region where the source agent is located.                                                                                         |
| `thousandeyes.source.agent.geo.country.iso_code` | String   | ISO code for the country where the source agent is located.                                                                                        |
| `thousandeyes.stream.id`                         | String   | UUID of the integration used to export the data.                                                                                                   |
| `thousandeyes.stream.name`                       | String   | Name of the integration used to export the data. This attribute changes when you rename the integration.                                           |
| `thousandeyes.test.domain`                       | String   | Identifies the origin of the test data. Possible values: `cea` (Network & App Synthetics)                                                          |
| `thousandeyes.test.id`                           | String   | Identifies the ThousandEyes test                                                                                                                   |
| `thousandeyes.test.name`                         | String   | Name of the ThousandEyes test                                                                                                                      |
| `thousandeyes.test.type`                         | String   | Identifies the type of test. Possible values: `"page-load"`, `"web-transactions"`, `"api"`                                                         |

### HAR Span Attributes

| **Attribute**         | **Type** | **Description**                                                                                                                                                                                                                                                   |
| --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `http.request.method` | String   | <p>HTTP request method. Enum:</p><ul><li><code>GET</code></li><li><code>POST</code></li><li><code>HEAD</code></li><li><code>PUT</code></li><li><code>DELETE</code></li><li><code>OPTIONS</code></li><li><code>PATCH</code></li><li><code>CONNECT</code></li></ul> |
| `http.response.code`  | Integer  | HTTP response code                                                                                                                                                                                                                                                |
| `server.address`      | String   | Server address                                                                                                                                                                                                                                                    |
| `server.port`         | Integer  | Server port                                                                                                                                                                                                                                                       |
| `url.full`            | String   | Full URL of the request                                                                                                                                                                                                                                           |
| `step`                | Integer  | Step ID for API tests. Identifies individual steps in multi-step API test sequences.                                                                                                                                                                              |

For a representative HAR payload, see [OpenTelemetry Collector Data v2 Trace Examples](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/traces/data-format).

## Network Path Traces

### Supported Tests

Network Path traces are supported for the following tests:

* Agent-to-server and agent-to-agent tests.
* HTTP server, page load, web transaction, API, FTP server, DNS server, SIP server, and RTP stream tests when **Perform Network Measurements** is enabled.

### Trace Structure and Timing

Network Path traces model the route from a source agent to a target as a topology. They use the following span hierarchy:

```
ThousandEyes test task [INTERNAL]
└── network path attempt observed [INTERNAL]
    └── network path edge to <receiving node> [CLIENT]
        └── network path edge from <sending node> [SERVER]
            └── next topology edge, if present
```

* ThousandEyes creates one `ThousandEyes test task` root span for each test datapoint. It uses the measured task interval and the source agent resource. If the task end time is unavailable or precedes the start time, the root span is a point observation at the task start time.
* Each path attempt produces a `network path attempt observed` child span.
* Each normalized topology edge produces a client and server span pair. The first client span is a child of the attempt span. For a multi-hop path, each subsequent client span is a child of the preceding server span.
* The client span resource represents the sending node. Its `network.local.*` attributes describe the sender and its `network.peer.*` attributes describe the receiver.
* The server span resource represents the receiving node. Its endpoint roles are reversed, so `network.local.*` describes the receiver and `network.peer.*` describes the sender.

The attempt and edge spans are point observations at the task end time, so their start and end timestamps are equal. Span duration does not represent link latency. On each edge pair, `network.path.hop.index` identifies the receiving hop, and `network.path.hop.rtt` reports the round-trip time (RTT) in milliseconds from the source agent to that hop. If the test does not report an RTT, the span omits this attribute.

Network Path traces currently include topology and source-to-hop RTT. They do not include Forward Loss or Link Delay from Path Visualization.

When a path does not reach its destination, the attempt span has error status with `error.type` set to `destination_not_reached`. If the trace includes a dropped destination edge, that edge has error status with `error.type` set to `lost`. Unknown intermediate nodes use a generated service name such as `unknown hop 3`.

Network Path spans use the `thousandeyes.network.path.model` instrumentation scope with version `1.0`. Some observability platforms display these scope fields as `otel.scope.name` and `otel.scope.version`.

### Enabling Network Path Trace Input

Create or edit an OpenTelemetry trace integration and select **Data Sources > Network Path**. A trace stream can export HAR application trace data, Network Path data, or both.

To enable Network Path input using the API, set `signal` to `trace`, `dataModelVersion` to `v2`, and `inputConfig.trace.netpath.enabled` to `true`:

```json
{
  "signal": "trace",
  "dataModelVersion": "v2",
  "inputConfig": {
    "trace": {
      "netpath": {
        "enabled": true
      }
    }
  }
}
```

This example enables Network Path input only. When you include `inputConfig`, explicitly enable each trace source that you want to export. Omitted trace sources are disabled, and at least one trace source must be enabled.

If you omit `inputConfig` when creating a trace integration, HAR trace input is enabled by default and Network Path input is disabled. For the complete request schema, see the [ThousandEyes for OpenTelemetry API](https://developer.cisco.com/docs/thousandeyes/thousandeyes-for-opentelemetry-api-overview/).

### Network Path Resource Attributes

The resource attached to a Network Path span identifies the node represented by that span and retains the shared stream, account, test, and source-agent context.

| Attribute                                        | Type   | Description                                                                                 |
| ------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------- |
| `server.address`                                 | String | Target server address for the test. This attribute is included on source-node resources.    |
| `service.name`                                   | String | Source agent, intermediate hop, or destination represented by the resource.                 |
| `thousandeyes.account.id`                        | String | Account associated with the telemetry data.                                                 |
| `thousandeyes.data.version`                      | String | Data model version. The value is `v2`.                                                      |
| `thousandeyes.permalink`                         | String | Link to the ThousandEyes test view.                                                         |
| `thousandeyes.source.agent.geo.country.iso_code` | String | Country ISO code for the source agent.                                                      |
| `thousandeyes.source.agent.geo.region.iso_code`  | String | Region ISO code for the source agent.                                                       |
| `thousandeyes.source.agent.geoname.id`           | String | GeoNames ID for the source agent.                                                           |
| `thousandeyes.source.agent.id`                   | String | ID of the source agent that ran the test.                                                   |
| `thousandeyes.source.agent.location`             | String | Location of the source agent.                                                               |
| `thousandeyes.source.agent.name`                 | String | Name of the source agent.                                                                   |
| `thousandeyes.source.agent.network.address`      | String | Public IP address of the source agent. This attribute is included on source-node resources. |
| `thousandeyes.stream.id`                         | String | UUID of the integration that routed the datapoint.                                          |
| `thousandeyes.stream.name`                       | String | Name of the integration that exported the datapoint.                                        |
| `thousandeyes.test.domain`                       | String | Origin of the test data. The value is `cea`.                                                |
| `thousandeyes.test.id`                           | String | ID of the ThousandEyes test.                                                                |
| `thousandeyes.test.name`                         | String | Name of the ThousandEyes test.                                                              |
| `thousandeyes.test.type`                         | String | Type of the ThousandEyes test.                                                              |

### Network Path Span Attributes

Network Path spans can include the following attributes. Endpoint and topology attributes apply to edge spans. Attributes for unavailable endpoint metadata are omitted.

| Attribute                 | Type    | Description                                           |
| ------------------------- | ------- | ----------------------------------------------------- |
| `cloud.availability_zone` | String  | Cloud availability zone for the peer endpoint.        |
| `cloud.platform`          | String  | Cloud platform for the peer endpoint.                 |
| `cloud.provider`          | String  | Cloud provider for the peer endpoint.                 |
| `cloud.region`            | String  | Cloud region for the peer endpoint.                   |
| `cloud.service`           | String  | Cloud service type for the peer endpoint.             |
| `error.type`              | String  | Error class for a failed root, attempt, or edge span. |
| `geo.geoname.id`          | String  | GeoNames ID for the peer endpoint.                    |
| `network.local.address`   | String  | IP address of the local endpoint.                     |
| `network.local.hostname`  | String  | Reverse DNS hostname of the local endpoint.           |
| `network.local.prefix`    | String  | CIDR prefix of the local endpoint.                    |
| `network.path.hop.index`  | Integer | Hop index of the receiving node for the edge.         |
| `network.peer.address`    | String  | IP address of the peer endpoint.                      |
| `network.peer.prefix`     | String  | CIDR prefix of the peer endpoint.                     |
| `network.peer.as.number`  | Integer | Autonomous system number of the peer endpoint.        |
| `network.peer.hostname`   | String  | Reverse DNS hostname of the peer endpoint.            |
| `network.path.hop.rtt`    | Integer | Source-to-receiving-hop RTT in milliseconds.          |

For a representative Network Path payload, see [OpenTelemetry Collector Data v2 Trace Examples](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/traces/data-format).

## Shared Trace Concepts

The following span fields and resource attribute behavior apply to HAR application traces and Network Path traces.

### Span Fields

The field names use the OpenTelemetry Protocol (OTLP) protobuf representation. The following table lists the span fields used by HAR application and Network Path traces and identifies optional fields:

| **Field**                   | **Type**                                                                                                                                                                       | **Description**                                                                                                                                                                                                                                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trace_id`                  | String                                                                                                                                                                         | Trace ID representing the trace that the span is a part of                                                                                                                                                                                                                                                                              |
| `span_id`                   | String                                                                                                                                                                         | Span ID representing the span                                                                                                                                                                                                                                                                                                           |
| `parent_span_id` (optional) | String                                                                                                                                                                         | Parent span ID representing the parent span of the current span                                                                                                                                                                                                                                                                         |
| `name`                      | String                                                                                                                                                                         | Name of the span                                                                                                                                                                                                                                                                                                                        |
| `kind`                      | Enum                                                                                                                                                                           | <p>Kind of span. Enum:</p><ul><li><code>SPAN\_KIND\_UNSPECIFIED</code></li><li><code>SPAN\_KIND\_INTERNAL</code></li><li><code>SPAN\_KIND\_SERVER</code></li><li><code>SPAN\_KIND\_CLIENT</code></li><li><code>SPAN\_KIND\_PRODUCER</code></li><li><code>SPAN\_KIND\_CONSUMER</code></li></ul>                                          |
| `start_time_unix_nano`      | Integer                                                                                                                                                                        | The start time of the span, expressed in the number of nanoseconds since the Unix epoch                                                                                                                                                                                                                                                 |
| `end_time_unix_nano`        | Integer                                                                                                                                                                        | The end time of the span, expressed in the number of nanoseconds since the Unix epoch                                                                                                                                                                                                                                                   |
| `status` (optional)         | <p>Possible values for <code>code</code>:</p><ul><li><code>STATUS\_CODE\_UNSET</code></li><li><code>STATUS\_CODE\_OK</code></li><li><code>STATUS\_CODE\_ERROR</code></li></ul> | <p>Optional span status. If omitted, the status is equivalent to <code>STATUS\_CODE\_UNSET</code>. When present, status contains the following properties:</p><ul><li><code>code</code>: One of the status codes in the Type column.</li><li><code>message</code>: Optional description for <code>STATUS\_CODE\_ERROR</code>.</li></ul> |

For more information on the OpenTelemetry data model, see the [OpenTelemetry specification](https://opentelemetry.io/docs/concepts/signals/traces/#span-status).

### Tags as Attributes

ThousandEyes converts [tags](https://developer.cisco.com/docs/thousandeyes/list-tags/) from tests and associated Cloud and Enterprise Agents into OpenTelemetry `Resource` attributes. Each tag consists of a `key` and a corresponding `value`.

If a stream uses `tagMatch`, `tagMatch` selects which tests are included in the stream. It does not limit which supported tags are converted to attributes.

Tags are streamed as attributes unless the tag key is not compliant with the [OpenTelemetry naming conventions for attributes](https://opentelemetry.io/docs/specs/semconv/general/naming/#recommendations-for-application-developers) or matches a ThousandEyes reserved OpenTelemetry attribute name. ThousandEyes excludes those tags from the `Resource` attributes.

When a tag is converted to an attribute, the tag key becomes the attribute name. Some tags might have multiple values or be shared between tests and agents. These cases are handled as follows:

* **Single value**: If a tag key has only one value, the value is represented as `string_value`.
* **Multiple values**: If there are several values for the same key, the value is represented as `array_value`, with each associated value as a `string_value` element.
* **Shared tags**: If tests and Cloud or Enterprise Agents are assigned to the same tag, the unique set of values is provided as the attribute value.

For more information, see [Tags and OpenTelemetry Streams](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/tags-and-opentelemetry-streams.md).

#### Example

Consider the following scenario:

* A stream is configured with test `1234` and the following tags:
  * `branch:sfo`
  * `branch:nyc`
  * `team:netops`
* The following tags are associated with test `1234`:
  * `branch:sfo`
  * `branch:nyc`
  * `team:netops`
  * `cluster:analytics`
* The following tags are associated with the source agent used by test `1234`:
  * `branch:sfo`
  * `location:us`

The resulting attributes would be structured as follows:

```
{
  resource_spans {
    resource {
      attributes {
        key: "branch"
        value {
          array_value: {
            values: [
              {
                string_value: "sfo"
              },
              {
                string_value: "nyc"
              }
            ]
          }
        }
      }
      attributes {
        key: "team"
        value {
          string_value: "netops"
        }
      }
      attributes {
        key: "cluster"
        value {
          string_value: "analytics"
        }
      }
      attributes {
        key: "location"
        value {
          string_value: "us"
        }
      }
    }
  }
}
```

The `branch:sfo` tag is not added twice to the `Resource` because the key-value pair already exists in the attributes.

{% hint style="info" %}
Not all observability platforms support string arrays for attribute values. For example, New Relic and Splunk Observability Cloud do not support this format. If your backend does not support string arrays for attributes, the tag attribute or the data point might be excluded.
{% endhint %}
