Osservabilità dell'IA

L'osservabilità dell'IA OpenSearch fornisce end-to-end strumenti per il monitoraggio, il debug e l'ottimizzazione dei flussi di lavoro degli agenti AI e dei modelli di linguaggio di grandi dimensioni (LLM). Basato sulle convenzioni semantiche GenAI e integrato nativamente con OpenTelemetry (OTel), offre una visibilità completa sul comportamento delle applicazioni di intelligenza artificiale in produzione.

L'osservabilità dell'IA include le seguenti funzionalità:

• Tracciamento degli agenti: acquisisce le tracce di esecuzione gerarchiche tra le fasi di orchestrazione degli agenti, le chiamate LLM, le chiamate agli strumenti e le operazioni di recupero.

• Convenzioni semantiche GenAI: utilizza attributi standardizzati come e per descrivere la telemetria specifica dell'intelligenza artificiale. OTel gen_ai.system gen_ai.request.model gen_ai.usage.input_tokens

• Strumentazione automatica: acquisisci automaticamente le tracce dai framework e dai provider di intelligenza artificiale più diffusi, tra cui OpenAI, Anthropic, Amazon Bedrock e più di 20 librerie aggiuntive. LangChain

• Interrogazione PPL: interroga e aggrega i dati di traccia utilizzando Piped Processing Language (PPL) direttamente dall'interfaccia utente. OpenSearch

Nozioni di base

Questa sezione illustra come utilizzare un agente AI, inviare tracce ad Amazon OpenSearch Service e visualizzarle nell' OpenSearch interfaccia utente.

Per installare l'SDK

Installa il pacchetto di strumentazione OpenTelemetry GenAI:

pip install opentelemetry-instrumentation-openai-v2 opentelemetry-sdk opentelemetry-exporter-otlp

Per strumentare il codice del tuo agente

L'esempio seguente mostra come registrare l' OTel SDK, annotare le funzioni dell'agente con il @observe decoratore e arricchire gli intervalli con gli attributi GenAI.

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

# Register the tracer provider
provider = TracerProvider()
processor = BatchSpanProcessor(
    OTLPSpanExporter(endpoint="<your-osis-endpoint>")  # Use your OpenSearch Ingestion endpoint with SigV4
)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

# Decorate your agent function
@observe
def run_agent(prompt: str):
    with tracer.start_as_current_span("invoke_agent") as span:
        span.set_attribute("gen_ai.operation.name", "invoke_agent")
        span.set_attribute("gen_ai.system", "openai")
        span.set_attribute("gen_ai.request.model", "gpt-4")

        # Enrich with token usage after the LLM call
        response = call_llm(prompt)
        span.set_attribute("gen_ai.usage.input_tokens", response.input_tokens)
        span.set_attribute("gen_ai.usage.output_tokens", response.output_tokens)
        return response

Nota

Quando invii tracce ad Amazon OpenSearch Service, utilizza l'endpoint della pipeline OpenSearch Ingestion con l'autenticazione SigV4 anziché un endpoint localhost. Per ulteriori informazioni sulla configurazione delle pipeline di Ingestion, consulta. OpenSearch Panoramica di Amazon OpenSearch Ingestion

Per visualizzare le tracce nell'interfaccia utente OpenSearch

Dopo che l'applicazione strumentata ha inviato i dati di traccia, puoi esplorarli nell' OpenSearch interfaccia utente. Nel tuo spazio di lavoro sull'osservabilità, espandi Discover nella barra di navigazione a sinistra e scegli Agent Traces.

Interfaccia utente di Agent Tracing

La pagina Agent Traces nell' OpenSearch interfaccia utente fornisce un'interfaccia appositamente creata per l'esplorazione, il debug e il monitoraggio delle tracce di esecuzione degli agenti LLM. Offre agli sviluppatori e agli operatori di piattaforma la piena osservabilità nelle applicazioni di intelligenza artificiale agentiche, tra cui viste di traccia gerarchiche, riepiloghi di dettaglio, visualizzazioni dei flussi e metriche aggregate.

Architecture

Il diagramma seguente mostra il flusso di dati dalle applicazioni strumentate all'interfaccia utente di Agent Traces:

LLM Application (with OTel SDK + GenAI instrumentation)
    |
    |  OTLP (gRPC/HTTP)
    v
OTel Collector (batch, transform)
    |
    +---- OTLP ----> OpenSearch Ingestion --> OpenSearch (otel-v1-apm-span-*)
    |
    +---- Prometheus Remote Write --> Prometheus (metrics)
                                          |
                                          v
                              OpenSearch UI
                              +-- Agent Traces Plugin

Prerequisiti

Prima di utilizzare Agent Traces, assicurati di disporre di quanto segue:

• Un OpenSearch cluster con dati di traccia indicizzati in otel-v1-apm-span-* indici.

• OpenTelemetry strumentazione con convenzioni semantiche GenAI abilitate nell'applicazione LLM.

• OpenSearch Inserimento configurato con il processore in cui inserire intervalli. otel_trace_raw OpenSearch

• Supporto per query PPL abilitato nell'interfaccia utente. OpenSearch

Attributi span richiesti

Agent Traces richiede attributi span specifici per visualizzare correttamente i dati di traccia. Le tabelle seguenti descrivono i campi principali e gli attributi specifici di GenAI.

Campi Core Span

Ogni intervallo deve includere i seguenti campi principali:

Campo	Tipo	Description
traceId	Stringa	Identificatore univoco per l'intera traccia.
spanId	Stringa	Identificatore univoco per questo intervallo.
parentSpanId	Stringa	Identificatore dell'intervallo principale. Vuoto per le estensioni principali.
startTime	Time stamp	Ora in cui è iniziato l'intervallo.
endTime	Time stamp	Ora in cui l'intervallo è terminato.
durationInNanos	Long	Durata dell'intervallo in nanosecondi.
status.code	Numero intero	Codice di stato Span (0 = non impostato, 1 = OK, 2 = errore).

Attributi GenAI

I seguenti gen_ai.* attributi abilitano funzionalità specifiche dell'intelligenza artificiale nell'interfaccia utente di Agent Traces:

Attributo	Valore di esempio	Description
gen_ai.operation.name	chat	Il tipo di operazione GenAI. Determina la categoria di estensione.
gen_ai.system	openai	Il sistema o il provider di intelligenza artificiale.
gen_ai.request.model	gpt-4	Il modello utilizzato per la richiesta.
gen_ai.usage.input_tokens	150	Numero di token di input consumati.
gen_ai.usage.output_tokens	85	Numero di token di output generati.
gen_ai.response.finish_reasons	["stop"]	Motivi per cui il modello ha smesso di generare.

Layout della pagina e barra delle metriche

La pagina Agent Traces mostra una barra delle metriche nella parte superiore che riassume le statistiche chiave su tutte le tracce visibili. Le metriche includono il numero totale di tracce, la durata media, il tasso di errore e l'utilizzo dei token. Questi valori vengono aggiornati dinamicamente in base al filtro temporale e alla query.

Scheda Tracce

La scheda Traces elenca tutte le tracce dell'agente principale che corrispondono alla query e all'intervallo di tempo correnti. Ogni riga rappresenta una singola chiamata all'agente.

La tabella seguente descrive le colonne della tabella trace:

Colonna	Description
ID di traccia	Identificatore univoco per la traccia. Scegli il link per aprire il riquadro a comparsa dei dettagli della traccia.
Nome dell'agente	Nome dell'agente che ha avviato la traccia.
Stato	Stato generale della traccia (OK o Errore).
Durata	Tempo totale dal primo all'ultimo intervallo della traccia.
Intervalli	Numero totale di intervalli nella traccia.
Token di input	Token di input totali consumati in tutte le chiamate LLM nella traccia.
Token di output	Token di output totali generati in tutte le chiamate LLM nella traccia.
Ora di inizio	Timestamp di inizio della traccia.

Amplia le categorie

Gli intervalli sono classificati in base all'attributo. gen_ai.operation.name Ogni categoria viene visualizzata con un colore e un'icona unici nell'interfaccia utente.

Nome operazione	Categoria	Description
invoke_agent, create_agent	Agente	Fase di orchestrazione degli agenti.
chat	LLM	Chiamata di completamento della chat LLM.
text_completion, generate_content	Contenuti	Operazione di generazione del testo.
execute_tool	Strumento	Invocazione dello strumento.
embeddings	Embedding	Generazione di incorporamento.
retrieval	Recupero	Operazione di recupero dei dati.

Scheda Spans

La scheda Estensioni mostra le singole estensioni su tutte le tracce. Puoi filtrare e ordinare gli intervalli per trovare operazioni specifiche.

Visualizza i dettagli di Trace

Quando scegli un ID di traccia, si apre un pannello a tendina con due aree principali:

• Pannello sinistro: visualizza l'albero di traccia, che mostra le relazioni gerarchiche padre-figlio tra gli intervalli. Include anche un DAG (grafico aciclico diretto) di flusso che visualizza il percorso di esecuzione dell'agente.

• Pannello destro: contiene due schede. La scheda Dettagli mostra gli attributi span, gli attributi delle risorse e i metadati specifici di GenAI. La scheda Cronologia mostra un grafico a cascata delle durate degli intervalli e delle relative relazioni temporali.

Interrogazione delle tracce

Agent Traces utilizza PPL (Piped Processing Language) per il recupero di tutti i dati. È possibile scrivere interrogazioni nel pannello delle interrogazioni nella parte superiore della pagina.

Per elencare le tracce principali

La seguente query restituisce le 100 tracce di root agent più recenti:

source = otel-v1-apm-span-*
| where parentSpanId = "" AND isnotnull(`attributes.gen_ai.operation.name`)
| sort - startTime
| head 100

Per recuperare tutti gli intervalli di una traccia

La seguente query restituisce lo span tree completo per una traccia specifica:

source = otel-v1-apm-span-*
| where traceId = "trace-id"
| head 1000

Per calcolare metriche aggregate

La seguente query calcola la durata media e l'utilizzo totale dei token raggruppati per modello:

source = otel-v1-apm-span-*
| where isnotnull(`attributes.gen_ai.request.model`)
| stats avg(durationInNanos) as avg_duration,
        sum(`attributes.gen_ai.usage.input_tokens`) as total_input_tokens,
        sum(`attributes.gen_ai.usage.output_tokens`) as total_output_tokens
    by `attributes.gen_ai.request.model`