Adicionar rastreamento do lado do cliente aos agentes da Foundry (versão de pré-visualização)

Importante

Os itens marcados como pré-visualização neste artigo estão atualmente em pré-visualização. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e a Microsoft não a recomenda para cargas de trabalho de produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos de Utilização Suplementares para Microsoft Azure Pré-visualizações.

A Microsoft Foundry captura automaticamente os registos do lado do servidor para agentes executados no portal. O rastreamento do lado do cliente estende essa visibilidade ao seu próprio código de aplicação. Ao instrumentar a sua aplicação agente com OpenTelemetry, pode capturar spans para chamadas de modelo, invocações de ferramentas e lógica personalizada — depois exportá-los para o Azure Monitor Application Insights, a consola ou qualquer backend de observabilidade que suporte o protocolo OpenTelemetry (OTLP), como Datadog, Grafana Tempo, Jaeger ou Honeycomb.

Neste artigo, aprende como:

  • Instale os pacotes de rastreamento necessários do OpenTelemetry.
  • Ativar a instrumentação de rastreamento GenAI para aplicações de agentes.
  • Exporta os traços para o Azure Monitor, para a consola ou para um backend compatível com OTLP.
  • Ative a gravação de conteúdo para capturar o conteúdo das mensagens.
  • Ative a propagação do contexto de traços para rastreamento distribuído (Python).
  • Monitorizar funções personalizadas.

Pré-requisitos

Pré-requisitos específicos da língua

  • Python 3.10 ou posterior.
  • A versão 2.0.0 ou posterior do pacote azure-ai-projects.

Instalar pacotes de rastreio

Instale o Microsoft Foundry SDK, OpenTelemetry e o exportador Azure Monitor:

pip install azure-ai-projects opentelemetry-sdk azure-core-tracing-opentelemetry azure-monitor-opentelemetry

Para exportação apenas para consola ou OTLP (por exemplo, Aspire Dashboard), instale o exportador OTLP:

pip install opentelemetry-exporter-otlp

Ativar o rastreamento GenAI

A instrumentação de rastreamento GenAI é uma funcionalidade experimental de pré-visualização. Spans, atributos e eventos podem mudar em versões futuras. Tem de optar explicitamente por ele antes de o rastreamento estar ativo.

Defina a AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING variável de ambiente para trueantes de chamar AIProjectInstrumentor().instrument():

import os

os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"

from azure.ai.projects.telemetry import AIProjectInstrumentor

# Enable instrumentation
AIProjectInstrumentor().instrument()

Se a variável não estiver definida ou não for true (independentemente de maiúsculas e minúsculas), a instrumentação de rastreio não está ativada e um aviso é registado.

Exportar traces para Azure Monitor

Envie traços para Aplicação Azure Insights para que apareçam na vista Traces do portal Foundry e na Azure Monitor.

import os

os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity import DefaultAzureCredential
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
AGENT_NAME = "MyAgent"

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project,
):
    # Get the Application Insights connection string from the project
    connection_string = project.telemetry.get_application_insights_connection_string()
    configure_azure_monitor(connection_string=connection_string)

    tracer = trace.get_tracer(__name__)

    with tracer.start_as_current_span("agent-tracing-scenario"):
        # Create an agent
        agent = project.agents.create_version(
            agent_name=AGENT_NAME,
            definition=PromptAgentDefinition(
                model=os.environ["FOUNDRY_MODEL_NAME"],
                instructions="You are a helpful assistant.",
            ),
        )
        print(f"Agent created (id: {agent.id}, name: {agent.name})")

        with project.get_openai_client(agent_name=agent.name) as openai:
            # Create a conversation and get a response
            conversation = openai.conversations.create()
            response = openai.responses.create(
                conversation=conversation.id,
                input="What is the largest city in France?",
            )
            print(f"Response: {response.output_text}")

            # Clean up
            openai.conversations.delete(conversation_id=conversation.id)

        project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

Referência: AIProjectClient, DefaultAzureCredential, configure_azure_monitor

Nota

Para correlacionar as pistas com um agente específico no portal Foundry, inclua o agent_reference com name e id na sua chamada responses.create() (como mostrado no exemplo Python acima). Os vestígios normalmente aparecem entre 2 a 5 minutos.

Exportar traços para a consola

A exportação de consola é útil para depuração local. Os registos são enviados diretamente para a saída padrão.

import os

os.environ["AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING"] = "true"

from azure.ai.projects.telemetry import AIProjectInstrumentor
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor

# Set up console tracing
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(
    SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# Enable instrumentation
AIProjectInstrumentor().instrument()

tracer = trace.get_tracer(__name__)

Também pode usar o Aspire Dashboard como um visualizador local compatível com OTLP. Instale o exportador OTLP (pip install opentelemetry-exporter-otlp) e configure-o como exportador em vez de ConsoleSpanExporter.

Referência: AIProjectInstrumentor, ConsoleSpanExporter

Ativar gravação de conteúdos

A gravação de conteúdo captura o conteúdo das mensagens e os argumentos das chamadas de ferramenta nos rastreamentos. Estes dados podem incluir informações sensíveis dos utilizadores.

Cautela

A gravação de conteúdo capta mensagens do utilizador, argumentos de chamadas de ferramenta e saídas de modelos. Só ative esta configuração em ambientes de desenvolvimento. Não ative a gravação de conteúdos em produção a menos que os seus requisitos de conformidade e privacidade o permitam.

Defina a variável de ambiente antes de instrumentar:

import os

os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "true"

Importante

Esta variável controla a gravação apenas para traços incorporados. Quando usas o @trace_function decorador nas tuas próprias funções, todos os parâmetros e valores de retorno são sempre rastreados, independentemente desta definição.

Desativar instrumentação automática (Python)

O SDK Python instrumenta automaticamente as chamadas das APIs de Respostas e Conversas da OpenAI. Para desativar esta auto-instrumentação, defina AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API para false antes de chamar AIProjectInstrumentor().instrument(). Quando desativado, apenas spans personalizados explícitos são registados.

import os

os.environ["AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API"] = "false"

Rastrear dados binários (Python)

Quando a gravação de conteúdo está ativada, o SDK traça IDs e nomes de ficheiros por defeito. Para incluir URLs de imagem completas (incluindo URIs de dados base64) e dados de ficheiros em spans, defina AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA para true.

import os

os.environ["AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA"] = "true"

Aviso

Ativar AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA pode aumentar significativamente o tamanho da carga útil de traço. Alguns backends de traçado têm limitações quanto ao tamanho máximo dos dados de span. Verifique se o seu backend de observabilidade suporta os tamanhos esperados de carga útil antes de ativar esta configuração.

Ativar propagação de contexto de traço (Python)

A propagação do contexto de rastreamento permite que spans do lado do cliente se correlacionem com spans do lado do servidor do Azure OpenAI e outros serviços do Azure. Quando ativado, o SDK injeta automaticamente cabeçalhos de Contexto de Traço do W3C (traceparent e tracestate) em pedidos HTTP feitos por clientes OpenAI obtidos via get_openai_client().

A propagação do contexto de rastreamento é ativada por padrão quando o rastreamento está ativado. Para a desativar, defina a AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION variável ambiente para false, ou passe o parâmetro diretamente:

from azure.ai.projects.telemetry import AIProjectInstrumentor

# Disable trace context propagation
AIProjectInstrumentor().instrument(enable_trace_context_propagation=False)

As alterações a esta definição afetam apenas os clientes OpenAI obtidos get_openai_client() a alteração. Os clientes adquiridos anteriormente não são afetados.

Controlo de propagação de bagagem (Python)

Por defeito, apenas os cabeçalhos traceparent e tracestate são propagados. Para incluir também o baggage cabeçalho, defina AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE para true.

Importante

O baggage cabeçalho pode conter pares chave-valor arbitrários, incluindo identificadores de utilizador, informações de sessão ou outros dados potencialmente sensíveis. Antes de ativar a propagação de bagagem:

  • Audite quais dados são adicionados à bagagem do OpenTelemetry pela sua aplicação e bibliotecas de terceiros.
  • Perceba que a bagagem é enviada para o Azure OpenAI e pode ser registada pelos serviços do Azure.
  • Nunca adicione informação sensível à bagagem quando a propagação estiver ativada.

Nota

O SDK C# baseia-se na propagação padrão .NET System.Diagnostics.Activity. A injeção explícita de contexto de rastreio por pedido não é exposta como uma funcionalidade separada do SDK.

Traçar funções personalizadas

Python — use o decorador @trace_function

O trace_function decorador cria um span OpenTelemetry para cada chamada à sua função. Os parâmetros são registados como code.function.parameter.<name> e o valor de retorno como code.function.return.value.

from azure.ai.projects.telemetry import trace_function

@trace_function
def fetch_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"Weather in {location}: sunny, 72°F"

Para usar um nome de abrangência personalizado em vez do nome da função, passe como parâmetro:

@trace_function("get-current-weather")
def fetch_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"Weather in {location}: sunny, 72°F"

O decorador regista:

  • Parâmetros como code.function.parameter.<name> atributos span.
  • Devolve valores como code.function.return.value.
  • Tipos suportados: str, int, float, bool, e coleções (list, dict, tuple, set). Os tipos de objetos são omitidos.

Nota

A OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT variável ambiente não afeta o rastreamento de funções personalizadas. O @trace_function decorador traça sempre parâmetros e valores de retorno.

C# — usar ActivitySource manualmente

O SDK de C# não inclui um decorador de traçado. Use o .NET ActivitySource padrão para instrumentar as suas próprias funções:

using System.Diagnostics;

using ActivitySource source = new("MyApp.CustomFunctions");

string FetchWeather(string location)
{
    using var activity = source.StartActivity("FetchWeather");
    activity?.SetTag("input.location", location);

    var result = $"Weather in {location}: sunny, 72°F";
    activity?.SetTag("output", result);
    return result;
}

Registe a sua fonte personalizada juntamente com a fonte SDK no seu fornecedor de traçadores:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .AddSource("MyApp.CustomFunctions")
    .SetResourceBuilder(
        ResourceBuilder.CreateDefault().AddService("MyApp"))
    .AddConsoleExporter()
    .Build();

Configurar instrumentação programáticamente (Python)

Como alternativa às variáveis de ambiente, passa os parâmetros de configuração diretamente para AIProjectInstrumentor().instrument():

from azure.ai.projects.telemetry import AIProjectInstrumentor

AIProjectInstrumentor().instrument(
    enable_content_recording=True,
    enable_trace_context_propagation=True,
    enable_baggage_propagation=False,
)
Parâmetro Variável ambiental equivalente Padrão
enable_content_recording OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT False
enable_trace_context_propagation AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION True*
enable_baggage_propagation AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE False

* O padrão é True quando o rastreio está ativado.

Quando tanto um parâmetro como a sua variável de ambiente correspondente são definidos, o valor do parâmetro tem prioridade.

Adicionar atributos personalizados aos spans

Crie um SpanProcessor personalizado para injetar metadados, como IDs de sessão, em cada span:

from opentelemetry.sdk.trace import SpanProcessor, ReadableSpan
from opentelemetry.trace import Span

class CustomAttributeSpanProcessor(SpanProcessor):
    def on_start(self, span: Span, parent_context=None):
        span.set_attribute("session.id", "user-session-abc")

    def on_end(self, span: ReadableSpan):
        pass

Registe o processador junto do fornecedor global de traçadores:

from typing import cast
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

provider = cast(TracerProvider, trace.get_tracer_provider())
provider.add_span_processor(CustomAttributeSpanProcessor())

Controlar o comportamento de rastreamento usando variáveis de ambiente

A tabela seguinte lista todas as variáveis de ambiente que pode usar para configurar o comportamento de rastreamento:

Variável Linguagem Padrão Descrição
AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING Python, C # false Ative a instrumentação de rastreamento GenAI.
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT Python, C # false Capturar o conteúdo das mensagens e os parâmetros das chamadas de ferramenta.
AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION Python true* Injetar cabeçalhos de Trace Context do W3C nos pedidos.
AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE Python false Inclua o baggage cabeçalho na propagação do contexto de rastreio.
AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API Python true APIs de Instrumentação Automática de Respostas e Conversas.
AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA Python false Inclua dados de imagem e ficheiros em intervalos (não apenas IDs de ficheiros).

* O padrão é true quando o rastreio está ativado.

Para a lista completa de variáveis do ambiente e o seu comportamento, veja Tracing no SDK Azure AI Projects README.

Segurança e privacidade

O rastreio do lado do cliente pode captar informações sensíveis. Siga estas práticas para reduzir o risco:

  • Gravação de conteúdo: Captura entradas do utilizador, respostas do modelo e argumentos de chamada de ferramenta. Desativar na produção, a menos que seja necessário.
  • Propagação de bagagem: Pode expor informações pessoalmente identificáveis e de sessão. Desativado por defeito.
  • Propagação do contexto de rastreio: Envia IDs de rastreio para serviços Azure. Se os requisitos de conformidade proibirem a partilha de identificadores de traço, desative-o.
  • Segredos: Não armazene segredos, credenciais ou tokens em prompts, argumentos de ferramentas ou atributos de span.
  • Controlo de acesso: Trate os dados de rastreio como telemetria de produção. Aplique os mesmos controlos de acesso e políticas de retenção que usa para registos e métricas.

Resolução de problemas

Problema Resolução
O rastreamento não produz intervalos Verifique se AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING está definido para trueantes chamando AIProjectInstrumentor().instrument() (Python) ou antes de criar o fornecedor de traçadores (C#).
O conteúdo da mensagem não aparece em intervalos Definir OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT para true.
Os rastos não aparecem no Azure Monitor Verifique se a cadeia de ligação do Application Insights está correta e o recurso está acessível. Verifica se a tua conta tem a função Log Analytics Leitor. Se as tabelas estiverem protegidas, atribua também a função Leitor de Dados de Monitorização com Privilégios.
Os spans do lado do cliente e do lado do servidor não estão correlacionados (Python) Verifique se a propagação do contexto de traços está ativada e que os clientes OpenAI são obtidos via instrumentação get_openai_client()after.
Os traços aparecem com um atraso As pistas normalmente demoram entre 2 a 5 minutos a aparecer no portal Foundry e no Azure Monitor. Espera e atualiza.

Conteúdo relacionado

  • Última atualização a