Passer au contenu principal
Lisez les données de métriques avec l’API publique (V2). Récupérez une série temporelle pour des graphiques, une liste agrégée pour des tableaux, ou découvrez quelles métriques et tags possède un site. Tous les points de terminaison s’authentifient avec votre jeton d’API personnel et sont limités à un seul site_id. Cette page explique comment construire des requêtes de métriques. Pour chaque champ de chaque requête et réponse, consultez la référence des points de terminaison de métriques.

Migrer depuis les métriques GraphQL

La lecture des métriques via l’API GraphQL est obsolète. Si votre intégration lit des données de métriques via GraphQL, utilisez cette comparaison pour la migrer vers le point de terminaison des séries temporelles de l’API REST (V2).

Interroger une série temporelle

Ce point de terminaison renvoie une ou plusieurs séries de points de données sur une plage temporelle. Utilisez-le pour dessiner des graphiques.
La requête prend un site_id, une plage temporelle from et to, et un tableau select. Si vous omettez resolution, AppSignal en choisit une adaptée à la plage temporelle. Voir résolutions. Chaque entrée select demande un champ de métrique. Fournissez un name de métrique, un objet tags, et un field (voir champs). Les valeurs de tags peuvent utiliser * comme caractère générique. Vous pouvez aussi fournir une aggregation (voir agrégations) et une valeur fill. Les valeurs de fill sont ZERO (par défaut), PREVIOUS et NONE. Les intégrations existantes peuvent aussi utiliser le champ optionnel draw_null_as_zero. true remplit les points manquants avec zéro, comme ZERO. false reporte la valeur précédente, comme PREVIOUS. Si vous envoyez les deux champs, fill est prioritaire. Utilisez des valeurs en majuscules pour field et aggregation. Le point de terminaison des séries temporelles ne prend pas en charge group_by. La référence liste un champ limit, mais le point de terminaison des séries temporelles ne l’applique pas. Le nombre de séries est plutôt plafonné par les limites de traitement. Cette requête récupère la trace_duration moyenne du namespace web. Son draw_null_as_zero: false reporte la dernière valeur sur les points manquants.
La réponse contient un tableau series, avec une série par combinaison de tags et de champ ayant renvoyé des données. Contrairement à l’API GraphQL de métriques, ce point de terminaison ne nécessite pas de requête séparée pour les clés de métriques. Utilisez le tableau series pour voir quelles combinaisons de tags et de champs ont renvoyé des données. Si une requête risque d’atteindre les limites de traitement, n’utilisez pas series.length comme nombre total de clés de métriques correspondantes.

Interroger une liste

Ce point de terminaison renvoie des valeurs de métriques agrégées regroupées en lignes. Utilisez-le pour créer des tableaux.
La requête prend les mêmes site_id, from, to et resolution optionnelle qu’une requête de série temporelle, plus un tableau group_by. Voir résolutions. Pour plafonner le nombre de lignes, ajoutez limit, ou paginez la liste. Un sélecteur de liste est comme un sélecteur de séries temporelles, avec un id supplémentaire. L’id nomme la valeur du sélecteur dans l’objet data de chaque ligne. Chaque entrée group_by est l’une des suivantes, toutes deux sensibles à la casse :
  • La chaîne "Name", pour regrouper par nom de métrique.
  • Un objet tel que {"Tag": "hostname"}, pour regrouper par valeur d’un tag.
Utilisez des valeurs en majuscules pour field et aggregation. Si un sélecteur utilise * pour un tag dans tags, ajoutez ce même tag à group_by sous la forme {"Tag": "tag_name"}, sinon la requête échoue.
La réponse contient un tableau rows. Chaque ligne a un objet group avec les valeurs de tags qui la définissent. Son objet data contient les valeurs agrégées, indexées par id de sélecteur, par exemple { "mean": 42.5 }.

Paginer une liste

Ajoutez un objet pagination au corps de la requête pour lire la liste page par page. Il nécessite ces trois champs :
  • per_page : combien de lignes renvoyer par page.
  • order : ASC ou DESC. Les lignes sont triées par leur id.
  • cursor : { "id": null } pour la première page.
Si une requête contient à la fois pagination et limit, pagination est prioritaire. Pour obtenir la page suivante, envoyez la même requête avec cursor.id défini sur l’id de la dernière ligne. Répétez jusqu’à ce qu’une page renvoie moins de lignes que per_page. Cette page est la dernière. Une réponse paginée a la même forme que toute autre réponse de liste.
La pagination a des limites. Une requête qui les dépasse renvoie une réponse 400 dont le champ error nomme le problème :
  • per_page accepte des valeurs de 1 à 1 000. Toute autre valeur renvoie pagination_invalid_per_page.
  • Une requête paginée lit jusqu’à 100 000 clés de métrique ou lignes sur l’ensemble de ses pages. Au-delà de cette limite, elle renvoie pagination_key_limit_exceeded au lieu d’un résultat partiel. Réduisez les filtres de tags ou la plage temporelle et renvoyez la requête.
  • Pour les métriques personnalisées, chaque tag utilisant un caractère générique * doit aussi apparaître dans group_by. Le name de la métrique ne peut pas contenir de caractère générique. Sinon, la requête renvoie pagination_requires_deterministic_grouping.
  • Les métriques d’événement event_duration et event_metric, ainsi que la métrique d’erreur d’incident incident_error_count, ne peuvent pas encore être paginées. Elles renvoient pagination_unsupported_for_selector. Interrogez-les dans une requête séparée, sans pagination.

Lister les noms de métriques

Renvoie chaque nom de métrique disponible pour un site.
Renvoie un tableau de chaînes. Utilisez l’une d’elles comme name dans les entrées select d’une requête. Pour savoir comment l’interroger, obtenez son type et ses tags. Pour la réponse complète, consultez la référence Lister les noms de métriques. Pour restreindre la liste, ajoutez un paramètre de requête filter, tel que ?filter=queue. Il ne renvoie que les noms contenant ce terme, sans tenir compte de la casse, jusqu’à 200 caractères. Les métriques personnalisées n’apparaissent que si elles ont été signalées au cours des dernières 24 heures. La liste en contient au maximum 1 000, et filter recherche au-delà de ces 1 000.

Obtenir le type et les tags d’une métrique

Renvoie le type d’une métrique et les combinaisons de tags avec lesquelles elle peut être interrogée.
Renvoie un metric_type (GAUGE, COUNTER ou MEASUREMENT) et available_tags, un tableau où chaque entrée est une combinaison valide de clés de tag. Le type détermine les champs que vous pouvez sélectionner. Une métrique GAUGE a le champ GAUGE, et une métrique COUNTER a le champ COUNTER. Une métrique MEASUREMENT a MEAN, COUNT, MIN, MAX et les percentiles. Utilisez une combinaison de tags comme clés des tags d’un sélecteur. Pour la réponse complète, consultez la référence Obtenir le type et les tags d’une métrique.

Timing des moniteurs de disponibilité

La métrique uptime_monitor_timing est une jauge qui enregistre la durée de chaque phase d’une vérification de disponibilité, en millisecondes. Le tag phase sélectionne la phase : dns, connect, tls, ttfb, download ou total. Pour savoir ce que mesure chaque phase, consultez timing de la requête. Interrogez la métrique avec region, phase, et soit le name, soit l’id du moniteur. phase se comporte différemment dans les deux points de terminaison de requête :
  • Dans une requête de série temporelle, phase accepte le caractère générique * et renvoie une série par phase.
  • Dans une requête de liste, chaque sélecteur doit nommer une phase. Ajoutez un sélecteur par phase souhaitée, et regroupez par region, name ou id, pas par phase.
Une phase que la vérification n’a pas mesurée est omise de la réponse. C’est le cas de tls pour une URL HTTP simple et de download sans vérification du corps. Cette requête de liste renvoie le temps moyen par phase et par région pour un moniteur :

Métriques de journal

La métrique log_metrics transforme des lignes de journal en nombres. Elle compte les lignes correspondantes, ou calcule la somme, la moyenne, le minimum ou le maximum d’un champ numérique. AppSignal la calcule au moment de la requête, elle couvre donc aussi les journaux que vous avez déjà envoyés. Interrogez-la via le point de terminaison de série temporelle ou de liste, et configurez-la avec les tags du sélecteur : Pour chaque sélecteur :
  • Définissez field sur GAUGE. Le tag aggregation définit la valeur ; la propriété aggregation du sélecteur est ignorée.
  • Incluez à la fois source_id et query. Sans eux, le sélecteur ne renvoie rien, et aucune erreur.
  • Nommez les champs en notation pointée, comme user.age.
  • N’agrégez que des champs du JSON de votre journal. Les champs intégrés tels que severity renvoient un 400.
La plage temporelle est limitée à votre rétention des journaux. Les résultats sont regroupés ainsi :
  • Série temporelle : une série par combinaison group_by, avec les valeurs des champs comme tags de la série.
  • Liste : une ligne par groupe, sur toute la plage temporelle. Regroupez avec le group_by de la requête, tel que [{"Tag": "severity"}]. Un tag group_by sur le sélecteur renvoie un 400. Les sélecteurs qui partagent un groupe sont fusionnés en une seule ligne.
Cette requête compte les lignes signup et calcule la moyenne de leur duration, par niveau de gravité :
À savoir sur les résultats de liste :
  • Une ligne omet un sélecteur dont le champ n’a pas de valeur numérique dans ce groupe.
  • Les lignes sans le champ regroupé sont regroupées sous une chaîne vide.
  • Le champ agrégé ne peut pas être aussi un champ group_by.
  • Sans pagination, limit plafonne chaque sélecteur séparément. Une ligne fusionnée peut alors manquer les valeurs de certains sélecteurs.
Regrouper par un champ ayant de nombreuses valeurs, comme un ID d’utilisateur, ralentit la requête.

Requêtes de métriques à forte cardinalité

Une requête de métrique a une forte cardinalité lorsqu’elle correspond à plus de séries que le point de terminaison ne peut en traiter. AppSignal stocke chaque combinaison de tags unique comme une clé de métrique distincte. Par exemple, chaque combinaison de valeurs queue et worker crée une clé de métrique distincte. Les limites de cette section s’appliquent aux métriques personnalisées et à transaction_duration. Elles s’appliquent aussi à incident_error_count lorsqu’une requête utilise un caractère générique pour incident_digest ou revision. Elles ne s’appliquent pas aux autres métriques dans l’implémentation V2 actuelle. Chaque combinaison de clé de métrique et de champ compte comme une série. Par exemple, demander MEAN et COUNT pour une même clé de métrique compte comme deux séries. Pour les métriques concernées, AppSignal limite le nombre de séries qu’il traite avant de récupérer leurs données :
  • /api/v2/metrics/timeseries traite jusqu’à 100 séries.
  • /api/v2/metrics/list traite jusqu’à 1 000 séries par page. Une requête paginée peut lire jusqu’à 100 000 clés de métrique sur l’ensemble de ses pages. Voir Paginer une liste.
Ces limites protègent la base de données de métriques contre les requêtes qui prendraient trop de temps à s’exécuter. Elles s’appliquent à l’ensemble de la réponse, et non séparément à chaque entrée select. Le champ limit ne peut pas les augmenter. Les graphiques de tableau de bord chargent leurs données depuis /api/v2/metrics/timeseries, la limite de 100 séries s’applique donc aussi aux graphiques. Si une requête correspond à plus de séries que le point de terminaison ne peut en traiter, AppSignal ne renvoie qu’une partie des données. La réponse n’indique pas qu’elle est incomplète, donc les totaux agrégés peuvent être trop bas. Répéter la même requête renvoie le même sous-ensemble, mais le résultat reste incomplet. Pour lire plus de séries à partir d’une requête de liste, paginez-la. Une requête paginée qui correspond à plus de 100 000 clés de métrique renvoie pagination_key_limit_exceeded au lieu d’un résultat partiel. La page Limites montre quelles métriques personnalisées signalent le plus de combinaisons de tags uniques par minute. Lorsque les valeurs de tags changent au fil du temps, une requête sur une plage plus longue peut correspondre à plus de séries que ce que montre la page. Les métriques personnalisées fonctionnent mieux avec des tags ayant un ensemble de valeurs restreint et fixe, comme region, plan ou queue. Si une métrique existante a des tags à forte cardinalité, des filtres de tags exacts peuvent réduire le nombre de séries correspondantes, mais la réponse ne peut pas confirmer qu’elle contient toutes les séries. Consultez Tags de métriques pour des conseils sur le choix des valeurs de tags.

Référence

Champs

Le field sélectionne quelle mesure récupérer à partir d’une métrique : Pour voir quels champs possède une métrique, obtenez son type et ses tags. Pour tous les types de l’API, consultez la référence lisible par machine.

Agrégations

L’aggregation combine plusieurs valeurs dans un intervalle temporel : SUM, AVERAGE, MIN, MAX, FIRST ou LAST. Si vous omettez aggregation, la valeur par défaut dépend du champ :

Résolutions

resolution accepte MINUTELY, HOURLY ou DAILY. MINUTELY s’applique uniquement lorsque la plage est de 12 heures ou moins et commence dans les 48 dernières heures. En dehors de cette fenêtre, AppSignal utilise HOURLY à la place et l’indique dans le champ resolution de la réponse.