Configuring ThousandEyes for OpenTelemetry Using the API

This section describes how to create data streams using the ThousandEyes for OpenTelemetry API. For information on creating integrations and data streams using the ThousandEyes application UI, see Configuring ThousandEyes for OpenTelemetry Using the UI

Prerequisites

To use the ThousandEyes API, make sure you meet the following requirements:

• Your user role must have the following permissions:

  • API access permission. The three built-in roles (Organization Admin, Account Admin, and Regular User) include this permission by default.

  • Edit streaming integrations, to view and manage integrations.

  • View streaming integrations, to view details about integrations.

  • Edit labels and View labels, to create and manage tags.

• You must have a user API token generated by the ThousandEyes platform to authenticate your requests. For more details, see the ThousandEyes Developer Reference.

Step 1: Set Up a Network Test

This step is optional. If you have already set up a test to configure your data stream, call the test list endpoint to get a list of tests. Copy the test's testId for use in configuring the data stream. Once you have the testId, proceed to Step 2 or Step 3.

Follow these steps to set up a network test under CEA (Cloud and Enterprise Agents):

1. Check which agents are available:

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

   The response should contain a list of available agents:

   { 
     [
       {
         "agentId": 12345,
         "agentName": "Tests",
         "agentType": "Cloud",
         "countryId": "US",
         "targetOnly": 0,
         "ipAddresses": [
             "128.0.0.1"
         ],
         "location": "San Francisco Area",
         "createdDate": "2023-01-25 22:01:45"
       },
       ...
     ]
   }

2. From the list of available agents, select one Cloud Agent and use its 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": "Opentelemetry Test",
           "server": "www.thousandeyes.com",
           "port": 80,
           "alertsEnabled": 0
       }'

   The response contains a testId field. Set this value aside for use in assigning a tag to this test in subsequent steps.

   {
   "test": [
       {
       "enabled": 1,
       "testId": 987654,
       "testName": "Opentelemetry Test",
       "type": "agent-to-server"
       ...
       }
     ]
   }

Step 2: Set Up Tags (Optional)

Once you’ve set up your test, the next step is to create a tag and assign the tag to the test. This step is necessary if you prefer to associate streams with tests through tags.

Follow these steps to create a tag and assign it to a test:

1. Create a new tag:

   curl -i -XPOST https://api.thousandeyes.com/v7/tags -H "Content-Type: application/json" -H "Authorization: Bearer $BEARER_TOKEN" -d '{
           "key": "TestKey",
           "value": "TestValue",
           "objectType": "test",
           "accessType": "all"
       }'

   The response contains an id attribute. Set this value aside for use in associating your test with this tag.

     {
     "id": "adec2ee7-e5b8-463d-aa54-551d1cb5b368",
     "aid": 67890,
     "objectType": "test",
     "key": "TestKey",
     "value": "TestValue",
     "color": "#A7EB10",
     "accessType": "all",
     "createDate": "2023-03-01T15:28:34Z"
     }

2. Using the tag ID and test ID, send a request to assign the tag to your test. Note that the tag ID is used as part of the path in the request URL:

   curl -i -XPOST https://api.thousandeyes.com/v7/tags/adec2ee7-e5b8-463d-aa54-551d1cb5b368/assign -H "Content-Type: application/json" -H "Authorization: Bearer $BEARER_TOKEN" -d '{
    "assignments": [
      {
        "id": "987654",
        "type": "test"
      }
    ]
   }'

Step 3: Create a Stream

To create a stream, there are two methods:

• Using a test ID

• Using a tag (see Step 2: Set Up Tags).

Select the method that best suits your setup and follow the corresponding instructions below:

Using Test ID

Send a request to the /v7/stream endpoint with the target endpoint details and the CEA (Cloud and Enterprise Agents) test's id and domain, matching the details from step 1:

curl -i -XPOST https://api.thousandeyes.com/v7/stream -H "Content-Type: application/json" -H "Authorization: Bearer $BEARER_TOKEN" -d '{
  "type": "opentelemetry",
  "testMatch": [
      {
        "id": "987654",
        "domain": "cea"
      }
  ],
  "streamEndpointUrl": "https://example.org",
  "customHeaders" : {
    "test": "value"
  }
}'

When you create a stream, the streamEndpointUrl must satisfy the Stream endpoint URL requirements.

testMatch takes a list of items. When the list comprises multiple items the logical operator OR is utilized.

The response contains the details of the created stream:

{
  "id": "79c7f72e-2e10-427d-b3e9-43d0d422ecfe",
  "enabled": true,
  "type": "opentelemetry",
  "signal": "metric",
  "dataModelVersion": "v2",
  "streamEndpointUrl": "https://example.org",
  "testMatch": [
      {
        "id": "987654",
        "domain": "cea"
      }
  ],
  "auditOperation": {
      "createdDate": 1721648143513,
      "createdBy": 84157
  },
  "_links": {
      "self": {
          "href": "https://api.thousandeyes.com/v7/stream/79c7f72e-2e10-427d-b3e9-43d0d422ecfe"
      }
  }
}

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 "Content-Type: application/json" -H "Authorization: Bearer $BEARER_TOKEN" -d '{
  "type": "opentelemetry",
  "tagMatch": [
      {
        "key": "TestKey",
        "value": "TestValue"
      }
  ],
  "streamEndpointUrl": "https://example.org",
  "customHeaders" : {
    "test": "value"
  }
}'

When you create a stream, the streamEndpointUrl must satisfy the Stream endpoint URL requirements.

tagMatch takes a list of items. When the list comprises multiple items The logical operator OR is utilized.

The response contains the details of the created stream:

{
  "id": "79c7f72e-2e10-427d-b3e9-43d0d422ecfe",
  "enabled": true,
  "type": "opentelemetry",
  "signal": "metric",
  "dataModelVersion": "v2",
  "streamEndpointUrl": "https://example.org",
  "tagMatch": [
      {
        "key": "TestKey",
        "value": "TestValue"
      }
  ],
  "auditOperation": {
      "createdDate": 1721648143513,
      "createdBy": 84157
  },
  "_links": {
      "self": {
          "href": "https://api.thousandeyes.com/v7/stream/79c7f72e-2e10-427d-b3e9-43d0d422ecfe"
      }
  }
}