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 or Elasticsearch cluster and Grafana as well as configuring Unblu Spark.

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

Data analytics are 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 Unblu team.

Users are allowed only to view the data. They can’t update data sources or dashboards. All dashboards are predefined in Unblu Spark and synchronized when an admin logs in to data analytics. If you need additional dashboards, contact the Unblu support team.

Data analytics are primarily intended for use with the Unblu Cloud. If you want to use them 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.
To deploy an Elasticsearch cluster, you can use the helm chart provided by Elastic.

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 Grafana settings:

Table 1. Mandatory Grafana settings
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, set com.unblu.analytics.enabled to true.

Search engine configuration

First specify the type of search engine you want to use in com.unblu.search.engine.type. The possible values are OPEN_SEARCH and ELASTIC_SEARCH. The default value is OPEN_SEARCH.

Depending on whether you use Elasticsearch or OpenSearch, you have to set different configuration properties to configure the search engine:

If you use OpenSearch, the configuration properties are named com.unblu.search.engine.os.*.
If you use Elasticsearch, the configuration properties are named com.unblu.search.engine.es.*.

In the table below, both keys are listed in the first column. Set the property appropriate for the type of search engine you deployed.

Table 2. Mandatory Collaboration Server configuration properties related to the search engine
Property name	Description
com.unblu.search.engine.os.host com.unblu.search.engine.es.host	URL of the search cluster with port, for example https://opensearch:9200. Defined during cluster deployment.
com.unblu.search.engine.os.username com.unblu.search.engine.es.username	The username of the user created in the search cluster. Must have index, create, and update permissions.
com.unblu.search.engine.os.password com.unblu.search.engine.es.password	The password of the user created in the search cluster.
com.unblu.search.engine.os.authType com.unblu.search.engine.es.authType	The authentication type to use for the search cluster. For OpenSearch, the possible values are `BASIC` and `NO_AUTH`; the default value is `BASIC`. For Elasticsearch, the possible values are `API_KEY`, `BASIC`, `NO_AUTH` and `TOKEN`; the default value is `BASIC`.

Three configuration properties are exclusive to Elasticsearch:

com.unblu.search.engine.es.token specifies the token to use if the Elasticsearch authentication type is TOKEN. You must set this configuration property if com.unblu.search.engine.es.authType is set to TOKEN.
com.unblu.search.engine.es.apikeyId and com.unblu.search.engine.es.apikeySecret specify the API key and secret, respectively, if the Elasticsearch authentication type is API_KEY. You must set both configuration properties if com.unblu.search.engine.es.authType is set to API_KEY.

Grafana configuration

The table below lists the configuration properties related to Grafana that you must set in the Collaboration Server.

Table 3. Mandatory Collaboration Server configuration properties related to Grafana
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 `opensearch`.
com.unblu.analytics.grafana.grafanaDataSourceUrl
URL of the search cluster, for example `https://opensearch:9200`. Must be accessible from Grafana.
com.unblu.analytics.grafana.grafanaDataSourceUsername
Username of the OpenSearch or Elasticsearch user that Grafana accesses the search cluster with. Must have index read permissions.
com.unblu.analytics.grafana.grafanaDataSourcePassword
Password of the OpenSearch or Elasticsearch user that Grafana accesses the search cluster 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.

Use com.unblu.analytics.grafana.dashboards to specify which dashboards are enabled.
To grant non-admin users access to Grafana, enable com.unblu.analytics.grafana.allowAccessToAnalytics.

Accessing external account analytics

To access the analytics, open the Account Configuration interface and click your avatar in the upper right-hand corner. This opens 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