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.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.
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.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.
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.
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 objetpagination 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:ASCouDESC. Les lignes sont triées par leurid.cursor:{ "id": null }pour la première page.
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.
400 dont le champ error nomme le problème :
per_pageaccepte des valeurs de 1 à 1 000. Toute autre valeur renvoiepagination_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_exceededau 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 dansgroup_by. Lenamede la métrique ne peut pas contenir de caractère générique. Sinon, la requête renvoiepagination_requires_deterministic_grouping. - Les métriques d’événement
event_durationetevent_metric, ainsi que la métrique d’erreur d’incidentincident_error_count, ne peuvent pas encore être paginées. Elles renvoientpagination_unsupported_for_selector. Interrogez-les dans une requête séparée, sanspagination.
Lister les noms de métriques
Renvoie chaque nom de métrique disponible pour un site.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.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étriqueuptime_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,
phaseaccepte 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,nameouid, pas parphase.
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étriquelog_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
fieldsurGAUGE. Le tagaggregationdéfinit la valeur ; la propriétéaggregationdu sélecteur est ignorée. - Incluez à la fois
source_idetquery. 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
severityrenvoient un400.
- Série temporelle : une série par combinaison
group_by, avec les valeurs des champs commetagsde la série. - Liste : une ligne par groupe, sur toute la plage temporelle. Regroupez
avec le
group_byde la requête, tel que[{"Tag": "severity"}]. Un taggroup_bysur le sélecteur renvoie un400. Les sélecteurs qui partagent un groupe sont fusionnés en une seule ligne.
signup et calcule la moyenne de leur
duration, par niveau de gravité :
- 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,
limitplafonne chaque sélecteur séparément. Une ligne fusionnée peut alors manquer les valeurs de certains sélecteurs.
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 valeursqueue 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/timeseriestraite jusqu’à 100 séries./api/v2/metrics/listtraite 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.
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
Lefield 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.