Varnish Orca
← Tutorials

Setting up Grafana for Varnish Orca

Grafana Observability Tutorial

Monitor Varnish Orca with Prometheus, Tempo, and Grafana. Track cache performance, registry traffic, and artifact metrics.

Prerequisites

  • Docker and Docker Compose installed

Note: If using the complete docker-compose example below, Orca is included - no separate installation needed. If you’re setting up monitoring for an existing Orca installation, see the installation guide.

Overview

Varnish Orca includes built-in OpenTelemetry (OTLP) support for exporting metrics and traces. This tutorial sets up a complete observability stack:

  • Varnish Orca pushes metrics and traces via OTLP
  • Prometheus receives and stores metrics
  • Tempo receives distributed traces
  • Grafana visualizes metrics with pre-built dashboards

Licensing:

  • Metrics export is available in the free version (no license required)
  • Tracing requires a license with sup-otel and vmod-otel addons (Premium feature)
  • Get a trial license by filling in the sign-up form

The dashboard provides insights into:

  • Cache hit rates (overall and per virtual registry)
  • Request rates and bandwidth by registry and artifact type
  • Backend health and error rates
  • Storage usage and memory management
  • Ykey cache invalidation metrics

Everything is pre-configured. Just clone and run:

git clone https://github.com/varnish/orca.git
cd orca/docs/tutorials/grafana
docker compose up -d

This starts:

  • Varnish Orca with metrics and tracing configured
  • Prometheus with OTLP receiver
  • Tempo for distributed tracing
  • Grafana with dashboard pre-loaded

Metrics work immediately. To enable tracing, uncomment the volumes and license config in docker-compose.yaml and mount your license file (needs sup-otel and vmod-otel addons). See the license tutorial for details.

Generate some traffic, then open Grafana at http://localhost:3000 (admin/admin).

Configure Existing Orca Installation

If you already have Orca running and want to add monitoring:

  1. Configure OTLP export in your Orca config file (typically /etc/varnish-orca/config.yaml):

    otel:
  service_name: varnish-orca
  metrics:
    enabled: true
    endpoint: http://your-prometheus:9090/api/v1/otlp/v1/metrics
    protocol: http/protobuf

  2. (Optional) Enable tracing by adding a license with sup-otel and vmod-otel addons and configuring the tracing endpoint.

See the OTEL configuration reference for all available options and the license tutorial for how to add a license.

Restart Orca:

sudo systemctl restart varnish-orca

Then set up Prometheus, Tempo, and Grafana using the example configs as reference.

Troubleshooting

No metrics in Grafana

Check Prometheus is receiving data:

curl http://localhost:9090/api/v1/query?query=varnish_main_client_requests

Docker Compose setup:

# Check Orca is running
docker compose ps

# Check Prometheus logs
docker compose logs prometheus

# Check Orca is pushing metrics
docker compose logs orca | grep -i otlp

Common issues

No data in dashboard:

  • Wait 15 seconds for first metrics export
  • Check the job label matches what your dashboard expects (set via service_name in config)

Connection refused:

  • Docker Compose: Use service names (http://prometheus:9090)
  • Host install: Use http://localhost:9090 or actual hostname