Exporter depuis Langfuse Cloud
Suivez ce guide pour configurer une intégration de stockage de blob dans Langfuse Cloud et planifier des exportations. Vous pouvez planifier l’exportation de vos données de trace vers un stockage d’objet jusqu’à toutes les20 minutes, ou selon une planification hourly, daily ou weekly. Par défaut, chaque exportation contient vos observations (enrichies des attributs de trace) ainsi que vos scores.
Organisation des fichiers exportés
L’intégration de stockage de blob de Langfuse Cloud écrit les données dans le bucket ou le conteneur de stockage cible selon l’arborescence de répertoires suivante :Importer dans ClickHouse Cloud
Une fois qu’une intégration de stockage de blob est configurée dans Langfuse Cloud, les données de trace sont exportées de manière planifiée vers le bucket ou le conteneur de stockage cible. Pour importer ces données dans ClickHouse Cloud, vous pouvez utiliser ClickPipes et ses connectors managés pour le stockage d’objet :Créer un ClickPipe
Cet exemple utilise le S3 ClickPipe pour importer des données depuis un bucket S3 qui reçoit des exports planifiés depuis Langfuse Cloud. Il peut servir de modèle pour toutes les cibles d’export vers un stockage d’objet. Pour des instructions spécifiques à chaque source de données, consultez la documentation ClickPipes.1
Sélectionnez la source de données
1. Dans ClickHouse Cloud, sélectionnez Data sources dans le menu de navigation principal, puis cliquez sur Create ClickPipe.
2. Cliquez sur la vignette Amazon S3. Cette vignette permet également de vous connecter à d’autres services compatibles S3 qui ne figurent pas dans l’interface de ClickPipes.


2
Configurer la connexion
1. Renseignez les informations dont ClickPipes a besoin pour se connecter et s’authentifier auprès du bucket qui reçoit vos exports Langfuse Cloud.
3. Cliquez sur Incoming data. ClickPipes récupérera les métadonnées de votre bucket et déduira le schéma de la table cible à l’étape suivante.
-
Méthode d’authentification : le S3 ClickPipe prend en charge les identifiants IAM (
Credentials) et l’authentification basée sur un rôle IAM (IAM role). ClickPipes n’a besoin que d’un accès en lecture au bucket. Consultez la documentation de référence pour en savoir plus sur l’authentification et les permissions. -
Chemin du fichier S3 : faites pointer le ClickPipe vers un sous-répertoire et utilisez le caractère générique
*pour cibler l’ensemble des fichiers exportés. Vous devez créer un ClickPipe par sous-répertoire, car les fichiers exportés dans chaque sous-répertoire ont des schémas différents.Consultez la documentation de référence pour connaître les motifs pris en charge, notamment la manière de cibler des fichiers répartis sur des préfixes imbriqués.

3
Valider les données entrantes
1. ClickPipes se connecte à votre bucket et liste les fichiers présents dans le path spécifié, en déduisant automatiquement leur format. Dans cet exemple, nous avons utilisé le format d’export par défaut de Langfuse Cloud (Parquet).
2. Cliquez sur Parse information. ClickPipes s’appuie sur un fichier échantillon pour déduire le schéma des données exportées et mapper automatiquement les champs source vers une target table ClickHouse.

4
Configurer la destination
1. À cette étape, vous pouvez examiner le schéma déduit et personnaliser la configuration de la target table, notamment en ajustant le mappage des types de données, en définissant la clé de tri et en choisissant le table engine.
Sous Upload data to, laissez New table sélectionné et définissez :
Les fenêtres d’export de l’intégration Blob Storage de Langfuse Cloud incluent leurs deux bornes ; un même enregistrement peut donc se retrouver dans plusieurs fichiers exportés. À moins que vos modèles de requêtes analytiques ne soient idempotents (par exemple,

-
Database et Name : une base de données dédiée à vos données Langfuse (par exemple,
langfuse) et un nom explicite pour la table de destination (par exemple,scores). Par défaut, ClickPipes utilisedefault.s3-<uuid>afin d’éviter les conflits de noms. -
Sorting key : la clé de tri de la table de destination, qui détermine la manière dont ClickHouse stocke les données sur disque. Pour des performances optimales, la clé de tri doit correspondre à vos modèles d’accès aux données, afin que les requêtes puissent ignorer le plus de données possible à la lecture.
Cette clé sert également à la déduplication dans les tables
ReplacingMergeTree; l’ensemble de colonnes doit donc aussi identifier un enregistrement de manière unique. Si vous chargez plusieurs projets Langfuse dans une même table, ajoutezproject_iden tête de la clé de tri. Consultez la documentation de référence pour savoir comment choisir une clé de tri. -
Partition by : laissez ce champ vide, sauf si vous prévoyez de faire expirer les anciennes traces. Dans ClickHouse, le partitionnement sert à la gestion des données plutôt qu’à l’optimisation des requêtes ; la clé de tri suggérée élague déjà les requêtes portant sur des plages temporelles. Si vous avez besoin d’une politique de rétention, partitionnez selon la colonne de temps (
toYYYYMM(start_time), outoYYYYMM(timestamp)pourscores) afin que l’expiration d’un mois de traces se résume à une seule opérationDROP PARTITION.
ReplacingMergeTree pour garantir la déduplication, en utilisant updated_at comme colonne Version.
uniq(), max(), min()), vous devez gérer la déduplication dans le modèle de données en aval, en utilisant ReplacingMergeTree comme moteur cible.Dédupliquer avec ReplacingMergeTreeCe table engine élimine les doublons au moyen de fusions en arrière-plan. Pour une déduplication complète à la lecture (c’est-à-dire une sémantique de fusion à la lecture), vous devez utiliser le modificateur
FINAL (ou des agrégations de type argMax()) au moment de la requête.5
Configurer les autorisations
ClickPipes crée un utilisateur dédié pour écrire les données dans la table de destination. Sélectionnez un rôle pour cet utilisateur interne, soit un rôle personnalisé, soit l’un des rôles prédéfinis :
Cliquez sur Complete setup pour créer le ClickPipe.
Full access: accès complet au cluster. Obligatoire si vous utilisez une vue matérialisée ou un dictionnaire avec la table de destination.Only destination table: permissionsINSERTsur la table de destination uniquement.

6
Terminer la configuration
Et voilà, tout est prêt ! ClickPipes commencera par un backfill historique de tous les fichiers présents dans le path spécifié, puis ingérera les nouveaux fichiers au fur et à mesure de leur arrivée dans le bucket.
Répétez les étapes de ce guide pour chaque sous-répertoire que vous souhaitez importer dans ClickHouse Cloud.
