Skip to main content

Telemetry in Saleor

Introduction​

Saleor implements telemetry using the OpenTelemetry framework to provide comprehensive observability of your application. This document describes how telemetry is implemented, how to configure it, and best practices for using it in your own deployment.

What is OpenTelemetry?​

OpenTelemetry is an open-source observability framework that provides tools, APIs, and SDKs to help instrument, generate, collect, and export telemetry data (metrics, logs, and traces) for analysis. OpenTelemetry is a Cloud Native Computing Foundation (CNCF) project designed to make observability a built-in feature of cloud-native applications.

Telemetry in Saleor architecture​

Saleor's telemetry system is primarily located in the saleor.core.telemetry package and consists of the following key components:

Tracing​

Tracing is provided through the Tracer class which is a wrapper around OpenTelemetry's tracing capabilities. It allows you to:

  • Create spans to measure operation execution time
  • Add attributes and events to spans
  • Establish parent-child relationships between spans
  • Link spans across asynchronous operations

Saleor implements two distinct scopes for traces:

  • CORE: For internal system operations and core functionality
  • SERVICE: For business logic and service-level operations

What is being traced:

  • HTTP requests including their duration, full URL, request method, client's IP address, and length of response.
  • GraphQL queries including their duration, query string, and execution errors.
  • GraphQL resolvers including their duration, field name, parent type, and execution errors.
  • Database queries including their duration and the SQL statement.

Metrics​

Metrics are handled through the Meter class, which is a wrapper around OpenTelemetry's metrics capabilities. It supports:

  • Counters
  • Histograms
  • Up/Down Counters

Like traces, metrics are also separated into CORE and SERVICE scopes.

Context propagation​

Saleor implements context propagation to ensure telemetry context is maintained across:

  • Synchronous operations
  • Asynchronous Celery tasks (via Span Links)
  • Web requests

Context propagation between Saleor and external services is handled through OpenTelemetry's W3C Trace Context standard.

Setting up your own observability​

If you're running your own Saleor instance, you can set up telemetry collection and viewing using standard OpenTelemetry tooling. Below is an example of a observability setup where Saleor is configured to send telemetry data to an OpenTelemetry Collector, which then exports the data to a Jaeger instance for visualization.

1. Configure an OpenTelemetry Collector​

Set up an OpenTelemetry Collector to receive, process, and export telemetry data.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  jaeger:
    endpoint: jaeger:4317  # example Jaeger endpoint
    tls:
      insecure: true  # enable TLS in production

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [jaeger]
Expand â–¼

Note: Only traces are exported in this example as Jaeger doesn't support metrics. You can add additional exporters for metrics if needed.

2. Set Up Environment Variables​

Configure the necessary environment variables for your Saleor instance to connect to your telemetry system:

# OpenTelemetry configuration
export OTEL_SERVICE_NAME=saleor
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317

3. Run Saleor with OpenTelemetry Instrumentation​

Use the OpenTelemetry instrumentation command to automatically instrument your application:

opentelemetry-instrument uvicorn saleor.asgi:application