OS4X Grafana Integration

OS4X supports the integration of Grafana (when using the MySQL/MariaDB database backend). It helps you automated in these tasks:

• check the authentication token
• create and check the data source
• create and check the dashboard
• publishing the dashboard anonymously, to be embedded as an iframe in the OS4X admin panel

If one of these tasks has to be manually

Requirements

A Grafana server with installed MySQL Data Source plugin is required. For the configuration of the integration you need an API token with administrative permissions.

Grafana server configuration

Since the panel is being embedded as an HTML iframe, the HTTP response header must not contain "X-Frame-Options: DENY". Change the Grafana configuration (default: /etc/grafana/grafana.ini) the following value:

allow_embedding = true

Restart Grafana afterwards:

systemctl restart grafana-server.service

Authentication token

The dynamic setup of the Grafana data source, dashboard and panel requires an administrative API token. You can generate one in the Grafana admin interface in "Administration" -> "Users and access" -> "Service accounts". Pick an existing service account or create a new one with role "Admin". Add a service account token. The token is only required during setup and can be removed afterwards.

OS4X configuration

Navigate to "Configuration" -> "Grafana" to setup the integration:

Connection

After entering the Grafana API URL and admin API token (optionally an Org-ID value), you can click on "Test connection" which verifies the functionality. If it succeeds, the next button will be enabled.

Data source

The current database connection needs to be defined in Grafana. This only defines the connection, but cannot check its functionality. If something doesn't work with the connectivity, check the chapter "Error resolving hints" below. If the datasource isn't defined in Grafana yet, it will be added automatically. The value of "Datasource UID" will be filled out dynamically. If successful, the last button "Check dashboard" will be enabled.

Dashboard

The last button "Check dashboard" verifies the existance of a dashboard for this OS4X installation (identified by its dynamically created UUID). If the dashboard doesn't exist, it will be created automatically. This dashboard will be named "OS4X throughput per partner - <UUID>". This dashboard will be shared externally from Grafana, so no API token or authentication is required to access its panel. If everything works fine, the dashboard UID and URL will be added dynamically to the configuration panel. You are now ready to save the created and defined values.

Accessing Grafana graph

OS4X integrates the Grafana graph in a separate panel, accessible via the administrative web interface in "Logs" -> "Grafana":