Configuring ThousandEyes for OpenTelemetry

You can create and manage OpenTelemetry (OTel) integrations or data streams using the ThousandEyes ThousandEyes for OpenTelemetry API.

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.

Follow these steps to set up a network test:

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"
    },
    ...
  ]
}

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

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, since streams are associated with tests through tags.

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

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"
  }

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, send a request to the /v7/stream endpoint with the target endpoint details and the tag's key and value, matching the details from the previous step:

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",
        "objectType": "test"
      }
  ],
  "streamEndpointUrl": "https://example.org",
  "customHeaders" : {
    "test": "value"
  }
}'

When you create a stream, the streamEndpointUrl must satisfy the following conditions:

For a URL to be a valid streamEndpointUrl, it must be syntactically correct, reachable and use the HTTPS protocol.
When you use the grpc endpointType, streamEndpointUrl cannot contain paths. The following are examples of valid and invalid URLs:
- Valid grpc - https://example.com
- Invalid grpc - https://example.com/collector
When you use the http endpointType, the endpoint must match the exact final full URL (including the path if there is one) to which the metrics will be sent. For example:
- Valid http - https://example.com/collector
The streamEndpointUrl must be reachable from the ThousandEyes platform at the IP addresses below. If the streamEndpointUrl is not reachable, the stream integration service rejects the creation request.
- US region:
  - 52.52.142.26
  - 52.52.36.83
  - 13.56.245.241
  - 52.9.183.148
  - 3.220.243.232
  - 3.221.227.188
  - 3.218.27.195
  - 18.232.232.61
  - 35.168.54.3
  - 107.22.84.44
  - 44.197.76.117
  - 54.224.75.111
  - 54.205.59.175
- EU region:
  - 3.127.8.252
  - 3.70.3.30
  - 18.158.163.183
  - 34.243.129.225
  - 108.128.60.238
  - 46.51.169.205

For more information on streamEndpointUrl, see the schema definition in the developer documentation.

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",
  "type": "opentelemetry",
  "streamEndpointUrl": "https://example.org",
  "tagMatch": [
      {
        "key": "TestKey",
        "value": "TestValue",
        "objectType": "test"
      }
  ],
  "_links": {
    "self": "/v7/stream/79c7f72e-2e10-427d-b3e9-43d0d422ecfe"
  }
}

PreviousThousandEyes for OpenTelemetry NextThousandEyes for OpenTelemetry Metrics

Last updated 1 month ago