Syntaxe de requête

Docs > APM > Trace Explorer > Syntaxe de requête

Requête de recherche

Tous les paramètres de recherche sont contenus dans l’URL de la page, ce qui permet de partager facilement votre vue.

Syntaxe de recherche

Une requête est composée de termes et opérateurs.

Il existe deux types de termes :

Attribut de span : Contenu du span, collecté avec une instrumentation automatique ou manuelle dans l’application.
Tag de span : Enrichissements de contexte liés au span. Par exemple, des tags d’hôte ou de conteneur décrivant l’infrastructure sur laquelle le service fonctionne.

Pour combiner plusieurs termes en une requête complexe, utilisez l’un des opérateurs booléens suivants :

Opérateur	Description	Exemple
`AND`	Intersection : les deux termes figurent dans les événements sélectionnés (si rien n’est ajouté, AND est utilisé par défaut)	authentication AND failure
`OR`	Union : l’un ou l’autre des termes figure dans les événements sélectionnés	authentication OR password
`-`	Exclusion : le terme suivant n’est PAS dans l’événement	authentication AND -password

Recherche d’attribut

Pour rechercher un attribut de span, vous devez ajouter @ au début de la clé de l’attribut.

Par exemple, si vous voulez accéder à une span avec l’attribut ci-dessous, vous pouvez utiliser :

@git.commit.sha:12345

  "git": {
    "commit": {
      "sha": "12345"
    },
    "repository": {
      "id": "github.com/datadog/datadog"
    }
  }

Les attributs de span sont visibles dans l’onglet Aperçu du panneau latéral de trace.

Remarque : Vous n’avez pas besoin d’utiliser @ sur les attributs réservés : env, operation_name, resource_name, service, status, span_id, timestamp, trace_id, type, link

Recherche de tags

Vos spans héritent des tags des hosts et des intégrations qui les génèrent.

Exemple :

Requête	Correspondance
`(hostname:web-server OR env:prod)`	Toutes les traces avec la balise d’infrastructure `hostname:web-server` ou l’attribut réservé `env:prod`
`(availability-zone:us-east OR container_name:api-frontend)`	Toutes les traces avec l’une de ces balises d’infrastructure
`(service:api AND -kube_deployment:canary)`	Toutes les traces du service `api` qui ne sont pas déployées sur le déploiement `canary`

Les balises de span sont visibles dans l’onglet Infrastructure du panneau latéral de trace.

Formats de balises non standards

Si vos balises ne respectent pas les meilleures pratiques des balises, alors n’utilisez pas la syntaxe key:value. Utilisez plutôt la requête de recherche suivante :

tags:<MY_TAG>

Par exemple, cette balise ne suit pas les meilleures pratiques :
auto-discovery.cluster-autoscaler.k8s.io/daffy

Pour rechercher cette balise, utilisez la requête suivante :
tags:"auto-discovery.cluster-autoscaler.k8s.io/daffy"

Wildcards

Pour effectuer une recherche avec un wildcard multi-caractères, utilisez le symbole * comme suit :

service:web* correspond à chaque trace ayant un service commençant par web
@url:data* correspond à chaque trace ayant un url commençant par data.

Valeurs numériques

Utilisez <, >, <= ou >= pour effectuer une recherche sur des attributs numériques. Par exemple, récupérez toutes les traces ayant un temps de réponse supérieur à 100 ms avec :

@http.response_time:>100

Il est également possible de rechercher des attributs numériques dans une plage spécifique. Par exemple, récupérez toutes vos erreurs 4xx avec :

@http.status_code:[400 TO 499]

Autocomplétion

Taper une requête complexe peut être fastidieux. Utilisez la fonctionnalité de saisie automatique de la barre de recherche pour compléter votre requête en utilisant des valeurs existantes :

Échappement des caractères spéciaux

Les attributs suivants sont considérés comme spéciaux : ?, >, <, :, =, ", ~, / et \ nécessitent un échappement. Par exemple, pour rechercher des traces contenant user=JaneDoe dans leur url, la recherche suivante doit être saisie :

@url:*user\=JaneDoe*

La même logique doit être appliquée aux espaces dans les attributs de trace. Il n’est pas recommandé d’avoir des espaces dans les attributs de trace, mais dans de tels cas, les espaces nécessitent un échappement. Si un attribut s’appelle user.first name, effectuez une recherche sur cet attribut en échappant l’espace :

@user.first\ name:myvalue

Recherches enregistrées

Ne perdez pas de temps à construire les mêmes vues chaque jour. Les recherches enregistrées contiennent votre requête de recherche, les colonnes et l’horizon temporel. Elles sont ensuite disponibles dans la barre de recherche grâce à l’auto-complétion qui correspond soit au nom de la recherche, soit à la requête.

Pour supprimer une recherche enregistrée, cliquez sur l’icône en forme de corbeille sous le menu déroulant de la recherche de traces.

Rechercher des services et des entités

Plage horaire

La plage horaire vous permet d’afficher des traces dans une période donnée. Changez rapidement la plage horaire en sélectionnant une plage prédéfinie dans le menu déroulant (ou en saisissant une plage horaire personnalisée) :

Table des spans

Le tableau des spans est la liste des spans qui correspondent au contexte sélectionné. Un contexte est défini par un filtre de barre de recherche et une plage horaire.

Affichage d’une trace complète

Cliquez sur une span pour afficher les détails de la trace associée :

Colonnes

Pour ajouter d’autres span tags ou attributs en tant que colonnes à la liste, cliquez sur le bouton Options et sélectionnez la dimension que vous souhaitez ajouter :

Groupes de traces

Regroupez la requête par toute balise ou attribut span pour observer les comptes de requêtes, les taux d’erreur et les distributions de latence dans la vue de liste. Vous pouvez sélectionner jusqu’à quatre dimensions dans la clause Grouper par.

Requêtes ‘Grouper par’ avancées

Après avoir sélectionné une dimension à regrouper, vous pouvez spécifier d’où obtenir les valeurs de la dimension en utilisant le menu déroulant de :

Span : Regroupez par la dimension du span interrogé (par défaut). Par exemple, a.
Parent du span : Regroupez par la dimension spécifiée du span parent des spans correspondant à la requête. Par exemple, pour visualiser comment un point de terminaison API fonctionne en fonction du service qui l’appelle, regroupez par service de parent(a).
Span racine : Regroupez par la dimension spécifiée du span racine de la trace. Par exemple, pour analyser les modèles de requêtes backend en fonction des pages frontend d’où proviennent les requêtes, regroupez par @view.name de root.

Voir les groupes de traces dans la liste des groupes

Les groupes de traces sont affichés comme des valeurs uniques de la dimension sélectionnée. Chaque groupe est présenté avec trois indicateurs clés :

REQUÊTES : Nombre de spans au sein du groupe.
ERREURS : Taux d’erreur et nombre d’erreurs.
P95 Latency : Latence P95 des spans.

Pour voir ces indicateurs agrégés sur le span parent ou racine au lieu du span interrogé, sélectionnez parent(a) ou root dans l’instruction Afficher les indicateurs de.

De plus, le Latency Breakdown montre comment le temps est réparti entre différents services au sein des requêtes de chaque groupe, vous permettant de repérer visuellement les goulets d’étranglement de latence pour les groupes donnés.

Pour une analyse plus approfondie, cliquez sur n’importe quel groupe pour examiner les événements individuels qui composent les métriques agrégées.

Une facette affiche toutes les valeurs distinctes d’un attribut ou d’une étiquette et fournit des analyses de base telles que le nombre de traces représentées. Ce commutateur permet également de filtrer vos données.

Les facettes vous permettent de pivoter ou de filtrer vos ensembles de données en fonction d’un attribut donné. Des exemples de facettes incluent des utilisateurs, des services, etc…

Mesures

Les mesures sont un type spécifique de facettes destiné aux valeurs quantitatives.

Les mesures vous permettent d’accomplir les tâches suivantes :

Valeurs agrégées provenant de plusieurs traces. Par exemple, créez une mesure sur le nombre de lignes dans Cassandra et visualisez le P95 ou les référents les plus importants par somme de taille de fichier demandée.
Calculez numériquement les services ayant la latence la plus élevée pour les valeurs de panier d’achat supérieures à 1000 $.
Filtrer les valeurs continues. Par exemple, la taille en octets de chaque segment de charge utile d’un flux vidéo.

Types

Les mesures disposent d’un entier (long) ou d’une double valeur. Ces deux types proposent des fonctionnalités équivalentes.

Unités

Les mesures prennent en charge les unités (temps en secondes ou taille en octets) pour le traitement des ordres de grandeur lors de la requête et de l’affichage. L’unité est une propriété de la mesure elle-même, et non du champ. Par exemple, considérez une mesure de durée en nanosecondes : vous avez une étiquette de portée de service:A où duration:1000 représente 1000 milliseconds, et d’autres étiquettes de portée de service:B où duration:500 représente 500 microseconds : Convertissez la durée en nanosecondes pour toutes les balises span traitées par le processeur arithmétique. Utilisez un multiplicateur de *1000000 sur les balises span de service:A, et un multiplicateur de *1000 sur les balises span de service:B. Utilisez duration:>20ms (voir la syntaxe de recherche pour référence) pour interroger de manière cohérente les balises span des deux services en même temps, et voir un résultat agrégé d’une minute maximum.

Pour commencer à utiliser un attribut en tant que facette ou dans une recherche, cliquez dessus et ajoutez-le en tant que facette :

Après avoir créé une nouvelle facette, elle est disponible dans le volet de facettes pour le filtrage et l’analyse de base.

Utilisez des facettes pour filtrer vos traces. La barre de recherche et l’URL reflètent automatiquement vos sélections.

Visualisations

Sélectionnez un type de visualisation d’analyse à l’aide du sélecteur d’analyse :

Séries temporelles
Liste des meilleurs
Tableau

Séries temporelles

Visualisez l’évolution de la métrique Duration (ou un compte unique de valeurs d’une facette) sur une période de temps sélectionnée, et (optionnellement) divisez par une facette disponible.

Les analyses de séries temporelles suivantes montrent l’évolution de la pc99 durée par étapes de 5min pour chaque Service.

Liste des meilleurs

Visualisez les meilleures valeurs d’une facette selon leur Duration (ou un compte unique de valeurs d’une facette).

Les analyses de liste principale suivantes montrent la pc99 durée de Service :

Table

Visualisez les valeurs principales d’une facette selon une mesure choisie (la première mesure que vous choisissez dans la liste), et affichez la valeur des mesures supplémentaires pour les éléments apparaissant dans cette liste principale. Mettez à jour la requête de recherche ou examinez les journaux correspondant à l’une ou l’autre dimension.

Lorsque plusieurs dimensions sont présentes, les valeurs principales sont déterminées selon la première dimension, puis selon la deuxième dimension parmi les valeurs principales de la première dimension, puis selon la troisième dimension parmi les valeurs principales de la deuxième dimension.
Lorsque plusieurs mesures sont présentes, la liste supérieure ou inférieure est déterminée selon la première mesure.
Le sous-total peut différer de la somme réelle des valeurs dans un groupe, car seul un sous-ensemble (supérieur ou inférieur) est affiché. Les événements avec une valeur nulle ou vide pour cette dimension ne sont pas affichés comme un sous-groupe.

Remarque : Une visualisation de tableau utilisée pour une seule mesure et une seule dimension est la même qu’une liste principale, juste avec un affichage différent.

Les analyses de journaux de tableau suivantes montrent l’évolution des codes d’état principaux selon leur débit, ainsi que le nombre d’adresses IP client uniques, et ce, au cours des 15 dernières minutes :

Sélectionnez une section du graphique ou cliquez dessus pour l’agrandir ou consulter la liste des traces correspondant à votre sélection :

Exporter

Exporter vos requêtes :

Vous pouvez également générer une nouvelle mesure pour la requête.

Remarque : Les requêtes APM dans les tableaux de bord et [notebook] sont basées sur tous les spans indexés. Les requêtes APM dans les moniteurs sont basées uniquement sur les spans indexés par custom retention filters.