Grafana Data Source

Grafana is an open source visualization tool which can be used to visualize data from ITRS Analytics. If you have existing Grafana installs, you can seamlessly integrate data from ITRS Analytics into your current dashboards.

You can also create visualizations using ITRS Analytics Dashboards.

Prerequisites Copied

Note

Starting with Grafana data source version 3.0.2, the new ITRS Analytics data source plugin replaces the previous ITRS Group Obcerv plugin. The old ITRS Group Obcerv plugin is no longer supported.

• Grafana (version 12.x or higher) is installed and running. For more information, refer to the Grafana installation documentation.

• The Grafana and ITRS Analytics Keycloak integration is configured and functioning correctly. For guidance, see How to configure Grafana to authenticate users via ITRS Analytics.

• The API Gateway is deployed and exposes the Public API v2. Metric queries require API Gateway 2.7.0 or later, while log queries require API Gateway 2.10.0 or later.

• Log data is ingested into ITRS Analytics for the entities and time range you want to inspect.

Configure the data source Copied

To download and install the plugin, choose one of the following options:

• From the Grafana Plugins website
• By manually downloading the Grafana data source from the ITRS Resources website

Once you have logged into your instance of Grafana, you must configure the ITRS Analytics data source.

To add a new data source:

1. Go to Administration > Data sources in the Grafana navigation panel.

2. Click Add data source, search for ITRS Analytics and select it.

3. Specify the data source settings. The following settings are available:

   

   Expand table

   Field	Description
   Name	Specify a display name for the data source.
   ITRS Analytics API	Host and port of the ITRS Analytics REST API, for example, 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.

4. Click Save & test to save the configuration.

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

Query the data source Copied

To visualize data from ITRS Analytics, create a panel in a new or existing Grafana dashboard.

1. Open a dashboard or create a new dashboard.
2. Click New > New dashboard, and then click Panel.
3. Click Configure visualization from the main screen or Configure from the panel configuration window on the right.
4. Under Queries, set the data source to ITRS Analytics.
5. Set Mode to Metrics or Logs and specify the query parameters for that mode.

Note

A dashboard can combine metrics and logs from ITRS Analytics. Use separate panels for metrics and logs so each panel uses the visualization type that fits the data (for example, time series for metrics and logs for log lines). Within a panel, you can add multiple queries by clicking Add query to define additional Metrics or Logs queries, each with its own parameters.

Query metrics Copied

Set Mode to Metrics and specify the query parameters:

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

Query logs Copied

The data source can also return log lines from ITRS Analytics. Use Logs mode to search ingested logs and display them in Grafana’s Logs panel.

To create a logs panel:

1. Add or edit a panel and select the Logs visualization type.
2. Under Queries, select ITRS Analytics as the data source.
3. Set Mode to Logs.
4. Choose whether you want to run a Simple or Advanced search. Complete the required fields and run the query.
5. Use the dashboard time picker to set the range of log entries to retrieve.

Simple search Copied

Simple search is the fastest way to get started when you know roughly which log file you need but not its full entity context.

1. Set Search to Simple.
2. Click Log name and type a keyword to filter the list of known log sources.
3. Select a log source from the dropdown.

The data source discovers log sources by calling the API endpoint POST /api/v2/logs/log-sources for the current dashboard time range (up to 10,000 sources per request). Options are filtered by the text you type against the actual log name.

Each option shows:

• Label — the log source name (for example output.log).
• Description — the log namespace and a summary of entity dimensions (for example itrsgroup.com/c2/kubernetes-plugin | pod=my-pod, namespace=itrs).

When you select a source, the data source stores the log name, namespace, and entity dimensions from the API response and runs the query automatically. Clearing the selection removes those values.

Advanced search Copied

Advanced search lets you specify the log source manually and refine which log lines are returned.

1. Set Search to Advanced.

2. Enter Log name and Log namespace.

3. Add one or more Dimensions rows:

   • Key — type to search dimension names. Suggestions come from POST /api/v2/lookup/names (dimensions only). Select a name from the list.
   • Value — type to search values for the selected key. Suggestions come from POST /api/v2/lookup/values, using the dimension’s namespace when available, or the log namespace as a fallback.
   • Click Add dimension for additional key/value pairs, or Remove to delete a row.

4. Optionally refine the query using the fields below:

   • Message contains — one substring per line. Log lines match if the message contains any of these substrings (OR logic).
   • Trace id — return only log lines with this trace ID.
   • Span id — return only log lines with this span ID.
   • Max lines — maximum number of log lines to return. Leave empty to use the API default (1000 lines). The API accepts up to 10,000.
   • Oldest first — when enabled, results are sorted oldest-to-newest. When disabled (default), results are newest first.

5. Click Run query.

Fields marked with * are required before the data source sends a log query. If any required value is missing, the panel returns no log lines. The data source sends the completed query to POST /api/v2/logs/log-data.

Log line results Copied

Each returned log line includes:

If a log line includes a trace ID, Grafana can use it for trace correlation in supported visualizations.

Templates and variables Copied

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

To add a new ITRS Group ITRS Analytics query variable:

1. Go to the Dashboards and click Edit to switch to edit mode.

2. Open the Dashboard settings.

3. Click Variables > Add variable.

4. Configure the variable using the following options:

   

   Expand table

   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 Analytics.
   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 Run query.

Grafana query syntax Copied

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

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

Consider this as an example:

{ "name": "container" }

Variables with filter Copied

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 dependent variables.

Variables in log queries Copied

Log query fields support the same dashboard variables as metric queries. Use ${variable} or $variable in log name, log namespace, dimensions, message filters, or trace and span id fields. For example, ${log_namespace} in Log namespace.