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.12.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.12.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)

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, 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 $:

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

And you will be able to use the variable in your dashboard.

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:

{ "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:

{ "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

Variable syntax

Templates and variables