Grafana Image Renderer is a powerful plugin that turns time‑series dashboards into high‑quality images and PDFs. It enables teams to automate report generation, snapshot dashboards, and embed visuals in documentation without opening a browser.
Instead of relying on screenshots or manual exports, Grafana Image Renderer streams rendered charts directly from Grafana servers. This makes it ideal for scheduled reports, CI pipelines, and alert notifications that need consistent, production‑ready visuals.
Renderer Capabilities at a Glance
| Feature | Description | Use Case | Default / Configurable |
|---|---|---|---|
| Headless Chrome | Uses Chromium to render dashboards exactly as they appear in Grafana | Accurate visuals, including custom fonts and SVG | Configurable binary path and Chrome flags |
| Multiple Output Formats | PNG, JPEG, PDF, SVG | Reports, presentations, and scalable graphics | PNG and PDF most common; select per request |
| Time Range Control | Override dashboard time range via query parameters | render specific windows or historical snapshotsDefaults to dashboard time; override for scheduled reports | |
| Authentication Support | Proxy Grafana security with cookies, tokens, or basic auth | integrate safely into CI/CD and external servicesConfigurable headers and secret management |
Rendering Architecture and Performance
How Image Renderer Works
Grafana Image Renderer runs as a standalone service that Grafana calls via an HTTP endpoint. When Grafana receives a render request, it forwards parameters such as dashboard UID, panel IDs, and desired format to the renderer. The service launches a Chrome instance, loads the dashboard in an offscreen browser, and exports the result as an image or PDF.
Performance Tuning and Scaling
Rendering is CPU and memory intensive, so performance tuning is essential. You can control Chrome sandboxing, limit concurrent browser pages, and set timeouts to avoid hung processes. For heavy workloads, run multiple renderer replicas behind a load balancer and increase Grafana’s HTTP client timeouts to accommodate larger PDFs.
Resource planning starts with measuring render time and memory per dashboard. Use smaller image dimensions for thumbnails and higher DPI for print‑ready PDFs. Monitoring renderer metrics such as request duration and Chrome crashes helps right‑size your deployment and avoid bottlenecks in production dashboards.
Deployment Options and Integration
Running as a Kubernetes Deployment
In Kubernetes, deploy Grafana Image Renderer as a Deployment with a Service and optional HorizontalPodAutoscaler. Use a sidecar or init container to share Chrome fonts and ensure the binary is available inside the container. Configure readiness probes so Grafana does not send traffic until Chrome is fully initialized.
Integrating into CI/CD and Automation
Outside Grafana, you can call the renderer directly to generate reports as part of pipelines. Pass signed tokens or temporary credentials to authenticate without exposing Grafana to the public internet. Combine with cron jobs or GitHub Actions to snapshot dashboards nightly, attach them to release notes, or archive compliance records.
Operational Practices and Troubleshooting
Operational reliability depends on observability and sensible defaults. Set reasonable timeouts per panel, enable request logging, and export renderer metrics to Prometheus. Keep Chrome and the renderer binary patched, and test upgrades in staging before rolling to production to prevent rendering regressions.
Common issues include blank images, missing fonts, and Chrome sandbox failures. Verify that the renderer can reach Grafana over HTTPS, that time ranges align, and that API keys or cookies are valid. Adjust Chrome flags such as --no-sandbox carefully, only in controlled environments, and prefer configuring Grafana plugin settings for timeouts and concurrency.
Best Practices and Recommendations
- Run Grafana Image Renderer as a separate service or sidecar to isolate resource usage.
- Define timeouts and concurrency limits that match your dashboard complexity and load.
- Use PDF output for archival and PNG for quick previews to balance size and quality.
- Automate snapshot testing to detect rendering regressions after Grafana upgrades.
- Monitor Chrome crashes, request latency, and renderer memory to plan capacity.
FAQ
Reader questions
How do I secure the Grafana Image Renderer endpoint in production?
Enable authentication headers, restrict source IPs, and use mTLS between Grafana and the renderer. Avoid exposing the renderer service publicly and rotate API keys regularly.
What causes blank or incomplete PNG renders?
Blank renders usually stem from time range mismatches, missing panels, or Chrome sandbox issues. Check renderer logs, verify Grafana queries return data, and test with a simple dashboard to isolate the cause.
Can I render large dashboards with many panels without slowing down Grafana?
Yes, offload rendering to the Image Renderer service and tune concurrency limits. Use shorter time ranges for previews and higher resolutions only for scheduled exports to reduce load on Grafana.
Is it safe to run Chrome in sandbox mode inside containers?
In most container setups, you must disable the sandbox or use the correct sandbox namespace when running as root. Follow renderer and Chrome runtime guidance for your specific container platform and Kubernetes distributions.