Grafana

Note: Information here is based on the following app version: 1.0.0.

Grafana is an open source analytics and monitoring tool which can be used to visualise data from Obcerv and create alerts. If you have existing Grafana installs, you can seamlessly integrate data from Obcerv into your current dashboards.

You can also create visualisations using Obcerv Dashboards.

Prerequisites

The Grafana integration requires the API gateway

Install

You can install a Grafana instance in the same cluster as Obcerv. Then you must configure the data source in Grafana to create dashboards using Obcerv data.

It is also possible to configure the Obcerv data source in an existing Grafana instance. However, some features may not be available.

Install Grafana

To install the Grafana app:

  1. Create a chart config file named grafana.yaml with contents similar to:

    externalHostname: www.obcerv.local
    ingress:
      annotations:
        kubernetes.io/ingress.class: "nginx"
        nginx.org/mergeable-ingress-type: "minion"
    
    • The externalHostname parameter must match the DNS name configured above (apps.externalHostname).
    • Your ingress controller may require custom annotations in the ingress field (this example is for ingress-nginx).
  2. Install using the chart and your config.

    • To install with certificates signed by a trusted CA, run:
      helm install -f grafana.yaml obcerv-app-grafana itrs/obcerv-app-grafana --version 1.0.0.XX -n itrs --wait
      
    • To install with self-signed certificates, run:
      helm install -f grafana.yaml obcerv-app-grafana itrs/obcerv-app-grafana --version 1.0.0.XX -n itrs  --set api.tlsSkipVerify=true --wait
      

Once the pod is ready, Grafana will be accessible via https://www.obcerv.local/grafana (adjusted to your actual DNS name) with the default login of obcerv/obcerv. Click Sign in with OAuth to login.

Configure the data source

Once you have logged into Grafana, you must configure the Obcerv data source.

To add a new data source:

  1. Go to Configuration > Data sources in the Grafana navigation panel.
  2. Click on Add data source, search for ITRS Group Obcerv and select it.
  3. Specify the data source settings. The following settings are available: Data source image
    Field Description
    Name Specify a display name for the data source.
    Obcerv API Host and port of the Obcerv REST API, for example, https://local.itrslab.com/api
    Skip tls verification If you want to skip the TLS verification.
  1. Click on Save & test to save the configuration.

For more information, see the official Grafana doc to add a data source here.

Query the data source

To visualise data from Obcerv, you can create a new panel in a new or existing Grafana dashboard.

  1. Open a dashboard or create a new dashboard.
  2. Click the Add Panel button.
  3. Click Add Query.
  4. Set the Query to the Obcerv data source using the name you specified above.
  5. Specify the query parameters: Obcerv query editor image
    Field Description
    Alias Displayed in the legend to identify a time series.
    Metric Name of the metric.
    Filter Filters will be available for auto-completion when composing a query, they are in the form attribute/dimension=“value”. For example pod=“collection-agent-sx6cv”
    Group by Dimensions or attributes to group by the results.
    Buckets Used to populate the Buckets in BucketRequest.
    Bucket function Used to populate the Function in BucketRequest.
    Forecast If enabled, returns the forecast of the selected metric. Please note that it only works if the filter returns only one metric.

To use status metrics, select the metric and select All fields to display non-numeric fields:

Status metrics

Templates and variables

You can define variables in Grafana that allow you to dynamically change the data displayed on your dashboards. You can use the Obcerv data source to populate variables.

To add a new ITRS Group Obcerv query variable:

  1. Open the Dashboard settings menu.
  2. Click Variables.
  3. Click New.
  4. Configure the variable using the following options: variable configuration image
    Field Description
    Name Variable name, this name will be used in the data source to refer to the variable with the $ symbol in front.
    Label Label of the text box displayed in the panel.
    Data source Specify ITRS Group Obcerv.
    Query Specify the query used to populate the variables list.
  5. (optional) You can check multi-value switch if you want to choose more than one value for the variable.
  6. To see a preview of the values, click Update.

Grafana query syntax

The syntax for the Query used to get the variable values is json with the form:

{ "name": "<dimension-or-attribute>" }

Consider as an example:

{ "name": "container" }

Variables with filter

Variables can be filtered by another variable, using a dimension or an attribute. The syntax to populate variables with a filter is:

{ "name": "<dimension-or-attribute>", "filter": [{ "name": "<dimension-or-attribute>", "value": "$variableName1" }] }

The filter is a list of objects with the fields name and value. The name must be an attribute or dimension name, the value can be a specific value or the name of another variable with the $preffix. For example, if a variable named kubecontainer exists, then the query could be:

{ "name": "pod", "filter": [{ "name": "container", "value": "$kubecontainer" }] }

This allows variable chaining so the values of some variables can be used to filter other dependant variables.

["Obcerv"] ["User Guide"]

Was this topic helpful?