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.

• Additional Requirements

  • Ensure the URL target (UI) or Stream Endpoint URL (API) meets the 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
Integration Status	Toggle the integration status to either enable or disable the integration upon creation.
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 - 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.

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: Similarly, 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.

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 -i -XGET https://api.thousandeyes.com/v7/agents -H "Authorization: Bearer $BEARER_TOKEN"

2. Use an agentId to create a test:

   curl -i -XPOST https://api.thousandeyes.com/v6/tests/agent-to-server/new.json -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 to fetch the testId of your existing tests.

   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) or 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:

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

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.

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

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

In the response, inspect the streamStatus object:

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

Next Steps

• Explore some supported obervability and big data platforms.

• Explore advanced configuration options URL Target Requirements.

• Learn about the ThousandEyes for OpenTelemetry Data Model.