Observabilidade da IA

A observabilidade da IA OpenSearch fornece end-to-end ferramentas para monitorar, depurar e otimizar fluxos de trabalho do agente de IA e do modelo de linguagem grande (LLM). Construído com base nas convenções semânticas do GenAI e integrado nativamente com OpenTelemetry (OTel), ele oferece visibilidade total de como seus aplicativos de IA se comportam na produção.

A observabilidade da IA inclui os seguintes recursos:

• Rastreamento de agentes — Capture rastreamentos hierárquicos de execução nas etapas de orquestração do agente, chamadas de LLM, invocações de ferramentas e operações de recuperação.

• Convenções semânticas do GenAI — Use OTel atributos padronizados comogen_ai.system, e gen_ai.usage.input_tokens para descrever a telemetria gen_ai.request.model específica de IA.

• Instrumentação automática — Capture automaticamente traços de estruturas e fornecedores populares de IA, incluindo OpenAI, Anthropic, Amazon Bedrock LangChain e mais de 20 bibliotecas adicionais.

• Consulta PPL — Consulte e agregue dados de rastreamento usando a Piped Processing Language (PPL) diretamente da interface do usuário. OpenSearch

Introdução

Esta seção explica como instrumentar um agente de IA, enviar rastros para o Amazon OpenSearch Service e visualizá-los na OpenSearch interface do usuário.

Para instalar o SDK

Instale o pacote de instrumentação OpenTelemetry GenAI:

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

Para instrumentar seu código de agente

O exemplo a seguir mostra como registrar o OTel SDK, anotar suas funções de agente com o @observe decorador e enriquecer extensões com atributos 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

Ao enviar rastreamentos para o Amazon OpenSearch Service, use seu endpoint de pipeline OpenSearch de ingestão com autenticação SigV4 em vez de um endpoint localhost. Para obter mais informações sobre como configurar pipelines OpenSearch de ingestão, consulte. Visão geral da OpenSearch ingestão da Amazon

Para visualizar traços na OpenSearch interface do usuário

Depois que seu aplicativo instrumentado enviar dados de rastreamento, você poderá explorá-los na OpenSearch interface do usuário. Em seu espaço de trabalho de observabilidade, expanda Discover no painel de navegação à esquerda e escolha Agent Traces.

UI de rastreamento de agentes

A página Agent Traces na OpenSearch UI fornece uma interface específica para explorar, depurar e monitorar rastreamentos de execução do agente LLM. Ele oferece aos desenvolvedores e operadores de plataforma total observabilidade em aplicativos de IA agentes, incluindo visualizações hierárquicas de rastreamento, menus de detalhes, visualizações de fluxo e métricas agregadas.

Arquitetura

O diagrama a seguir mostra o fluxo de dados dos aplicativos instrumentados para a interface do 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

Pré-requisitos

Antes de usar o Agent Traces, verifique se você tem o seguinte:

• Um OpenSearch cluster com dados de rastreamento indexados em otel-v1-apm-span-* índices.

• OpenTelemetry instrumentação com convenções semânticas GenAI habilitadas em seu aplicativo LLM.

• OpenSearch Ingestão configurada com o otel_trace_raw processador para o qual a ingestão se estende. OpenSearch

• Suporte a consultas PPL habilitado na OpenSearch interface do usuário.

Atributos de extensão necessários

O Agent Traces exige atributos de amplitude específicos para renderizar os dados de rastreamento corretamente. As tabelas a seguir descrevem os campos principais e os atributos específicos do Genai.

Campos de extensão principal

Cada período deve incluir os seguintes campos principais:

Campo	Tipo	Description
traceId	String	Identificador exclusivo para todo o rastreamento.
spanId	String	Identificador exclusivo para esse período.
parentSpanId	String	Identificador do período principal. Esvazie para extensões de raiz.
startTime	Timestamp	Hora em que o período começou.
endTime	Timestamp	Hora em que o período terminou.
durationInNanos	Longo	Duração do intervalo em nanossegundos.
status.code	Inteiro	Código de status do Span (0 = não definido, 1 = OK, 2 = erro).

Atributos do GenAI

Os gen_ai.* atributos a seguir habilitam recursos específicos de IA na interface de usuário do Agent Traces:

Atributo	Valor de exemplo	Description
gen_ai.operation.name	chat	O tipo de operação do GenAI. Determina a categoria de extensão.
gen_ai.system	openai	O sistema ou provedor de IA.
gen_ai.request.model	gpt-4	O modelo usado para a solicitação.
gen_ai.usage.input_tokens	150	Número de tokens de entrada consumidos.
gen_ai.usage.output_tokens	85	Número de tokens de saída gerados.
gen_ai.response.finish_reasons	["stop"]	Motivos pelos quais o modelo parou de gerar.

Layout da página e barra de métricas

A página Rastreamentos do agente exibe uma barra de métricas na parte superior que resume as principais estatísticas de todos os rastreamentos visíveis. As métricas incluem contagem total de rastreamentos, duração média, taxa de erro e uso de tokens. Esses valores são atualizados dinamicamente com base no filtro de tempo e na consulta.

Aba Traços

A guia Traços lista todos os rastreamentos do agente raiz que correspondem à sua consulta atual e ao intervalo de tempo. Cada linha representa uma única invocação de agente.

A tabela a seguir descreve as colunas na tabela de rastreamentos:

Coluna	Description
ID de rastreamento	Identificador exclusivo para o rastreamento. Escolha o link para abrir o menu suspenso de detalhes do rastreamento.
Nome do agente	Nome do agente que iniciou o rastreamento.
Status	Status geral do rastreamento (OK ou Erro).
Duração	Tempo total do primeiro intervalo até o último intervalo no rastreamento.
Segmentos	Número total de extensões no traçado.
Tokens de entrada	Total de tokens de entrada consumidos em todas as chamadas LLM no rastreamento.
Tokens de saída	Total de tokens de saída gerados em todas as chamadas LLM no rastreamento.
Horário de início	Registro de data e hora em que o rastreamento começou.

Categorias de abrangência

Os intervalos são categorizados com base no atributogen_ai.operation.name. Cada categoria é exibida com uma cor e um ícone exclusivos na interface do usuário.

Nome da operação	Categoria	Description
invoke_agent, create_agent	Agente	Etapa de orquestração do agente.
chat	LLM	Chamada de conclusão do bate-papo LLM.
text_completion, generate_content	Conteúdo	Operação de geração de texto.
execute_tool	Ferramenta	Invocação da ferramenta.
embeddings	Incorporações	Geração de incorporação.
retrieval	Recuperação	Operação de recuperação de dados.

Aba de extensões

A guia Expansões exibe extensões individuais em todos os traços. Você pode filtrar e classificar períodos para encontrar operações específicas.

Menu de detalhes do rastreamento

Quando você escolhe uma ID de rastreamento, um painel suspenso é aberto com duas áreas principais:

• Painel esquerdo — Exibe a árvore de rastreamento, que mostra as relações hierárquicas entre pais e filhos entre as extensões. Também inclui um DAG de fluxo (gráfico acíclico direcionado) que visualiza o caminho de execução do agente.

• Painel direito — contém duas guias. A guia Detalhes mostra atributos de extensão, atributos de recursos e metadados específicos do Genai. A guia Cronograma mostra um gráfico em cascata das durações dos períodos e suas relações temporais.

Consultando traços

O Agent Traces usa PPL (Piped Processing Language) para todas as buscas de dados. Você pode escrever consultas no painel de consultas na parte superior da página.

Para listar traços de raiz

A consulta a seguir retorna os 100 rastreamentos mais recentes do agente raiz:

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

Para buscar todos os intervalos para um rastreamento

A consulta a seguir retorna a árvore de extensão completa de um rastreamento específico:

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

Para calcular métricas agregadas

A consulta a seguir calcula a duração média e o uso total do token agrupados por modelo:

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`