Adding data analytics for an Unblu Spark cluster

You can deploy data analytics tools to give your Unblu admins a better view of the data and events within your Unblu Spark installation. This involves deploying an OpenSearch cluster and Grafana as well as configuring Unblu Spark.

The Collaboration Server serves as an auth proxy. Neither Grafana nor the OpenSearch cluster need to be exposed to the internet.

Data analytics is accessible to Unblu users with the ADMIN role. Users with the SUPERVISOR role can also access data analytics if they’re supervisors of the default team.

This user is allowed only to view the data. Neither data source nor dashboard updates are possible. All dashboards are predefined in Unblu Spark and synchronized when an admin logs into Data analytics. The dashboards can’t be changed. If you need additional dashboards, contact the Unblu support team.

Data analytics is primarily intended for use with the Unblu Cloud. If you want to use it with an on-premises installation of Unblu Spark, contact the Unblu support team.

OpenSearch cluster deployment and configuration

The easiest way to deploy an OpenSearch cluster is to use either a Helm chart or an operator.

When your cluster is up and running, create a new user for it with permission to create, read, and update indices.

Grafana deployment

We recommend that you use a separate Grafana deployment. You can configure it by providing a grafana.ini file on startup. For more information, refer to the Grafana documentation.

The Grafana deployment must be configured to use auth proxy as an authentication method. The table below describes the other required settings:

Table 1. Mandatory Grafana configuration properties
Name	Description
[auth.proxy] section
`enabled`	Enables auth proxy authentication
`header_name`	Header used for authentication. Must be set to `X-WEBAUTH-USER`.
`header_property`	Defines which of user’s properties is passed int `X-WEBAUTH-USER` header. Must be set to `username`.
`auto_sign_up`	Defines if Grafana creates new user if one provided in the auth header doesn’t exist. Set to `false` as we do it automatically.
`headers_encoded`	Encoding for non-ASCII characters in the auth header. Set to `false`, we don’t need this.
`enable_login_token`	Set to `false`. Required headers are passed automatically.
`headers`	Defines which information Grafana can find in auth headers. Must be set to `Name:X-WEBAUTH-NAME Email:X-WEBAUTH-EMAIL Role:X-WEBAUTH-ROLE`.
[users] section
`allow_sign_up`	Allows users to sign up manually. Set to `false`; this process is automated.
`auto_assign_org`	When set to `false`, new users automatically cause a new organization to be created for that new user. Set it to `true` as organizations are created using the API.
`auto_assign_org_role`	Sets the default role for new users. Set to `Viewer`.
[server] section
`domain`	Set to the root URL of the Collaboration Server including the protocol but without a trailing slash
`root_url`	Set to the root URL of the Collaboration Server including the protocol, followed by the Grafana auth proxy path with a trailing slash
[live] section
`max_connections`	Set to `0` to disable web sockets usage in Grafana. If you don’t, error logs might be visible in Unblu Spark and Grafana itself.

Your grafana.ini file should end up looking similar to the example below:

Listing 1. Example grafana.ini config file

[snapshots]
external_snapshot_url = https://my-unblu-deployment-domain.com/app/grafana (1)
external_snapshot_name = Send to Unblu
[auth.proxy]
enabled: true
header_name: X-WEBAUTH-USER
header_property: username
auto_sign_up: false
enable_login_token: false
headers: "Name:X-WEBAUTH-NAME Email:X-WEBAUTH-EMAIL Role:X-WEBAUTH-ROLE"
[users]
allow_sign_up: false
auto_assign_org: true
auto_assign_org_role: Viewer
[server]
domain: https://my-unblu-deployment-domain.com (2)
root_url: https://my-unblu-deployment-domain.com/app/grafana/ (3)
[live]
max_connections: 0

1	Only required if you use Grafana’s snapshot feature. Replace the URL with the appropriate value for your deployment.
2	Replace with the appropriate URL for your Grafana installation.
3	Replace with the domain of your Unblu deployment.

Collaboration Server configuration

To enable External Analytics in the Collaboration Server, a bunch of additional properties must be set.

Table 2. Mandatory Collaboration Server properties
Property name	Description
com.unblu.analytics.enabled	Enables OpenSearch cluster configuration.
com.unblu.search.engine.es.host	URL of the OpenSearch cluster with port, for example https://opensearch:9200. Defined during cluster deployment.
com.unblu.search.engine.es.username	The username of the user created in the OpenSearch cluster. Must have index create and update permissions.
com.unblu.search.engine.es.password	The password of the user created in the OpenSearch cluster.
com.unblu.analytics.grafana.enabled	Enables Grafana configuration.
com.unblu.analytics.grafana.grafanaRootUrl	The host of the Grafana deployment, for example `http://grafana:3000/app/grafana`. The URL must end in `/app/grafana` as this is the path used within the Spark auth proxy.
com.unblu.analytics.grafana.grafanaAdminUser	Username of the Grafana user. Used to manage users and organizations. Must have admin permissions.
com.unblu.analytics.grafana.grafanaAdminPassword	Password of the Grafana user.
com.unblu.analytics.grafana.grafanaDataSourceName	Name of the datasource created in Grafana for each user, for example `elasticsearch`.
com.unblu.analytics.grafana.grafanaDataSourceUrl	URL of the OpenSearch cluster, for example `https://opensearch:9200`. Must be accessible from Grafana.
com.unblu.analytics.grafana.grafanaDataSourceUsername	Username of the OpenSearch user that Grafana accesses OpenSearch with. Must have index read permissions.
com.unblu.analytics.grafana.grafanaDataSourcePassword	Password of the OpenSearch user that Grafana accesses OpenSearch with.
com.unblu.ui.usermenu.showExternalAccountAnalytics	Enables access to External Analytics from Unblu admin panel. Set to `true`.
com.unblu.ui.usermenu.itemExternalAccountAnalytics	The label of the menu item to access External Analytics. The default value is `Account analytics`.

Accessing external account analytics

To access the analytics, open the Account Configuration interface and click your avatar in the upper right-hand corner to open the user menu. In the menu, click Account analytics to open Grafana.

Figure 1. Account analytics menu item

This opens Grafana. You can now access the dashboards through the burger menu in the top-left corner:

Figure 2. Navigate to Grafana dashboards

Adding data analytics for an Unblu Spark cluster

OpenSearch cluster deployment and configuration

Grafana deployment

Collaboration Server configuration

Accessing external account analytics

See also