Présentation
Le widget Wildcard de Datadog étend la flexibilité du langage “Grammar of Graphics” open source Vega-Lite et l’intègre à la plateforme Datadog. Le widget Wildcard vous permet de créer des graphiques qui ne sont pas disponibles dans les widgets et systèmes de requêtes natifs de Datadog.
Utilisez le widget Wildcard dans les Dashboards et les Notebooks.
Meilleures pratiques
Datadog recommande d’utiliser un widget de dashboard existant pour répondre à votre cas d’usage. Tous les widgets natifs bénéficient d’optimisations de conception et de performances qui ne sont pas disponibles dans le widget Wildcard. Pour les limitations connues, consultez la section Informations complémentaires.
Cependant, si aucun des widgets Datadog ne répond à vos besoins de visualisation, le widget Wildcard est un moyen rapide d’ajouter une nouvelle fonctionnalité à vos dashboards sans attendre qu’un nouveau type de fonctionnalité ou de graphique soit ajouté.
- Ne partez pas de zéro. Vega-Lite maintient une galerie publique avec plus de 150 exemples officiels. Si vous ne savez pas quel type de graphique utiliser, forkez un exemple existant pour tester la visualisation. Utilisez Vega-Lite plutôt que Vega pour sa simplicité et sa facilité de débogage.
- Testez le widget Wildcard. La flexibilité du widget Wildcard comporte le risque de créer des visualisations lentes, peu attrayantes ou incohérentes. Testez le widget Wildcard sur un brouillon ou un dashboard vide avant d’ajouter des widgets Wildcard en production.
- Validez votre requête. Les widgets Datadog garantissent que les visualisations de données sont alignées sémantiquement avec la requête, ce qui assure que la configuration produit le graphique attendu. Avec le widget Wildcard, vous ajoutez une spécification Vega-Lite personnalisée qui définit la manière dont la requête est mappée aux éléments visuels. Cela crée le risque de récupérer un champ de données non utilisé dans votre visualisation. Utilisez l’aperçu des données pour aider à déboguer les incohérences.
Configuration
Après avoir créé un widget Wildcard, vous pouvez le configurer soit en tant que nouvelle configuration, soit en important une configuration depuis un widget existant.
- Vérifiez les widgets natifs. Vérifiez si un widget Datadog peut répondre à vos exigences.
- Si aucun widget Datadog ne répond à vos exigences, dans un dashboard nouveau ou existant, cliquez sur Add Widgets.
- Cliquez sur l’icône du widget Wildcard dans le panneau de widgets et faites-la glisser.
- Sélectionnez dans le menu déroulant Request Type. Pour plus d’informations sur les types Scalar et Timeseries, consultez la section Formulas Scalar et Formulas Timeseries de cette page.
- Copiez une définition Vega-Lite depuis la galerie publique pour trouver une spécification Vega-Lite de départ.
- Ouvrez l’éditeur plein écran du widget Wildcard et cliquez sur Define Visual.
- Collez la définition Vega-Lite copiée.
- Cliquez sur Run pour appliquer vos modifications de configuration, visualiser un aperçu de la visualisation et affiner votre conception.
Remarque : vous devez cliquer sur Run pour prendre en compte vos modifications, mais cela n’enregistre pas votre configuration.
- (Facultatif) Déboguez les incohérences de la spécification Vega-Lite avec l’aperçu des données. Vérifiez que la requête dans votre spécification Vega-Lite correspond à la requête Datadog.
- Cliquez sur Save.
Dans les dashboards Datadog, les visualisations sont alimentées par plusieurs types de requêtes, notamment scalar et timeseries. Chaque type de requête modifie le nombre et le type de champs disponibles pour les données dans un widget Wildcard.
- Timeseries
- Ce format de données est conçu pour afficher l’évolution de vos données dans le temps.
- Cas d’usage : il est idéal pour surveiller des métriques fluctuantes, telles que l’utilisation du CPU, la consommation de mémoire ou les taux de requêtes. Il aide à identifier les tendances, les modèles et les anomalies sur un intervalle de temps défini.
- Scalar
- Ce format de données agrège vos données en produisant 1 valeur par “groupe”. Le format scalar est utilisé pour les widgets toplist, treemap, diagramme circulaire et tableau, où chaque groupe correspond à 1 forme (barre, rectangle, secteur ou ligne respectivement) dans votre graphique.
- Cas d’usage : il est particulièrement adapté à l’affichage d’indicateurs clés de performance (KPI) ou de statistiques récapitulatives telles que les moyennes, les sommes ou les centiles. Il fournit une vue synthétique de l’état actuel ou d’une métrique spécifique. Si vous ne décrivez pas des changements dans le temps, utilisez Scalar.
Le format de données Timeseries met en évidence les tendances des données dans le temps, tandis que le format Scalar se concentre sur la présentation de valeurs uniques calculées pour des évaluations rapides. Choisissez le type Timeseries si vous avez besoin de visualiser le temps sur un axe ou si vous avez besoin de compartiments temporels individuels. Si vous ne visualisez pas par rapport au temps, sélectionnez le type Scalar pour de meilleures performances.
Remarque : le préfixe “Formulas” est utilisé spécifiquement pour les formats Scalar et Timeseries car ils sont compatibles avec l’API Functions. Les autres formats, tels que Histogram et List, ne prennent pas en charge cette API.
- Copiez depuis un widget Datadog existant avec
cmd+c. - Ouvrez l’éditeur plein écran du widget Wildcard.
- Collez avec
cmd+v. - Cliquez sur Save.
Palette de commandes
La palette de commandes offre un accès rapide aux outils du widget Wildcard. Activez-la avec cmd + shift + p ou cliquez sur l’icône d’information en haut de la page.
Aperçu des données
Le tableau d’aperçu des données affiche la réponse, les champs et les valeurs de votre requête de données disponibles pour votre spécification Vega-Lite. Pour y accéder, cliquez sur la flèche en bas de l’éditeur du widget Wildcard pour afficher l’aperçu des données. Il existe trois types de tableaux dans l’aperçu :
- Lignes de requête : affiche vos données réelles.
- Colonnes de requête : affiche les statistiques récapitulatives des colonnes et les types de données.
- Tableaux internes : affiche les données transformées stockées par Vega-Lite.
Mapper les données Datadog aux spécifications Vega-Lite
Les widgets natifs Datadog mappent automatiquement les résultats des requêtes aux éléments de visualisation, mais le widget Wildcard nécessite l’ajout d’une spécification Vega-Lite personnalisée qui définit comment la requête Datadog est mappée aux éléments visuels. Cela crée le risque d’une incohérence. Avec l’aperçu des données, vous pouvez vérifier que la spécification Vega-Lite correspond à la bonne réponse de requête.
Pour voir comment les valeurs Datadog sont mappées à la spécification Vega-Lite, commencez par l’exemple de requête de métrique system.cpu.user moyennée par env :
Cliquez sur l’onglet Define Visual pour voir comment cette requête est mappée à Vega-Lite. Ouvrez le panneau Aperçu des données et observez les champs query1 et env correspondants répertoriés dans la spécification Vega-Lite et la colonne Aperçu des données.
{
"$schema": "https://vega.github.io/schema/vega-lite/v5.json",
"data": {
"name": "table1"
},
"encoding": {
"x": {
"field": "env",
"type": "nominal"
},
"y": {
"field": "query1",
"type": "quantitative"
}
},
"mark": {
"type": "rect",
"tooltip": {
"content": "data"
}
}
}
| Sélectionner la configuration des données | Définir la spécification visuelle |
|---|
| |
Pour illustrer une incohérence entre les données Datadog et la spécification Vega-Lite, ajoutez un alias à la requête. La visualisation ne fonctionne pas car la spécification Vega-Lite pointe toujours vers “query1”, mais la colonne Aperçu des données indique que la nouvelle requête porte désormais le nouvel alias “example”. Pour corriger cette visualisation, remplacez field:"query1" par field:"example".
| Sélectionner la configuration des données | Définir la spécification visuelle |
|---|
| |
Le widget Wildcard prend en charge les requêtes de données provenant de toutes les sources de données prises en charge dans les widgets natifs :
| Type de requête | Widgets utilisant ce type de requête |
|---|
| Requêtes Scalar | Change, Pie Chart, Query Value, Scatter Plot, Table, Treemap, Top List, Distribution (de groupes), Geomap |
| Requêtes Timeseries | Timeseries, Heatmap |
| Requêtes Distribution | Distribution (de points) |
| Requêtes List | Toutes les données “orientées événements” dans le widget List |
Choisir entre Vega et Vega-Lite
Pour plus de simplicité et de concision, optez pour Vega-Lite. Le système prend en charge Vega-Lite version 5.18.1. Réservez Vega aux besoins de visualisation plus complexes ou avancés.
Utilisez la ressource datadog_dashboard_json lorsque vous travaillez avec des widgets Wildcard dans les dashboards Terraform.
Limites connues
Évitez d’utiliser des widgets Wildcard dans les scénarios suivants :
- Visualisations à forte cardinalité. Si vos visualisations comptent plus de 5 000 lignes par requête, envisagez de pré-agréger les données côté serveur avant de les représenter graphiquement.
- Visualisations réseau ou hiérarchiques.
- Visuels nécessitant des mises en page basées sur la physique.
- Cartographie géographique avancée.
- Représentations graphiques en 3D.
Pour aller plus loin
Documentation, liens et articles supplémentaires utiles:
