> 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/getting-started.md). # Getting Started with ThousandEyes for OpenTelemetry This article explains how to configure ThousandEyes for OpenTelemetry using the ThousandEyes platform or the API. ## Prerequisites Before you begin, make sure you have the following permissions and configuration details: * **User Permissions** * *Edit streaming integrations*: Required to create or update integrations. * *View streaming integrations*: Required to view existing integrations. * *View tags*: Required to select tags for a stream. * *Edit tags*: Required to create or manage tags. * *View tests*: Required to assign Network & App Synthetics tests to a stream. * *View endpoint tests*: Required to assign Endpoint Experience tests to a stream. * **Endpoint PII permissions**: Required when an integration includes selections under **Endpoint Experience Tests**, tags associated with Endpoint Experience tests under **Tags**, or selections under **Endpoint Experience Tags**. You must have all five permissions: * *View endpoint experience data that identifies Endpoint Agents* * *View endpoint experience data that identifies location* * *View endpoint experience data that identifies network* * *View endpoint experience data that identifies users* * *View endpoint experience data that identifies visited pages* * When you update an existing integration, the Endpoint PII permissions are not required if the resulting configuration contains no selections under **Endpoint Experience Tests**, no tags associated with Endpoint Experience tests under **Tags**, and no selections under **Endpoint Experience Tags**. * For descriptions of these permissions, see [Built-In Roles and Permissions](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control/built-in-roles-and-permissions). * **API Authentication Credential** * Use an [API Key](https://docs.thousandeyes.com/product-documentation/user-management/authorization/api-keys) or [OAuth bearer token](https://docs.thousandeyes.com/product-documentation/user-management/authorization/rb-access-control#user-api-tokens) with the permissions required to configure streams with the API. * For help choosing a credential, see [ThousandEyes Developer Documentation: Authentication](https://developer.cisco.com/docs/thousandeyes/v7/authentication/). * **Additional Requirements** * Make sure the URL target in the ThousandEyes platform, or the `streamEndpointUrl` API property, meets the [URL Target Requirements](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/url-target-requirements). ## Configuring OpenTelemetry Using the ThousandEyes Platform Follow these steps to create and configure an OpenTelemetry stream using the ThousandEyes platform. {% hint style="info" %} Skip [Creating a Test](#creating-a-test) if you already have a ThousandEyes test to stream. {% endhint %} ### Creating a Test 1. In the ThousandEyes platform, go to **Network & App Synthetics > Test Settings > Tests**, and select **+**. If you don't see this button, check that you have permission to create and edit test configurations. 2. Select **Web** as the **Layer** and **Page Load** as the **Test Type**. 3. Type a **Test Name** and **Test Description**. 4. Type the **URL** of the destination you want to test. 5. Set **Interval** to **1 minute**. 6. Select at least one **Agent**. 7. Select **Create New Test** to save and begin running the new page load test. ### Creating a New Integration 1. In the ThousandEyes platform, go to **Manage > Integrations 1.0**. 2. Select **+ New Integration**. 3. Select **ThousandEyes for OpenTelemetry**. ### Completing the Configuration Form Complete the following required fields: * **Name**: A unique name for your integration. * **Target Type**: Select **HTTP** or **gRPC**. * **Target URL**: Type the integration endpoint, such as `https://example.com/collector`. * **Integration Status**: Enable or disable the integration. You can also configure the following optional fields: | Field | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **OpenTelemetry Signal** | Select the type of telemetry data to send to the target. | | **Preset Configurations** | Select a preset configuration to populate authentication and custom header fields with sample content that you can adapt. Available presets include Splunk Observability Cloud, Grafana, Honeycomb, SigNoz, Dynatrace, and Elastic. When you select a preset configuration, existing authentication field values are deleted. | | **Auth Type** | Select the authentication method for your stream integration. Supported methods include basic authentication, bearer token, OAuth client credentials, and custom headers. | | **Custom Headers** | Add static key-value pairs for the integration HTTP or gRPC header. Select **+ New Header** to add a key-value pair, or select **-** to remove one. | | **Data Model Version** | Select how the telemetry data is represented in the OpenTelemetry format. For more information, see [ThousandEyes for OpenTelemetry Data Model](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model). | ### Configuring Test Data Under **Test Data Configuration**, select the tests and tags associated with your current account group: * **Network & App Synthetics Tests**: Select Network & App Synthetics test data to stream to the target. * **Endpoint Experience Tests**: Select Endpoint Experience test data to stream to the target. * **Tags**: Select tags from your current account group. Network & App Synthetics tests and Endpoint Experience tests assigned to the selected tags are streamed to the configured target. * **Local Network Configuration**: For metric streams that use data model V2, select **Endpoint Experience Tags** to stream local network data from the Endpoint Agents associated with those tags. * **Connected Devices Data**: For metric streams that use data model V2, turn on **Enable Connected Devices** to stream all Connected Devices data. Leave it turned off to exclude all Connected Devices data. Currently, Connected Devices does not support individual test or metric selection. * **Filter Configuration**: Optionally exclude specific metrics or attributes from the stream. Available options depend on the selected signal and data model version. For configuration details and supported names, see [Filter Streamed Telemetry](/product-documentation/integration-guides/opentelemetry/filter-streamed-telemetry.md). {% hint style="info" %} When a stream is configured with tags, the set of tests included in the stream is evaluated dynamically. If you assign additional Network & App Synthetics tests or Endpoint Experience tests to a selected tag after the integration is created, those tests are automatically included in the stream. Changes to tag assignments can take a short time to take effect while the system updates its internal cache. You do not need to delete or recreate the integration for new tagged tests to begin streaming. {% endhint %} ThousandEyes enforces [OpenTelemetry attribute naming requirements](https://opentelemetry.io/docs/specs/semconv/general/naming/#recommendations-for-application-developers) for telemetry streams. Tags with non-compliant keys or reserved OpenTelemetry attribute names are not exported as tag attributes. For more information, see [Tags and OpenTelemetry Streams](/product-documentation/integration-guides/opentelemetry/tags-and-opentelemetry-streams.md). ### Saving the Integration 1. Review the configuration. 2. Select **Save** to create the integration. 3. Verify that the integration appears in the list with a **Pending** status. The status changes to **Connected** after the integration begins sending data. If there is an issue, the status changes to **Failing**. ## Configuring OpenTelemetry Using the API Follow these steps to create a stream programmatically using the ThousandEyes API. ### Setting Up a Test If you have not already set up a test, retrieve available agents: ```bash curl -i -X GET https://api.thousandeyes.com/v7/agents \ -H "Authorization: Bearer $BEARER_TOKEN" ``` Use an `agentId` to create a test: ```bash curl -i -X POST https://api.thousandeyes.com/v7/tests/agent-to-server \ -H "Authorization: Bearer $BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "interval": 60, "agents": [{"agentId": 12345}], "testName": "OpenTelemetry Test", "server": "example.com" }' ``` If you already have a test, use the [test list endpoint](https://developer.cisco.com/docs/thousandeyes/list-configured-tests/) to retrieve the `testId`: ```bash curl -i -X GET https://api.thousandeyes.com/v7/tests \ -H "Authorization: Bearer $BEARER_TOKEN" ``` After you have the required `testId`, proceed to [Creating a Stream](#creating-a-stream). If you want to use tags to match tests, complete [Assigning Tags to Tests](#assigning-tags-to-tests) first. ### Assigning Tags to Tests This step applies when you want to use tags to match tests when creating streams. Tags help organize tests and associate them with streams. Create a tag that follows the [OpenTelemetry attribute naming requirements](https://opentelemetry.io/docs/specs/semconv/general/naming/#recommendations-for-application-developers): ```bash curl -i -X POST https://api.thousandeyes.com/v7/tags \ -H "Authorization: Bearer $BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "key": "exampleTag", "value": "exampleValue", "objectType": "test" }' ``` Use the returned tag ID when you create the stream. Assign the tag to a test: ```bash curl -i -X POST https://api.thousandeyes.com/v7/tags//assign \ -H "Authorization: Bearer $BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "assignments": [{"id": "987654", "type": "test"}] }' ``` ### Creating a Stream You can create a stream using test IDs or tags. #### Using a Test ID Send a request to the `/v7/streams` endpoint with the target endpoint details and the Network & App Synthetics test ID and domain: ```bash curl -i -X POST https://api.thousandeyes.com/v7/streams \ -H "Authorization: Bearer $BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "opentelemetry", "endpointType": "http", "testMatch": [{"id": "987654", "domain": "cea"}], "streamEndpointUrl": "https://example.com/collector" }' ``` `testMatch` takes a list of items. When the list includes multiple items, the logical operator `OR` is used. #### Using Tags Send a request to the `/v7/streams` endpoint with the target endpoint details and the tag ID: ```bash curl -i -X POST https://api.thousandeyes.com/v7/streams \ -H "Authorization: Bearer $BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "opentelemetry", "endpointType": "http", "tagMatch": [{"tagId": "c6b78e57-81a2-4c5f-a11a-d96c3c664d55"}], "streamEndpointUrl": "https://example.com/collector" }' ``` `tagMatch` takes a list of items. For new requests, use `tagId`. For backward compatibility, the API can resolve a `key` and `value` pair to a tag ID, but use only one representation in each `tagMatch` collection. When the list includes multiple items, the logical operator `OR` is used. `tagMatch` controls which tests are included in the stream. It does not limit which supported tags are exported as OpenTelemetry resource attributes. {% hint style="warning" %} Tags specified in `tagMatch` must already exist in your account group. Requests that reference tags not found in the account are rejected. {% endhint %} {% hint style="info" %} * If you have already set up tests and tags, you can create the stream directly and skip earlier steps. * The `streamEndpointUrl` must meet all target URL requirements. * For Endpoint Experience local network data, use `endpointAgentTag` or `endpointAgentLabel` instead of `tagMatch`. {% endhint %} ## Post-Configuration Checks After configuring the integration, verify that it works as expected. ### Verifying in the ThousandEyes Platform 1. In the ThousandEyes platform, go to **Manage > Integrations > Integrations 1.0**. 2. Locate your configured integration and check its status. The possible status values are: * **Connected**: Data is actively being sent to the target. * **Pending**: The integration has been created but is not yet sending data. * **Failing**: Data could not be sent to the target. If the status is **Failing**, review the stream configuration, verify network access to the target endpoint, and make sure authentication headers are correct. ### Verifying Using the ThousandEyes API You can also check the integration status programmatically by calling the [`GET /v7/streams/{id}`](https://developer.cisco.com/docs/thousandeyes/retrieve-data-stream/) endpoint. In the response, inspect the `streamStatus` object: ```json "streamStatus": { "lastSuccess": "2024-04-01T15:20:10Z", "lastFailure": null, "status": "connected" } ``` ## Next Steps * Explore [supported observability and big data platforms](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/observability-platforms). * Review [URL Target Requirements](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/url-target-requirements). * Learn about the [ThousandEyes for OpenTelemetry Data Model](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model). * Learn how [tags work with OpenTelemetry streams](/product-documentation/integration-guides/opentelemetry/tags-and-opentelemetry-streams.md).