Überwachen Sie alle KI-Aktivitäten mit der einheitlichen Trace-Tabelle

Die einheitliche Trace-Tabelle bietet Ihnen einen zentralen Ort, um alle Aktivitäten in Ihren Unity Gateway-Diensten zu überwachen, zu debuggen, zu sichern und zu prüfen.

Ein Metastore-Administrator richtet einmal einheitliches Tracking ein. Danach wird der gesamte Unity-Gateway-Verkehr automatisch protokolliert, ohne dass er pro Endpunkt eingerichtet ist.

Anforderungen

• Verbesserte Unity Gateway-Vorschau für dein Konto aktiviert. Siehe Manage Azure Databricks Previews.
• Unity-Katalog für Ihren Arbeitsbereich aktiviert.
• Metastore-Administratorrolle zum Einrichten der einheitlichen Nachverfolgung.
• CREATE TABLE, USE CATALOG und USE SCHEMA-Berechtigungen im Zielkatalog und -schema von Unity Catalog.
• Zum Abfragen der Tabelle: SELECT Berechtigung für die Trace-Tabelle. Standardmäßig kann nur der Metastore-Administrator das abfragen. Um anderen Zugriff zu gewähren, siehe Berechtigungen und Zugriffskontrolle.

Was ist die einheitliche Spurtabelle?

Die einheitliche Trace-Tabelle erfasst jede Anfrage und Antwort über alle Unity Gateway-Dienste in einer Unity-Katalog-Tabelle im OpenTelemetrie-("OTel")-Format. Sie bietet drei Vorteile gegenüber Schlusstabellen:

• Abgeschlossen. Alle Aktivitäten in jedem Dienst landen an einem Ort, ohne dass eine Einrichtung pro Endpunkt erforderlich ist.
• Durchsetzbar. Ein Metastore-Administrator erstellt die Tabelle einmal, und das Logging wird auf allen Diensten angewendet, ohne dass es blinde Flecken von Diensten gibt, die das Logging deaktiviert haben.
• Öffnen. Basierend auf dem OpenTelemetrie-Standard, sodass jedes Tool die Daten direkt konsumieren kann, ohne individuelle Nachbearbeitung.

Häufige Verwendungsmöglichkeiten:

• Debugging: Filtern Sie nach trace_id, um jeden Schritt eines fehlgeschlagenen Agentenlaufs erneut abzuspielen. Filtern Sie nach service_name und status.code um alle Fehler an einem bestimmten Endpunkt zu finden.
• Analysen zur KI-Nutzung: Nutzen Sie KI-Funktionen, um Interaktionen mit LLMs (einschließlich Codierassistenten) zu analysieren, um Muster bei Anrufern zu erfassen und den Wert von KI in Ihrer Organisation zu verstehen.
• Token-Nutzung reduzieren: KI-Funktionen nutzen, um häufige Fehlermuster in Aufrufen von LLMs oder MCPs zu analysieren und zu verstehen, wie die Effektivität von Agenten und Codierungsassistenten verbessert werden kann.
• Sicherheit und Compliance: Jede Spanne zeichnet die Identität des Anforderers, den Endpunktnamen und die vollständige Anfrage-Nutzlast auf, sodass Sie diese in Ihre Sicherheitstools zur Bedrohungserkennung und -untersuchung einspeisen können.
• Prüfbarkeit: Überprüfen Sie die KI-Aktivitäten für einen Nutzer, Endpunkt oder einen Zeitbereich.

Vereinheitlichte Spurtabelle vs. Inferenztabellen

Die einheitliche Trace-Tabelle ist der empfohlene Ansatz für neue Bereitstellungen. Inferenztabellen sind weiterhin verfügbar, sind jedoch nur für einen einzelnen Endpunkt für Modelldienste sowie für die Überwachung von Anfragen und Antworten ausgelegt. Weitere Informationen zu Inferenztabellen finden Sie unter Loganfragen und Antworten auf Inferenztabellen.

Aktivieren Sie die einheitliche Spurtabelle

Dies ist eine einmalige Operation, die von einem Metastore-Administrator durchgeführt wird. Die Tabelle lebt an einem von Ihnen gewählten Unity-Catalog-Pfad (zum Beispiel, <catalog>.<schema>.unity_gateway_otel_spans).

1. Klicken Sie in der Arbeitsbereichs-Randleiste auf AI-Gateway.
2. Klicken Sie auf Traces >steuern>Einrichten der Ablaufverfolgung.
3. Wählen Sie den Katalog und das Schema aus, in dem die Trace-Tabelle erstellt wird.
4. Klicken Sie auf Erstellen , um die Trace-Tabelle zu erstellen.

Die einheitliche Ablaufverfolgungstabelle verwenden

Anzeigen von Traces in der Benutzeroberfläche

1. Klicken Sie in der Seitenleiste des Arbeitsbereichs auf den Reiter AI Gateway>Govern>Traces .

Die Traces-Ansicht bietet folgende Steuerungen:

• Suche: Volltextsuche über den Inhalt im aktuellen Bildschirm.
• Zeitspanne: Filtere Spuren nach Zeitfenster (Standard: letzte 24 Stunden).
• Filter: Filtern Sie nach Service (Endpunktname), Principal (Anforderer), Servicetyp, Status oder Ausführungszeit.
• Spalten: Spalten anzeigen oder ausblenden.
• Warehouse: Wählen Sie das SQL-Warehouse aus, das zur Ausführung von Abfragen an der Trace-Tabelle verwendet wird.

Schreibe Abfragen mit Genie Code

Genie Code ist im gesamten Arbeitsbereich verfügbar. Öffne Genie Code in der Seitenleiste und bitte sie, SQL-Abfragen gegen deine Trace-Tabelle zu schreiben. Genie Code versteht Unity Catalog Tabellenschemata automatisch.

Beispielaufforderungen:

• "Zeig mir alle Rate-Limit-Fehler am Endpunkt des Kunden-Support-Bots in den letzten 24 Stunden"
• "Welche Nutzer hatten letzte Woche die längsten P99-Reaktionszeiten?"
• "Finde alle Spuren, bei denen der Agent mehr als drei Downstream-Anrufe gemacht hat"

Genie Code generiert das SQL, das du direkt in einem Notizbuch oder im SQL-Editor ausführen kannst.

Abfrage mit SQL oder einem Notizbuch

Die Tabelle ist durch timegruppiert. Fügen Sie diese Spalte in Ihre WHERE Klausel für die beste Leistung auf.

Ersetze <catalog>.<schema>.<table_name> durch den Pfad zu deiner Trace-Tabelle.

-- 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>';

Berechtigungen und Zugriffskontrolle

Da der gesamte Unity-Gateway-Verkehr in einer Tabelle landet, verwaltet man den Zugriff an einem Ort, anstatt separate Berechtigungen pro Endpunkt zu behalten.

Standardmäßig können nur Metastore-Administratoren die Trace-Tabelle abfragen. Der Metastore-Administrator, der die Tabelle erstellt hat, ist deren Eigentümer. Um anderen Nutzern Abfragezugriff zu gewähren, muss der Eigentümer der Tabelle USE SCHEMA für die Tabelle, USE CATALOG für das Schema und SELECT für den Katalog gewähren. Ohne Zeilenfilter kann jeder Benutzer mit diesen Rechten Traces aller Dienste im Arbeitsbereich sehen, daher empfiehlt Databricks, vor der Gewährung des Zugriffs eine ABAC-Zeilenfilter-Richtlinie anzuwenden.

Zugriff mit ABAC-Richtlinien eingrenzen

Databricks empfiehlt attributbasierte Zugriffskontrolle (ABAC), um jedem Benutzer oder Team nur Zugriff auf die Zeilen zu geben, die sie sehen sollten. Eine ABAC-Zeilenfilter-Richtlinie fügt der Trace-Tabelle (oder ihrem übergeordneten Katalog oder Schema) eine SQL-Funktion zu, die zur Abfragezeit ausgeführt wird. Wenn ein Nutzer ausführt SELECT *, erhält er automatisch nur seine Zeilen zurück, ohne manuelle WHERE Klausel und ohne Risiko, die Traces eines anderen Teams zu lesen.

Das folgende Beispiel implementiert eine gemeinsame Richtlinie: Administratoren sehen alle Spuren; Endpunktbesitzer sehen nur ihren eigenen Service; alle anderen sehen nichts.

Dieses Beispiel folgt einer Konvention, bei der jeder Dienst eine passende Kontogruppe namens <service_name>-ownershat. Diese Gruppen werden nicht automatisch erstellt. Im Rahmen der Einrichtung des Zugriffs muss ein Administrator jede Gruppe erstellen und die entsprechenden Mitglieder hinzufügen und dies wiederholen, sobald ein neuer Endpunkt hinzugefügt wird. Die Filterfunktion und -richtlinie ändern sich nicht, wenn Gruppen hinzugefügt werden.

1. Erstellen Sie die Filterfunktion. Es empfängt für jede Zeile einen Servicenamen und gibt TRUE zurück, wenn der aktuelle Benutzer diesen sehen darf.

   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. Markiere die Spalte service_name , damit die Richtlinie daran gebunden werden kann. ABAC-Policies übergeben Spalten anhand des Governance-Tags an die Filterfunktion.

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

3. Erstellen Sie die Zeilenfilter-Richtlinie in der Trace-Tabelle.

   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. Erstellen Sie die <service_name>-owners Kontogruppe für jeden Service (falls sie noch nicht existiert), fügen Sie deren Mitglieder hinzu und gewähren Sie ihm die erforderlichen Privilegien, um die Tabelle USE CATALOG abzufragen: im Katalog, USE SCHEMA im Schema und SELECT in der Tabelle.

   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`;
   

Mit dieser Richtlinie werden die Ergebnisse automatisch gefiltert, basierend darauf, wer die Abfrage ausführt:

• Ein Mitglied von customer-support-bot-owners, das SELECT * FROM <table> ausführt, sieht nur Zeilen, in denen service_name = 'customer-support-bot'.
• Ein Gruppenmitglied admins sieht alle Reihen.
• Jeder andere Nutzer sieht keine Zeilen.

Wenn ein neuer Endpunkt hinzugefügt wird, wiederholen Sie den letzten Schritt: Erstellen Sie die Matching-Gruppe <service_name>-owners und gewähren Sie sie SELECT. Die Richtlinie und die Filterfunktion ändern sich nicht.

Siehe attributbasierte Zugriffskontrolle im Unity-Katalog für die vollständige ABAC-Referenz und Common Patterns for Row Filtering and Column Masking für weitere Zeilenfiltermuster.

Scope-Zugriff mit PII-Redaktion

Ein anderer Ansatz, um den Zugang zu erweitern, besteht darin, eine Version der Tabelle zu erstellen, in der personenbezogene Daten geschwärzt wurden. Die geschwärzte Tabelle kann eine weiter gefasste SELECT-Berechtigung enthalten, die für mehr Nutzer gilt. Der Kompromiss ist, dass Spuren zweimal materialisiert werden: einmal in ihrer unredigierten Form in der ursprünglichen Tabelle, die strenge Zugriffsanforderungen einhält, und einmal in ihrer geschwärzten Form in einer separaten Tabelle, die für mehr Nutzer offen ist.

Eine Referenzlösung zum Schwärzen von PII aus OpenTelemetry-Traces in Unity Catalog finden Sie unter PII aus OpenTelemetry-Traces in Unity Catalog schwärzen.

Schema

Jede Zeile in der einheitlichen Trace-Tabelle ist eine OpenTelemetrie-Spannweite. Für die vollständige Spaltenliste, Attributschlüssel und Felder für Policy-Evaluationsereignisse siehe Unified Trace Table Schema Reference.

Einschränkungen

• Die maximal protokollierte Attributgröße beträgt 3 MiB (3.145.728 Bytes). Attribute, die diesen Wert überschreiten, werden gekürzt. Der Bereich wird mit databricks.trace.payload_truncated markiert und dessen dropped_attributes_count wird erhöht.
• Die Übertragung von Ablaufprotokollen ist die Best-Effort-Methode. Die meisten Spuren kommen innerhalb von Sekunden ein, aber bei neuen Tabellen kann es bis zu einer Stunde dauern, bis sie ankommen.
• Trace-Logs werden bei Fehlern 401, 403, 429 oder 500 nicht garantiert.
• Die Trace-Tabelle kann keine Logs mehr empfangen oder beschädigt werden, wenn Sie das Tabellenschema ändern, die Tabelle umbenennen oder die Tabelle löschen.
• Databricks verwaltet nicht den Lebenszyklus der Trace-Tabelle; ohne Aufbewahrungsrichtlinie wächst sie unbegrenzt. Um Zeilen nach einem festgelegten Zeitraum automatisch zu löschen, aktivieren Sie für die Tabelle die automatische Gültigkeitsdauer (Auto-TTL), wodurch DELETE und VACUUM im Hintergrund ausgeführt werden. Um die Aufbewahrungsdauer selbst zu verwalten, planen Sie regelmäßig DELETE ein, um abgelaufene Zeilen zu entfernen, und führen Sie anschließend VACUUM aus, um den Speicherplatz wieder freizugeben. Das alleinige Ausführen von VACUUM entfernt nur Dateien, auf die bereits nicht mehr verwiesen wird; es löscht keine Zeilen. Definieren Sie eine Aufbewahrungsrichtlinie, bevor Sie das Nachverfolgen in der Produktion aktivieren.
• Standardmäßig können nur Metastore-Administratoren die Trace-Tabelle abfragen. Ein Metastore-Administrator muss ABAC-Zeilenfilterrichtlinien konfigurieren und SELECT, USE SCHEMA und USE CATALOG gewähren, bevor Ersteller von Endpunkten oder Sicherheitsteams auf ihre eigenen Ablaufverfolgungen zugreifen können.