Configuring ThousandEyes for OpenTelemetry
You can create and manage OpenTelemetry (OTel) integrations or data streams using the ThousandEyes Data Streaming API.
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.
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:
- 1.Check which agents are available:curl -i -XGET https://api.thousandeyes.com/v6/agents.json -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 atestId
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"...}]}
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:
- 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"}]}'
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 thestreamEndpointUrl
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"
}
}