Adicionar rastreamento do lado do cliente a agentes do Foundry (versão prévia)

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

O Microsoft Foundry captura automaticamente rastreamentos do lado do servidor para agentes em execução no portal. O rastreamento do lado do cliente estende essa visibilidade para seu próprio código de aplicativo. Ao instrumentar seu aplicativo de agente com o OpenTelemetry, você pode capturar intervalos para chamadas de modelo, invocações de ferramentas e lógica personalizada , depois exportá-los para o Azure Monitor Application Insights, o console ou qualquer back-end de observabilidade que dê suporte ao protocolo OpenTelemetry (OTLP), como Datadog, Grafana Tempo, Jaeger ou Honeycomb.

Neste artigo, você aprenderá como:

  • Instale os pacotes necessários para rastreamento com OpenTelemetry.
  • Habilite a instrumentação de rastreamento do GenAI para aplicativos de agente.
  • Exporte rastreamentos para o Azure Monitor, o console ou um back-end compatível com OTLP.
  • Habilite a gravação de conteúdo para capturar o conteúdo da mensagem.
  • Habilite a propagação de contexto de rastreamento para o rastreamento distribuído (Python).
  • Rastrear funções personalizadas.

Pré-requisitos

  • Um projeto do Foundry com um recurso do Application Insights conectado.

  • Um modelo de IA implantado no projeto. Observe o nome da implantação.

  • Azure CLI instalado. Entre executando az login.

  • Colaborador ou função superior no projeto Foundry. Para exibir rastreamentos, você também precisa do Leitor do Log Analytics no recurso do Application Insights conectado. Para obter mais informações, consulte o controle de acesso baseado em função no Foundry.

  • As seguintes variáveis de ambiente estão definidas com seus próprios valores:

    Variable Descrição
    FOUNDRY_PROJECT_ENDPOINT A URL do endpoint do projeto Foundry. Localize-o na página Visão geral do projeto no portal do Foundry.
    FOUNDRY_MODEL_NAME Nome de implantação de um modelo de IA em seu projeto. Localize-o em Modelos no portal do Foundry.

Pré-requisitos específicos de cada idioma

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

Instalar pacotes de rastreamento

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

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

Para exportação somente de console ou OTLP (por exemplo, Aspire Dashboard), instale o exportador OTLP:

pip install opentelemetry-exporter-otlp

Habilitar o rastreamento do GenAI

A instrumentação de rastreamento do GenAI é um recurso de pré-visualização experimental. Intervalos, atributos e eventos podem mudar em versões futuras. Você deve optar explicitamente pela adesão antes que o rastreamento esteja ativo.

Defina a variável de AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING 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 (sem diferenciar maiúsculas de minúsculas), a instrumentação de rastreamento não será habilitada e um aviso será registrado.

Exportar rastreamentos para o Azure Monitor

Envie rastreamentos para o Azure Application Insights para que eles apareçam no modo de exibição Rastreamentos do portal do Foundry e no 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"]

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"):
        with project.get_openai_client() as openai:
            # Create an agent
            agent = project.agents.create_version(
                agent_name="MyAgent",
                definition=PromptAgentDefinition(
                    model=os.environ["FOUNDRY_MODEL_NAME"],
                    instructions="You are a helpful assistant.",
                ),
            )
            print(f"Agent created (id: {agent.id}, name: {agent.name})")

            # Create a conversation and get a response
            conversation = openai.conversations.create()
            response = openai.responses.create(
                conversation=conversation.id,
                extra_body={"agent_reference": {"name": agent.name, "id": agent.id, "type": "agent_reference"}},
                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, , DefaultAzureCredentialconfigure_azure_monitor

Observação

Para correlacionar rastreamentos com um agente específico no portal do Foundry, inclua o agent_reference junto com name e id em sua chamada responses.create() (conforme mostrado no exemplo de Python acima). Os traços normalmente aparecem entre 2 e 5 minutos.

Exportar rastreamentos para o console

A exportação de console é útil para depuração local. Os rastreamentos são impressos diretamente na 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__)

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

Referência: AIProjectInstrumentor, ConsoleSpanExporter

Habilitar gravação de conteúdo

A gravação de conteúdo captura o conteúdo das mensagens e os argumentos das chamadas de ferramentas nos rastreamentos. Esses dados podem incluir informações confidenciais do usuário.

Cuidado

A gravação de conteúdo captura mensagens do usuário, argumentos de chamada de ferramenta e saídas de modelo. Habilite apenas essa configuração em ambientes de desenvolvimento. Não habilite a gravação de conteúdo em produção, a menos que seus requisitos de conformidade e privacidade permitam isso.

Defina a variável de ambiente antes da instrumentação:

import os

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

Importante

Essa variável controla a gravação apenas para rastreamentos internos. Quando você usa o @trace_function decorador em suas próprias funções, todos os parâmetros e valores retornados são sempre rastreados independentemente dessa configuração.

Desabilitar instrumentação automática (Python)

O SDK do Python instrumenta automaticamente as chamadas à API de Conversas e Respostas OpenAI. Para desabilitar essa instrumentação automática, defina AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API como false antes de chamar AIProjectInstrumentor().instrument(). Quando desabilitado, somente intervalos personalizados explícitos são registrados.

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á habilitada, o SDK rastreia IDs de arquivo e nomes de arquivo por padrão. Para incluir URLs de imagem completa (incluindo URIs de dados base64) e dados de arquivo em intervalos, defina AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA como true.

import os

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

Aviso

A ativação do AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA pode aumentar significativamente o tamanho da carga de rastreamento. Alguns back-ends de rastreamento têm limitações no tamanho máximo dos dados de intervalo. Verifique se o back-end de observabilidade suporta os tamanhos de carga útil esperados antes de habilitar essa configuração.

Habilitar a propagação de contexto de rastreamento (Python)

A propagação de contexto de rastreamento permite que os intervalos do lado do cliente se correlacionem com intervalos do lado do servidor do OpenAI do Azure e de outros serviços do Azure. Quando habilitado, o SDK injeta automaticamente cabeçalhos de contexto de rastreamento W3C (traceparent e tracestate) em solicitações HTTP feitas por clientes OpenAI obtidas por meio de get_openai_client().

A propagação de contexto de rastreamento é habilitada por padrão quando o rastreamento está habilitado. Para desabilitá-la, defina a variável de ambiente AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION como 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 nessa configuração afetam apenas os clientes OpenAI obtidos via get_openai_client()após a alteração. Os clientes adquiridos anteriormente não são afetados.

Controlar a propagação de bagagem (Python)

Por padrão, somente traceparent e tracestate cabeçalhos são propagados. Para incluir também o baggage cabeçalho, defina AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE como true.

Importante

O baggage cabeçalho pode conter pares chave-valor arbitrários, incluindo identificadores de usuário, informações de sessão ou outros dados potencialmente confidenciais. Antes de habilitar a propagação de bagagem:

  • Audite quais dados seu aplicativo e bibliotecas de terceiros adicionam à bagagem do OpenTelemetry.
  • Entenda que a bagagem é enviada para o Azure OpenAI e pode ser registrada pelos serviços do Azure.
  • Nunca adicione informações confidenciais à bagagem quando a propagação estiver habilitada.

Observação

O SDK do C# depende da propagação padrão do .NET System.Diagnostics.Activity . A injeção explícita de contexto de rastreamento por solicitação não é exposta como um recurso separado do SDK.

Rastrear funções personalizadas

Python – use o decorador @trace_function

O decorador trace_function cria um intervalo OpenTelemetry para cada chamada para sua função. Os parâmetros são registrados como code.function.parameter.<name> e o valor retornado 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 intervalo personalizado em vez do nome da função, passe-o como um 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 registra:

  • Parâmetros como atributos de intervalo code.function.parameter.<name>.
  • Valores de retorno como code.function.return.value.
  • Tipos com suporte: str, , int, float, boole coleções (list, , dict, tuple). set Os tipos de objeto são omitidos.

Observação

A OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT variável de ambiente não afeta o rastreamento de função personalizada. O @trace_function decorador sempre rastreia parâmetros e retorna valores.

C# — use ActivitySource manualmente

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

using System.Diagnostics;

// Define a custom activity source
private static readonly ActivitySource s_source = new("MyApp.CustomFunctions");

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

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

Registre sua fonte personalizada junto com a origem do SDK em seu provedor de rastreamento:

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

Configurar a instrumentação programaticamente (Python)

Como alternativa às variáveis de ambiente, passe 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 Equivalente à variável de ambiente Default
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 rastreamento está habilitado.

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

Adicionar atributos personalizados a spans (Python)

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

Registre o processador com o provedor de rastreamento global:

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 com variáveis de ambiente

A tabela a seguir lista todas as variáveis de ambiente que você pode usar para configurar o comportamento de rastreamento:

Variable Linguagem Default Descrição
AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING Python, C# false Habilite a instrumentação de rastreamento do GenAI.
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT Python, C# false Capturar o conteúdo da mensagem e os parâmetros de chamada de ferramenta.
AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION Python true* Injete cabeçalhos de Contexto de Rastreamento W3C nas solicitações.
AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE Python false Inclua o cabeçalho baggage na propagação do contexto de rastreamento.
AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API Python true Instrumente automaticamente APIs de Respostas e Conversas.
AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA Python false Inclua dados de imagem e arquivo em intervalos (não apenas IDs de arquivo).

* O padrão é true quando o rastreamento está habilitado.

Para obter a lista completa de variáveis de ambiente e seu comportamento, consulte Rastreamento no README do SDK de Projetos de IA do Azure.

Segurança e privacidade

O rastreamento do lado do cliente pode capturar informações confidenciais. Siga estas práticas para reduzir o risco:

  • Gravação de conteúdo: captura entradas do usuário, respostas de modelo e argumentos de chamada de ferramenta. Desative na produção somente se necessário.
  • Propagação de bagagem: pode expor informações pessoais identificáveis (PII) e dados de sessão. Desabilitado por padrão.
  • Propagação de contexto de rastreamento: envia IDs de rastreamento para os serviços do Azure. Se os requisitos de conformidade proibirem o compartilhamento de identificadores de rastreamento, desabilite-os.
  • Segredos: não armazene segredos, credenciais ou tokens em prompts, argumentos de ferramenta ou atributos de extensão.
  • Controle de acesso: tratar dados de rastreamento como telemetria de produção. Aplique os mesmos controles de acesso e políticas de retenção que você usa para logs e métricas.

Solução de problemas

Questão Resolução
O rastreamento não produz intervalos Verifique AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING se está definido como trueantes de chamar AIProjectInstrumentor().instrument() (Python) ou antes de criar o provedor de rastreamento (C#).
O conteúdo da mensagem não é exibido em intervalos Defina OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT como true.
Rastros não aparecem no Azure Monitor Verifique se a cadeia de conexão do Application Insights está correta e se o recurso está acessível. Verifique se sua conta tem a função Leitor do Log Analytics.
Os intervalos do lado do cliente e do servidor não estão correlacionados (Python) Verifique se a propagação de contexto de rastreamento está habilitada e se os clientes do OpenAI são obtidos via get_openai_client()após a instrumentação.
Os rastreamentos aparecem com um atraso Os rastros normalmente levam de 2 a 5 minutos para aparecer no portal do Foundry e no Azure Monitor. Aguarde e atualize.

Conteúdo relacionado

  • Last updated on