From 75bf31b5c7c3ea3626969446d956872f76cb51b9 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Tue, 17 Sep 2019 19:24:03 +0200 Subject: [PATCH] docs: image rendering (#19183) Adds a new "Image Rendering" page in Administration section. Updates configuration page with rendering settings and also default.ini and sample.ini. Updates and cleanup pages that referencing image rendering. Ref #18914 --- conf/defaults.ini | 4 +- conf/sample.ini | 4 +- .../sources/administration/image_rendering.md | 51 +++++++++++++++++++ docs/sources/alerting/notifications.md | 4 +- docs/sources/installation/configuration.md | 11 ++++ docs/sources/reference/sharing.md | 4 +- 6 files changed, 73 insertions(+), 5 deletions(-) create mode 100644 docs/sources/administration/image_rendering.md diff --git a/conf/defaults.ini b/conf/defaults.ini index c825f2374d2..3bb57c3ac72 100644 --- a/conf/defaults.ini +++ b/conf/defaults.ini @@ -669,8 +669,10 @@ container_name = # does not require any configuration [rendering] -# Options to configure external image rendering server like https://github.com/grafana/grafana-image-renderer +# Options to configure a remote HTTP image rendering service, e.g. using https://github.com/grafana/grafana-image-renderer. +# URL to a remote HTTP image renderer service, e.g. http://localhost:8081/render, will enable Grafana to render panels and dashboards to PNG-images using HTTP requests to an external service. server_url = +# If the remote HTTP image renderer service runs on a different server than the Grafana server you may have to configure this to a URL where Grafana is reachable, e.g. http://grafana.domain/. callback_url = [panels] diff --git a/conf/sample.ini b/conf/sample.ini index b215a4fb02d..7e8d96065b9 100644 --- a/conf/sample.ini +++ b/conf/sample.ini @@ -598,8 +598,10 @@ # does not require any configuration [rendering] -# Options to configure external image rendering server like https://github.com/grafana/grafana-image-renderer +# Options to configure a remote HTTP image rendering service, e.g. using https://github.com/grafana/grafana-image-renderer. +# URL to a remote HTTP image renderer service, e.g. http://localhost:8081/render, will enable Grafana to render panels and dashboards to PNG-images using HTTP requests to an external service. ;server_url = +# If the remote HTTP image renderer service runs on a different server than the Grafana server you may have to configure this to a URL where Grafana is reachable, e.g. http://grafana.domain/. ;callback_url = [enterprise] diff --git a/docs/sources/administration/image_rendering.md b/docs/sources/administration/image_rendering.md new file mode 100644 index 00000000000..1e1801e6987 --- /dev/null +++ b/docs/sources/administration/image_rendering.md @@ -0,0 +1,51 @@ ++++ +title = "Image Rendering" +description = "" +keywords = ["grafana", "image", "rendering", "phantomjs"] +type = "docs" +aliases = ["/installation/image-rendering"] +[menu.docs] +parent = "admin" +weight = 8 ++++ + +# Image Rendering + +Grafana supports rendering of panels and dasnhboards as PNG-images. + +When an image is being rendered the PNG-image is temporary written to the filesystem, i.e. a sub-directory of Grafana's [data](/installation/configuration/#data) directory named `png`. + +A background job runs each 10 minutes and will remove temporary images. You can configure how long time an image should be stored before being removed by configuring the [temp-data-lifetime](/installation/configuration/#temp-data-lifetime) setting. + +## Rendering methods + +### PhantomJS + +> PhantomJS is deprecated since Grafana v6.4 and will be removed in a future release. Please migrate to Grafana image renderer plugin or remote rendering service. + +[PhantomJS](https://phantomjs.org/) have been the only supported and default image renderer since Grafana v2.x and is shipped with Grafana. + +Please note that for OSX and Windows, you will need to ensure that a phantomjs binary is available under tools/phantomjs/phantomjs. For Linux, a phantomjs binary is included - however, you should ensure that any required libraries, e.g. libfontconfig1, are available. + +### Grafana image renderer plugin + +The [Grafana image renderer plugin](https://grafana.com/grafana/plugins/grafana-image-renderer) is a plugin that runs on the backend and handles rendering panels and dashboards as PNG-images using headless chrome. + +You can install it using grafana-cli: + +```bash +grafana-cli plugins install grafana-image-renderer +``` + +For further information and instructions refer to the [plugin details](https://grafana.com/grafana/plugins/grafana-image-renderer). + +### Remote rendering service + +The [Grafana image renderer plugin](https://grafana.com/grafana/plugins/grafana-image-renderer) can also be run as a remote HTTP rendering service. In this setup Grafana will render an image by making a HTTP request to the remote rendering service, which in turn render the image and returns it back in the HTTP response to Grafana. + +To configure Grafana to use a remote HTTP rendering service, please refer to [rendering](/installation/configuration/#rendering) configuration section. + +## Alerting and render limits + +Alert notifications can include images, but rendering many images at the same time can overload the server where the renderer is running. For instructions of how to configure this, see [concurrent_render_limit](/installation/configuration/#concurrent-render-limit). + diff --git a/docs/sources/alerting/notifications.md b/docs/sources/alerting/notifications.md index 7ec53e402b1..e2231986eec 100644 --- a/docs/sources/alerting/notifications.md +++ b/docs/sources/alerting/notifications.md @@ -190,7 +190,9 @@ Webhook | `webhook` | yes, external only | yes # Enable images in notifications {#external-image-store} -Grafana can render the panel associated with the alert rule and include that in the notification. Most Notification Channels require that this image be publicly accessible (Slack and PagerDuty for example). In order to include images in alert notifications, Grafana can upload the image to an image store. It currently supports +Grafana can render the panel associated with the alert rule as a PNG image and include that in the notification. Read more about the requirements and how to configure image rendering [here](/administration/image_rendering/). + +Most Notification Channels require that this image be publicly accessible (Slack and PagerDuty for example). In order to include images in alert notifications, Grafana can upload the image to an image store. It currently supports Amazon S3, Webdav, Google Cloud Storage and Azure Blob Storage. So to set that up you need to configure the [external image uploader](/installation/configuration/#external-image-storage) in your grafana-server ini config file. Be aware that some notifiers requires public access to the image to be able to include it in the notification. So make sure to enable public access to the images. If you're using local image uploader, your Grafana instance need to be accessible by the internet. diff --git a/docs/sources/installation/configuration.md b/docs/sources/installation/configuration.md index 2920cd2c235..ade8cb296ce 100644 --- a/docs/sources/installation/configuration.md +++ b/docs/sources/installation/configuration.md @@ -688,6 +688,17 @@ Default setting for alert notification timeout. Default value is `30` Default setting for max attempts to sending alert notifications. Default value is `3` +## [rendering] + +Options to configure a remote HTTP image rendering service, e.g. using https://github.com/grafana/grafana-image-renderer. + +### server_url + +URL to a remote HTTP image renderer service, e.g. http://localhost:8081/render, will enable Grafana to render panels and dashboards to PNG-images using HTTP requests to an external service. + +### callback_url + +If the remote HTTP image renderer service runs on a different server than the Grafana server you may have to configure this to a URL where Grafana is reachable, e.g. http://grafana.domain/. ## [panels] diff --git a/docs/sources/reference/sharing.md b/docs/sources/reference/sharing.md index aebf76090f3..7f9599d0040 100644 --- a/docs/sources/reference/sharing.md +++ b/docs/sources/reference/sharing.md @@ -39,12 +39,12 @@ Click a panel title to open the panel menu, then click share in the panel menu t ### Direct Link Rendered Image -You also get a link to service side rendered PNG of the panel. Useful if you want to share an image of the panel. Please note that for OSX and Windows, you will need to ensure that a `phantomjs` binary is available under `tools/phantomjs/phantomjs`. For Linux, a `phantomjs` binary is included - however, you should ensure that any requisite libraries (e.g. libfontconfig1) are available. +You also get a link to render a PNG image of the panel. Useful if you want to share an image of the panel. Read more about the requirements and how to configure image rendering [here](/administration/image_rendering/). Example of a link to a server-side rendered PNG: ```bash -http://play.grafana.org/render/dashboard-solo/db/grafana-play-home?orgId=1&panelId=4&from=1499272191563&to=1499279391563&width=1000&height=500&tz=UTC%2B02%3A00&timeout=5000 +https://play.grafana.org/d/000000012/grafana-play-home?orgId=1&from=1568719680173&to=1568726880174&panelId=4&fullscreen ``` #### Query String Parameters For Server-Side Rendered Images