Searchvarnish-otel is intended to provide comprehensive observability for Varnish Cache environments. By leveraging OpenTelemetry to export logs, metrics and traces, varnish-otel will offer detailed insights into caching behavior, traffic flows, and system performance.
Important: varnish-otel is currently in beta and is not available through the main Varnish Enterprise repositories. Please contact your account manager or sales@varnish-software.com to get access to it.
Before anything else, make sure Varnish is already up and running. You can refer to our installation tutorials for detailed instructions.
You can also use the automated installation method for a quicker approach.
To enable tracing, include the otel.vcl at the top of you main VCL file:
vcl 4.1
include "otel.vcl";
...
varnish-otel package can be found in the experimental repository, for both debian-based and redhat-based distributions. You can install it directly using the quick-install script:
curl https://docs.varnish-software.com/scripts/setup.sh | TOKEN=INSERT_EXPERIMENTAL_TOKEN_HERE INSTALL="varnish-otel" REPO=experimental bash
varnish-otel is at the moment configured through environment variables, making it easy to embed in a container or configure with systemd via a drop-in file.
The table below lists some important variables.
| Variable | Description | Possible Values | Default |
|---|---|---|---|
| OTEL_EXPORTER | Default exporter for logs, metrics and trace | otlp, console, none |
otlp |
| OTEL_EXPORTER_OTLP_ENDPOINT | Base endpoint URL | String | Depends on other variables |
| OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | Protocol to use when exporting logs with the otlp exporter |
grpc, http/protobuf |
OTEL_EXPORTER_OTLP_PROTOCOL or grpc |
| OTEL_EXPORTER_OTLP_LOG_ENDPOINT | Base endpoint URL for logs | String | Depends on other variables |
| OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | Base endpoint URL for metrics | String | Depends on other variables |
| OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | Protocol to use when exporting metrics with the otlp exporter |
grpc, http/protobuf |
OTEL_EXPORTER_OTLP_PROTOCOL or grpc |
| OTEL_EXPORTER_OTLP_PROTOCOL | Default protocol for logs, metrics and trace when using the otlp exporter |
grpc, http/protobuf |
grpc |
| OTEL_EXPORTER_OTLP_TRACES-ENDPOINT | Base endpoint URL for traces | String | Depends on other variables |
| OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | Protocol to use when exporting trace with the otlp exporter |
grpc, http/protobuf |
OTEL_EXPORTER_OTLP_PROTOCOL or grpc |
| OTEL_LOGS_EXPORTER | Logs exporter | otlp, console, none |
OTEL_EXPORTER or otlp |
| OTEL_METRICS_EXPORTER | Metrics exporter | otlp, console, none |
OTEL_EXPORTER or otlp |
| OTEL_METRIC_EXPORT_INTERVAL | The time interval (in milliseconds) between the start of two export attempts. | Integer | 60000 |
| OTEL_METRIC_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data. | Integer | 30000 |
| OTEL_METRIC_SCRAPING_INTERVAL | Time between each scraping of metrics | Integer | 10000 |
| OTEL_RESOURCE_ATTRIBUTES | Allows specifying resource attributes | String | - |
| OTEL_SERVICE_NAME | Name of the service used in instrumentation | String | varnish |
| OTEL_TRACES_EXPORTER | Traces exporter | otlp, console, none |
OTEL_EXPORTER or otlp |
| OTEL_TRACES_OPT_IN_ATTRIBUTES | If off, traces only get a minimal set of attributes related to the request, to keep volumes low. |
on, off |
off |
| OTEL_TRACES_SAMPLER | Defines the sampler for traces | always_on, always_off |
always_on |
| OTEL_VARNISH_LOG_PROBE | Enables or disables log processing for backend probes | true, false |
false |
| OTEL_VARNISH_METRICS_FILTER | Specifies filters to include or exclude certain metrics from export | String | !varnish.lock.* |
| OTEL_VARNISH_WORKDIR | varnishd’s -n argument |
String | - |
To get started on some of the most popular observability platforms, check out the subpages in the sidebar.
OTEL_VARNISH_METRICS_FILTER allows to select which metrics will be exported. By default, all metrics except the ones matching the varnish.lock.* are exposed. The variable is a comma-separated list of globbing patterns, optionally prefixed with ^ or !. For example:
To determined if a metric should be exported, its final name is considered, looking at each element in the OTEL_VARNISH_METRICS_FILTER list, one by one:
^ or ! prefix: the metric is rejectBy default, varnish-otel only offers lightweight traces to avoid exporting too much data. This means for example that header values won’t be shown. It’s not an issue if you are also exporting logs as you can retrieve the full transaction details using the traceId and spanId, but you may want stand-alone traces to avoid relying on logs. If that is the case, set OTEL_TRACES_OPT_IN_ATTRIBUTES to on.