---
title: "ITRS Analytics data source plugin for Grafana"
description: "Data source for ITRS Analytics platform. ITRS Analytics data source plugin for Grafana by ITRS Group. Available in Grafana Cloud and self-managed Grafana."
---

> This is the Markdown version of https://grafana.com/grafana/plugins/itrs-analytics-datasource/

# ITRS Analytics

- Developer: ITRS Group
- Version: 3.5.0
- [Installation](https://grafana.com/grafana/plugins/itrs-analytics-datasource/installation.md)
- [Change log](https://grafana.com/grafana/plugins/itrs-analytics-datasource/changelog.md)

![config-empty](https://grafana.com/api/plugins/itrs-analytics-datasource/versions/3.5.0/images/img/config-empty-panel.png)

![query-empty](https://grafana.com/api/plugins/itrs-analytics-datasource/versions/3.5.0/images/img/query-empty-panel.png)

![variable-empty](https://grafana.com/api/plugins/itrs-analytics-datasource/versions/3.5.0/images/img/variable-empty-panel.png)

![add-variable](https://grafana.com/api/plugins/itrs-analytics-datasource/versions/3.5.0/images/img/add-variable-panel.png)

![query-use-variable](https://grafana.com/api/plugins/itrs-analytics-datasource/versions/3.5.0/images/img/query-use-variable-panel.png)

# ITRS Analytics data source for Grafana

## Prerequisites

The ITRS Analytics datasource connects exclusively to the **API Gateway**. It does not call individual platform services directly.

- The API Gateway must be deployed and expose **Public API v2** (`/api/v2/*`).
- **API Gateway 2.14.0 or later** is required.
- **Grafana 12.0.0 or later** is required.

| Query type         | Minimum API Gateway version |
| ------------------ | --------------------------- |
| Metrics            | 2.7.0                       |
| Logs               | 2.10.0                      |
| Lookup / variables | 2.14.0                      |

Authentication is handled by Grafana: users log in via the platform IAM (OAuth), and the datasource uses that session. The plugin does not have separate credentials.

## Datasource Usage

### Configure the data source

1. Go to Configuration > Data sources section

2. Click on "Add data source" and look for "ITRS Analytics" one and select it

ITRS Analytics Settings

| Field                 | Description                                                                          |
| --------------------- | ------------------------------------------------------------------------------------ |
| ITRS Analytics API    | Base URL of the API Gateway, i.e. `https://local.itrslab.com/obcerv-app-api-gateway` |
| Skip tls verification | If you want to skip the TLS verification                                             |

You can also click on the _Default_ switch on the top of the screen if you want it to appear as default datasource.

Click on _Save and test_ to save the configuration

(You can see the official Grafana doc to add a datasource [here](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/))

### Query the data source

At the top of the panel query editor, use the **Mode** radio to select **Metrics** or **Logs**. Metrics mode is the default when no mode is set.

Use a **time series**, **stat**, or **table** panel for metrics queries. Use Grafana's **Logs** panel for log queries.

#### Metrics mode

| Field           | Description                                                                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alias           | Optional legend label for the series                                                                                                                                  |
| Filter          | Build one or more entity filters via autocomplete (dimension or attribute name, `=` operator, value). Example chip: `pod = my-pod`. Multiple filters can be combined. |
| Metric          | Metric name (searchable combobox; shows namespace when present)                                                                                                       |
| Group by        | Dimensions to group results                                                                                                                                           |
| Buckets         | Time bucket interval (e.g. one minute, five minutes). Leave unset for automatic bucketing.                                                                            |
| Bucket function | Aggregation within each bucket: Avg (default), Sum, Min, Max, Count, First, Last, Rate, Percentile (with percentile selector)                                         |

- Note: Stat visualization, to use status metrics on "Options Panel", "Value options" section, select in Fields drop-down _All fields_ in order to display not only numeric fields.

#### Logs mode

Selecting **Logs** shows a **Search** radio with **Simple** or **Advanced** options.

**Simple search**

| Field    | Description                                                                               |
| -------- | ----------------------------------------------------------------------------------------- |
| Log name | Combobox of discovered log sources for the dashboard time range. Query runs on selection. |

**Advanced search**

| Field              | Description                                                                                                                                                                                               |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Log name           | Log source name (required)                                                                                                                                                                                |
| Log namespace      | Log source namespace (required)                                                                                                                                                                           |
| Dimensions         | One or more dimension key/value pairs (required; use _Add dimension_ for more rows). **Value** accepts dashboard template variables with a `$` prefix (e.g. Key `managedEntity`, Value `$managedEntity`). |
| Message contains   | Optional; one substring per line, OR-matched against log message text                                                                                                                                     |
| Trace id / Span id | Optional filters                                                                                                                                                                                          |
| Max lines          | Optional result cap                                                                                                                                                                                       |
| Oldest first       | Switch to return oldest log lines first                                                                                                                                                                   |
| Run query          | Click to execute (advanced mode does not auto-run on field change)                                                                                                                                        |

### Templates and variables

You can add variables to your dashboard. Go to dashboard settings and click _Add variable_ in the _Variables_ section.

Variables apply to metrics **Filter** values, Advanced logs **Dimensions** values, and dashboard Query-variable lookups (metric lookups).

You can **use** common Grafana variable types in those fields (Query, Textbox, Constant, Custom, Datasource, Interval, and similar) by referencing them with a `$` prefix. To **populate** a variable’s options from ITRS Analytics, create a **Query** variable that targets this data source (see metric lookups below).

To switch between IAX datasource instances on a panel, create a Grafana **Datasource** variable filtered to this plugin and set the panel’s data source to that variable. Grafana routes the query to the selected instance; the plugin accepts Datasource variables so their presence on the dashboard does not break queries.

In a metrics panel, you can reference a dashboard variable in a **Filter** expression value. Compose the filter as usual (dimension name, `=`, value) and enter the variable with a `$` prefix, for example `pod=$pod` or `container=$containerVar`. When the dashboard variable changes, the filter is resolved at query time and the panel refreshes.

In an **Advanced logs** panel, choose the dimension **Key** from lookup (e.g. `managedEntity` or `host`) and enter the dashboard variable in **Value** (e.g. `$managedEntity` or `$host`). Resolved dimension values are sent to `POST /api/v2/logs/log-data` when the query runs; changing the dashboard variable refreshes the log panel without re-editing the dimension fields.

**Multi-value note:** At most one multi-value variable is supported. The plugin fans out one API request per selected value of that variable.

**Metric lookups** (below) refer to the JSON query used when defining dashboard Query variables, not to the panel Metric combobox.

Required fields for a Query variable that loads values from this data source:

General

| Field | Value                                                                                                        |
| ----- | ------------------------------------------------------------------------------------------------------------ |
| Name  | Variable name, this name will be used in the data source to refer to the variable with the $ symbol in front |
| Type  | Query                                                                                                        |

Query Options

| Field       | Value                                                                       |
| ----------- | --------------------------------------------------------------------------- |
| Data source | ITRS Analytics                                                              |
| Query       | syntax: {"name":"dimension-or-attribute"}, example: { "name": "container" } |

- Note: Selection options, check multi-value switch if you want to choose more than one value for the variable

If you want to see a preview of the values, click on _Update_.

Then you can filter the widgets you want to depend on the variable using the name with a `$`:

```json
{ "name": "$<variable-name>" }
```

And you will be able to use the [variable in your dashboard](https://grafana.com/docs/grafana/latest/variables/).

#### Variables with filter

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

```json
{ "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 `$` prefix. For example, if it exists a variable named `kubecontainer`, the query could be:

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

This will allow variable chaining so the values of some variables can be used to filter other _dependant_ variables.

Some useful links with information about query variables:

[Add a query variable](https://grafana.com/docs/grafana/latest/variables/variable-types/add-query-variable/)

[Variable syntax](https://grafana.com/docs/grafana/latest/variables/syntax/)

[Templates and variables](https://grafana.com/docs/grafana/latest/variables/)
