Surveillez toute l’activité de l’IA à l’aide de la table de traces unifiée

info

Bêta

La table de traces unifiée est en version bêta. Unity AI Gateway est disponible de manière générale, mais ses fonctionnalités bêta sont activées séparément. Un administrateur de compte doit activer les fonctionnalités bêta de Enhanced Unity AI Gateway depuis la page Previews de la console de compte. Consultez Gérer les aperçus Databricks.

La table de traces unifiée vous offre un emplacement unique pour surveiller, déboguer, sécuriser et auditer toute l'activité de vos services Unity AI Gateway.

Un administrateur du métastore configure le traçage unifié une seule fois. Après cela, tout le trafic Unity AI Gateway est automatiquement consigné sans configuration par endpoint.

important

By default, seul l’administrateur du métastore qui crée la table de traces peut la lire. Aucun autre utilisateur — y compris les propriétaires d'Endpoint et les équipes de sécurité — ne peut interroger la table tant que le propriétaire n'a pas explicitement accordé l'accès via Unity Catalog. Voir Autorisations et contrôle d’accès.

Exigences

• L'aperçu de Unity AI Gateway améliorée est activé pour votre compte. Consultez Gérer les aperçus Databricks.
• Unity Catalog est activé pour votre workspace.
• Rôle d'administrateur du métastore pour configurer le traçage unifié.
• CREATE TABLE, USE CATALOG et USE SCHEMA autorisations dans le catalogue et le schéma Unity Catalog cibles.
• To query the table: privilège SELECT sur la table de traces. Par default, seul l’administrateur du metastore peut l’interroger. Pour accorder l’accès à d’autres personnes, consultez Autorisations et contrôle d’accès.

Qu’est-ce que le tableau de traces unifié ?

La table de traces unifiée capture chaque requête et réponse sur tous les services Unity AI Gateway dans une table Unity Catalog au format OpenTelemetry (« OTel »). Elle offre trois avantages par rapport aux tables d’inférences :

• Terminé. Toute l’activité de chaque service est centralisée au même endroit, sans configuration requise par endpoint.
• Applicable. Un administrateur de métastore crée la table une seule fois, et la journalisation est appliquée à tous les services sans angles morts provenant de services ayant désactivé la journalisation.
• Ouverture. Basé sur la norme OpenTelemetry, afin que tout outil puisse consommer les données directement sans post-traitement personnalisé.

Cas d’utilisation courants :

• Debugging : filtrez par trace_id pour rejouer chaque étape d'une exécution d'agent ayant échoué. Filtrez par service_name et status.code pour trouver toutes les erreurs sur un Endpoint spécifique.
• Analytique pour l’utilisation de l’IA : utilisez les fonctions d’IA pour analyser les interactions avec les LLM (y compris les assistants de codage) afin de capturer des modèles parmi les appelants et de comprendre la valeur que l’IA apporte à votre organisation.
• Réduire l'utilisation des jetons : utilisez les fonctions d'IA pour analyser les schémas d'erreur courants dans les appels aux LLM ou aux MCP et comprendre comment améliorer l'efficacité des agents et des assistants de codage.
• Sécurité et conformité : chaque étendue enregistre l’identité du demandeur, le nom de l’endpoint et la charge utile complète de la requête, afin que vous puissiez l’intégrer à vos outils de sécurité pour la détection et l’investigation des menaces.
• Auditabilité : examinez l’activité de l’IA pour un utilisateur, un endpoint ou une période donnée.

remarque

La livraison des traces s’effectue dans la mesure du possible (voir Limitations), de sorte que la table de traces unifiée complète les logs d’audit Databricks plutôt qu’elle ne les remplace. Continuez à utiliser les logs d’audit comme système d’enregistrement pour la conformité.

Table de trace unifiée vs tables d’inférences

La table de traces unifiée est l'approche recommandée pour les nouveaux déploiements. Les tables d’inférence restent disponibles, mais sont conçues uniquement pour le monitoring des requêtes/réponses d’un Endpoint de service de modèle unique. Pour en savoir plus sur les tables d'inférence, consultez Logs les requêtes et les réponses dans des tables d'inférence.

	Table de traces unifiée	Tables d'inférence
Périmètre	Tous les services de modèle Unity AI Gateway et les services MCP, dans une seule table	Par endpoint de mise en service du modèle, une table chacun
Installer	Configuration unique par l’administrateur du métastore ; s’applique à tous les services sur tous les workspaces associés au métastore	Doit être activé par endpoint
Schéma	Spans OpenTelemetry	Spécifique à Databricks (nécessite un post-traitement)
Workflows d’agents	Tous les sauts aboutissent dans une seule table ; des ID de trace partagés pour reconstruire une trace complète à sauts multiples seront bientôt disponibles	Fragmenté entre les tables par endpoint
Compatibilité MLflow	Les spans utilisent un schéma OTel compatible avec MLflow que les outils MLflow peuvent lire directement	Nécessite une extraction manuelle des traces
Propriétaire	Administrateur du métastore qui crée la table	Propriétaire de l'Endpoint
Contrôle d'accès	default: administrateurs du métastore uniquement. Accordez l’accès à d’autres utilisateurs avec les autorisations Unity Catalog et les politiques de filtrage de lignes ABAC	ACL Unity Catalog distinctes par endpoint

	Table de traces unifiée	Tables d'inférence
Périmètre	Tous les services de modèle Unity AI Gateway et les services MCP, dans une seule table	Par endpoint de mise en service du modèle, une table chacun
Installer	Configuration unique par l’administrateur du métastore ; s’applique à tous les services sur tous les workspaces associés au métastore	Doit être activé par endpoint
Schéma	Spans OpenTelemetry	Spécifique à Databricks (nécessite un post-traitement)
Workflows d’agents	Tous les sauts aboutissent dans une seule table ; des ID de trace partagés pour reconstruire une trace complète à sauts multiples seront bientôt disponibles	Fragmenté entre les tables par endpoint
Compatibilité MLflow	Les spans utilisent un schéma OTel compatible avec MLflow que les outils MLflow peuvent lire directement	Nécessite une extraction manuelle des traces
Propriétaire	Administrateur du métastore qui crée la table	Propriétaire de l'Endpoint
Contrôle d'accès	default: administrateurs du métastore uniquement. Accordez l’accès à d’autres utilisateurs avec les autorisations Unity Catalog et les politiques de filtrage de lignes ABAC	ACL Unity Catalog distinctes par endpoint

Activer la table de traces unifiée

Il s’agit d’une opération unique effectuée par un administrateur du métastore. La table se trouve sur un chemin Unity Catalog que vous choisissez (par exemple, <catalog>.<schema>.unity_gateway_otel_spans).

astuce

Stockez la table de traces dans un catalogue ou un schéma dédié. L’isolation empêche les autorisations provenant d’autres catalogues ou schémas d’exposer involontairement les données de trace. L’administrateur du métastore qui crée la table en devient le propriétaire et contrôle qui peut y accéder. Pour accorder l’accès aux requêtes à d’autres utilisateurs, nous recommandons de configurer l’ABAC comme indiqué dans Autorisations et contrôle d’accès.

1. Dans la barre latérale du workspace, cliquez sur AI Gateway .
2. Cliquez sur Gouverner > Traces > Configurer le traçage .
3. Sélectionnez le catalogue et le schéma dans lesquels la table de traces sera créée.
4. Cliquez sur Créer pour créer la table de traces.

Consommer la table de traces unifiée

important

Par défaut, seul l’administrateur du métastore peut interroger la table de traces. Avant de la partager, configurez une politique de filtre de lignes ABAC afin que chaque utilisateur ne voie que les traces qu’il est autorisé à voir. Voir Autorisations et contrôle d’accès ci-dessous.

Afficher les traces dans l’interface utilisateur

1. Dans la barre latérale du workspace, cliquez sur AI Gateway > Govern > onglet tab .

La vue des traces propose les contrôles suivants :

• Recherche : recherche plein texte dans le contenu de l’écran actuel.
• Plage horaire : filtrez les traces par fenêtre temporelle (default : dernières 24 heures).
• Filtres : filtrer par Service (nom de l’endpoint), Principal (demandeur), Type de service , État ou Temps d’exécution .
• Colonnes : afficher ou masquer les colonnes.
• Warehouse : sélectionnez le SQL warehouse utilisé pour exécuter des requêtes sur la table de traces.

Écrire des queries avec Genie Code

Genie Code est disponible dans tout le workspace. Ouvrez Genie Code depuis la barre latérale et demandez-lui d'écrire des queries SQL pour votre table de trace. Genie Code comprend automatiquement les schémas de table Unity Catalog.

Exemples d’invites :

• « Affichez toutes les erreurs de limite de vitesse sur l'endpoint customer-support-bot au cours des dernières 24 heures »
• « Quels utilisateurs ont eu les temps de réponse p99 les plus longs la semaine dernière ? »
• « Find all traces where the agent made more than three downstream calls »

Genie Code génère le SQL, que vous pouvez exécuter directement dans un notebook ou dans l’éditeur SQL.

query with SQL or a Notebook

La table est regroupée par time. Incluez cette colonne dans votre clause WHERE pour obtenir les meilleures performances.

Remplacez <catalog>.<schema>.<table_name> par le chemin de votre table de traces.

SQL

-- All spans for a specific trace
SELECT * FROM <catalog>.<schema>.<table_name>
WHERE trace_id = 'afdd29f3a069482f8b102380ba0fb3c8'
ORDER BY start_time_unix_nano;

-- All errors on a specific endpoint in the last 24 hours
SELECT trace_id, name, status, attributes
FROM <catalog>.<schema>.<table_name>
WHERE service_name = '<catalog>.<schema>.<model>'
  AND status.code = 'STATUS_CODE_ERROR'
  AND time >= current_timestamp() - INTERVAL 1 DAY;

-- Root spans only (one row per request), with requester and HTTP status
SELECT trace_id, name,
  attributes:`enduser.id`::string AS requester
  attributes:`http.response.status_code`::int AS status_code,
  status.code
FROM <catalog>.<schema>.<table_name>
WHERE parent_span_id IS NULL
  AND service_name = '<catalog>.<schema>.<model>';

Autorisations et contrôle d’accès

Comme tout le trafic Unity AI Gateway aboutit dans une seule table, vous gérez les accès à un seul endroit au lieu de maintenir des autorisations distinctes par endpoint.

Par default, seuls les administrateurs du métastore peuvent interroger la table de traces. L’administrateur du métastore qui a créé la table en est le propriétaire. Pour donner aux autres utilisateurs un accès en requête, le propriétaire de la table doit accorder SELECT sur la table, USE SCHEMA sur le schéma et USE CATALOG sur le catalogue. Sans filtre de ligne, tout utilisateur disposant de ces privilèges peut voir les traces de tous les services du workspace ; Databricks recommande donc d’appliquer une politique de filtre de ligne ABAC avant d’accorder l’accès.

Délimiter l’accès avec des politiques ABAC

Databricks recommande le contrôle d’accès basé sur les attributs (ABAC) pour donner à chaque utilisateur ou équipe l’accès uniquement aux lignes qu’ils sont autorisés à voir. Une politique de filtre de lignes ABAC attache une fonction SQL à la table de trace (ou à son catalogue ou schéma parent) qui s’exécute au moment de la query. Lorsqu’un utilisateur exécute SELECT *, il récupère automatiquement uniquement ses propres lignes, sans clause WHERE manuelle et sans risque de lire les traces d’une autre équipe.

L’exemple suivant met en œuvre une politique courante : les administrateurs voient toutes les traces ; les propriétaires d’endpoint ne voient que leur propre service ; tous les autres ne voient rien.

Cet exemple suit une convention selon laquelle chaque service dispose d’un groupe de compte correspondant nommé <service_name>-owners. Ces groupes ne sont pas créés automatiquement. Dans le cadre de la configuration de l’accès, un administrateur doit créer chaque groupe et ajouter les membres appropriés, et doit répéter cette opération chaque fois qu’un nouvel endpoint est ajouté. La fonction de filtre et la politique ne changent pas à mesure que des groupes sont ajoutés.

1. Créez la fonction de filtre. Elle reçoit un nom de service pour chaque ligne et renvoie TRUE si l'utilisateur actuel est autorisé à le voir.

   SQL

   CREATE OR REPLACE FUNCTION <catalog>.<schema>.ai_traces_filter(svc STRING)
   RETURNS BOOLEAN
   RETURN is_account_group_member('admins')
       OR is_account_group_member(svc || '-owners');

2. Appliquez un tag à la colonne service_name afin que la politique puisse s’y lier. Les politiques ABAC transmettent les colonnes à la fonction de filtrage par tag gouverné.

   SQL

   ALTER TABLE <catalog>.<schema>.<table_name>
   ALTER COLUMN service_name SET TAGS ('ai_trace_service' = '');

3. Créer la politique de filtre de lignes sur la table de traces.

   SQL

   CREATE POLICY ai_traces_filter
   ON TABLE <catalog>.<schema>.<table_name>
   COMMENT 'Restrict trace visibility to service owners and admins'
   ROW FILTER <catalog>.<schema>.ai_traces_filter
   TO `account users`
   FOR TABLES
   MATCH COLUMNS has_tag('ai_trace_service') AS svc
   USING COLUMNS (svc);

4. Créez le groupe de compte <service_name>-owners pour chaque service (s’il n’existe pas déjà), ajoutez ses membres et accordez-lui les privilèges requis pour query la table : USE CATALOG sur le catalogue, USE SCHEMA sur le schéma et SELECT sur la table.

   SQL

   GRANT USE CATALOG ON CATALOG <catalog> TO `customer-support-bot-owners`;
   GRANT USE SCHEMA ON SCHEMA <catalog>.<schema> TO `customer-support-bot-owners`;
   GRANT SELECT ON TABLE <catalog>.<schema>.<table_name> TO `customer-support-bot-owners`;

Avec cette politique en place, les résultats sont automatiquement filtrés en fonction de la personne qui exécute la query :

• Un membre de customer-support-bot-owners qui exécute SELECT * FROM <table> ne voit que les lignes où service_name = 'customer-support-bot'.
• Un membre du groupe admins voit toutes les lignes.
• Tout autre utilisateur ne voit aucune ligne.

Lorsqu’un nouvel endpoint est ajouté, répétez la dernière étape : créez le groupe <service_name>-owners correspondant et accordez-lui SELECT. La politique et la fonction de filtre ne changent pas.

Consultez Contrôle d'accès basé sur les attributs dans Unity Catalog pour la référence complète sur l'ABAC et Modèles courants de filtrage de lignes et de masquage de colonnes pour plus de modèles de filtrage de lignes.

Périmètre d'accès avec rédaction des PII

Une autre approche pour ouvrir l’accès consiste à matérialiser une version de la table avec les PII expurgées. La table expurgée peut bénéficier d’un droit SELECT plus large qui couvre davantage d’utilisateurs. Le compromis est que les traces sont matérialisées deux fois : une fois sous leur forme non expurgée dans la table d’origine, qui conserve des exigences d’accès strictes, et une fois sous leur forme expurgée dans une table distincte ouverte à davantage de consommateurs.

Pour une solution de référence permettant de masquer les PII des traces OpenTelemetry dans Unity Catalog, voir Masquer les PII des traces OpenTelemetry dans Unity Catalog.

Schéma

Chaque ligne du tableau de traces unifié correspond à un span OpenTelemetry. Pour obtenir la liste complète des colonnes, les clés d’attribut et les champs d’événement d’évaluation de politique, consultez la référence du schéma du tableau de traces unifié.

Limitations

• La taille maximale d'attribut enregistrée est de 3 Mio (3 145 728 octets). Les attributs qui dépassent cette limite sont tronqués. L'étendue est marquée avec databricks.trace.payload_truncated et son dropped_attributes_count est incrémenté.
• La livraison des logs de traces s’effectue dans la mesure du possible. La plupart des traces arrivent en quelques secondes ; toutefois, pour les nouvelles tables, les traces peuvent mettre jusqu’à une heure à arriver.
• Les logs de trace ne sont pas garantis pour les erreurs 401, 403, 429 ou 500.
• Le tableau de traces peut cesser de recevoir des Logs ou être corrompu si vous modifiez le schéma de la table, renommez la table ou supprimez la table.
• Databricks ne gère pas le cycle de vie de la table de trace ; sans politique de conservation, celle-ci croît indéfiniment. Pour supprimer automatiquement des lignes après une période définie, activez auto time-to-live (Auto-TTL) sur la table, ce qui exécute DELETE et VACUUM en arrière-plan. Pour gérer vous-même la rétention, planifiez une DELETE périodique afin de supprimer les lignes expirées, suivie d’une VACUUM pour récupérer leur stockage. L’exécution seule de VACUUM supprime uniquement les fichiers qui ne sont déjà plus référencés ; elle ne supprime aucune ligne. Définissez une politique de rétention avant d’activer le traçage en production.
• Par default, seuls les administrateurs du métastore peuvent interroger la table de traces. Un administrateur du métastore doit configurer les politiques de filtrage de lignes ABAC et accorder SELECT, USE SCHEMA et USE CATALOG avant que les créateurs d'Endpoint ou les équipes de sécurité puissent accéder à leurs propres traces.