# Getting Started with ThousandEyes for OpenTelemetry This guide explains how to configure ThousandEyes for OpenTelemetry using the UI or the API, including prerequisites and step-by-step instructions. ## Prerequisites Before you begin, ensure the following: * **User Permissions** * *Edit streaming integrations*: Required to configure integrations. * *View streaming integrations*: Required to view existing integrations. * *View/Edit labels*: Required to create and 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. * **API Authentication Token** * Generate a **user API token** if configuring integrations via the API. * For details, see [ThousandEyes Developer Documentation: Authentication](https://developer.cisco.com/docs/thousandeyes/v7/authentication/). * **Additional Requirements** * Ensure the URL target (UI) or Stream Endpoint URL (API) meets the [URL Target Requirements](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/url-target-requirements). ## Configuring OpenTelemetry Using the UI Follow these steps to create and configure an OpenTelemetry stream using the ThousandEyes UI: **Note**: Skip step 1 if you already have a ThousandEyes test created. ### Step 1: Create a Test 1. On the ThousandEyes platform, go to **Network & App Synthetics > Test Settings > Tests** and click **+**. 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. Enter a **Test Name** and **Test Description**. 4. Enter the **URL** of the destination you want to test. 5. Set the test **Interval** to **1 minute**. 6. Select at least one **Agent**. 7. Click **Create New Test** to save and begin running the new page load test immediately. ### Step 2: Create a New Integration 1. In the ThousandEyes platform, go to **Manage > Integrations 1.0**. 2. Click **+ New Integration**. 3. Select **ThousandEyes for OpenTelemetry**. ### Step 3: Fill Out the Configuration Form Complete the following mandatory fields: * **Name**: A unique name for your integration. * **Target Type**: Choose **HTTP** or **GRPC**. * **Target URL**: Enter the integration’s endpoint (e.g., `https://example.com`). * **Integration Status**: Toggle to enable or disable the integration. **Optional Fields**: | **Field** | **Description** | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **OpenTelemetry Signal** | Select how the telemetry data will be sent to the target. | | **Preset Configurations** |

Optional preset configurations provide a starting place for creating your stream integration. If you use a preset configuration, it populates authentication and custom headers with sample content that you can adapt.

Note: These preset configurations serve as a guide, but you should verify that the resulting integration’s structure and variables meet your requirements.

Available Presets: Splunk Observability Cloud, Grafana, Honeycomb, Signoz, Dynatrace, Elastic.

Caution: When you select a preset configuration, the authentication field will be deleted.

| | **Auth Type** |

Set the authentication method for your stream integration:

- Basic (user and password)

- Bearer token

- OAuth Client Credentials

- Custom headers

| | **Custom Headers** |

Contains key/value pairs that make up the integration’s HTTP/gRPC header to a server. The key/value pairs entered here are static (a set key and its set value).

To add a key/value pair, click + New Header and enter the key and value.

To remove a key/value pair, click the - symbol.

| | **Data Model Version** | Determines how the telemetry data is represented in the OTel format. For more information, see[ ThousandEyes for OpenTelemetry Data Model](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model). | ### Step 4: Configure Test Data Configure which data is streamed by selecting the tests and tags associated with your current account group under **Test Data Configuration**: * **Network & App Synthetics Tests:** Select Network & App Synthetics test data that is available in your account group 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 to associate with the integration. Data from Network & App Synthetics tests and Endpoint Experience tests that are tagged with the same tags selected in this dropdown will be streamed to the configured target. {% hint style="info" %} When a stream is configured using 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 tag after the integration is created, those tests are automatically included in the stream. Changes to tag assignments may 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 %} **Note:** ThousandEyes enforces full compliance with [OpenTelemetry attribute naming requirements](https://opentelemetry.io/docs/specs/semconv/general/naming/#recommendations-for-application-developers) for telemetry streams. ### Step 5: Save the Integration 1. Review the configuration. 2. Click **Save** to create the integration. 3. Verify the integration appears in the list with a **Pending** status. The status changes to **Connected** once the integration begins sending data. If there’s an issue, the status changes to **Failing**. ## Configuring OpenTelemetry Using the API Follow these steps to create a stream programmatically using the ThousandEyes API: ### Step 1: Set Up a Test If you haven’t already set up a test, follow these steps: 1. Retrieve available agents: ```curl curl -i -XGET https://api.thousandeyes.com/v7/agents -H "Authorization: Bearer $BEARER_TOKEN" ``` 2. Use an `agentId` to create a test: ```curl curl -i -XPOST https://api.thousandeyes.com/v7/tests/agent-to-server -H "Authorization: Bearer $BEARER_TOKEN" -d '{ "interval": 60, "agents": [{"agentId": 12345}], "testName": "OTel Test", "server": "example.com" }' ``` If you already have a test set up, you can skip the step above and retrieve a list of existing tests: 1. **Retrieve the list of tests**: Use the [test list endpoint](https://developer.cisco.com/docs/thousandeyes/v7/#!list-configured-tests) to fetch the `testId` of your existing tests. ```curl curl -i -XGET https://api.thousandeyes.com/v7/tests -H "Authorization: Bearer $BEARER_TOKEN" ``` 2. **Proceed to step 2 or step 3**: Once you have the required `testId`, proceed directly to [**Step 2: Assign Tags (optional)**](#step-2-assign-tags-to-tests-optional) or [**Step 3: Create a Stream**](#step-3-create-a-stream). ### Step 2: Assign Tags to Tests (Optional) This step only applies when you want to use tags to match tests when creating streams in Step 3. Tags help organize tests and associate them with streams. 1. Create a tag that follows the [OpenTelemetry attribute naming requirements](https://opentelemetry.io/docs/specs/semconv/general/naming/#recommendations-for-application-developers): ````curl curl -i -XPOST https://api.thousandeyes.com/v7/tags -H "Authorization: Bearer $BEARER_TOKEN" -d '{ "key": "exampleTag", "value": "exampleValue", "objectType": "test" }' ``` ```` 2. Assign the tag to a test: ```curl curl -i -XPOST https://api.thousandeyes.com/v7/tags//assign -H "Authorization: Bearer $BEARER_TOKEN" -d '{ "assignments": [{"id": "987654", "type": "test"}] }' ``` ### Step 3: Create a Stream You can create a stream in two ways using the ThousandEyes API: * Using a test ID * Using a tag #### Using Test ID Send a request to the `/v7/stream` endpoint with the target endpoint details and the Network & App Synthetics test's id and domain, matching the details from step 1: ```curl curl -i -XPOST https://api.thousandeyes.com/v7/stream -H "Authorization: Bearer $BEARER_TOKEN" -d '{ "type": "opentelemetry", "testMatch": [{"id": "987654", "domain": "cea"}], "streamEndpointUrl": "https://example.com/collector" }' ``` `testMatch` takes a list of items. When the list comprises multiple items the logical operator `OR` is used. #### Using Tags Send a request to the `/v7/stream` endpoint with the target endpoint details and the tag's key and value, matching the details from [step 2](https://github.com/thousandeyes/docs/blob/prod/product-documentation/integration-guides/opentelemetry/\(/README.md#step-2-assign-tags-to-tests-optional\)): ```curl curl -i -XPOST https://api.thousandeyes.com/v7/stream -H "Authorization: Bearer $BEARER_TOKEN" -d '{ "type": "opentelemetry", "testMatch": [{"tags": ["exampleTag"]}], "streamEndpointUrl": "https://example.com/collector" }' ``` `tagMatch` takes a list of items. When the list comprises multiple items, the logical operator `OR` is used. {% hint style="info" %} * If you have already set up tests and tags, you can directly call step 3 and skip earlier steps. * The `streamEndpointUrl` must meet all target URL requirements. {% endhint %} ## Post-Configuration Checks After configuring the integration, verify that it's working as expected. ### Verify in the ThousandEyes UI 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 ensure authentication headers are correct. ### Verify using the ThousandEyes API You can also check the integration status programmatically by calling the [`GET /v7/stream/{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 some [supported obervability and big data platforms](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/observability-platforms). * Explore advanced configuration options [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). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.