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.