Introduction
This document is intended for customers and prospects who wish to test their connectivity to one of the following destinations:
- Cloud Observability’s public Microsatellite pool
- Customer-managed on-premise Microsatellite pool
Protocols and formats accepted by Cloud Observability Microsatellites
Both public and on-premise Microsatellites accept telemetry data via the following reporting mechanisms:
- Protocol buffers over HTTP
- Protocol buffers over gRPC (HTTP/2)
- JSON over HTTP
- Thrift over HTTP
Support for Thrift over HTTP will be deprecated!
This document will focus on testing connectivity to public and on-premise Microsatellite pools over both HTTP and gRPC (HTTP/2).
Cloud Observability Microsatellite endpoints
The public Microsatellite pool’s gRPC endpoint for both trace and metric ingest is ingest.lightstep.com:443.
The public Microsatellite pool has a number of versioned HTTP endpoints, listed here.
All of Cloud Observability’s ingestion endpoints are encrypted with TLS.
On-premise Microsatellites follow the same endpoint scheme. Replace ingest.lightstep.com:443 with the IP address/hostname and port of your on-premise Microsatellite in order to determine its gRPC and HTTP ingestion points.
Test connectivity to a public or on-premise Microsatellite
The remainder of this document will focus primarily on testing connectivity for trace ingest purposes.
Testing the HTTP ingest path
Cloud Observability OTLP/HTTP endpoints for trace ingest are as follows:
Trace ingest endpoints
Endpoints accepting application/x-protobuf
- OTLP versions v0.5 - v0.9:
Start tabs
On-Premise Satellites
1
https://<microsatellite_ip>:<microsatellite_port>/v1/traces
Public Satellites
1
https://ingest.lightstep.com:443/v1/traces
End code tabs
Endpoints accepting application/json
- OTLP version v0.5:
Start tabs
On-Premise Satellites
1
https://<microsatellite_ip>:<microsatellite_port>/api/v2/otel/trace
Public Satellites
1
https://ingest.lightstep.com:443/api/v2/otel/trace
End code tabs
- OTLP versions v0.6 and above:
Start tabs
On-Premise Satellites
1
https://<microsatellite_ip>:<microsatellite_port>/v1/traces
Public Satellites
1
2
3
https://ingest.lightstep.com:443/traces/otlp/v0.6
or
https://ingest.lightstep.com:443/v1/traces
End code tabs
If you are using OTLP v0.5, you must upgrade as Cloud Observability support for v0.5 will be deprecated!
For on-premise Microsatellites, replace ingest.lightstep.com:443 with the Microsatellite’s IP address/hostname and port number.
In order to test connectivity to a public or on-premise Microsatellite via its HTTP ingestion points, you will need to use a command-line utility such as curl, and you will need your Cloud Observability access token in order to authenticate the request.
While using the following protobuf JSON payload, small_data.json, to represent a test span, run the following curl command to test overall connectivity to the public Microsatellite pool:
small_data.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
{
"resourceSpans": [
{
"resource": {
"attributes": [
{
"key": "service.name",
"value": {
"stringValue": "curl-test-otel-pipeline"
}
}
]
},
"scopeSpans": [
{
"spans": [
{
"traceId": "71699b6fe85982c7c8995ea3d9c95df2",
"spanId": "3c191d03fa8be065",
"name": "test-span",
"kind": 1,
"droppedAttributesCount": 0,
"events": [],
"droppedEventsCount": 0,
"status": {
"code": 1
}
}
],
"scope": {
"name": "local-curl-example"
}
}
]
}
]
}
Start tabs
curl to public Microsatellite pool
1
2
3
curl -ivL -H "Lightstep-Access-Token: <LIGHTSTEP_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
https://ingest.lightstep.com/traces/otlp/v0.9 -d @small_data.json
End code tabs
To test connectivity to an on-premise Microsatellite, run a curl command similar to the following:
Start tabs
curl to on-premise Microsatellite pool
1
2
3
curl -ivL -H "Lightstep-Access-Token: <LIGHTSTEP_ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
http://{Microsatellite_ip}:{port_number}/traces/otlp/v0.9 -d @small_data.json
End code tabs
A successful request against either type of Microsatellite should receive a 200 HTTP response, and a successful response will include a receive and transmit timestamp:
{"receiveTimestamp":"2022-04-29T03:57:33.827317232Z","transmitTimestamp":"2022-04-29T03:57:33.864646841Z"}
An HTTP response code of 400 Bad Request indicates either an issue with the access token in use, or a problem with the payload sent to the public Microsatellite pool.
If you receive an HTTP response indicating a request timeout, verify that a web proxy or firewall is not intercepting the traffic destined for the Microsatellite.
Testing the gRPC ingest path
Testing against a public or on-premise Microsatellite pool’s gRPC ingest path requires a tool called grpcurl, available here. You can ensure that you have a direct connection to Cloud Observability by downloading and running the aforementioned tool with your Cloud Observability access token for authentication:
grpcurl -H 'lightstep-access-token:{LS_ACCESS_TOKEN}' ingest.lightstep.com:443 list
You should receive a response listing the RPCs in use by the server:
1
2
3
4
5
6
7
$ grpcurl -H 'lightstep-access-token:{LS_ACCESS_TOKEN}' ingest.lightstep.com:443 list
grpc.reflection.v1alpha.ServerReflection
jaeger.api_v2.CollectorService
lightstep.collector.CollectorService
lightstep.egress.CollectorService
opentelemetry.proto.collector.trace.v1.TraceService
You can run grpcurl against an on-premise Microsatellite and expect a similar response:
1
2
3
4
5
6
7
$ grpcurl -H 'lightstep-access-token:{LS_ACCESS_TOKEN}' {Microsatellite_ip}:{grpc_port} list
grpc.reflection.v1alpha.ServerReflection
jaeger.api_v2.CollectorService
lightstep.collector.CollectorService
lightstep.egress.CollectorService
opentelemetry.proto.collector.trace.v1.TraceService
If you receive any errors such as:
Failed to dial target host "ingest.lightstep.com:443": context deadline exceeded
or
Failed to dial target host "ingest.lightstep.com:443": read tcp 192.168.95.2:37948->35.222.219.106:443: read: connection reset by peer
verify that there are no proxies or firewalls in the environment that might be blocking direct access via gRPC to the Microsatellite pool in question.
See also
Verify and test Microsatellite setup
Updated May 4, 2022