Image rendering on Grafana Labs

Monitoring the image renderer

Sat, 04 Apr 2026 12:26:57 +0000

Monitoring the image renderer

Rendering images requires a lot of memory, mainly because Grafana creates browser instances in the background for the actual rendering. Monitoring your service can help you allocate the right amount of resources to your rendering service and set the right rendering mode.

Enable Prometheus metrics endpoint

Configure this service to expose a Prometheus metrics endpoint. For information on how to configure and monitor this service using Prometheus as a data source, refer to Grafana Image Rendering Service dashboard.

Metrics endpoint output example:

# HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
# TYPE process_cpu_user_seconds_total counter
process_cpu_user_seconds_total 0.536 1579444523566

# HELP process_cpu_system_seconds_total Total system CPU time spent in seconds.
# TYPE process_cpu_system_seconds_total counter
process_cpu_system_seconds_total 0.064 1579444523566

# HELP process_cpu_seconds_total Total user and system CPU time spent in seconds.
# TYPE process_cpu_seconds_total counter
process_cpu_seconds_total 0.6000000000000001 1579444523566

# HELP process_start_time_seconds Start time of the process since unix epoch in seconds.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1579444433

# HELP process_resident_memory_bytes Resident memory size in bytes.
# TYPE process_resident_memory_bytes gauge
process_resident_memory_bytes 52686848 1579444523568

# HELP process_virtual_memory_bytes Virtual memory size in bytes.
# TYPE process_virtual_memory_bytes gauge
process_virtual_memory_bytes 2055344128 1579444523568

# HELP process_heap_bytes Process heap size in bytes.
# TYPE process_heap_bytes gauge
process_heap_bytes 1996390400 1579444523568

# HELP process_open_fds Number of open file descriptors.
# TYPE process_open_fds gauge
process_open_fds 31 1579444523567

# HELP process_max_fds Maximum number of open file descriptors.
# TYPE process_max_fds gauge
process_max_fds 1573877

# HELP nodejs_eventloop_lag_seconds Lag of event loop in seconds.
# TYPE nodejs_eventloop_lag_seconds gauge
nodejs_eventloop_lag_seconds 0.000915922 1579444523567

# HELP nodejs_active_handles Number of active libuv handles grouped by handle type. Every handle type is C++ class name.
# TYPE nodejs_active_handles gauge
nodejs_active_handles{type="WriteStream"} 2 1579444523566
nodejs_active_handles{type="Server"} 1 1579444523566
nodejs_active_handles{type="Socket"} 9 1579444523566
nodejs_active_handles{type="ChildProcess"} 2 1579444523566

# HELP nodejs_active_handles_total Total number of active handles.
# TYPE nodejs_active_handles_total gauge
nodejs_active_handles_total 14 1579444523567

# HELP nodejs_active_requests Number of active libuv requests grouped by request type. Every request type is C++ class name.
# TYPE nodejs_active_requests gauge
nodejs_active_requests{type="FSReqCallback"} 2

# HELP nodejs_active_requests_total Total number of active requests.
# TYPE nodejs_active_requests_total gauge
nodejs_active_requests_total 2 1579444523567

# HELP nodejs_heap_size_total_bytes Process heap size from node.js in bytes.
# TYPE nodejs_heap_size_total_bytes gauge
nodejs_heap_size_total_bytes 13725696 1579444523567

# HELP nodejs_heap_size_used_bytes Process heap size used from node.js in bytes.
# TYPE nodejs_heap_size_used_bytes gauge
nodejs_heap_size_used_bytes 12068008 1579444523567

# HELP nodejs_external_memory_bytes Nodejs external memory size in bytes.
# TYPE nodejs_external_memory_bytes gauge
nodejs_external_memory_bytes 1728962 1579444523567

# HELP nodejs_heap_space_size_total_bytes Process heap space size total from node.js in bytes.
# TYPE nodejs_heap_space_size_total_bytes gauge
nodejs_heap_space_size_total_bytes{space="read_only"} 262144 1579444523567
nodejs_heap_space_size_total_bytes{space="new"} 1048576 1579444523567
nodejs_heap_space_size_total_bytes{space="old"} 9809920 1579444523567
nodejs_heap_space_size_total_bytes{space="code"} 425984 1579444523567
nodejs_heap_space_size_total_bytes{space="map"} 1052672 1579444523567
nodejs_heap_space_size_total_bytes{space="large_object"} 1077248 1579444523567
nodejs_heap_space_size_total_bytes{space="code_large_object"} 49152 1579444523567
nodejs_heap_space_size_total_bytes{space="new_large_object"} 0 1579444523567

# HELP nodejs_heap_space_size_used_bytes Process heap space size used from node.js in bytes.
# TYPE nodejs_heap_space_size_used_bytes gauge
nodejs_heap_space_size_used_bytes{space="read_only"} 32296 1579444523567
nodejs_heap_space_size_used_bytes{space="new"} 601696 1579444523567
nodejs_heap_space_size_used_bytes{space="old"} 9376600 1579444523567
nodejs_heap_space_size_used_bytes{space="code"} 286688 1579444523567
nodejs_heap_space_size_used_bytes{space="map"} 704320 1579444523567
nodejs_heap_space_size_used_bytes{space="large_object"} 1064872 1579444523567
nodejs_heap_space_size_used_bytes{space="code_large_object"} 3552 1579444523567
nodejs_heap_space_size_used_bytes{space="new_large_object"} 0 1579444523567

# HELP nodejs_heap_space_size_available_bytes Process heap space size available from node.js in bytes.
# TYPE nodejs_heap_space_size_available_bytes gauge
nodejs_heap_space_size_available_bytes{space="read_only"} 229576 1579444523567
nodejs_heap_space_size_available_bytes{space="new"} 445792 1579444523567
nodejs_heap_space_size_available_bytes{space="old"} 417712 1579444523567
nodejs_heap_space_size_available_bytes{space="code"} 20576 1579444523567
nodejs_heap_space_size_available_bytes{space="map"} 343632 1579444523567
nodejs_heap_space_size_available_bytes{space="large_object"} 0 1579444523567
nodejs_heap_space_size_available_bytes{space="code_large_object"} 0 1579444523567
nodejs_heap_space_size_available_bytes{space="new_large_object"} 1047488 1579444523567

# HELP nodejs_version_info Node.js version info.
# TYPE nodejs_version_info gauge
nodejs_version_info{version="v14.16.1",major="14",minor="16",patch="1"} 1

# HELP grafana_image_renderer_service_http_request_duration_seconds duration histogram of http responses labeled with: status_code
# TYPE grafana_image_renderer_service_http_request_duration_seconds histogram
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="1",status_code="200"} 0
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="5",status_code="200"} 4
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="7",status_code="200"} 4
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="9",status_code="200"} 4
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="11",status_code="200"} 4
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="13",status_code="200"} 4
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="15",status_code="200"} 4
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="20",status_code="200"} 4
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="30",status_code="200"} 4
grafana_image_renderer_service_http_request_duration_seconds_bucket{le="+Inf",status_code="200"} 4
grafana_image_renderer_service_http_request_duration_seconds_sum{status_code="200"} 10.492873834
grafana_image_renderer_service_http_request_duration_seconds_count{status_code="200"} 4

# HELP up 1 = up, 0 = not up
# TYPE up gauge
up 1

# HELP grafana_image_renderer_http_request_in_flight A gauge of requests currently being served by the image renderer.
# TYPE grafana_image_renderer_http_request_in_flight gauge
grafana_image_renderer_http_request_in_flight 1

# HELP grafana_image_renderer_step_duration_seconds duration histogram of browser steps for rendering an image labeled with: step
# TYPE grafana_image_renderer_step_duration_seconds histogram
grafana_image_renderer_step_duration_seconds_bucket{le="0.3",step="launch"} 0
grafana_image_renderer_step_duration_seconds_bucket{le="0.5",step="launch"} 0
grafana_image_renderer_step_duration_seconds_bucket{le="1",step="launch"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="2",step="launch"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="3",step="launch"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="5",step="launch"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="+Inf",step="launch"} 1
grafana_image_renderer_step_duration_seconds_sum{step="launch"} 0.7914972
grafana_image_renderer_step_duration_seconds_count{step="launch"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="0.3",step="newPage"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="0.5",step="newPage"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="1",step="newPage"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="2",step="newPage"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="3",step="newPage"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="5",step="newPage"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="+Inf",step="newPage"} 1
grafana_image_renderer_step_duration_seconds_sum{step="newPage"} 0.2217868
grafana_image_renderer_step_duration_seconds_count{step="newPage"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="0.3",step="prepare"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="0.5",step="prepare"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="1",step="prepare"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="2",step="prepare"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="3",step="prepare"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="5",step="prepare"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="+Inf",step="prepare"} 1
grafana_image_renderer_step_duration_seconds_sum{step="prepare"} 0.0819274
grafana_image_renderer_step_duration_seconds_count{step="prepare"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="0.3",step="navigate"} 0
grafana_image_renderer_step_duration_seconds_bucket{le="0.5",step="navigate"} 0
grafana_image_renderer_step_duration_seconds_bucket{le="1",step="navigate"} 0
grafana_image_renderer_step_duration_seconds_bucket{le="2",step="navigate"} 0
grafana_image_renderer_step_duration_seconds_bucket{le="3",step="navigate"} 0
grafana_image_renderer_step_duration_seconds_bucket{le="5",step="navigate"} 0
grafana_image_renderer_step_duration_seconds_bucket{le="+Inf",step="navigate"} 1
grafana_image_renderer_step_duration_seconds_sum{step="navigate"} 15.3311258
grafana_image_renderer_step_duration_seconds_count{step="navigate"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="0.3",step="panelsRendered"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="0.5",step="panelsRendered"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="1",step="panelsRendered"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="2",step="panelsRendered"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="3",step="panelsRendered"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="5",step="panelsRendered"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="+Inf",step="panelsRendered"} 1
grafana_image_renderer_step_duration_seconds_sum{step="panelsRendered"} 0.0205577
grafana_image_renderer_step_duration_seconds_count{step="panelsRendered"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="0.3",step="screenshot"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="0.5",step="screenshot"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="1",step="screenshot"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="2",step="screenshot"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="3",step="screenshot"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="5",step="screenshot"} 1
grafana_image_renderer_step_duration_seconds_bucket{le="+Inf",step="screenshot"} 1
grafana_image_renderer_step_duration_seconds_sum{step="screenshot"} 0.2866623
grafana_image_renderer_step_duration_seconds_count{step="screenshot"} 1

# HELP grafana_image_renderer_browser_info A metric with a constant '1 value labeled by version of the browser in use
# TYPE grafana_image_renderer_browser_info gauge
grafana_image_renderer_browser_info{version="HeadlessChrome/79.0.3945.0"} 1

Troubleshooting

Sat, 04 Apr 2026 12:26:57 +0000

Troubleshoot image rendering

In this section, you’ll learn how to enable logging for the image renderer and you’ll find the most common issues.

Enable debug logging

To troubleshoot the image renderer, different kind of logs are available.

You can enable debug log messages for rendering in the Grafana configuration file and inspect the Grafana server logs.

[log]
filters = rendering:debug

You can also enable more logs in image renderer service itself by:

Missing libraries

The plugin and rendering service uses Chromium browser which depends on certain libraries. If you don’t have all of those libraries installed in your system you may encounter errors when trying to render an image, e.g.

Rendering failed: Error: Failed to launch chrome!/var/lib/grafana/plugins/grafana-image-renderer/chrome-linux/chrome:
error while loading shared libraries: libX11.so.6: cannot open shared object file: No such file or directory\n\n\nTROUBLESHOOTING: https://github.com/GoogleChrome/puppeteer/blob/master/docs/troubleshooting.md

In general you can use the ldd utility to figure out what shared libraries are not installed in your system:

cd <grafana-image-render plugin directory>
ldd chrome-linux/chrome
      linux-vdso.so.1 (0x00007fff1bf65000)
      libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007f2047945000)
      libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007f2047924000)
      librt.so.1 => /lib/x86_64-linux-gnu/librt.so.1 (0x00007f204791a000)
      libX11.so.6 => not found
      libX11-xcb.so.1 => not found
      libxcb.so.1 => not found
      libXcomposite.so.1 => not found
        ...

Ubuntu:

On Ubuntu 18.10 the following dependencies are required for the image rendering to function.

libx11-6 libx11-xcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrender1 libxtst6 libglib2.0-0 libnss3 libcups2  libdbus-1-3 libxss1 libxrandr2 libgtk-3-0 libasound2 libxcb-dri3-0 libgbm1 libxshmfence1

Debian:

On Debian 9 (Stretch) the following dependencies are required for the image rendering to function.

libx11 libcairo libcairo2 libxtst6 libxcomposite1 libx11-xcb1 libxcursor1 libxdamage1 libnss3 libcups libcups2 libxss libxss1 libxrandr2 libasound2 libatk1.0-0 libatk-bridge2.0-0 libpangocairo-1.0-0 libgtk-3-0 libgbm1 libxshmfence1

On Debian 10 (Buster) the following dependencies are required for the image rendering to function.

libxdamage1 libxext6 libxi6 libxtst6 libnss3 libcups2 libxss1 libxrandr2 libasound2 libatk1.0-0 libatk-bridge2.0-0 libpangocairo-1.0-0 libpango-1.0-0 libcairo2 libatspi2.0-0 libgtk3.0-cil libgdk3.0-cil libx11-xcb-dev libgbm1 libxshmfence1

Centos:

On a minimal CentOS 7 installation, the following dependencies are required for the image rendering to function:

libXcomposite libXdamage libXtst cups libXScrnSaver pango atk adwaita-cursor-theme adwaita-icon-theme at at-spi2-atk at-spi2-core cairo-gobject colord-libs dconf desktop-file-utils ed emacs-filesystem gdk-pixbuf2 glib-networking gnutls gsettings-desktop-schemas gtk-update-icon-cache gtk3 hicolor-icon-theme jasper-libs json-glib libappindicator-gtk3 libdbusmenu libdbusmenu-gtk3 libepoxy liberation-fonts liberation-narrow-fonts liberation-sans-fonts liberation-serif-fonts libgusb libindicator-gtk3 libmodman libproxy libsoup libwayland-cursor libwayland-egl libxkbcommon m4 mailx nettle patch psmisc redhat-lsb-core redhat-lsb-submod-security rest spax time trousers xdg-utils xkeyboard-config alsa-lib

On a minimal CentOS 8 installation, the following dependencies are required for the image rendering to function:

libXcomposite libXdamage libXtst cups libXScrnSaver pango atk adwaita-cursor-theme adwaita-icon-theme at at-spi2-atk at-spi2-core cairo-gobject colord-libs dconf desktop-file-utils ed emacs-filesystem gdk-pixbuf2 glib-networking gnutls gsettings-desktop-schemas gtk-update-icon-cache gtk3 hicolor-icon-theme jasper-libs json-glib libappindicator-gtk3 libdbusmenu libdbusmenu-gtk3 libepoxy liberation-fonts liberation-narrow-fonts liberation-sans-fonts liberation-serif-fonts libgusb libindicator-gtk3 libmodman libproxy libsoup libwayland-cursor libwayland-egl libxkbcommon m4 mailx nettle patch psmisc redhat-lsb-core redhat-lsb-submod-security rest spax time trousers xdg-utils xkeyboard-config alsa-lib libX11-xcb

Certificate signed by internal certificate authorities

In many cases, Grafana runs on internal servers and uses certificates that have not been signed by a CA (Certificate Authority) known to Chrome, and therefore cannot be validated. Chrome internally uses NSS (Network Security Services) for cryptographic operations such as the validation of certificates.

If you are using the Grafana Image Renderer with a Grafana server that uses a certificate signed by such a custom CA (for example a company-internal CA), rendering images will fail and you will see messages like this in the Grafana log:

t=2019-12-04T12:39:22+0000 lvl=error msg="Render request failed" logger=rendering error=map[] url="https://192.168.106.101:3443/d-solo/zxDJxNaZk/graphite-metrics?orgId=1&refresh=1m&from=1575438321300&to=1575459921300&var-Host=master1&panelId=4&width=1000&height=500&tz=Europe%2FBerlin&render=1" timestamp=0001-01-01T00:00:00.000Z
t=2019-12-04T12:39:22+0000 lvl=error msg="Rendering failed." logger=context userId=1 orgId=1 uname=admin error="Rendering failed: Error: net::ERR_CERT_AUTHORITY_INVALID at https://192.168.106.101:3443/d-solo/zxDJxNaZk/graphite-metrics?orgId=1&refresh=1m&from=1575438321300&to=1575459921300&var-Host=master1&panelId=4&width=1000&height=500&tz=Europe%2FBerlin&render=1"
t=2019-12-04T12:39:22+0000 lvl=error msg="Request Completed" logger=context userId=1 orgId=1 uname=admin method=GET path=/render/d-solo/zxDJxNaZk/graphite-metrics status=500 remote_addr=192.168.106.101 time_ms=310 size=1722 referer="https://grafana.xxx-xxx/d/zxDJxNaZk/graphite-metrics?orgId=1&refresh=1m"

If this happens, then you have to add the certificate to the trust store. If you have the certificate file for the internal root CA in the file internal-root-ca.crt.pem, then use these commands to create a user specific NSS trust store for the Grafana user (grafana for the purpose of this example) and execute the following steps:

Linux:

[root@server ~]# [ -d /usr/share/grafana/.pki/nssdb ] || mkdir -p /usr/share/grafana/.pki/nssdb
[root@merver ~]# certutil -d sql:/usr/share/grafana/.pki/nssdb -A -n internal-root-ca -t C -i /etc/pki/tls/certs/internal-root-ca.crt.pem
[root@server ~]# chown -R grafana: /usr/share/grafana/.pki/nssdb

Windows:

certutil –addstore "Root" <path>/internal-root-ca.crt.pem

Custom Chrome/Chromium

As a last resort, if you already have Chrome or Chromium installed on your system, then you can configure the Grafana Image renderer plugin to use this instead of the pre-packaged version of Chromium.

Note: Please note that this is not recommended, since you may encounter problems if the installed version of Chrome/Chromium is not compatible with the Grafana Image renderer plugin.

To override the path to the Chrome/Chromium executable in plugin mode, set an environment variable and make sure that it’s available for the Grafana process. For example:

export GF_PLUGIN_RENDERING_CHROME_BIN="/usr/bin/chromium-browser"

In remote rendering mode, you need to set the environment variable or update the configuration file and make sure that it’s available for the image rendering service process:

CHROME_BIN="/usr/bin/chromium-browser"

{
  "rendering": {
    "chromeBin": "/usr/bin/chromium-browser"
  }
}