OpenTelemetry

imgproxy can send request traces to an OpenTelemetry collector. To use this feature, do the following:

1. Install & configure the OpenTelemetry collector.

2. Set the IMGPROXY_OPEN_TELEMETRY_ENABLE environment variable to true to enable sending request traces to the collector. Default: false.

3. (optional) Set the IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS environment variable to true to enable sending metrics to the collector. Default: false.

4. (optional) Set the IMGPROXY_OPEN_TELEMETRY_ENABLE_LOGS environment variable to true to enable sending logs to the collector. Default: false.

5. (optional) Specify the collector protocol with OTEL_EXPORTER_OTLP_PROTOCOL environment variable.

   tip

   You can specify different protocols for traces, metrics, and logs by using the OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, OTEL_EXPORTER_OTLP_METRICS_PROTOCOL, and OTEL_EXPORTER_OTLP_LOGS_PROTOCOL environment variables.

   Supported protocols are:

   • grpc (default)
   • http/protobuf (aliases: http, https)

6. (optional) Specify the collector endpoint with OTEL_EXPORTER_OTLP_ENDPOINT environment variable.

   tip

   Use https:// scheme for secure connections (you may need to configure TLS certificates) and http:// for insecure connections.

   info

   The OTEL_EXPORTER_OTLP_ENDPOINT path should not contain signal-specific paths like /v1/traces or /v1/metrics. The signal-specific paths are added automatically.

   tip

   You can specify different endpoints for traces, metrics, and logs by using the OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, and OTEL_EXPORTER_OTLP_LOGS_ENDPOINT environment variables. If the http/protobuf protocol is used, these signal-specific endpoints should include the signal-specific paths like /v1/traces, /v1/metrics, or /v1/logs.

   Defaults are:

   • For the grpc protocol: https://localhost:4317
   • For the http/protobuf protocol: https://localhost:4318

7. (optional) Set the OTEL_SERVICE_NAME environment variable to be the desired service name. Default: imgproxy.

8. (optional) Set up TLS certificates.

9. (optional) Set the IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR environment variable to be the desired trace ID generator. Supported values are:

   • xray: (default) Amazon X-Ray compatible trace ID generator
   • random: random trace ID generator

10. (optional) Use OpenTelemetry configuration environment variables to further customize the behavior.

imgproxy will send the following info to the collector:

• Response time
• Queue time
• Image downloading time
• Image processing time
• Errors that occurred while downloading and processing an image

If IMGPROXY_OPEN_TELEMETRY_ENABLE_METRICS is set to true, imgproxy will also send the following metrics to the collector:

• workers: the configured number of imgproxy workers
• requests_in_progress: the number of requests currently in progress
• images_in_progress: the number of images currently in progress
• workers_utilization: the percentage of imgproxy's workers utilization. Calculated as requests_in_progress / workers * 100
• buffer_size_bytes: a histogram of buffer sizes (in bytes)
• buffer_default_size_bytes: calibrated default buffer size (in bytes)
• buffer_max_size_bytes: calibrated maximum buffer size (in bytes)
• vips_memory_bytes: libvips memory usage
• vips_max_memory_bytes: libvips maximum memory usage
• vips_allocs: the number of active vips allocations
• Some useful Go metrics like memstats and goroutines count

Configuration

imgproxy supports the standard general and OTLP exporter-specific environment variables with the following specifics:

• http/json protocol` is not supported.
• OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, and OTEL_LOGS_EXPORTER environment variables are ignored as imgproxy always uses the OTLP exporter.

Also, imgproxy supports the following environment variables:

• IMGPROXY_OPEN_TELEMETRY_PROPAGATE_EXTERNAL: when true, imgproxy will propagate OpenTelemetry tracing headers to external requests such as image downloads. Default: false
• IMGPROXY_OPEN_TELEMETRY_TRACE_ID_GENERATOR: the desired trace ID generator. Supported values are:
  • xray: (default) Amazon X-Ray compatible trace ID generator
  • random: random trace ID generator
• TLS configuration environment variables.

TLS Configuration

If your OpenTelemetry collector is secured with TLS, you may need to specify the collector's certificate on the imgproxy side. You can do this by either providing a path to the certificate file or by specifying the certificate itself:

• IMGPROXY_OPEN_TELEMETRY_SERVER_CERT: OpenTelemetry collector TLS certificate, PEM-encoded (you can replace line breaks with \n). Default: blank

If your collector uses mTLS for mutual authentication, you'll also need to specify the client's certificate/key pair:

• IMGPROXY_OPEN_TELEMETRY_CLIENT_CERT: OpenTelemetry client TLS certificate, PEM-encoded (you can replace line breaks with \n). Default: blank
• IMGPROXY_OPEN_TELEMETRY_CLIENT_KEY: OpenTelemetry client TLS key, PEM-encoded (you can replace line breaks with \n). Default: blank

warning

If IMGPROXY_OPEN_TELEMETRY_SERVER_CERT is set and the grpc protocol is used, imgproxy will try to establish a secure connection to the collector even if the collector's endpoint scheme is http://.