Ingérer des données à partir de Cribl Stream dans Azure Data Explorer
Cribl Stream est un moteur de traitement qui collecte, traite et diffuse en continu les données d’événements machine à partir de n’importe quelle source, en toute sécurité. Il vous permet d’analyser et de traiter ces données de manière sécurisée pour n’importe quelle destination à des fins d’analyse et de gestion.
Cet article explique comment ingérer des données avec Cribl Stream.
Pour obtenir une liste complète des connecteurs de données, consultez Vue d’ensemble des intégrations de données.
Prérequis
- Un compte Cribl Stream.
- Un cluster et une base de données Azure Data Explorer avec les stratégies de cache et de rétention par défaut.
- Un environnement de requête. Pour plus d’informations, consultez Vue d’ensemble des intégrations de requêtes.
- Votre URI de cluster Kusto pour la valeur TargetURI au format https://ingest-<cluster>.<région>.kusto.windows.net. Pour plus d’informations, consultez Ajouter une connexion de cluster.
Créer un principal de service Microsoft Entra
Le principal du service Microsoft Entra peut être créé dans le portail Azure ou programmatiquement, comme dans l’exemple suivant.
Ce principal de service est l’identité utilisée par le connecteur pour écrire des données dans votre table en Kusto. Vous accorderez ultérieurement des autorisations pour ce principal de service afin d’accéder à des ressources Kusto.
Connectez-vous à votre abonnement Azure via Azure CLI. Authentifiez-vous ensuite dans le navigateur.
az loginChoisissez l’abonnement pour héberger le principal. Cette étape est nécessaire quand vous avez plusieurs abonnements.
az account set --subscription YOUR_SUBSCRIPTION_GUIDCréez le principal de service. Dans cet exemple, le principal de service est appelé
my-service-principal.az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}À partir des données JSON retournées, copiez le
appId,passwordettenantpour une utilisation ultérieure.{ "appId": "00001111-aaaa-2222-bbbb-3333cccc4444", "displayName": "my-service-principal", "name": "my-service-principal", "password": "00001111-aaaa-2222-bbbb-3333cccc4444", "tenant": "00001111-aaaa-2222-bbbb-3333cccc4444" }
Vous avez créé votre application Microsoft Entra et votre principal de service.
Créer une table cible
Créez une table cible pour les données entrantes et un mappage d’ingestion pour mapper les colonnes de données ingérées aux colonnes de la table cible.
Exécutez la commande de création de table dans votre éditeur de requête, en remplaçant l’espace réservé TableName par le nom de la table cible :
.create table <TableName> (_raw: string, _time: long, cribl_pipe: dynamic)Exécutez la commande de création de mappage d’ingestion suivante, en remplaçant l’espace réservé TableName par le nom de la table cible et l’espace réservé TableNameMapping par le nom du mappage d’ingestion :
.create table <TableName> ingestion csv mapping '<TableNameMapping>' 'CriblLogMapping' '[{"Name":"_raw","DataType":"string","Ordinal":"0","ConstValue":null},{"Name":"_time","DataType":"long","Ordinal":"1","ConstValue":null},{"Name":"cribl_pipe","DataType":"dynamic","Ordinal":"2","ConstValue":null}]'Accordez au principal de service Créer un principal de service Microsoft Entra les autorisations de rôle d’ingestion de base de données pour travailler avec la base de données. Pour plus d’informations, consultez Exemples. Remplacez l’espace réservé DatabaseName par le nom de la base de données cible et ApplicationID par la valeur
AppIdque vous avez enregistrée lors de la création d’un principal de service Microsoft Entra..add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'
Créer une destination Cribl Stream
La section suivante explique comment créer une destination Stream Cribl qui écrit des données dans votre table en Kusto. Chaque table nécessite un connecteur de destination Cribl Stream distinct.
Sélectionner une destination
Pour connecter Cribl Stream à votre table :
Dans la navigation supérieure de Cribl, sélectionnez Manage, puis sélectionnez un Worker Group.
Sélectionnez Routing>QuickConnect (Stream)>Add Destination.
Dans la fenêtre Set up new QuickConnect Destination, choisissez Azure Data Explorer, puis Add now.
Configurer les paramètres généraux
Dans la fenêtre New Data Explorer, dans General Settings, définissez les paramètres suivants :
| Paramètre | valeur | Description |
|---|---|---|
| Output ID | <OutputID>, par exemple KustoDestination | Nom utilisé pour identifier votre destination. |
| Ingestion Mode | Batching (par défaut) ou Streaming | Paramètres du mode d’ingestion. Le mode Batching permet à votre table d’extraire des lots de données à partir d’un conteneur de stockage Cribl lors de l’ingestion de grandes quantités de données sur une courte durée. Le mode Streaming envoie les données directement à la table KQL cible. Le mode Streaming est utile pour ingérer de plus petites quantités de données ou, par exemple, pour envoyer une alerte critique en temps réel. Le mode Streaming peut générer une latence inférieure à celle du mode Batching. Si le mode d’ingestion est défini sur Streaming, vous devrez activer une stratégie de streaming. Pour plus d’informations, consultez Stratégie d’ingestion en streaming. |
| Cluster base URI | URI de base | URI de base. |
| Ingestion service URI | URI d’ingestion | S’affiche lorsque le mode Batching est sélectionné. URI d’ingestion. |
| Nom de la base de données | <DatabaseName> | Nom de votre base de données cible. |
| Nom de la table | <TableName> | Nom de votre table cible. |
| Validate database settings | Yes (par défaut) ou No. | Valide les informations d’identification de l’application du principal de service que vous avez entrées lors de l’enregistrement ou du démarrage de votre destination. Il valide le nom de la table, sauf lorsque l’option Add mapping object est activée. Ce paramètre doit être désactivé si votre application ne dispose pas à la fois des rôles Database Viewer et Table Viewer. |
| Add mapping object | Yes ou No (par défaut). | Affiché uniquement lorsque le mode Batching est sélectionné au lieu du champ de texte par défaut Data mapping. Si vous sélectionnez Yes, une fenêtre s’ouvre pour vous permettre d’entrer un mappage de données en tant qu’objet JSON. |
| Mappage de données | Nom du schéma de mappage tel que défini à l’étape Créer une table cible. | Nom du schéma de mappage. Il s’agit de la vue par défaut lorsque Add mapping object est défini sur No. |
| Compresser | gzip (par défaut) | Lorsque Data format est défini sur Parquet, Compress n’est pas disponible. |
| Format de données | JSON (par défaut), Raw ou Parquet. | Format de données. Parquet est disponible uniquement en mode Batching et n’est pris en charge que sur Linux. |
| Backpressure behavior | Block (par défaut) ou Drop | Indiquez s’il faut bloquer ou supprimer les événements lorsque les récepteurs exercent une contre-pression. |
| Balises | Valeurs facultatives | Balises facultatives pour filtrer et regrouper les destinations dans la page Manage Destinations de Cribl Stream. Utilisez une tabulation ou un retour chariot inconditionnel entre les noms des balises. Ces balises ne sont pas ajoutées aux événements traités. |
Une fois que vous avez terminé, sélectionnez Next.
Paramètres d’authentification
Sélectionnez Authentication Settings dans la barre latérale. Utilisez les valeurs que vous avez enregistrées dans Créer un principal de service Microsoft Entra avec votre URI de base, comme suit :
| Paramètre | valeur | Description |
|---|---|---|
| Tenant ID | <TenantID> | Utilisez la valeur tenant que vous avez enregistrée dans Créer un principal de service Microsoft Entra. |
| ID client | <ClientID> | Utilisez les valeurs appId que vous avez enregistrées dans Créer un principal de service Microsoft Entra. |
| Portée | <baseuri>/.default |
Utilisez la valeur de l’URI de base pour baseuri. |
| Méthode d’authentification | Client secret, Client secret (text secret) ou Certificate | Pour Client secret, utilisez la clé secrète client de l’application Microsoft Entra que vous avez créée dans Créer un principal de service Microsoft Entra. Pour Certificate, votre certificat utilise la clé publique que vous avez inscrite ou que vous allez inscrire pour l’application Microsoft Entra créée dans Créer un principal de service Microsoft Entra. |
Sélectionnez ensuite Suivant.
File d’attente persistante
S’affiche lorsque Ingestion mode est défini sur Streaming et que Backpressure behavior est défini sur Persistent Queue.
| Paramètre | valeur | Description |
|---|---|---|
| Max file size | 1 Mo (par défaut) | Taille maximale du fichier de file d’attente à atteindre avant de fermer le fichier. Incluez une unité comme Ko ou Mo lorsque vous entrez un nombre. |
| Max queue size | 5 Go (default) | Quantité maximale d’espace disque que la file d’attente peut consommer sur chaque processus Worker avant que la destination cesse de mettre les données en file d’attente. Vous devez entrer un nombre positif avec une unité comme Ko, Mo ou Go. La valeur maximale est de 1 To. |
| Queue file path | $CRIBL_HOME/state/queues (valeur par défaut) |
Emplacement du fichier de file d’attente persistante. Cribl Stream ajoute /<worker‑id>/<output‑id> à cette valeur. |
| Compression | Aucun (par défaut), gzip | Méthode de compression à utiliser pour compresser les données persistantes lors de la fermeture. |
| Queue-full behavior | Block ou Drop | Indiquez s’il faut bloquer ou supprimer les événements lorsque la file d’attente exerce une contre-pression en raison d’une capacité de disque faible ou pleine. |
| Strict ordering | Yes (par défaut) ou No | Lorsque la valeur est définie sur Yes, les événements sont transférés selon l’ordre du premier entré, premier sorti. Définissez la valeur sur No pour envoyer les nouveaux événements avant les événements précédemment mis en file d’attente. |
| Drain rate limit (EPS) | 0 (valeur par défaut) | Cette option, qui s’affiche lorsque Strict ordering est défini sur No, vous permet de définir un taux de limitation (en événements par seconde) lors de l’écriture de la file d’attente vers les récepteurs. La limitation du taux de drainage des événements mis en file d’attente augmente le débit des connexions nouvelles ou actives. La valeur zéro désactive la limitation. |
| Clear Persistent Queue | NA | Sélectionnez cette option pour supprimer les fichiers actuellement en file d’attente de livraison vers votre destination. Vous devez confirmer cette action, car les données mises en file d’attente sont supprimées définitivement sans être livrées. |
Quand vous avez terminé, sélectionnez Suivant.
Paramètres de traitement
| Paramètre | valeur | Description |
|---|---|---|
| Pipeline | <\defined_pipeline> | Pipeline facultatif pour traiter les données avant de les envoyer à l’aide de cette sortie. |
| System fields | cribl_pipe (par défaut), cribl_host, cribl_input, cribl_output, cribl_route ou cribl_wp |
Liste des champs automatiquement ajoutés aux événements avant qu’ils ne soient envoyés à leur destination. Les caractères génériques sont pris en charge. |
Quand vous avez terminé, sélectionnez Suivant.
Paramètres Parquet
S’affiche lorsque Parquet est sélectionné pour Data Format.
Si vous choisissez Parquet, un onglet Parquet Settings s’ouvre pour vous permettre de sélectionner le schéma Parquet.
| Paramètre | valeur | Description |
|---|---|---|
| Schéma automatique | Activé ou désactivé | Sélectionnez On pour générer un schéma Parquet en fonction des événements de chaque fichier Parquet écrit par Cribl Stream. |
| Parquet schema | liste déroulante | S’affiche lorsque Automatic schema est défini sur Off pour vous permettre de sélectionner votre schéma Parquet. |
| Parquet version | 1.0, 2.4, 2.6 (par défaut) | La version détermine les types de données pris en charge et la façon dont ils sont représentés. |
| Data page version | V1, V2 (par défaut) | Format de sérialisation de la page de données. Si votre lecteur Parquet ne prend pas en charge Parquet V2, utilisez V1. |
| Group row limit | 1 000 (par défaut) | Nombre maximal de lignes que chaque groupe peut contenir. |
| Taille de page | 1 Mo (par défaut) | Taille de mémoire cible pour les segments de page. Des valeurs plus faibles peuvent améliorer la vitesse de lecture, tandis que des valeurs plus élevées peuvent améliorer la compression. |
| Log invalid rows | Oui ou Non | Si Yes est sélectionné et que Log level est défini sur debug, génère jusqu’à 20 lignes uniques qui ont été ignorées en raison d’une incompatibilité de format de données. |
| Write statistics | On (par défaut) ou Off | Sélectionnez On si des outils d’affichage des statistiques Parquet sont configurés. |
| Write page indexes | On (par défaut) ou Off | Sélectionnez On si votre lecteur Parquet utilise des statistiques d’index de page Parquet pour activer les sauts de page. |
| Write page checksum | Activé ou désactivé | Sélectionnez On si vous utilisez des outils Parquet pour vérifier l’intégrité des données à l’aide de sommes de contrôle de page Parquet. |
| Métadonnées (facultatif)* | Propriétés des métadonnées du fichier de destination qui peuvent être incluses sous forme de paires clé-valeur. |
Nouvelle tentatives
S’affiche lorsque Ingestion mode est défini sur Streaming.
| Paramètre | valeur | Description |
|---|---|---|
| Honor Retry-After header | Oui ou Non | Indique si un en-tête Retry-After doit être honoré. Lorsque ce paramètre est activé, un en-tête Retry-After reçu est prioritaire et est utilisé avant les autres options configurées dans la section Retries, à condition que l’en-tête spécifie un délai de 180 secondes ou moins. Sinon, les en-têtes Retry-After sont ignorés. |
| Settings for failed HTTP requests | Codes d’état HTTP | Liste des codes d’état HTTP à réessayer automatiquement en cas d’échec de connexion. Cribl Stream retente automatiquement 429 requêtes ayant échoué. |
| Retry timed-out HTTP requests | Activé ou désactivé | Lorsque vous définissez ce paramètre, d’autres paramètres liés au comportement de nouvelle tentative deviennent disponibles. |
| Pre-backoff interval (ms) | 1 000 ms (par défaut) | Délai d’attente avant une nouvelle tentative. |
| Backoff multiplier | 2 s (par défaut) | Utilisé comme base pour l’algorithme de backoff exponentiel afin de déterminer l’intervalle entre les nouvelles tentatives. |
| Backoff limit (ms) | 10 000 ms (par défaut) | Intervalle de backoff maximal pour la nouvelle tentative de streaming finale. Les valeurs possibles vont de 10 000 millisecondes (10 secondes) à 180 000 millisecondes (3 minutes). |
Quand vous avez terminé, sélectionnez Suivant.
Paramètres avancés
Sélectionnez Advanced Settings dans la barre latérale. Le tableau suivant décrit les paramètres avancés lorsque le mode Batching est sélectionné :
| Paramètre | valeur | Description |
|---|---|---|
| Flush immediately | Yes ou No (par défaut). | Définissez la valeur sur Yes pour remplacer l’agrégation de données en Kusto. Pour plus d’informations, consultez Bonnes pratiques pour la bibliothèque Kusto Ingest. |
| Retain blob on success | Yes ou No (par défaut). | Définissez la valeur sur Yes pour conserver l’objet blob de données une fois l’ingestion terminée. |
| Extent tags | <\ExtentTag, ET2,...> | Si vous le souhaitez, définissez des balises sur les étendues partitionnées de la table cible. |
| Enforce uniqueness via tag values | Sélectionnez Add value pour spécifier une liste de valeurs ingest-by à utiliser pour filtrer les étendues entrantes et ignorer les étendues correspondant à une valeur listée. Pour plus d’informations, consultez Extensions (partitions de données). |
|
| Report level | DoNotReport, FailuresOnly (par défaut) et FailuresAndSuccesses. | Niveau des rapports d’état d’ingestion. |
| Report method | Queue (par défaut), Table et QueueAndTable (valeur recommandée). | Cible pour les rapports d’état d’ingestion. |
| Champs supplémentaires | Si vous le souhaitez, ajoutez d’autres propriétés de configuration à envoyer au service d’ingestion. | |
| Staging location | /tmp (valeur par défaut) |
Emplacement du système de fichiers local dans lequel mettre en mémoire tampon les fichiers avant de les compresser et de les déplacer vers la destination finale. Cribl recommande un emplacement offrant stabilité et haute performance. |
| File name suffix expression | .${C.env["CRIBL_WORKER_ID"]}.${__format}${__compression === "gzip" ? ".gz" : ""} (par défaut) |
Expression JavaScript, placée entre guillemets ou guillemets inversés, utilisée comme suffixe du nom de fichier de sortie. format peut être JSON ou raw, et __compression peut être none ou gzip. Une séquence aléatoire de six caractères est ajoutée à la fin des noms de fichiers pour empêcher leur remplacement. |
| Max file size (MB) | 32 Mo (par défaut) | Taille maximale du fichier de sortie non compressée que les fichiers peuvent atteindre avant qu’ils ne soient fermés et déplacés vers le conteneur de stockage. |
| Max file open time (sec) | 300 secondes (par défaut) | Durée maximale, en secondes, pendant laquelle des données sont écrites dans un fichier avant sa fermeture et son déplacement vers le conteneur de stockage. |
| Max file idle time (sec) | 30 secondes (par défaut) | Durée maximale, en secondes, pendant laquelle les fichiers inactifs doivent rester ouverts avant leur fermeture et leur déplacement vers le conteneur de stockage. |
| Max open files | 100 (par défaut) | Nombre maximal de fichiers à garder ouverts en même temps avant que les fichiers ouverts les plus anciens ne soient fermés et déplacés vers le conteneur de stockage. |
| Max concurrent file parts | 1 (par défaut) | Nombre maximal de parties de fichiers à charger en même temps. La valeur par défaut est 1 et la valeur la plus élevée est 10. Le fait de définir la valeur sur 1 permet d’envoyer une partie à la fois, de manière séquentielle. |
| Remove empty staging dirs | Yes (par défaut) ou No | Lorsque vous activez ce paramètre, Cribl Stream supprime les répertoires intermédiaires vides après le déplacement de fichiers. Cela empêche la prolifération de répertoires vides orphelins. Lorsque vous activez ce paramètre, Staging cleanup period est exposé. |
| Staging cleanup period | 300 (par défaut) | Durée en secondes avant la suppression des répertoires vides lorsque le paramètre Remove staging dirs est activé. S’affiche lorsque le paramètre Remove empty staging dirs est défini sur Yes. La valeur minimale est de 10 secondes et la valeur maximale de 86 400 secondes (toutes les 24 heures). |
| Environment | Lorsque le paramètre est vide (par défaut), la configuration est activée partout. Si vous utilisez GitOps, vous pouvez spécifier la branche GIT dans laquelle vous souhaitez activer la configuration. |
Quand vous avez terminé, sélectionnez Save.
Configuration de connexion
Dans la fenêtre Connection Configuration qui s’ouvre, sélectionnez Passthru connection, puis Save. Le connecteur commence à mettre en file d’attente les données.
Confirmer l’ingestion de données
Quand les données arrivent dans la table, vérifiez le nombre de lignes pour confirmer le transfert de données :
<Tablename> | countConfirmez les ingestions mises en file d’attente au cours des cinq dernières minutes :
.show commands-and-queries | where Database == "" and CommandType == "DataIngestPull" | where LastUpdatedOn >= ago(5m)Confirmez qu’il n’y a pas de défaillance dans le processus d’ingestion :
- Pour le mode Batching :
.show ingestion failures- Pour le mode Streaming :
.show streamingingestion failures | order by LastFailureOn descVérifiez les données dans votre table :
<TableName> | take 10
Pour obtenir des exemples de requête et de l’aide, consultez Écrire des requêtes en KQL et Documentation sur le Langage de requête Kusto.