Skip to main content

OpenTelemetry (OTLP)

The Conversion Service supports OpenTelemetry, an open standard for exporting traces, logs, and metrics to observability backends such as Grafana, Datadog, Jaeger, or Seq.

Configuration​

To enable OpenTelemetry, set environment variables on the host machine (Windows) or in the container configuration (Docker).

Environment variables​

VariableDescriptionExample
OTEL_EXPORTER_OTLP_ENDPOINTOpenTelemetry Protocol (OTLP) collector endpoint (required)http://localhost:4317
OTEL_EXPORTER_OTLP_PROTOCOLExport protocol: grpc (default) or http/protobufgrpc
OTEL_SERVICE_NAMEService name shown in traces and logsConversion Service
OTEL_RESOURCE_ATTRIBUTESAdditional resource attributesservice.instance.id=node-1

When you set OTEL_EXPORTER_OTLP_ENDPOINT, the service exports telemetry data using the specified protocol (gRPC by default).

For the complete list of environment variables, see the OpenTelemetry SDK Environment Variables.

Examples​

Set system environment variables or configure them in the service settings:

$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4317"
$env:OTEL_SERVICE_NAME = "Conversion Service"

Cluster deployments​

When you deploy Conversion Service across a cluster with more than one instance, use OTEL_SERVICE_NAME or OTEL_RESOURCE_ATTRIBUTES to identify each instance:

# Option 1: Unique service name per instance
-e OTEL_SERVICE_NAME="Conversion Service (Node 1)"

# Option 2: Use resource attributes
-e OTEL_SERVICE_NAME="Conversion Service"
-e OTEL_RESOURCE_ATTRIBUTES="service.instance.id=node-1,deployment.environment=production"

Telemetry data​

When enabled, the service exports:

TypeDescription
TracesRequest flow through the service with timing for each operation
LogsService logs with trace correlation (trace_id, span_id)
MetricsRuntime metrics: requests, duration, errors

The service correlates traces and logs by trace ID, so you can navigate from a trace to its related log entries in supported backends.

Verify your configuration​

To confirm OpenTelemetry is working:

  1. Start the Conversion Service with the environment variables configured.
  2. Send a conversion request using the API, a connector, or the Conversion Service Client.
  3. Check your observability backend for incoming data:
    • Traces: Look for spans with the service name you configured.
    • Logs: Verify log entries include trace_id and span_id fields.
  4. In the service logs, confirm there are no connection errors to the OTLP endpoint.

If telemetry data doesn’t appear, verify that:

  • The OTEL_EXPORTER_OTLP_ENDPOINT URL is reachable from the service.
  • The configured protocol (grpc or http/protobuf) matches your collector configuration.
  • Your firewall allows outbound connections to the collector port (default: 4317 for gRPC, 4318 for HTTP).

Learn more​

For more information about OpenTelemetry, refer to the following external resources: