Documentation

Lumigo OpenTelemetry Endpoint

The OpenTelemetry Protocol (otlp) is a general-purpose telemetry data delivery protocol developed as part of the OpenTelemetry project. It supports standardized transmission of traces, metrics, and logs.

This guide explains how to configure the OpenTelemetry Protocol to send telemetry data to Lumigo, including supported transports, endpoint details, authorization requirements, and common error troubleshooting.

Supported transports

Lumigo supports the following transport protocol for OTLP:

  • OTLP/HTTP: This protocol can use either protobuf or json encoding.

Supported subsets

Lumigo accepts the following subsets of OTLP data:

  • Traces (/v1/traces)
  • Logs (/v1/logs)
  • Metrics (/v1/metrics)

📘

Note

Although Lumigo accepts metrics, it does not currently support a /v1/metrics endpoint. see Cannot Export Metrics for more details.

Lumigo OpenTelemetry endpoint URL

To send OTLP data to Lumigo, use the following globally available endpoint:

https://ga-otlp.lumigo-tracer-edge.golumigo.com

📘

Note

In most cases, you do not need to add /v1/traces to the URL. In virtually all cases, the OpenTelemetry exporter will append a v1/traces path to the endpoint when exporting tracing data.

Lumigo OpenTelemetry Authorization

To authenticate with Lumigo's OpenTelemetry endpoint, you must provide an Authorization HTTP header as shown below:

Authorization: LumigoToken <token>

Replace <token> with the your Lumigo token, which is available in Settings -> Tracing -> Manual tracing. For further details, see the Lumigo Tokens documentation.\

Security Tip: For enhanced security, store the Lumigo token as an environment variable and reference it in your configuration (e.g., ${LUMIGO_TOKEN}). This prevents sensitive information from being hardcoded in configuration files.

Troubleshooting Lumigo OpenTelemetry Errors

If you encounter issues when exporting telemetry data to Lumigo, use the following guidelines to identify and resolve common errors.

Authorization header is missing

Error:

If your Authorization header is missing, you will receive an HTTP 401 status code with the following message:

The 'Authorization: LumigoToken <token>' header is missing

Solution:

  • Ensure the Authorization header is correctly configured.
  • Confirm that the header is in the following format:
Authorization: LumigoToken <token>
  • Verify that the Lumigo token is valid and correctly referenced in your configuration.

Authorization header is malformed

Error:

If your Authorization header is malformed, you will receive an HTTP 401 status code with the following message:

The value of the 'Authorization' header is invalid; expected a 'LumigoToken <token>' value

Solution:

  • Double-check the format of the Authorization header.
  • Ensure that the header starts with LumigoToken followed by a space and your token, for example:
Authorization: LumigoToken abc123exampletoken
  • Make sure there are no extra spaces or typos in the header value.

Cannot export metrics

Error:

Lumigo does not currently provide a /v1/metrics endpoint. Attempting to export metrics may result in a connection error:

io.opentelemetry.exporter.internal.okhttp.OkHttpExporter - Failed to export metrics. The request could not be executed. Full error message: Failed to connect to https://ga-otlp.lumigo-tracer-edge.golumigo.com:4318/v1/metrics

Solution:

  • Disable the exporting of metrics by setting the following environment variable:
`OTLP_EXPORTER_OTLP_METRICS_ENABLED=false`

Alternatively, you can adjust the OpenTelemetry configuration to exclude metrics from the export pipeline.

Additional Resources

OpenTelemetry Protocol Specification
OpenTelemetry Collector Documentation Lumigo Documentation

If you need further assistance, consult the additional resources or contact Lumigo Support.