Plugins 〉Grafana Image Renderer

Renderer

grafana

Grafana Image Renderer

Overview
Installation
Change log
Related content

A Grafana backend plugin that handles rendering panels and dashboards to PNGs using a headless browser (Chromium).

Requirements

Supported operating systems

Linux (x64)
Windows (x64)
Mac OS X (x64)

Dependencies

This plugin is packaged in a single executable with Node.js runtime and Chromium browser. This means that you don't need to have Node.js and Chromium installed in your system for the plugin to function.

However, the Chromium browser depends on certain libraries. If you don't have all of those libraries installed in your system, you may see some errors when you try to render an image. For more information including troubleshooting help, refer to Grafana Image Rendering documentation.

Memory requirements

Rendering images requires a lot of memory, mainly because Grafana creates browser instances in the background for the actual rendering. We recommend a minimum of 16GB of free memory on the system rendering images.

Rendering multiple images in parallel requires an even bigger memory footprint. You can use the remote rendering service in order to render images on a remote system, so your local system resources are not affected.

Plugin installation

You can install the plugin using Grafana CLI (recommended way) or with Grafana Docker image.

Grafana CLI (recommended)

grafana-cli plugins install grafana-image-renderer

Grafana Docker image

This plugin is not compatible with the current Grafana Docker image and requires additional system-level dependencies. We recommend setting up another Docker container for rendering and using remote rendering instead. For instruction, refer to Run in Docker.

If you still want to install the plugin with the Grafana Docker image, refer to the instructions on building a custom Grafana image in Grafana Docker documentation.

Remote rendering service installation

Note: Requires an internet connection.

You can run this plugin as a remote HTTP rendering service. In this setup, Grafana renders an image by making an HTTP request to the remote rendering service, which in turn renders the image and returns it back in the HTTP response to Grafana.

You can run the remote HTTP rendering service using Docker or as a standalone Node.js application.

Run in Docker

Grafana Docker images are published at Docker Hub.

The following example shows how you can run Grafana and the remote HTTP rendering service in two separate Docker containers using Docker Compose.

Create a docker-compose.yml with the following content:

version: '2'

services: grafana: image: grafana/grafana:latest ports: - ‘3000:3000’ environment: GF_RENDERING_SERVER_URL: http://renderer:8081/render GF_RENDERING_CALLBACK_URL: http://grafana:3000/ GF_LOG_FILTERS: rendering:debug renderer: image: grafana/grafana-image-renderer:latest ports: - 8081

Next, run docker compose.
```
docker-compose up
```

Run as standalone Node.js application

The following example describes how to build and run the remote HTTP rendering service as a standalone Node.js application and configure Grafana appropriately.

Clone the Grafana image renderer plugin Git repository.

Install dependencies and build:

yarn install --pure-lockfile
yarn run build

Run the server:
```
node build/app.js server --port=8081
```

Update Grafana configuration:

[rendering]
server_url = http://localhost:8081/render
callback_url = http://localhost:3000/

Restart Grafana.

Security

Access to the rendering endpoints is restricted to requests providing an auth token. This token should be configured in the Grafana configuration file and the renderer configuration file. This token is important when you run the plugin in remote rendering mode to avoid unauthorized file disclosure (see CVE-2022-31176).

See Grafana Image Rendering documentation to configure this secret token. The default value - is configured on both Grafana and the image renderer when you get started but we strongly recommend you to update this to a more secure value.

Configuration

For available configuration settings, please refer to Grafana Image Rendering documentation.

Troubleshooting

For troubleshooting help, refer to Grafana Image Rendering troubleshooting documentation.

Testing

In order to run the image-renderer automated test suites, you need to run the following command from the root folder:

yarn test

This will launch a Grafana instance in Docker and, then, run the test suites.

Notes:

If there are some expected changes in the reference image files (located in /tests/testdata), run yarn test-update and push the updated references.

If the tests are failing and you want to see the difference between the image you get and the reference image, run yarn test-diff. This will generate images (called diff_<test case>.png) containing the differences in the /tests/testdata folder.

Fixing Drone issues

If tests are successful in your local environement but fail in Drone. You can follow these steps to run the tests in an environment similar to the Drone pipeline. This will mount your local files of the grafana-image-renderer repo in the Docker image so any change that happens in the Docker image will be available in your local environment. This allows you to run yarn test-diff and yarn test-update in Docker and see the results locally.

Run the Drone environment in Docker:

cd ./devenv/docker/drone
docker-compose up

Open a terminal within the drone-docker-puppeteer container and run the following commands:

cd /drone/src
PUPPETEER_CACHE_DIR=/drone/src/cache yarn install --frozen-lockfile --no-progress
PUPPETEER_CACHE_DIR=/drone/src/cache CI=true yarn test-ci

Notes: The tests might take longer in the Docker container. If you run into timeout issues, you can run the test command with the --testTimeout option:

PUPPETEER_CACHE_DIR=/drone/src/cache CI=true yarn test-ci --testTimeout=10000

Installing Grafana Image Renderer on Grafana Cloud:

For more information, visit the docs on plugin installation.

3.11.6 (2024-10-17)

Chore: Upgrade express from 4.21.0 to 4.21.1 #577, AgnesToulet
Chore: Don't install dev packages in Docker image #575, McTonderski, AgnesToulet
Bump dompurify from 2.4.7 to 2.5.4 #574, dependabot[bot]

3.11.5 (2024-09-12)

Bump express to 4.21.0 #567, evictorero
Bump micromatch from 4.0.7 to 4.0.8 #561, dependabot[bot]

3.11.4 (2024-08-30)

Puppeteer: Upgrade to v22 #556, evictorero

3.11.3 (2024-08-13)

Full page image: Fix blank page screenshot when scenes is turned on #554, juanicabanas

3.11.2 (2024-08-08)

Properly support dashboards where the scrollable element is the document #552, ashharrison90

3.11.1 (2024-07-15)

Full page image: Fix wait condition for dashboard with rows #542, AgnesToulet
Chore: Upgrade Jimp deps 541, AgnesToulet

3.11.0 (2024-06-13)

Chore: Upgrade chokidar and jest dependencies #532, AgnesToulet
Bump @grpc/grpc-js from 1.8.20 to 1.8.22 #531, dependabot[bot]
Server: Fix CSV deletion #530, AgnesToulet
Server: Support HTTPS configuration #527, AgnesToulet

3.10.5 (2024-05-23)

Packages: Release Alpine package without Chromium #525, AgnesToulet
Full page image: Fix scrolling with the new native scroll #524, AgnesToulet

3.10.4 (2024-05-06)

Chore: Remove unused dependencies #517, evictorero

3.10.3 (2024-04-16)

Bump protobufjs from 7.2.4 to 7.2.6 #515, dependabot[bot]

3.10.2 (2024-04-08)

Bump express from 4.18.2 to 4.19.2 #510, dependabot[bot]
Bump follow-redirects from 1.15.5 to 1.15.6 #508, dependabot[bot]

3.10.1 (2024-03-07)

Bump axios from 1.6.0 to 1.6.7 #503, evictorero
Bump ip from 1.1.8 to 1.1.9 #500, dependabot[bot]
PDF: Fix resolution when zooming in #502, AgnesToulet

3.10.0 (2024-02-20)

WaitingForPanels: Change waiting logic for Scenes #496, torkelo
Experimental: Support PDF rendering #487, ryantxu

3.9.1 (2024-01-29)

Chore: Upgrade jimp and node #492, AgnesToulet
Bump follow-redirects from 1.15.3 to 1.15.4 #489, dependabot[bot]

3.9.0 (2023-12-04)

Config: Improve consistency between plugin and server mode #477, AgnesToulet
Chore: Bump axios from 0.27.2 to 1.6.0 #480, dependabot[bot]

3.8.4 (2023-10-17)

Bump xml2js to 0.6.2 #473, AgnesToulet
Browser: Fix panel rendered waiting condition #472, AgnesToulet
Docker: Add build for arm64 #468, michbeck100
Fix timezone config always overwritten #463, zhichli

3.8.3 (2023-09-29)

Chore: Upgrade to Node 18 #448, Clarity-89

3.8.2 (2023-09-21)

Browser: Revert to old headless mode to fix usage with Kubernetes #459, AgnesToulet

3.8.1 (2023-09-18)

Fix check condition to avoid timeouts in invalid panels #299, spinillos
Plugin: fix Chrome path #451, AgnesToulet

3.8.0 (2023-08-22)

Puppeteer: upgrade to v21 #433, Clarity-89
Fix fullpage waitFor conditions #446, AgnesToulet

3.7.2 (2023-07-27)

Chore: update all dependencies #443, AgnesToulet
Bump protobufjs from 7.1.1 to 7.2.4 #438, dependabot[bot]
Bump tough-cookie from 4.1.2 to 4.1.3 #439, dependabot[bot]
Bump semver from 6.3.0 to 6.3.1 #440, dependabot[bot]
Bump word-wrap from 1.2.3 to 1.2.4 #441, dependabot[bot]

3.7.1 (2023-05-15)

Docker: remove alpine edge repo #413, sozercan
Bump yaml from 2.1.1 to 2.2.2 #421, dependabot[bot]

3.7.0 (2023-04-17)

Security: can set array of auth tokens #417, AgnesToulet
Bump pkg from 5.8.0 to 5.8.1 #415, AgnesToulet
Bump jimp from 0.16.1 to 0.16.13 #406, AgnesToulet

3.6.4 (2023-02-10)

Add Snyk workflow #402, SadFaceSmith
Fix null error #403, spinillos

3.6.3 (2023-01-11)

Add support for page zooming option #387, kaffarell
Migrate from CircleCI to Drone #394, spinillos, joanlopez

3.6.2 (2022-10-22)

Log errors related to JSHandle@object as debug #376, spinillos
Chore: Update Puppeteer deprecated functions #375, spinillos
Fix: Update _client with _client() to avoid to fail when creating a CSV #372, spinillos
Chore: Update all dependencies #369, DanCech

3.6.1 (2022-08-30)

Chore: Update to Node 16 #365, Clarity-89
Update waiting condition for full page screenshots #362, spinillos
Fix invalid Content-Disposition #357, spinillos

3.6.0 (2022-08-16)

Security: Add support for auth token #364, xlson, joanlopez

3.5.0 (2022-07-18)

Added File Sanitization API with DOMPurify as the backend. #349, ArturWierzbicki
Security: upgrade dependencies #356, #348, #347, AgnesToulet

3.4.2 (2022-03-23)

Security: upgrade dependencies #337, AgnesToulet
Fix: set captureBeyondViewport to false by default to fix rendering old panels #335, AgnesToulet

3.4.1 (2022-02-23)

Fix: replace sharp with jimp to resolve issues with installing native dependencies #325, ArturWierzbicki

3.4.0 (2022-02-17)

Support new concurrency mode: contextPerRenderKey #314, ArturWierzbicki
Support full height dashboards and scaled thumbnails #312, ryantxu

3.3.0 (2021-11-18)

Chore: Bump pkg from 5.3.3 to 5.4.1 #305, AgnesToulet
Configuration: Add timeout setting for clustered mode #303, AgnesToulet

3.2.1 (2021-10-07)

Chore: Upgrade dev dependencies #294, AgnesToulet
Chore: Fix eslint usage #293, AgnesToulet
Docs: Fix links in README.md #290, simonc6372
Security: Bump semver-regex from 3.1.2 to 3.1.3 #289, dependabot[bot]

3.2.0 (2021-09-17)

Docs: Update documentation to improve visibility and avoid duplicates with Grafana documentation #277, AgnesToulet
Instrumentation: Update grafana_image_renderer_step_duration_seconds buckets #287, AgnesToulet
Security: Bump chokidar from 3.5.1 to 3.5.2 #284, AgnesToulet
Instrumentation: Add gauge of total number of requests in flight #281, AgnesToulet
Security: Bump axios from 0.21.1 to 0.21.4 #283, dependabot[bot]
Chore: Add self-contained setup for load test #275, pianohacker

3.1.0 (2021-09-01)

Settings: Set the maximum device scale factor to 4 as default #276, AgnesToulet
Metrics: Add browser timing metrics #263, AgnesToulet
Settings: Add --disable-gpu in the default Chromium args #262, AgnesToulet
Security: Update path-parse to v1.0.7 #268, joanlopez
Chore: Upgrade dependencies #246, Clarity-89
Docker: Run image renderer under non-root Grafana user #144, wardbekker

Important change

The default Chromium flags have been updated to include --disable-gpu as it fixes memory leaks issues when using the default rendering mode. If you don't want to use this flag, you need to update your service configuration, either through the service configuration file, the environment variables or the Grafana configuration file (if you're using the plugin mode).

3.0.1 (2021-06-10)

Browser: Fix panel timezone when the timezone query parameter is specified #224, Bujupah
Docker: Fix version endpoint for Docker images #248, mbentley

3.0.0 (2021-06-07)

Security: Bump path-parse from 1.0.6 to 1.0.7 #244, AgnesToulet
HTTP Server: Add version endpoint to get the current version #239, AgnesToulet
Security: Bump ws from 7.4.5 to 7.4.6 #238, dependabot[bot]
Remove support for plugin V1 protocol #233, AgnesToulet
Browser: Fix moving CSV file when the tmp folder is not on the same device as the target file path #232, AgnesToulet
Chore: Upgrade grabpl version #231, AgnesToulet
Add CSV rendering feature #217, AgnesToulet

3.0.0-beta2 (2021-05-26)

Remove support for plugin V1 protocol #233, AgnesToulet
Browser: Fix moving CSV file when the tmp folder is not on the same device as the target file path #232, AgnesToulet
Chore: Upgrade grabpl version #231, AgnesToulet

3.0.0-beta1 (2021-05-19)

Add CSV rendering feature #217, AgnesToulet

2.1.1 (2021-05-18)

Chore: Add changelog in package files #226, AgnesToulet

2.1.0 (2021-05-11)

Chore/Security: Upgrade dependencies and bump Node to LTS (14.16.1) #218, AgnesToulet

2.0.1 (2021-01-26)

Browser: Use timeout parameter for initial navigation to the dashboard being rendered #171,

2.0.0 (2020-05-16)

Plugin: Migrate to @grpc/grpc-js to resolve problems when IPv6 is disabled #135, aknuds1
Adds support for new Grafana backend plugin system #128, marefr
Browser: Adds support for setting viewport device scale factor #128, marefr
Browser: Adds support for attaching Accept-Language header to support render is name locale as Grafana user #128, marefr
Browser: Fail render if the URL has socket protocol #127, aknuds1
Chore: Upgrade typescript dependencies #129, marefr

2.0.0-beta1 (2020-04-22)

Adds support for new Grafana backend plugin system #128, marefr
Browser: Adds support for setting viewport device scale factor #128, marefr
Browser: Adds support for attaching Accept-Language header to support render is name locale as Grafana user #128, marefr
Browser: Fail render if the URL has socket protocol #127, aknuds1
Chore: Upgrade typescript dependencies #129, marefr

1.0.12 (2020-03-31)

Remote rendering: Delete temporary file after serving it to client #120, marefr
Remote rendering: More configuration options #123, marefr

1.0.12-beta1 (2020-03-30)

Remote rendering: More configuration options #123, marefr

1.0.11 (2020-03-20)

Render: Add support for enabling verbose logging using environment variable #105, marefr
Render: Fix panel titles should not be focused when rendering #114, AgnesToulet
Security: Upgrade minimist dependency to v1.2.5 #118, marefr

1.0.10 (2020-02-18)

Plugin: Fix unable to start Grafana (Windows) with version 1.0.8 and 1.0.9 #103, marefr

1.0.9 (2020-01-30)

Remote rendering: Improve error handling, logging and metrics #92, marefr
- Service: Don't swallow exceptions and fix logging of parameters
- Metrics: Use status 499 when client close the connection
- Docker: Set NODE_ENV=production
- Changed request logging to use debug level if status < 400 and error if >= 400
Plugin: Adds icon #95, marefr

1.0.8 (2020-01-20)

Build: Upgrade Node.js requirement to LTS (v12) #57, marefr
Docker: Add unifont font to support rendering other language, like Chinese/Japanese #75, okhowang
Subscribing to page events to catch errors from browser #88, marefr
Plugin: Automatically assign grpc port per default #87, marefr
Plugin: Support configuring default timezone thru environment variable #86, marefr
Remote rendering: Support configuring default timezone thru config file and environment variable #86, marefr
Remote rendering: Support configuring HTTP host and port thru config and environment variables #40, marefr
Remote rendering: Support reading config from file #73, marefr
Remote rendering: Collect and expose Prometheus metrics #71, marefr

Breaking changes

Plugin now automatically assigns gPRC port not in use. Before port 50059 was used. You can change this by using the GF_RENDERER_PLUGIN_GRPC_PORT environment variable.

1.0.8-beta1 (2019-12-17)

Remote rendering: Collect and expose Prometheus metrics #71, marefr
Build: Upgrade Node.js requirement to LTS (v12) #57, marefr

1.0.7 (2019-12-03)

Provide correctly named config parameter to Chromium when overriding to skip https errors using environment variable GF_RENDERER_PLUGIN_IGNORE_HTTPS_ERRORS and/or IGNORE_HTTPS_ERRORS #62, marefr

1.0.6 (2019-11-25)

Wait until all network connections to be idle before rendering #24, d1ff
Support ignoring https errors using environment variable #59, marefr
Docker: Update dependencies to remove vulnerabilities #53, marefr
Fix typo in log statement #39, ankon
Updated documentation

1.0.5 (2019-09-11)

Include md5 checksums in release artifacts

1.0.4 (2019-09-11)

Update readme and docs

1.0.3 (2019-09-10)

Automate docker release

1.0.2 (2019-09-10)

Don't include dist directory in archive (zip) files

1.0.1 (2019-09-09)

Switch docker base image from node:10 to node:alpine-10 #36, marefr
Updated the panel render wait function to account for Grafana version 6 #26, bmichaelis
Updated dependencies

1.0.0 (2019-08-16)

Initial release containing prebuilt binaries available for download. Right now the binaries themselves should be considered alpha as they need more testing.