Project: YDB (App Definition and Development / Database)
File: grafana.md

The allows you to use to query and visualize data from {{ ydb-short-name }}. Prerequisites: the plugin requires Grafana `v9.2` or higher. Follow the Grafana's to install a plugin named `ydb-grafana-datasource-plugin`. Set up an {{ ydb-short-name }} user account with read-only permissions and access to databases and tables you want to query. {% note warning %} Please note that Grafana does not validate that queries are safe. Queries can contain any SQL statements, including data modification instructions. {% endnote %} The plugin supports transport protocols. Once the plugin is installed on your Grafana instance, follow to add a new {{ ydb-short-name }} data source, and enter configuration options. Alternatively, Grafana's provisioning system allows you to configure data sources using configuration files. To read about how it works, including all the settings you can set for this data source, refer to the documentation. The Grafana plugin supports the following : Anonymous, Access Token, Metadata, Service Account Key and Static Credentials. Below is an example config for authenticating a {{ ydb-short-name }} data source using username and password: ```yaml apiVersion: 1 datasources: name: YDB type: ydbtech-ydb-datasource jsonData: authKind: '<password>' endpoint: 'grpcs://<hostname>:2135' dbLocation: '<locationtodb>' user: '<username>' secureJsonData: password: '<userpassword>' certificate: | <full content of *.pem file> ``` Here are fields that are supported in connection configuration: | Name | Description | Type | | :- | : | :-: | | authKind | Authentication type | `"Anonymous"`, `"ServiceAccountKey"`, `"AccessToken"`, `"UserPassword"`, `"MetaData"` | | endpoint | Database endpoint | `string` | | dbLocation | Database location | `string` | | user | User name | `string` | | serviceAccAuthAccessKey | Service account access key | `string` (secured) | | accessToken | OAuth access token | `string` (secured) | | password | User password | `string` (secured) | | certificate | If self-signed certificates are used on your {{ ydb-short-name }} cluster nodes, specify the certificate used to issue them | `string` (secured) | {{ ydb-short-name }} is queried with a SQL dialect named . The query editor allows to get data in different representations: time series, table, or logs. Time series visualization options are selectable if the query returns at least one field with `Date`, `Datetime`, or `Timestamp` type (for now, working with time is supported only in UTC timezone) and at least one field with `Int64`, `Int32`, `Int16`, `Int8`, `Uint64`, `Uint32`, `Uint16`, `Uint8`, `Double` or `Float` type. Then, you can select time series visualization options. Any other column is treated as a value

To create a multi-line time series, the query must return at least 3 fields: field with `Date`, `Datetime` or `Timestamp` type (for now, working with time is supported only in UTC timezone) metric - field with `Int64`, `Int32`, `Int16`, `Int8`, `Uint64`, `Uint32`, `Uint16`, `Uint8`, `Double` or `Float` type either metric or field with `String` or `Utf8` type - the value for splitting metrics into separate series. For example: ```sql SELECT `timestamp`, `responseStatus` AVG(`requestTime`) AS `avgReqTime` FROM `/database/endpoint/my-logs` GROUP BY `responseStatus`, `timestamp` ORDER BY `timestamp` ``` Table visualizations will always be available for any valid {{ ydb-short-name }} query that returns exactly one result set. To use the Logs panel, your query must return a `Date`, `Datetime`, or `Timestamp` value and a `String` value. You can select logs visualizations using the visualization options. Only the first text field will be represented as a log line by default. This behavior can be customized using the query builder. The query can contain macros, which simplify syntax and allow for dynamic parts, like date range filters. There are two kinds of macros - and {{ ydb-short-name }}-level. The plugin will parse query text and, before sending it to {{ ydb-short-name }}, substitute variables and Grafana-level macros with particular values. After that {{ ydb-short-name }}-level macroses will be treated by {{ ydb-short-name }} server-side. Here is an example of a query with a macro that will use Grafana's time filter: ```sql SELECT `timeCol` FROM `/database/endpoint/my-logs` WHERE $timeFilter(`timeCol`) ``` ```sql SELECT `timeCol` FROM `/database/endpoint/my-logs` WHERE $timeFilter(`timeCol` + Interval("PT24H")) ``` Macro | Description | Output example | | -- | -- | -- | | `$timeFilter(expr)` | Replaced by a conditional that filters the data (using the provided column or expression) based on the time range of the panel in microseconds | `foo >= CAST(1636717526371000 AS Timestamp) AND foo <= CAST(1668253526371000 AS Timestamp)' )` | | `$fromTimestamp` | Replaced by the starting time of the range of the panel cast to Timestamp | `CAST(1636717526371000 AS Timestamp)` | | `$toTimestamp` | Replaced by the ending time of the range of the panel cast to Timestamp | `CAST(1636717526371000 AS Timestamp)` | | `$varFallback(condition, $templateVar)` | Replaced by the first parameter when the template variable in the second parameter is not provided. | `$varFallback('foo', $bar)` `foo` if variable `bar` is not provided, or `$bar`'s value | To add a new {{ ydb-short-name }} query variable, refer to . After creating a variable, you can use it in your {{ ydb-short-name }} queries by using . For more information about variables, refer to . Add . Configure and use . Add . Set up alerting; refer to .