Connect Lantern.

Before you begin

Using the hosted service requires no local database, Docker, Node.js or Go toolchain. The optional local MCP bridge, for clients without remote MCP support, needs Go 1.26.10 to build. Lantern’s server dependencies are Go, GreptimeDB and PostgreSQL; this guide connects to the hosted service rather than deploying that stack.

1. Get your endpoint and keys

Both origins use HTTPS through Cloudflare. Use OTLP/HTTP Protobuf (application/x-protobuf); gzip is supported. The public ingestion endpoint does not accept OTLP/gRPC or OTLP/JSON.

Read and ingestion keys are different credentials. An account password or browser session cookie is not an exporter key. Inject only the key each process needs, using your local secret manager or deployment secret store. Never commit token values or send them in chat, URLs or screenshots.

2a. Export from an existing SDK

Use this path when your application already initializes OpenTelemetry with an OTLP HTTP exporter. These variables configure a compatible exporter; they do not install instrumentation or start an SDK.

# First inject OBSERVABILITY_INGEST_TOKEN locally from your secret store.
# Do not paste its value into this command or into chat.
export OTEL_SERVICE_NAME="checkout-api"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.lanternstack.sh"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${OBSERVABILITY_INGEST_TOKEN}"
export OTEL_EXPORTER_OTLP_COMPRESSION="gzip"

The generic endpoint is a base URL: an SDK following the OTLP exporter specification appends /v1/traces, /v1/metrics or /v1/logs. A signal-specific setting such as OTEL_EXPORTER_OTLP_TRACES_ENDPOINT must include the full /v1/traces path. Existing signal-specific variables can override the generic ones.

The header string uses URL-encoded space (%20) in Bearer%20. If your SDK configures headers in code, supply the actual header value Bearer followed by the injected key. Check your language exporter’s support for environment configuration and compression. OTLP exporter specification →

Apply the environment to the service process and restart or reload it through your normal deployment procedure. Confirm its trace exporter, metric reader and log bridge are enabled for the signals you intend to send. Plain stdout logs are not exported automatically.

2b. Export from a Collector

Use this path when applications already send telemetry to an OpenTelemetry Collector. Add a named exporter to its existing configuration:

exporters:
  otlp_http/lantern:
    endpoint: https://ingest.lanternstack.sh
    encoding: proto
    compression: gzip
    headers:
      Authorization: "Bearer ${env:OBSERVABILITY_INGEST_TOKEN}"
    retry_on_failure:
      enabled: true
    sending_queue:
      enabled: true

Securely inject OBSERVABILITY_INGEST_TOKEN into the Collector’s environment. Append otlp_http/lantern to the exporter list of each selected trace, metric or log pipeline. Preserve its receivers, processors and existing exporters. This fragment is not a replacement for your complete configuration.

Current Collector releases use otlp_http; older distributions may use otlphttp. Use the component name supported by your exact installed version. Official HTTP exporter configuration →

# Substitute your installed Collector binary and actual merged file.
otelcol-contrib validate --config=/path/to/merged-collector.yaml

Validate with that installed binary before reloading. Test the new export branch on one service first and inspect its queue, retries and delivery errors. The default in-memory queue is lost on process restart; durable queues require the file_storage extension and a persistent, writable volume.

Lantern currently bounds both compressed and decompressed request bodies to 4 MiB. Keep batches below that byte limit; a span-count setting alone cannot bound large attributes or log bodies. Retry queues do not guarantee lossless delivery.

3. Verify real data

1. Send one recognizable request to the instrumented service. Note its approximate time and, if available, its trace ID.
2. Check SDK or Collector diagnostics for successful export. Resolve authentication, TLS, payload or retry errors.
3. With MCP connected, ask your agent to call setup_status. It lists each service sending traces, logs or metrics in the last 15 minutes, and any batches Lantern refused with the reason and fix. Then use stream_spans in a recent window to find your known request.
4. Have your agent inspect that request with get_trace. Check its operation, attributes, duration and parent links. Discover and verify each separately configured metric or log signal too.

Prefer a visual check? Open Lantern and use Stream, Query or the trace view with a recent time range. The dashboard is optional for the MCP path.

A successful ingestion response proves acceptance of that batch, not full instrumentation coverage. Check a known request end to end before enabling more services. MCP verification is a separate step in the MCP guide.

If telemetry does not appear

Next, learn how to read spans or connect your AI assistant.