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 bêta. Unity 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 Gateway depuis la page Aperçus de la console de compte. Consultez Gérer les aperçus Databricks.

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

Un administrateur du métastore configure le traçage unifié une seule fois. Après cela, tout le trafic Unity 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

• Aperçu de Enhanced Unity Gateway activé pour votre compte. Consultez Gérer les aperçus Databricks.
• Unity Catalog est activé pour votre workspace.
• Zerobus Ingest est disponible pour votre workspace. La table unifiée de traces écrit les spans dans Unity Catalog via Zerobus Ingest. Pour connaître les régions prises en charge, consultez la disponibilité de l’ingestion.
• 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.

Pour utiliser un catalogue adossé au stockage default, un administrateur du Workspace doit également activer Zerobus Ingest Default Storage dans Settings > Previews . Consultez Gérer les aperçus Databricks.

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

La table de trace unifiée capture chaque requête et réponse sur tous les services Unity Gateway dans une table Unity Catalog au format OpenTelemetry (« OTel »). Il 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 et services MCP de Unity Gateway, dans un seul tableau	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 et services MCP de Unity Gateway, dans un seul tableau	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 Enregistrer 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>';

Envoyer des traces côté client depuis votre application

Vos applications peuvent envoyer des étendues OpenTelemetry côté client à Unity Gateway via son endpoint d'ingestion OTLP, depuis n'importe quel SDK OpenTelemetry. Le SDK Claude dispose également d’une prise en charge intégrée du traçage de ses requêtes API. Les étendues d'application atterrissent dans la même table de trace unifiée que les étendues de requête de la passerelle (<catalog>.<schema>.<table_name>, choisie lors de la configuration), afin que vous puissiez surveiller ce que votre application a fait et ce que la passerelle a servi au même endroit.

info

Bêta

L'ingestion de spans côté client est en version Bêta et est activée par workspace. Pour l'activer pour votre workspace, contactez l'équipe de votre compte Databricks.

Exigences

• La table de traces unifiée est configurée pour votre workspace. Voir Activer la table de traces unifiée.
• L'ingestion de spans côté client est activée pour votre workspace.
• Un jeton Databricks, par exemple un jeton d’accès personnel. Les spans ingérées sont attribuées au principal du jeton. Les attributs d’identité dans la charge utile, tels que enduser.id, sont ignorés.
• Le principal du jeton a accès au workspace. Les requêtes sont rejetées dans le cas contraire.

Envoyer des spans avec un SDK OpenTelemetry

Pointez un exportateur OTLP vers https://<workspace-url>/ai-gateway/otel/v1/traces. L’endpoint n’accepte que l’OTLP sur HTTP avec un encodage protobuf binaire (http/protobuf). JSON et gRPC ne sont pas pris en charge. Envoyez la charge utile non compressée : n’activez pas la compression sur l’exportateur (par exemple, ne définissez pas OTEL_EXPORTER_OTLP_COMPRESSION).

Les exemples suivants envoient des portées à partir de n'importe quelle application :

Python

1. Installez les packages du SDK OpenTelemetry et de l’exportateur OTLP : opentelemetry-sdk et opentelemetry-exporter-otlp-proto-http.

2. Enregistrez un fournisseur de tracer avec un exportateur de span OTLP pointant vers l'endpoint d'ingestion :

   Python

   import os
   
   from opentelemetry import trace
   from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
   from opentelemetry.sdk.resources import Resource
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import BatchSpanProcessor
   
   DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')
   
   # service.name becomes the service_name of these spans in the trace table.
   provider = TracerProvider(
       resource=Resource.create({"service.name": "<your-application-name>"})
   )
   exporter = OTLPSpanExporter(
       endpoint="https://<workspace-url>/ai-gateway/otel/v1/traces",
       headers={"Authorization": f"Bearer {DATABRICKS_TOKEN}"},
   )
   provider.add_span_processor(BatchSpanProcessor(exporter))
   trace.set_tracer_provider(provider)

3. Créer des spans dans votre code d'application :

   Python

   tracer = trace.get_tracer(__name__)
   
   with tracer.start_as_current_span(""):
       # Your application code
       ...

BatchSpanProcessor exporte les étendues de manière asynchrone. Dans les scripts de courte durée, appelez provider.shutdown() (ou provider.force_flush()) avant la fermeture du processus afin que les étendues mises en mémoire tampon soient envoyées.

TypeScript

1. Installez les packages du SDK OpenTelemetry et de l’exportateur OTLP : npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-proto @opentelemetry/resources.

2. Enregistrez un fournisseur de tracer avec un exportateur de span OTLP pointant vers l'endpoint d'ingestion :

   TypeScript

   import { trace } from '@opentelemetry/api';
   import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
   import { resourceFromAttributes } from '@opentelemetry/resources';
   import { BatchSpanProcessor, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
   
   // service.name becomes the service_name of these spans in the trace table.
   const provider = new NodeTracerProvider({
     resource: resourceFromAttributes({ 'service.name': '<your-application-name>' }),
     spanProcessors: [
       new BatchSpanProcessor(
         new OTLPTraceExporter({
           url: 'https://<workspace-url>/ai-gateway/otel/v1/traces',
           headers: { Authorization: `Bearer ${process.env.DATABRICKS_TOKEN}` },
         }),
       ),
     ],
   });
   provider.register();

3. Créer des spans dans votre code d'application :

   TypeScript

   const tracer = trace.getTracer('<your-application-name>');
   
   tracer.startActiveSpan('', (span) => {
     // Your application code
     span.end();
   });

BatchSpanProcessor exporte les spans de manière asynchrone. Dans les scripts de courte durée, appelez await provider.shutdown() avant la fermeture du processus afin que les portées mises en tampon soient envoyées.

Pour configurer l’exportateur sans code, utilisez les variables d’environnement standard de l’exportateur OpenTelemetry. Les SDK OpenTelemetry qui implémentent la spécification d’exportateur OTLP les lisent, par exemple lorsque vous créez OTLPSpanExporter() en Python sans arguments. La valeur d’en-tête est codée en pourcentage, de sorte que l’espace après Bearer est écrit sous la forme %20:

Bash

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://<workspace-url>/ai-gateway/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer%20<token>"
export OTEL_SERVICE_NAME="<your-application-name>"

Gardez le comportement suivant à l’esprit :

• Définissez l’attribut de ressource service.name sur chaque fournisseur de trace. Les étendues sans cet attribut apparaissent dans le tableau des traces sous unknown_external_service.
• Les spans doivent avoir un ID de trace de 16 octets, des ID de span et de span parent de 8 octets, et une heure de start. Les spans dont la validation échoue sont rejetées et comptabilisées dans le champ partial_success de la réponse.

Corréler les traces côté client et côté passerelle

Lorsque votre application propage le contexte de trace W3C (l'en-tête traceparent) dans ses requêtes vers Unity Gateway, les spans de requête de la passerelle rejoignent le contexte de trace propagé, de sorte qu'ils peuvent apparaître dans la même trace que les spans de votre application. Avec un SDK OpenTelemetry générique, propagez le contexte en utilisant l'instrumentation OpenTelemetry pour votre client HTTP ou en injectant le contexte dans les en-têtes de requête. W3C TraceContext est le propagateur default.

La liaison de trace de passerelle est en Bêta et est activée par workspace, séparément de l’ingestion de portée côté client. Pour l'activer pour votre workspace, contactez l'équipe de votre compte Databricks. Lorsque la liaison de trace est activée, la passerelle adopte le contexte de trace entrant pour les services de modèles Unity Catalog et les requêtes MCP. La passerelle ne transmet pas le contexte de trace au fournisseur de modèles en amont.

Comportement et limites des réponses

• L’endpoint renvoie un OTLP ExportTraceServiceResponse. HTTP 200 signifie que le batch a été accepté pour livraison, pas que les portées sont stockées de manière durable. Les écritures sont asynchrones.
• Les spans rejetées, par exemple les spans avec des identifiants mal formés ou les spans envoyées avant que le traçage ne soit activé pour le workspace, sont signalées dans le champ partial_success de la réponse. Inspectez partial_success au lieu de réessayer des batchs entiers.
• L'endpoint renvoie HTTP 404 si l'ingestion de spans côté client n'est pas activée pour le workspace, HTTP 403 si le principal du jeton n'a pas accès au workspace, et HTTP 400 si le corps de la requête n'est pas un protobuf OTLP valide, par exemple un corps JSON ou compressé.
• L'endpoint accepte jusqu'à 32 MiB par requête et 100 requêtes par seconde par organisation. Les valeurs d'attribut de chaîne de plus de 3 MiB (3 145 728 octets) sont tronquées. Les attributs de type tableau et carte ne sont pas tronqués, et les spans qui dépassent la limite de taille d'enregistrement peuvent être abandonnés. Voir Limites.

Trace des requêtes Claude

Unity Gateway s’intègre à la prise en charge d’OpenTelemetry de Claude pour enregistrer les requêtes de l’API Claude Messages et les sessions des agents gérés par Claude sous forme de portées dans la table de traces unifiée. Il existe deux sources de portées Claude : le SDK Claude émet des portées côté client à partir de votre application, et la console Claude exporte des portées côté serveur pour les requêtes de l’API Messages et les sessions des agents gérés. Vous pouvez utiliser l'une ou l'autre source, ou les deux.

Vous pouvez tracer ce qui suit :

• Requêtes de l’API Messages : chaque requête avec son modèle, sa latence et son utilisation de jetons. Si vous activez la capture de contenu, les étendues incluent également les prompts et les réponses.
• Sessions d'agents gérées par Claude : Chaque tour d'agent avec ses requêtes de modèle, l'utilisation d'outils et l'utilisation de jetons, pour que vous puissiez suivre ce qu'un agent a fait étape par étape.

Pour plus de détails sur les éléments enregistrés par chaque source, consultez la documentation OpenTelemetry d'Anthropic.

SDK Claude

Le SDK émet des spans côté client pour les requêtes API effectuées par votre application. Le SDK utilise le fournisseur de tracer enregistré de votre application. Une fois que vous avez configuré le fournisseur de tracer dans Envoyer des spans avec un SDK OpenTelemetry, aucun exportateur spécifique au SDK n'est requis. Le jeton Databricks dans cette configuration authentifie uniquement l'exportateur de span. Vos requêtes Anthropic sont envoyées directement à Anthropic et utilisent votre clé d’API Anthropic.

Python

1. Installez ou mettez à jour le dernier package anthropic, par exemple pip install --upgrade anthropic.

2. Installez les packages OpenTelemetry et enregistrez le fournisseur de trace comme décrit dans Envoyer des étendues avec un SDK OpenTelemetry.

3. Créez un client SDK Claude et envoyez une requête :

   Python

   import anthropic
   
   # Uses your Anthropic API key from the ANTHROPIC_API_KEY environment variable.
   client = anthropic.Anthropic()
   
   message = client.messages.create(
       model="claude-opus-5-5",
       max_tokens=256,
       messages=[
           {"role": "user", "content": "What is a mixture of experts model?"},
       ],
   )

TypeScript

1. Installez ou mettez à jour le dernier package @anthropic-ai/sdk, par exemple npm install @anthropic-ai/sdk@latest.

2. Installez les packages OpenTelemetry et enregistrez le fournisseur de trace comme décrit dans Envoyer des étendues avec un SDK OpenTelemetry.

3. Créez un client SDK Claude et envoyez une requête :

   TypeScript

   import Anthropic from '@anthropic-ai/sdk';
   
   // Uses your Anthropic API key from the ANTHROPIC_API_KEY environment variable.
   const client = new Anthropic();
   
   const message = await client.messages.create({
     model: 'claude-opus-5-5',
     max_tokens: 256,
     messages: [{ role: 'user', content: 'What is a mixture of experts model?' }],
   });

Ce que le SDK Claude enregistre

Les étendues respectent les conventions sémantiques OpenTelemetry GenAI : une étendue par requête API (par exemple, anthropic.messages.create), avec l’utilisation des jetons enregistrée dans les attributs gen_ai.usage.*. Pour les réponses en streaming, l’étendue de la requête se termine lorsque le flux est entièrement lu ou fermé.

Le SDK prend en charge les options supplémentaires suivantes. Les exemples utilisent le SDK Python :

• Mode de contenu : default, les portées ne contiennent que des métadonnées (metadata_only). Pour inclure les invites et les réponses dans les portées, définissez traces.content_mode sur content (par exemple, Anthropic(open_telemetry={"tracer_provider": provider, "traces": {"content_mode": "content"}})). La clé tracer_provider n'est nécessaire que pour envoyer les portées de ce client à un fournisseur différent de celui enregistré globalement. Le contenu des invites et des réponses se trouve dans la table de traces, donc limitez l'accès à celui-ci avec des politiques ABAC ou la rédaction de données personnelles sensibles comme décrit dans Autorisations et contrôle d'accès. Le contenu qui dépasse la limite de contenu par portée du SDK est tronqué, les anciens messages d'entrée étant tronqués en premier. Les images et les documents ne contribuent que par leur type, pas par leurs données.
• ID de conversation : pour regrouper des requêtes dans une conversation, transmettez un ID de conversation par requête : client.with_options(open_telemetry={**client.open_telemetry, "conversation_id": "<conversation-id>"}). with_options remplace la totalité du paramètre open_telemetry ; Merge donc les paramètres existants du client pour conserver des options telles que le mode de contenu.
• Désactiver le traçage : Transmettez open_telemetry=False pour désactiver le traçage pour un client. La variable d’environnement ANTHROPIC_OPEN_TELEMETRY contrôle le traçage pour tous les clients, et ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE définit le mode de contenu, par exemple ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content.

Console Claude

Pour envoyer les étendues côté serveur de la console à la table de trace unifiée, ajoutez une destination de télémétrie Databricks. Les étendues côté client de votre application, comme les appels de SDK et les outils exécutés par votre application, proviennent du traçage du SDK Claude.

1. Dans la console Claude, accédez à Destinations de télémétrie.

2. Ajoutez une destination Databricks, puis saisissez l’URL de votre Workspace et un jeton d’accès personnel Databricks.

Les conditions préalables ci-dessus, notamment l’attribution des jetons aux principaux, s’appliquent également aux étendues de la console.

Comptage des jetons

Si vous envoyez des portées à la fois depuis le SDK Claude et depuis la Console Claude vers la même table de traces, chaque requête génère deux portées anthropic.messages.create avec le même nombre de jetons : une portée SPAN_KIND_CLIENT depuis le SDK et une portée SPAN_KIND_SERVER depuis l’API. Pour compter chaque requête une seule fois, faites la somme des attributs gen_ai.usage.* sur un seul type de portée. La query suivante utilise les portées client du SDK. Si vous envoyez des portées uniquement depuis la Console Claude, utilisez plutôt kind = 'SPAN_KIND_SERVER'.

SQL

SELECT
  sum(attributes:`gen_ai.usage.input_tokens`::bigint) AS input_tokens,
  sum(attributes:`gen_ai.usage.output_tokens`::bigint) AS output_tokens
FROM <catalog>.<schema>.<table_name>
WHERE name = 'anthropic.messages.create'
  AND kind = 'SPAN_KIND_CLIENT';

Autorisations et contrôle d’accès

Comme tout le trafic Unity Gateway aboutit dans une seule table, vous gérez l’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 qui masque les informations PII des traces OpenTelemetry dans Unity Catalog, consultez la section Govern and redact traces in 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.