Monitora tutta l'attività dell'IA utilizzando la tabella di traccia unificata

La tabella di tracciamento unificata ti offre un unico luogo dove monitorare, fare il debug, mettere in sicurezza e auditare tutte le attività tra i tuoi servizi Unity AI Gateway.

Un amministratore del metastore configura il tracciamento unificato una sola volta. Dopo di ciò, tutto il traffico del Gateway AI di Unity viene registrato automaticamente senza configurazione per endpoint.

Requirements

• Anteprima di Unity AI Gateway avanzato abilitata per il tuo account. Vedere Gestire le anteprime di Azure Databricks.
• Catalogo Unity abilitato per l'area di lavoro.
• Ruolo di amministratore del metastore per configurare il tracciamento unificato.
• le autorizzazioni CREATE TABLE, USE CATALOG e USE SCHEMA nel catalogo e nello schema di destinazione di Unity Catalog.
• Per interrogare la tabella: SELECT privilegio sulla tabella di tracciamento. Per impostazione predefinita, solo l'amministratore del metastore può interrogarla. Per concedere accesso ad altri, vedi Permessi e controllo accessi.

Cos'è la tabella di tracciamento unificata?

La tabella di tracciamento unificata cattura ogni richiesta e risposta su tutti i servizi Unity AI Gateway in un'unica tabella Unity Catalog in formato OpenTelemetry ("OTel"). Offre tre vantaggi rispetto alle tabelle di inferenza:

• Completato. Tutta l'attività su ogni servizio si concentra in un unico posto, senza bisogno di configurazione per endpoint.
• Applicabile. Un amministratore del metastore crea la tabella una sola volta e il logging viene applicato a tutti i servizi, senza punti ciechi dovuti ai servizi che hanno il logging disabilitato.
• Apertura. Costruito sullo standard OpenTelemetry, quindi qualsiasi strumento può consumare i dati direttamente senza post-processing personalizzato.

Usi comuni:

• Debug: Filtra per trace_id per ripercorrere ogni passaggio di un'esecuzione non riuscita dell'agente. Filtra per service_name e status.code per trovare tutti gli errori su un endpoint specifico.
• Analisi per l'uso dell'IA: Usa le funzioni di IA per analizzare le interazioni con gli LLM (inclusi gli assistenti di codifica) per catturare i modelli tra i chiamanti e comprendere il valore che l'IA offre alla tua organizzazione.
• Ridurre l'uso dei token: Utilizzare funzioni di IA per analizzare i modelli di errore comuni nelle chiamate a LLM o MCP e capire come migliorare l'efficacia di agenti e assistenti di codifica.
• Sicurezza e conformità: Ogni span registra l'identità del richiedente, il nome dell'endpoint e il payload completo della richiesta, così puoi inserirli nei tuoi strumenti di sicurezza per il rilevamento e l'indagine delle minacce.
• Auditabilità: Esaminare l'attività dell'IA per un utente, un endpoint o un intervallo temporale.

Tabella di tracciamento unificata vs. tabelle di inferenza

La tabella di traccia unificata è l'approccio raccomandato per le nuove implementazioni. Le tabelle di inferenza rimangono disponibili ma sono progettate solo per il monitoraggio richiesta/risposta a un singolo endpoint modello-servizio. Per maggiori informazioni sulle tabelle di inferenza, vedi Richieste di log e risposte alle tabelle di inferenza.

Abilita la tabella di traccia unificata

Questa è un'operazione una tantum eseguita da un amministratore del metastore. La tabella si trova in un percorso di Unity Catalog scelto da te (ad esempio, <catalog>.<schema>.unity_gateway_otel_spans).

1. Nella barra laterale dell'area di lavoro fare clic su Gateway di intelligenza artificiale.
2. Clicca su Governa>Tracce>Imposta il tracciamento.
3. Seleziona il catalogo e lo schema dove verrà creata la tabella di tracciamento.
4. Clicca su Crea per creare la tabella dei tracciati.

Consuma la tabella di traccia unificata

Visualizzare le tracce nell'interfaccia utente

1. Nella barra laterale dello spazio di lavoro, clicca sulla scheda AI Gateway>Govern>Traces .

La vista Traces fornisce i seguenti controlli:

• Ricerca: Ricerca nel testo completo tra i contenuti della schermata corrente.
• Intervallo di tempo: Filtra le tracce per finestra temporale (predefinito: ultime 24 ore).
• Filtri: Filtra per Servizio (nome endpoint), Principal (richiedente), Tipo di servizio, Stato o Tempo di Esecuzione.
• Colonne: Mostra o nascondi le colonne.
• Warehouse: Seleziona il SQL warehouse usato per eseguire query sulla tabella di tracciamento.

Scrivi query con Genie Code

Genie Code è disponibile in tutto lo spazio di lavoro. Apri Genie Code dalla barra laterale e chiedigli di scrivere query SQL sulla tua tabella di traccia. Genie Code comprende automaticamente gli schemi delle tabelle del Catalogo Unity.

Prompt di esempio:

• "Mostrami tutti gli errori del limite di velocità sull'endpoint del client support-bot nelle ultime 24 ore"
• "Quali utenti hanno avuto i tempi di risposta p99 più lunghi la scorsa settimana?"
• "Trova tutte le tracce in cui l'agente ha effettuato più di tre chiamate a valle"

Genie Code genera l'SQL, che puoi eseguire direttamente in un notebook o nell'editor SQL.

Esegui query con SQL o con un notebook

La tabella è raggruppata da time. Includi questa rubrica nella tua WHERE clausola per ottenere le migliori prestazioni.

Sostituisci <catalog>.<schema>.<table_name> con il percorso della tabella di tracciamento.

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

Permessi e controllo degli accessi

Poiché tutto il traffico del Gateway Unity AI arriva in un'unica tabella, gestisci l'accesso in un unico posto invece di mantenere permessi separati per ogni endpoint.

Di default, solo gli amministratori del metastore possono interrogare la tabella dei tracciati. L'amministratore del metastore che ha creato la tabella è il suo proprietario. Per dare accesso agli altri utenti alle query, il proprietario della tabella deve concedere SELECT sulla tabella, USE SCHEMA sullo schema e USE CATALOG sul catalogo. Senza un filtro a riga, qualsiasi utente con questi privilegi può vedere le tracce di tutti i servizi nello spazio di lavoro, quindi Databricks raccomanda di applicare una policy di filtro a riga ABAC prima di concedere l'accesso.

Definire l'accesso in base all'ambito tramite criteri ABAC

Databricks raccomanda il controllo di accesso basato sugli attributi (ABAC) per dare a ogni utente o team accesso solo alle righe che dovrebbero vedere. Una policy di filtro a riga ABAC collega una funzione SQL alla tabella di tracciamento (o al suo catalogo o schema genitore) che viene eseguita al momento della query. Quando un utente esegue SELECT *, ottiene automaticamente solo le proprie righe, senza dover specificare manualmente la clausola WHERE e senza il rischio di leggere le tracce di un altro team.

Il seguente esempio implementa una politica comune: gli amministratori vedono tutte le tracce; i proprietari degli endpoint vedono solo il proprio servizio; tutti gli altri non vedono nulla.

Questo esempio segue una convenzione in cui ogni servizio ha un gruppo di account corrispondente chiamato <service_name>-owners. Questi gruppi non vengono creati automaticamente. Come parte della configurazione dell'accesso, un amministratore deve creare ogni gruppo e aggiungere i membri appropriati, e deve ripetere ogni volta che viene aggiunto un nuovo endpoint. La funzione di filtro e la policy non cambiano quando vengono aggiunti gruppi.

1. Crea la funzione filtro. Riceve un nome di servizio per ogni riga e restituisce TRUE se l'utente attuale è autorizzato a vederlo.

   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. Etichetta la service_name colonna così la policy può essere collegata ad essa. Le policy ABAC passano le colonne alla funzione filtro tramite un tag governato.

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

3. Crea la policy di filtro per righe nella tabella delle tracce.

   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. Crea il <service_name>-owners gruppo di account per ogni servizio (se non esiste già), aggiungi i suoi membri e concedigli i privilegi necessari per interrogare la tabella: USE CATALOG sul catalogo, USE SCHEMA sullo schema e SELECT sulla tabella.

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

Con questa politica in vigore, i risultati vengono automaticamente filtrati in base a chi esegue la query:

• Un membro di customer-support-bot-owners che esegue SELECT * FROM <table> vede solo le righe in cui service_name = 'customer-support-bot'.
• Un membro del gruppo admins vede tutte le righe.
• Qualsiasi altro utente non vede righe.

Quando viene aggiunto un nuovo endpoint, ripeti l'ultimo passaggio: crea il gruppo corrispondente <service_name>-owners e concedigli SELECT. La policy e la funzione filtro non cambiano.

Vedi Controllo degli accessi basato su attributi in Unity Catalog per il riferimento completo per ABAC e Pattern comuni per il filtraggio delle righe e il mascheramento delle colonne per altri pattern di filtraggio delle righe.

Accesso con ambito definito e oscuramento dei dati personali

Un altro approccio per aprire l'accesso è materializzare una versione della tabella con le informazioni personali oscurate. La tabella con dati omessi può prevedere un'autorizzazione più ampia SELECT che si applica a più utenti. Il compromesso è che le tracce vengono materializzate due volte: una volta nella loro forma non oscurata nella tabella originale, che mantiene requisiti di accesso rigorosi, e una volta nella loro forma oscurata in una tabella separata aperta a più consumatori.

Per una soluzione di riferimento che oscura i dati PII nelle tracce OpenTelemetry in Unity Catalog, vedi Oscurare i dati PII nelle tracce OpenTelemetry in Unity Catalog.

Schema

Ogni riga della tabella unificata delle tracce è uno span OpenTelemetry. Per la lista completa delle colonne, le chiavi di attributo e i campi degli eventi di valutazione delle policy, vedi Unified trace table schema reference.

Limitations

• La dimensione massima dell'attributo registrata è di 3 MiB (3.145.728 byte). Gli attributi che superano questo valore vengono troncati. L'intervallo è contrassegnato con databricks.trace.payload_truncated e il relativo dropped_attributes_count viene incrementato.
• La consegna dei tracce log è il miglior sforzo. La maggior parte delle tracce arriva in pochi secondi, tuttavia per le nuove tabelle, le tracce possono impiegare fino a un'ora ad arrivare.
• I trace log non sono garantiti per errori 401, 403, 429 o 500.
• La tabella di tracciamento potrebbe smettere di ricevere i log o corrompersi se cambi lo schema della tabella, rinomini la tabella o la cancelli.
• Databricks non gestisce il ciclo di vita della tabella di tracciamento; senza una politica di retention, essa cresce indefinitamente. Per eliminare automaticamente le righe dopo un periodo prestabilito, abilita la scadenza automatica (Auto-TTL) per la tabella, che esegue DELETE e VACUUM in background. Per gestire autonomamente la conservazione, pianifica periodicamente DELETE per rimuovere le righe scadute, seguito da VACUUM per recuperare lo spazio di archiviazione. Eseguire VACUUM da solo rimuove solo i file già non referenziati; non elimina nessuna riga. Definisci una politica di retention prima di abilitare il tracciamento in produzione.
• Di default, solo gli amministratori del metastore possono interrogare la tabella dei tracciati. Un amministratore del metastore deve configurare i criteri ABAC di filtro delle righe e concedere SELECT, USE SCHEMA e USE CATALOG prima che i creatori di endpoint o i team di sicurezza possano accedere alle rispettive tracce.