Les tables de référence vous permettent de combiner des métadonnées personnalisées avec des informations déjà présentes dans Datadog. Vous pouvez définir de nouvelles entités telles que les détails des clients, les noms et informations des services, ou les adresses IP en téléchargeant un fichier CSV contenant un tableau d’informations. Les entités sont représentées par une clé primaire dans une Reference Table et les métadonnées associées.
Vous pouvez par exemple :
Enrichissez les logs et les données de sécurité pour des enquêtes plus rapides : Corrélez les logs, les traces et les événements de sécurité avec un contexte métier à jour (comme les noms des clients, les propriétaires de compte, les renseignements sur les menaces ou les descriptions des codes d’erreur) pour accélérer le dépannage et l’analyse.
Segmentez les utilisateurs et les ressources pour des analyses ciblées et la gestion des coûts : Regroupez les utilisateurs, les clients ou les ressources cloud en segments significatifs (comme les niveaux d’utilisateurs, les équipes ou les unités commerciales) pour des analyses de produit plus approfondies et une attribution précise des coûts à l’aide d’outils tels que Tag Pipelines.
Améliorez les données pour des requêtes et des rapports avancés : Joignez des données externes provenant de tables de référence dans Sheets, l’éditeur DDSQL ou les Notebooks pour effectuer des requêtes complexes, des agrégations et créer des rapports personnalisés sans expertise technique.
Créer une Reference Table
Datadog prend en charge les sources de données suivantes, y compris les intégrations et le téléchargement manuel de fichiers CSV :
Cliquez sur New Reference Table +, puis chargez un fichier CSV, nommez les colonnes appropriées et définissez la clé primaire pour les correspondances.
Remarque : La méthode de chargement manuel de CSV prend en charge les fichiers jusqu’à 4 Mo.
Amazon S3
Les tables de référence peuvent automatiquement extraire un fichier CSV d’un compartiment Amazon S3 pour maintenir vos données à jour. L’intégration recherche les modifications apportées au fichier CSV dans S3, et lorsque le fichier est mis à jour, elle remplace la Reference Table par les nouvelles données. Cela permet également une mise à jour par API avec l’API S3 une fois la Reference Table initiale configurée. Remarque : Les tables de référence ne sont pas remplacées si le contenu du fichier CSV est inchangé.
Pour mettre à jour les tables de référence depuis S3, Datadog utilise le rôle IAM de votre compte AWS que vous avez configuré pour l’intégration AWS. Si vous n’avez pas encore créé ce rôle, suivez ces étapes pour le faire. Pour autoriser ce rôle à mettre à jour vos tables de référence, ajoutez l’instruction d’autorisation suivante à ses politiques IAM. Assurez-vous de modifier les noms des compartiments pour qu’ils correspondent à votre environnement.
Remarque : Si vous utilisez le chiffrement côté serveur, vous pouvez charger des tables de référence chiffrées avec des clés gérées par Amazon S3 (SSE-S3) ou des clés AWS Key Management Service (SSE-KMS).
{"Statement":[{"Sid":"EnrichmentTablesS3","Effect":"Allow","Action":["s3:GetObject",// Grant KMS decrypt permissions if uploading KMS-encrypted object
// "kms:Decrypt",
"s3:ListBucket"],"Resource":["arn:aws:s3:::<MY_BUCKET_NAME_1/*>","arn:aws:s3:::<MY_BUCKET_NAME_2>"]}],"Version":"2012-10-17"}
Définir le tableau
Cliquez sur New Reference Table +, puis ajoutez un nom, sélectionnez Amazon S3, remplissez tous les champs, cliquez sur importer et définissez la clé primaire pour les correspondances.
Remarque : La méthode de chargement depuis un compartiment S3 prend en charge les fichiers jusqu’à 200 Mo.
Dans le portail Azure, sélectionnez le compte de stockage qui contient vos fichiers de Reference Table.
Dans votre compte de stockage, accédez à Access Control (IAM) et sélectionnez Add > Add Role Assignment.
Saisissez et sélectionnez le rôle Storage Blob Data Reader. Le Storage Blob Data Reader rôle permet à Datadog de lire et de lister les conteneurs de stockage et les blobs.
Dans l’onglet Members, cliquez sur
Select members
. Sélectionnez la app registration que vous avez créée à l'étape 1.
<div class="shortcode-wrapper shortcode-img expand"><figure class="text-center"><a href="https://docs.dd-static.net/images/reference_tables/add_members.bbbaf670376f94f45cde38445df6bebd.png?fit=max&auto=format" class="pop" data-bs-toggle="modal" data-bs-target="#popupImageModal"><picture class="" style="width:85%;" >
<img
class="img-fluid"
srcset="https://docs.dd-static.net/images/reference_tables/add_members.bbbaf670376f94f45cde38445df6bebd.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/reference_tables/add_members.bbbaf670376f94f45cde38445df6bebd.png?auto=format&fit=max&w=850&dpr=2 2x"
style="width:85%;" alt="La section Membres du portail Azure où un membre est sélectionné et où les données sont renseignées pour le Nom, l'ID d'objet et le Type" />
</picture></a></figure>
</div>
Après avoir examiné et attribué le rôle, vous pouvez importer des données dans les tables de référence depuis Azure. Il peut s’écouler quelques minutes avant que votre configuration Azure ne soit mise à jour dans Datadog.
Remarque : Le téléchargement depuis le stockage d’objets cloud prend en charge les fichiers jusqu’à 200 Mo.
Stockage Google Cloud
Stockage Google Cloud
Les tables de référence ne sont pas disponibles pour votre site Datadog sélectionné ()
Si vous n’avez pas configuré d’intégration Google Cloud avec Datadog ou si vous utilisez des fichiers d’ID de projet Google hérités (les projets hérités sont indiqués dans votre tuile d’intégration GCP), suivez les instructions pour configurer l’intégration Google Cloud Platform. Cela implique de créer un compte de service Google Cloud.
Depuis la console Google Cloud, accédez à la page Cloud Storage.
Trouvez le bucket auquel vous souhaitez accorder l’accès et cliquez dessus.
Cliquez sur l’onglet Permissions. Sous « Afficher par principaux », cliquez sur le bouton Grant Access.
Dans la fenêtre qui s’affiche, sous le champ « Nouveaux principaux », saisissez l’adresse e-mail du compte de service que vous avez créé et ajouté à la tuile GCP à l’étape 1. Sous « Attribuer des rôles », sélectionnez Storage Object Viewer le rôle. Cliquez sur Save.
Après avoir examiné et attribué le rôle, vous pouvez importer dans les tables de référence depuis Google Cloud. Il peut s’écouler quelques minutes avant que votre configuration ne soit mise à jour dans Datadog.
Remarque : Le téléchargement depuis le stockage d’objets cloud prend en charge les fichiers jusqu’à 200 Mo.
Terraform
Utilisez la ressource datadog_reference_table pour gérer les tables de référence en tant qu’infrastructure en tant que code. Configurez la ressource avec le schéma de votre tableau, les clés primaires et les détails d’accès au stockage cloud.
Remarque : Terraform prend en charge les mêmes limites de taille de fichier que les chargements vers le stockage cloud. Consultez les limites des Reference Tables pour plus de détails.
Créez des Reference Tables par programmation à l’aide de l’API Datadog.
Pour les sources de stockage cloud (S3, Azure, GCS), fournissez access_details dans file_metadata pointant vers un fichier CSV dans le stockage cloud.
Pour les fichiers locaux, appelez POST /api/latest/reference-tables/uploads pour obtenir un ID de chargement et charger vos données CSV. Ensuite, appelez le endpoint Créer une Reference Table avec le upload_id dans file_metadata.
Remarque : L’API prend en charge les mêmes limites de taille de fichier que les chargements vers le stockage cloud. Consultez les limites des Reference Tables pour plus de détails.
Cette Reference Table peut être utilisée pour ajouter des attributs supplémentaires aux logs avec le Lookup Processor.
Règles de validation
Les noms de Reference Table et les en-têtes de colonne sont validés selon les conventions de nommage suivantes et automatiquement mis à jour ou normalisés, si nécessaire.
Règle
Normalisation
Les noms et les en-têtes ne peuvent pas être dupliqués.
Les noms dupliqués sont énumérés. Par exemple, si fileid est utilisé deux fois comme nom, la première instance devient fileid1 et la seconde instance devient fileid2. Si un nom ou un en-tête est énuméré et qu’il dépasse 56 caractères, il est rejeté et doit être renommé.
Les noms et les en-têtes ne peuvent pas contenir de lettres majuscules.
Les noms contenant des lettres majuscules sont convertis en minuscules. Cette conversion peut entraîner des noms en double, qui sont ensuite énumérés. Par exemple, Fileid et FileID deviennent tous deux fileid et sont énumérés en fileid1 et fileid2 respectivement.
Les noms et les en-têtes ne peuvent pas contenir d’espaces.
Les espaces autres que les espaces de début et de fin sont remplacés par des caractères de soulignement _. Les espaces de début et de fin sont supprimés. Par exemple, customer names est remplacé par customer_names.
Les noms et les en-têtes doivent commencer par une lettre minuscule.
Les caractères majuscules sont convertis en minuscules. Les caractères de début qui ne sont pas des lettres sont supprimés. Par exemple, 23Two_three devient two_three.
Les noms et les en-têtes ne prennent en charge que les lettres minuscules, les chiffres et le caractère _.
Les caractères non pris en charge sont remplacés par le caractère de soulignement _, sauf si cela enfreint l’une des règles ci-dessus. Dans ce cas, les caractères non pris en charge sont normalisés par la règle respective.
Les noms et les en-têtes doivent comporter 56 caractères ou moins.
Aucune normalisation n’est effectuée. Les noms et les en-têtes comportant plus de 56 caractères sont rejetés et doivent être renommés.
Modifier une Reference Table
Pour modifier une Reference Table existante avec de nouvelles données, sélectionnez un tableau et cliquez sur Update Config dans le coin supérieur droit.
Le CSV sélectionné est upserté dans le tableau, ce qui signifie que :
Toutes les lignes existantes ayant la même clé primaire sont mises à jour
Toutes les nouvelles lignes sont ajoutées
Toutes les anciennes lignes qui ne figurent pas dans le nouveau fichier sont supprimées
Une fois le tableau enregistré, les lignes upsertées sont traitées de manière asynchrone et mises à jour dans l’aperçu. La mise à jour peut prendre jusqu’à 10 minutes.
Exporter une table de référence
Pour exporter une Reference Table, sélectionnez un tableau et cliquez sur Query in DDSQL Editor. À partir de là, vous pouvez utiliser l’Éditeur DDSQL pour exporter vers CSV, Dashboard, et plus encore.
Supprimer une Reference Table
Pour supprimer une Reference Table, sélectionnez un tableau, cliquez sur l’icône d’engrenage dans le coin supérieur droit, puis cliquez sur Delete Table.
Le tableau et toutes les lignes associées sont supprimés.
S’il existe un processeur de correspondance utilisant une Reference Table pour l’enrichissement des logs, alors l’enrichissement s’arrête. Il peut s’écouler jusqu’à 10 minutes avant que l’enrichissement ne s’arrête.
Surveiller l’activité de la Reference Table
Vous pouvez surveiller l’activité de la Reference Table avec Audit Trail ou Change Events. Pour afficher l’audit trail et les change events pour une Reference Table spécifique, sélectionnez le tableau et cliquez sur l’icône Settings à côté de Update Config. Vous avez besoin d’autorisations de gestion d’organisation pour afficher la piste d’audit.
Audit Trail
Utilisez l’Audit Trail pour les tables de référence afin de suivre les actions déclenchées par l’utilisateur. Les événements d’Audit Trail sont envoyés lorsqu’un utilisateur télécharge ou importe initialement un fichier CSV, ou lorsqu’un utilisateur crée, modifie ou supprime une Reference Table.
Le type d’actif reference_table_file affiche les événements d’importation/téléchargement et le type d’actif reference_table affiche les événements de Reference Table. La piste d’audit offre une observabilité sur le contenu d’une Reference Table.
Change Events
Utilisez Change Events pour les tables de référence afin de suivre les actions automatisées ou déclenchées par l’utilisateur. Ils sont envoyés lorsqu’un fichier cloud est importé par un utilisateur ou par une actualisation automatique. (Le téléchargement d’un fichier local ne génère pas de Change Event.) Bien que les événements puissent suivre les actions déclenchées par l’utilisateur, ils sont principalement utilisés pour suivre les importations déclenchées lorsqu’une Reference Table extrait automatiquement un nouveau fichier CSV.
Les événements contiennent des informations sur le statut de réussite, le chemin d’accès et le nom du tableau de l’importation. Si une erreur se produit, des informations sur le type d’erreur sont fournies.
Alerting
Pour être alerté des erreurs rencontrées lors des importations, utilisez les Event Monitors pour les Change Events des Reference Tables. Les Change Events des Reference Tables sont envoyés depuis la source reference_tables.
Vous pouvez créer des monitors depuis l’onglet Monitors, ou cliquer sur l’icône Settings à côté de New Reference Table + pour générer un monitor pré-rempli.
Limites des Reference Tables
Une Reference Table peut comporter jusqu’à 200 colonnes
Une seule ligne ne peut pas dépasser 500 KiB
La taille d’un fichier de Reference Table téléchargé via l’interface utilisateur peut atteindre 200 Mo
La taille d’un fichier de Reference Table téléchargé via un fichier de bucket cloud peut atteindre 200 Mo
La taille d’un fichier de Reference Table téléchargé via une intégration peut atteindre 200 Mo
Vous pouvez avoir jusqu’à 100 Reference Tables par organisation
Contactez le support si vous avez un cas d’utilisation qui dépasse ces limites.
Fréquence de mise à jour automatique
Les tables de référence peuvent être mises à jour automatiquement, selon la source de données :
Stockage de fichiers cloud (Amazon S3, Azure Storage, Google Cloud Storage) : Toutes les 5 minutes
Intégrations : Toutes les heures
Téléchargements manuels de CSV : Les mises à jour automatiques ne sont pas prises en charge
Autorisations
Accès basé sur les rôles
Pour afficher les tables de référence, les utilisateurs ont besoin de l’autorisation reference_tables_read. Pour créer ou modifier des tables de référence, les utilisateurs ont besoin de l’autorisation reference_tables_write.
Pour plus d’informations sur les autorisations, consultez la documentation RBAC.
Contrôles d’accès granulaires
Restreignez l’accès à des tables individuelles en spécifiant une liste d’équipes, de rôles ou d’utilisateurs autorisés à les consulter ou à les modifier.
Cliquez sur un tableau pour ouvrir sa page de détails.
Cliquez sur l’icône cog dans le coin supérieur droit.
Sélectionnez Permissions dans le menu.
Cliquez Restrict Access.
Utilisez le menu déroulant pour sélectionner une ou plusieurs équipes, un ou plusieurs rôles ou un ou plusieurs utilisateurs.
Cliquez sur Add.
Sélectionnez soit Editor soit Viewer.
Cliquez sur Save pour appliquer les modifications.
Pour aller plus loin
Documentation, liens et articles supplémentaires utiles:
