Introduction
This document is intended for customers and prospects who wish to test their connectivity to one of the following destinations:
- Lightstep Observability’s public Microsatellite pool
- Customer-managed on-premise Microsatellite pool
Protocols and formats accepted by Lightstep 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).
Lightstep 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 Lightstep 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
Lightstep 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
2
3
https://<microsatellite_ip>:<microsatellite_port>/traces/otlp/v0.6
or
https://<microsatellite_ip>:<microsatellite_port>/traces/otlp/v0.9
Public Satellites
1
2
3
https://ingest.lightstep.com:443/traces/otlp/v0.6
or
https://ingest.lightstep.com:443/traces/otlp/v0.9
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
2
3
https://<microsatellite_ip>:<microsatellite_port>/traces/otlp/v0.6
or
https://<microsatellite_ip>:<microsatellite_port>/traces/otlp/v0.9
Public Satellites
1
2
3
https://ingest.lightstep.com:443/traces/otlp/v0.6
or
https://ingest.lightstep.com:443/traces/otlp/v0.9
End code tabs
If you are using OTLP v0.5, you must upgrade as Lightstep 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 Lightstep 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"
}
}
]
},
"instrumentationLibrarySpans": [
{
"spans": [
{
"traceId": "71699b6fe85982c7c8995ea3d9c95df2",
"spanId": "3c191d03fa8be065",
"name": "test-span",
"kind": 1,
"droppedAttributesCount": 0,
"events": [],
"droppedEventsCount": 0,
"status": {
"code": 1
}
}
],
"instrumentationLibrary": {
"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 Lightstep Observability by downloading and running the aforementioned tool with your Lightstep 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.