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.

• API Authentication Credential

  • Use an API Key or OAuth bearer token with the permissions required to configure streams with the API.

  • For help choosing a credential, see ThousandEyes Developer Documentation: Authentication.

• Additional Requirements

  • Make sure the URL target in the ThousandEyes platform, or the streamEndpointUrl API property, meets the URL Target Requirements.

Configuring OpenTelemetry Using the ThousandEyes Platform

Follow these steps to create and configure an OpenTelemetry stream using the ThousandEyes platform.

Skip Creating a Test if you already have a ThousandEyes test to stream.

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.

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.

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.

ThousandEyes enforces OpenTelemetry attribute naming requirements 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.

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:

curl -i -X GET https://api.thousandeyes.com/v7/agents \
  -H "Authorization: Bearer $BEARER_TOKEN"

Use an agentId to create a test:

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 to retrieve the testId:

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. If you want to use tags to match tests, complete 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:

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:

curl -i -X POST https://api.thousandeyes.com/v7/tags/<tagId>/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:

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:

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.

Tags specified in tagMatch must already exist in your account group. Requests that reference tags not found in the account are rejected.

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

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} endpoint.

In the response, inspect the streamStatus object:

"streamStatus": {
  "lastSuccess": "2024-04-01T15:20:10Z",
  "lastFailure": null,
  "status": "connected"
}

Next Steps

• Explore supported observability and big data platforms.

• Review URL Target Requirements.

• Learn about the ThousandEyes for OpenTelemetry Data Model.

• Learn how tags work with OpenTelemetry streams.