Connect à une source de données PostgreSQL

Vous pouvez utiliser la source de données PostgreSQL pour interroger et visualiser les données de vos bases de données Amazon Aurora PostgreSQL.

Important

Grafana version 8 modifie la structure de données sous-jacente des trames de données pour les sources de données Postgres, MySQL et Microsoft SQL Server. Par conséquent, le résultat d'une requête de série chronologique est renvoyé dans un format large. Pour plus d'informations, consultez la section Format large dans la documentation des trames de données Grafana. Pour que vos visualisations fonctionnent comme elles le faisaient avant la version 8, vous devrez peut-être effectuer des migrations manuelles. Une solution est documentée sur Github à l'adresse Postgres/MySQL/MSSQL : modification majeure de la version 8.0 concernant les requêtes de séries chronologiques et l'ordre des colonnes de données.

Dans la version 9 de Grafana, la source de données PostgreSQL configure le certificat racine pour la connexion à votre base de données différemment des versions précédentes. Si vous mettez à jour votre espace de travail de la version 8 à la version 9, vous devrez peut-être modifier le mode de connexion. Pour plus d’informations, consultez Résolution des problèmes liés aux espaces de travail mis à jour.

Ajouter la source de données

1. Ouvrez le menu latéral en choisissant l'icône Grafana dans l'en-tête supérieur.

2. Dans le menu latéral, sous l'icône de configuration, vous devriez trouver un lien vers les sources de données.

3. Cliquez sur le bouton + Ajouter une source de données dans l'en-tête supérieur.

4. Sélectionnez PostgreSQL dans la liste déroulante Type.

Options de source de données

Name (Nom)	Description
Name	Le nom de la source de données. C'est ainsi que vous voyez la source de données dans les panneaux et les requêtes.
Default	La source de données par défaut signifie qu'elle sera présélectionnée pour les nouveaux panneaux.
Host	Adresse IP/nom d'hôte et port facultatif de votre instance PostgreSQL. N'incluez pas le nom de la base de données. La chaîne de connexion pour la connexion à Postgres ne sera pas correcte et provoquera des erreurs.
Database	Nom de votre base de données PostgreSQL.
User	Login/nom d'utilisateur de l'utilisateur de la base de données.
Password	Mot de passe utilisateur de la base de données
SSL Mode	Cette option détermine si ou avec quelle priorité une connexion TCP/IP SSL sécurisée sera négociée avec le serveur.
Max open	Nombre maximum de connexions ouvertes à la base de données, par défaut unlimited (Grafana v5.4+).
Max idle	Nombre maximal de connexions dans le pool de connexions inactives, par défaut 2 (Grafana v5.4+).
Max lifetime	Durée maximale en secondes pendant laquelle une connexion peut être réutilisée, 14400 4 heures par défaut (Grafana v5.4+).
Version	Cette option détermine les fonctions disponibles dans le générateur de requêtes (uniquement disponible dans Grafana 5.3+).
TimescaleDB	TimescaleDB est une base de données de séries chronologiques créée sous forme d'extension PostgreSQL. Si cette option est activée, Grafana utilisera time_bucket dans la $__timeGroup macro et affichera des fonctions d'agrégation spécifiques à TimescaleDB dans le générateur de requêtes (uniquement disponible dans Grafana 5.3+).

Intervalle de temps minimum

Une limite inférieure pour les $_interval $_interval_ms variables. Il est recommandé de régler la fréquence d'écriture, par exemple 1m si vos données sont écrites toutes les minutes. Cette option peut également être remplacée/configurée dans un panneau de tableau de bord sous Options de source de données. Cette valeur doit être formatée sous la forme d'un nombre suivi d'un identifiant horaire valide, par exemple 1m (1 minute) ou 30s (30 secondes). Les identifiants horaires suivants sont pris en charge.

Identifiant	Description
y	Année
M	Mois
w	semaine
d	jour
h	Heure
m	Minute
s	Seconde
ms	Milliseconde

Autorisations utilisateur de base de données

Important

L'utilisateur de base de données que vous spécifiez lorsque vous ajoutez la source de données ne doit disposer des autorisations SELECT que sur la base de données et les tables spécifiées que vous souhaitez interroger. Grafana ne confirme pas que la requête est sûre. La requête peut inclure n'importe quelle instruction SQL. Par exemple, des instructions telles que DELETE FROM user; et DROP TABLE user; seraient exécutées. Pour vous protéger contre cela, nous vous recommandons vivement de créer un utilisateur PostgreSQL spécifique avec des autorisations restreintes.

L'exemple de code suivant montre la création d'un utilisateur PostgreSQL spécifique avec des autorisations restreintes.

 CREATE USER grafanareader WITH PASSWORD 'password';
 GRANT USAGE ON SCHEMA schema TO grafanareader;
 GRANT SELECT ON schema.table TO grafanareader;

Assurez-vous que l'utilisateur n'obtient aucune autorisation indésirable de la part du rôle public.

Éditeur de requête

Vous trouverez l'éditeur de requêtes PostgreSQL dans l'onglet métriques du mode d'édition du panneau Graph ou Singlestat. Vous passez en mode édition en choisissant le titre du panneau, puis en modifiant.

L'éditeur de requêtes possède un lien SQL généré qui s'affiche après l'exécution d'une requête, en mode édition du panneau. Choisissez-le, il se développera et affichera la chaîne SQL interpolée brute qui a été exécutée.

Sélectionnez le tableau, la colonne horaire et la colonne métrique (FROM)

Lorsque vous entrez en mode édition pour la première fois ou que vous ajoutez une nouvelle requête, Grafana essaie de préremplir le générateur de requêtes avec la première table contenant une colonne d'horodatage et une colonne numérique.

Dans le champ FROM, Grafana proposera des tables qui se trouvent dans le fichier de l'utilisateur search_path de la base de données. Pour sélectionner une table ou une vue qui ne figure pas dans votre tableau, search_path vous pouvez saisir manuellement un nom complet (schema.table) tel que. public.metrics

Le champ de colonne Heure fait référence au nom de la colonne contenant vos valeurs temporelles. La sélection d'une valeur pour le champ de colonne métrique est facultative. Si une valeur est sélectionnée, le champ de colonne métrique sera utilisé comme nom de série.

Les suggestions de colonnes métriques ne contiendront que des colonnes contenant un type de données texte (char, varchar, texte). Pour utiliser une colonne avec un type de données différent comme colonne métrique, vous pouvez saisir le nom de la colonne avec un transtypage :ip::text. Vous pouvez également saisir des expressions SQL arbitraires dans le champ de la colonne métrique qui correspondent à un type de données texte tel quehostname || ' ' || container_name.

Colonnes, fenêtres et fonctions d'agrégation (SELECT)

Dans la SELECT ligne, vous pouvez spécifier les colonnes et les fonctions que vous souhaitez utiliser. Dans le champ de colonne, vous pouvez écrire des expressions arbitraires au lieu d'un nom de colonne tel quecolumn1 * column2 / column3.

Les fonctions disponibles dans l'éditeur de requêtes dépendent de la version de PostgreSQL que vous avez sélectionnée lors de la configuration de la source de données. Si vous utilisez des fonctions d'agrégation, vous devez regrouper votre jeu de résultats. Si vous ajoutez une fonction d'agrégation, l'éditeur ajoutera automatiquement unGROUP BY time.

L'éditeur essaie de simplifier et d'unifier cette partie de la requête.

Vous pouvez ajouter d'autres colonnes de valeur en cliquant sur le bouton plus et en sélectionnant Colonne dans le menu. Les colonnes de valeurs multiples seront tracées sous forme de séries distinctes dans le panneau graphique.

Filtrage des données (WHERE)

Pour ajouter un filtre, cliquez sur l'icône plus à droite de la WHERE condition. Vous pouvez supprimer des filtres en choisissant le filtre et en sélectionnant Supprimer. Un filtre pour la plage de temps actuellement sélectionnée est automatiquement ajouté aux nouvelles requêtes.

Grouper par

Pour regrouper par heure ou par toute autre colonne, cliquez sur l'icône plus à la fin de la ligne GROUPER PAR. La liste déroulante des suggestions n'affiche que les colonnes de texte du tableau actuellement sélectionné, mais vous pouvez saisir manuellement n'importe quelle colonne. Vous pouvez supprimer le groupe en choisissant l'élément, puis en sélectionnant Supprimer.

Si vous ajoutez un regroupement, une fonction d'agrégation doit être appliquée à toutes les colonnes sélectionnées. Le générateur de requêtes ajoute automatiquement des fonctions d'agrégation à toutes les colonnes sans fonctions d'agrégation lorsque vous ajoutez des groupements.

Combler les lacunes

Amazon Managed Grafana peut renseigner les valeurs manquantes lorsque vous les regroupez par heure. La fonction time accepte deux arguments. Le premier argument est la fenêtre temporelle selon laquelle vous souhaitez effectuer le regroupement, et le second argument est la valeur avec laquelle vous souhaitez que Grafana remplisse les éléments manquants.

Mode éditeur de texte (RAW)

Vous pouvez passer en mode éditeur de requête brut en choisissant l'icône en forme de hamburger et en sélectionnant Changer le mode éditeur ou en choisissant Modifier le code SQL sous la requête.

Note

Si vous utilisez l'éditeur de requête brut, assurez-vous que votre requête contient ORDER BY time au minimum un filtre sur la plage de temps renvoyée.

Macros

Les macros peuvent être utilisées dans une requête pour simplifier la syntaxe et autoriser les parties dynamiques.

Exemple de macro	Description
$__time(dateColumn)	Sera remplacée par une expression à convertir en horodatage UNIX et à renommer la colonne en. time_sec Par exemple, UNIX_TIMESTAMP (DateColumn) en tant que time_sec.
$__timeEpoch(dateColumn)	Sera remplacée par une expression à convertir en horodatage UNIX et à renommer la colonne en. time_sec Par exemple, UNIX_TIMESTAMP (DateColumn) en tant que time_sec.
$__timeFilter(dateColumn)	Sera remplacé par un filtre de plage de temps utilisant le nom de colonne spécifié. Par exemple, DateColumn BETWEEN FROM_UNIXTIME (1494410783) ET FROM_UNIXTIME (1494410983).
$__timeFrom()	Sera remplacé par le début de la sélection d'heure actuellement active. Par exemple, FROM_UNIXTIME (1494410783).
$__timeTo()	Sera remplacé à la fin de la sélection d'heure actuellement active. Par exemple, FROM_UNIXTIME (1494410983).
$__timeGroup(dateColumn,'5m')	Sera remplacée par une expression utilisable dans la clause GROUP BY. Par exemple, cast (cast (UNIX_TIMESTAMP (DateColumn)/(300) comme signé) 300 comme signé), *
$__timeGroup(dateColumn,'5m', 0)	Identique à la ligne précédente, mais avec un paramètre de remplissage, les points manquants dans cette série seront ajoutés par grafana et 0 sera utilisé comme valeur.
$__timeGroup(dateColumn,'5m', NULL)	Comme ci-dessus, mais NULL sera utilisé comme valeur pour les points manquants.
$__timeGroup(dateColumn,'5m', previous)	Comme ci-dessus, mais la valeur précédente de cette série sera utilisée comme valeur de remplissage si aucune valeur n'a été vue, mais la valeur NULL sera utilisée (uniquement disponible dans Grafana 5.3+).
$__timeGroupAlias(dateColumn,'5m')	Sera remplacé de la même manière que $__timeGroup mais avec un alias de colonne ajouté
$__unixEpochFilter(dateColumn)	Sera remplacé par un filtre de plage horaire utilisant le nom de colonne spécifié avec les heures représentées par un horodatage Unix. Par exemple, *DateColumn > 1494410783 ET DateColumn < 1494497183*
$__unixEpochFrom()`	| Sera remplacé par le début de la sélection d'heure actuellement active sous forme d'horodatage Unix. Par exemple, *1494410783*
$__unixEpochTo()	Sera remplacé par la fin de la sélection d'heure actuellement active sous forme d'horodatage Unix. Par exemple, *1494497183*
$__unixEpochNanoFilter(dateColumn)	Sera remplacé par un filtre de plage de temps utilisant le nom de colonne spécifié, les heures étant représentées par un horodatage en nanosecondes. Par exemple, *DateColumn > 1494410783152415214 ET DateColumn < 1494497183142514872*
$__unixEpochNanoFrom()	Sera remplacé par le début de la sélection temporelle actuellement active sous forme d'horodatage en nanosecondes. Par exemple, *1494410783152415214*
$__unixEpochNanoTo()	Sera remplacé par la fin de la sélection temporelle actuellement active sous forme d'horodatage en nanosecondes. Par exemple, *1494497183142514872*
$__unixEpochGroup(dateColumn,"5m", [fillmode])	Identique à $__timeGroup mais pour les heures stockées sous forme d'horodatage Unix.

Requêtes de table

Si l'option de requête est définie sur Formater en tant que table, vous pouvez essentiellement effectuer n'importe quel type de requête SQL. Le panneau du tableau affiche automatiquement les résultats des colonnes et des lignes renvoyées par votre requête.

Vous pouvez contrôler le nom des colonnes du panneau Table à l'aide de la syntaxe as SQL classique de sélection des colonnes.

Requêtes de séries chronologiques

Si vous définissez Format surTime series, pour une utilisation dans un panneau graphique par exemple, la requête doit renvoyer une colonne nommée time qui renvoie soit une date SQL, soit un type de données numérique représentant l'époque Unix. Toute colonne sauf time et metric est traitée comme une colonne de valeur. Vous pouvez renvoyer une colonne nommée metric qui est utilisée comme nom de métrique pour la colonne de valeurs. Si vous renvoyez plusieurs colonnes de valeurs et qu'une colonne est nomméemetric, cette colonne est utilisée comme préfixe pour le nom de série.

Les ensembles de résultats des requêtes de séries chronologiques doivent être triés par ordre chronologique.

L'exemple de code suivant montre une metric colonne.

SELECT
  $__timeGroup("time_date_time",'5m'),
  min("value_double"),
  'min' as metric
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time

L'exemple de code suivant montre comment utiliser le paramètre fill dans la macro $__TimeGroup pour convertir des valeurs nulles en zéro à la place.

SELECT
  $__timeGroup("createdAt",'5m',0),
  sum(value) as value,
  measurement
FROM test_data
WHERE
  $__timeFilter("createdAt")
GROUP BY time, measurement
ORDER BY time

L'exemple de code suivant montre plusieurs colonnes.

SELECT
  $__timeGroup("time_date_time",'5m'),
  min("value_double") as "min_value",
  max("value_double") as "max_value"
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time

Création de modèles

Au lieu de coder en dur des éléments tels que le nom du serveur, de l'application et du capteur dans vos requêtes métriques, vous pouvez utiliser des variables à leur place. Les variables sont affichées sous forme de boîtes de sélection déroulantes en haut du tableau de bord. Vous pouvez utiliser ces listes déroulantes pour modifier les données affichées dans votre tableau de bord.

Pour plus d'informations sur les modèles et les variables de modèles, consultezModèles.

Variable de requête

Si vous ajoutez une variable de modèle de ce typeQuery, vous pouvez écrire une requête PostgreSQL qui peut renvoyer des éléments tels que des noms de mesures, des noms de clés ou des valeurs de clé affichées sous forme de zone de sélection déroulante.

Par exemple, vous pouvez avoir une variable contenant toutes les valeurs de la hostname colonne d'une table si vous spécifiez une requête comme celle-ci dans le paramètre Query de la variable de modèle.

SELECT hostname FROM host

Une requête peut renvoyer plusieurs colonnes et Grafana créera automatiquement une liste à partir de celles-ci. Par exemple, la requête suivante renverra une liste contenant les valeurs de hostname ethostname2.

SELECT host.hostname, other_host.hostname2 FROM host JOIN other_host ON host.city = other_host.city

Pour utiliser des macros dépendantes d'une plage de temps, comme $__timeFilter(column) dans votre requête, le mode d'actualisation de la variable de modèle doit être défini sur On Time Range Change.

SELECT event_name FROM event_log WHERE $__timeFilter(time_column)

Une autre option est une requête qui permet de créer une variable clé/valeur. La requête doit renvoyer deux colonnes nommées __text et__value. La valeur de la __text colonne doit être unique (si elle ne l'est pas, la première valeur est utilisée). Les options de la liste déroulante comporteront un texte et une valeur qui vous permettront d'avoir un nom convivial sous forme de texte et un identifiant comme valeur. Exemple de requête avec hostname comme texte et id comme valeur :

SELECT hostname AS __text, id AS __value FROM host

Vous pouvez également créer des variables imbriquées. En utilisant une variable nomméeregion, vous pouvez faire en sorte que la variable hosts n'affiche que les hôtes de la région actuellement sélectionnée. L'exemple de code suivant montre une requête de ce type (s'il s'regionagit d'une variable à valeurs multiples, utilisez l'opérateur de IN comparaison plutôt que de la comparer = à plusieurs valeurs).

SELECT hostname FROM host  WHERE region IN($region)

Utilisation __searchFilter pour filtrer les résultats dans une variable de requête

L'utilisation __searchFilter du champ de requête filtrera le résultat de la requête en fonction de ce que l'utilisateur saisit dans la zone de sélection déroulante. Lorsque rien n'a été saisi par l'utilisateur, la valeur par défaut __searchFilter est%.

Note

Il est important que vous entouriez l'__searchFilterexpression de guillemets, car Grafana ne le fait pas pour vous.

L'exemple suivant montre comment l'utiliser __searchFilter dans le champ de requête pour activer la recherche hostname pendant que l'utilisateur tape dans la zone de sélection déroulante.

SELECT hostname FROM my_host  WHERE hostname LIKE '$__searchFilter'

Utilisation de variables dans les requêtes

Les valeurs des variables de modèle ne sont citées que lorsque la variable de modèle est unmulti-value.

Si la variable est une variable à valeurs multiples, utilisez l'opérateur de IN comparaison plutôt que de = la comparer à plusieurs valeurs.

Il existe deux syntaxes :

$<varname>Exemple avec une variable de modèle nommée hostname :

SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp ASC

[[varname]]Exemple avec une variable de modèle nommée hostname :

SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp ASC

Désactiver les guillemets pour les variables à valeurs multiples

Amazon Managed Grafana crée automatiquement une chaîne entre guillemets séparée par des virgules pour les variables à valeurs multiples. Par exemple : si server01 et server02 sont sélectionnés, ils seront formatés comme suit :'server01', 'server02'. Pour désactiver les guillemets, utilisez l'option de formatage csv pour les variables.

${servers:csv}

Pour plus d'informations sur les options de mise en forme des variables, consultezModèles et variables.

Annotations

Utilisez des annotations pour superposer des informations détaillées sur les événements au-dessus des graphiques. Vous pouvez ajouter des requêtes d'annotation via le menu Tableau de bord/Vue des annotations. Pour plus d’informations, consultez Annotations.

L'exemple de code suivant montre une requête utilisant une colonne de temps avec des valeurs d'époque.

SELECT
  epoch_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)

L'exemple de code suivant montre une requête de région utilisant des colonnes d'heure et de fin de période avec des valeurs d'époque.

Note

Ceci n'est disponible que dans Grafana v6.6 et versions ultérieures.

SELECT
  epoch_time as time,
  epoch_time_end as timeend,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)

L'exemple de code suivant montre une requête utilisant une colonne de temps de type date/heure SQL natif.

SELECT
  native_date_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__timeFilter(native_date_time)

Name (Nom)	Description
time	Nom du champ date/heure. Il peut s'agir d'une colonne avec un type de données de date/heure ou une valeur d'époque SQL natif.
timeend	Nom facultatif du champ date/heure de fin. Il peut s'agir d'une colonne avec un type de données de date/heure ou une valeur d'époque SQL natif (Grafana v6.6+).
text	Champ de description de l'événement.
tags	Nom de champ facultatif à utiliser pour les balises d'événements sous forme de chaîne séparée par des virgules.

Alerte

Les requêtes de séries chronologiques devraient fonctionner dans des conditions d'alerte. Les requêtes mises en forme de tableau ne sont pas encore prises en charge dans les conditions des règles d'alerte.