Adición del seguimiento del lado del cliente a agentes de Foundry (versión preliminar)

Importante

Los elementos marcados como versión preliminar en este artículo se encuentran actualmente en versión preliminar. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y Microsoft no lo recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para obtener más información, vea Supplemental Terms of Use for Microsoft Azure Previews.

Microsoft Foundry captura automáticamente los seguimientos del lado servidor para los agentes que se ejecutan en el portal. El seguimiento del lado del cliente amplía esa visibilidad al código de su propia aplicación. Mediante la instrumentación de la aplicación del agente con OpenTelemetry, puede capturar intervalos para llamadas de modelo, invocaciones de herramientas y lógica personalizada, y luego exportarlas a Azure Monitor Application Insights, la consola o cualquier back-end de observabilidad que admita el protocolo OpenTelemetry (OTLP), como Datadog, Grafana Tempo, Jaeger o Honeycomb.

En este artículo, aprenderá a:

Instale los paquetes de seguimiento de OpenTelemetry necesarios.
Habilite la instrumentación de seguimiento de GenAI para las aplicaciones del agente.
Exporte seguimientos a Azure Monitor, la consola o un back-end compatible con OTLP.
Habilite la grabación de contenido para capturar el contenido del mensaje.
Habilite la propagación del contexto de seguimiento para el seguimiento distribuido (Python).
Seguimiento de funciones personalizadas.

Requisitos previos

Un proyecto Foundry con un recurso de Application Insights integrado.
Un modelo de IA implementado en el proyecto. Anote el nombre del despliegue.
CLI de Azure instalado. Inicie sesión ejecutando az login.
Colaborador o rol superior en el proyecto Foundry. Para ver los seguimientos, también necesita Lector de Log Analytics en el recurso conectado de Application Insights. Si esas tablas Log Analytics están protegidas, asigne también lector de datos de supervisión con privilegios. Para obtener más información, consulte Control de acceso basado en rol en Foundry.

Las siguientes variables de entorno establecidas con sus propios valores:

Variable	Descripción
`FOUNDRY_PROJECT_ENDPOINT`	Dirección URL del punto de conexión del proyecto Foundry. Busque en la página Información general del proyecto en el portal de Foundry.
`FOUNDRY_MODEL_NAME`	El nombre de implementación de un modelo de IA en tu proyecto. Busque en Modelos en el portal de Foundry.

Requisitos previos específicos del idioma

Python 3.10 o posterior.
El azure-ai-projects paquete versión 2.0.0 o posterior.

Instalación de paquetes de seguimiento

Instale el SDK de Microsoft Foundry, OpenTelemetry y el exportador de Azure Monitor:

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

Para exportación únicamente en consola o mediante OTLP (por ejemplo, Panel Aspire), instale el exportador de OTLP:

pip install opentelemetry-exporter-otlp

Agregue los paquetes NuGet necesarios:

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.Identity
dotnet add package Azure.Monitor.OpenTelemetry.Exporter
dotnet add package OpenTelemetry.Exporter.Console

Para las aplicaciones de ASP.NET Core, Azure.Monitor.OpenTelemetry.AspNetCore es el paquete preferido. El paquete Azure.Monitor.OpenTelemetry.Exporter que se muestra aquí funciona para todos los tipos de aplicación .NET.

Instale el SDK de Microsoft Foundry, OpenTelemetry y el exportador de Azure Monitor:

npm install @azure/ai-projects @azure/identity @azure/monitor-opentelemetry @opentelemetry/api dotenv

Para la exportación solo para consola, también necesita los paquetes del SDK de OpenTelemetry:

npm install @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base

Habilitación del seguimiento de GenAI

La instrumentación de seguimiento de GenAI es una característica de versión preliminar experimental. Los intervalos, los atributos y los eventos pueden cambiar en versiones futuras. Debe dar su consentimiento explícitamente antes de que el seguimiento se active.

Establezca la variable de AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING entorno en trueantes de llamar a AIProjectInstrumentor().instrument():

import os

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

from azure.ai.projects.telemetry import AIProjectInstrumentor

# Enable instrumentation
AIProjectInstrumentor().instrument()

Si la variable no está establecida o no es true (no distingue entre mayúsculas y minúsculas), la instrumentación de seguimiento no está habilitada y se registra una advertencia.

Use un AppContext conmutador o la misma variable de entorno:

// Enable GenAI tracing
AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

Al habilitar Azure.Experimental.EnableGenAITracing, el SDK habilita automáticamente la marca Azure.Experimental.EnableActivitySource, que es necesaria para que la instrumentación de OpenTelemetry funcione.

Si tanto el AppContext switch como la variable de entorno están establecidos, el AppContext switch tiene prioridad.

Nota

En C#, todas las variables de entorno relacionadas con el seguimiento aceptan true (no distinguen mayúsculas de minúsculas) o 1 como valores de habilitación equivalentes.

Pasa tracingOptions en experimental: true cuando crees AIProjectClient. A diferencia de los SDK de Python y C#, el SDK de JavaScript/TypeScript habilita el seguimiento por instancia de cliente en lugar de mediante una llamada de instrumentación independiente:

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: {
      experimental: true,
    },
  },
);

También puede establecer la AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING variable de entorno en true en lugar de pasar la opción . La tracingOptions propiedad tiene prioridad sobre la variable de entorno. Consulte Exportación de seguimientos a Azure Monitor para obtener un ejemplo completo.

Exportación de rastros a Azure Monitor

Envíe rastros a Aplicación de Azure Insights para que aparezcan en la vista Traces del portal de Foundry y en 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)

Referencia: AIProjectClient, , DefaultAzureCredentialconfigure_azure_monitor

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenAI.Responses;

var projectEndpoint = Environment.GetEnvironmentVariable(
    "FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException(
        "FOUNDRY_PROJECT_ENDPOINT isn't set.");
var modelName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL_NAME isn't set.");

// Enable GenAI tracing
AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Get the Application Insights connection string from the project
var connectionString = await projectClient.Telemetry
    .GetApplicationInsightsConnectionStringAsync();

// The Azure Monitor exporter reads this environment variable automatically
Environment.SetEnvironmentVariable(
    "APPLICATIONINSIGHTS_CONNECTION_STRING", connectionString);

// Configure OpenTelemetry with Azure Monitor exporter
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .SetResourceBuilder(
        ResourceBuilder.CreateDefault().AddService("AgentTracingSample"))
    .AddAzureMonitorTraceExporter()
    .Build();

using (tracerProvider)
{
    // Create an agent
    DeclarativeAgentDefinition agentDefinition = new(model: modelName)
    {
        Instructions = "You are a helpful assistant."
    };
    ProjectsAgentVersion agent = await projectClient.AgentAdministrationClient
        .CreateAgentVersionAsync(
            agentName: $"agent-tracing-{Guid.NewGuid():N}",
            options: new(agentDefinition));
    try
    {
        Console.WriteLine(
            $"Agent created (id: {agent.Id}, name: {agent.Name})");

        // Call the agent to emit GenAI spans
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient
            .GetProjectResponsesClientForAgent(agent.Name);
#pragma warning disable OPENAI001
        ResponseItem request = ResponseItem.CreateUserMessageItem(
            "What is the largest city in France?");
        ResponseResult response = await responseClient.CreateResponseAsync(
            [request]);
#pragma warning restore OPENAI001
        Console.WriteLine($"Response: {response.GetOutputText()}");
    }
    finally
    {
        await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(
            agentName: agent.Name,
            agentVersion: agent.Version);
    }
}

Referencia: AIProjectClient, , DefaultAzureCredentialSdk.CreateTracerProviderBuilder

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import {
  useAzureMonitor,
  shutdownAzureMonitor,
} from "@azure/monitor-opentelemetry";
import { context, trace } from "@opentelemetry/api";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "";
const modelName = process.env["FOUNDRY_MODEL_NAME"] || "";

// Enable tracing when you create the client. To capture prompt and
// completion content, set contentRecording to true (off by default).
const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: { contentRecording: false, experimental: true },
  },
);
const openAIClient = project.getOpenAIClient();

// Get the Application Insights connection string from the project
const connectionString =
  await project.telemetry.getApplicationInsightsConnectionString();

// Configure Azure Monitor tracing
useAzureMonitor({
  azureMonitorExporterOptions: { connectionString },
});

const tracer = trace.getTracer("AgentTracingSample");
const span = tracer.startSpan("agent-tracing-scenario");
const ctx = trace.setSpan(context.active(), span);

await context.with(ctx, async () => {
  // Create an agent
  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: modelName,
    instructions: "You are a helpful assistant.",
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name})`);

  // Create a conversation and get a response
  const conversation = await openAIClient.conversations.create({});
  const response = await openAIClient.responses.create(
    {
      conversation: conversation.id,
      input: "What is the largest city in France?",
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
      },
    },
  );
  console.log(`Response: ${response.output_text}`);

  // Clean up
  await openAIClient.conversations.delete(conversation.id);
  await project.agents.deleteVersion(agent.name, agent.version);
});

span.end();

// Shut down Azure Monitor to flush all pending traces before exit
await shutdownAzureMonitor();

Referencia: clase AIProjectClient, telemetry.getApplicationInsightsConnectionString

Nota

Para correlacionar las trazas con un agente específico en el portal de Foundry, incluya el agent_reference con name y id en su llamada de responses.create() (como se muestra en el ejemplo de Python anterior). Los rastros suelen aparecer en 2 a 5 minutos.

Exportar trazas a la consola

La exportación de consola es útil para la depuración local. Lo seguimientos se imprimen directamente en la salida estándar.

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__)

También puede usar Aspire Dashboard como visor local compatible con OTLP. Instale el exportador de OTLP (pip install opentelemetry-exporter-otlp) y configúrelo como exportador en lugar de ConsoleSpanExporter.

Referencia: AIProjectInstrumentor, ConsoleSpanExporter

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using OpenAI.Responses;

var projectEndpoint = Environment.GetEnvironmentVariable(
    "FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException(
        "FOUNDRY_PROJECT_ENDPOINT isn't set.");
var modelName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL_NAME isn't set.");

// Enable GenAI tracing
AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

AIProjectClient projectClient = new(
    endpoint: new Uri(projectEndpoint),
    tokenProvider: new DefaultAzureCredential());

// Configure OpenTelemetry with console exporter
var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .SetResourceBuilder(
        ResourceBuilder.CreateDefault().AddService("AgentTracingSample"))
    .AddConsoleExporter()
    .Build();

using (tracerProvider)
{
    DeclarativeAgentDefinition agentDefinition = new(model: modelName)
    {
        Instructions = "You are a helpful assistant."
    };
    ProjectsAgentVersion agent = await projectClient.AgentAdministrationClient
        .CreateAgentVersionAsync(
            agentName: $"agent-tracing-{Guid.NewGuid():N}",
            options: new(agentDefinition));
    try
    {
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient
            .GetProjectResponsesClientForAgent(agent.Name);
#pragma warning disable OPENAI001
        ResponseItem request = ResponseItem.CreateUserMessageItem(
            "What is the largest city in France?");
        ResponseResult response = await responseClient.CreateResponseAsync(
            [request]);
#pragma warning restore OPENAI001
        Console.WriteLine($"Response: {response.GetOutputText()}");
    }
    finally
    {
        await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(
            agentName: agent.Name,
            agentVersion: agent.Version);
    }
}

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import { context, trace } from "@opentelemetry/api";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-base";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "";
const modelName = process.env["FOUNDRY_MODEL_NAME"] || "";

// Set up console tracing
const provider = new NodeTracerProvider({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});
provider.register();

const tracer = trace.getTracer("AgentTracingConsoleSample");

// Enable tracing when you create the client
const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: { contentRecording: false, experimental: true },
  },
);
const openAIClient = project.getOpenAIClient();

const span = tracer.startSpan("agent-tracing-console-scenario");
const ctx = trace.setSpan(context.active(), span);

await context.with(ctx, async () => {
  // Agent operations emit traces to the console
  const agent = await project.agents.createVersion("MyAgent", {
    kind: "prompt",
    model: modelName,
    instructions: "You are a helpful assistant.",
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name})`);
  await project.agents.deleteVersion(agent.name, agent.version);
});

span.end();
await provider.shutdown();

Referencia: clase AIProjectClient

Habilitación de la grabación de contenido

La grabación de contenido captura el contenido de los mensajes y los argumentos de llamada de herramienta en los seguimientos. Estos datos pueden incluir información confidencial del usuario.

Precaución

La grabación de contenido captura mensajes de usuario, argumentos de llamada de herramienta y salidas del modelo. Solo habilite esta configuración en entornos de desarrollo. No habilite la grabación de contenido en producción a menos que los requisitos de cumplimiento y privacidad lo permitan.

Establezca la variable de entorno antes de instrumentar:

import os

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

Importante

Esta variable controla la grabación solo para seguimientos integrados. Cuando usa el decorador @trace_function en sus propias funciones, se realiza siempre un seguimiento de todos los parámetros y valores devueltos, independientemente de la configuración.

Use un AppContext conmutador o la variable de entorno:

// Enable content recording
AppContext.SetSwitch("Azure.Experimental.TraceGenAIMessageContent", true);

O bien, establezca la variable de OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT entorno en true. Si tanto el AppContext switch como la variable de entorno están establecidos, el AppContext switch tiene prioridad.

Establezca contentRecording: true en tracingOptions al crear AIProjectClient:

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
  {
    tracingOptions: { contentRecording: true, experimental: true },
  },
);

También puede establecer la OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT variable de entorno en true en lugar de pasar la opción . La tracingOptions propiedad tiene prioridad sobre la variable de entorno.

Deshabilitar la instrumentación automática (Python)

El SDK de Python instrumenta automáticamente las llamadas a openAI Responses and Conversations API. Para deshabilitar esta instrumentación automática, establezca AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API en false antes de llamar a AIProjectInstrumentor().instrument(). Cuando está deshabilitado, solo se registran intervalos personalizados explícitos.

import os

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

Seguimiento de datos binarios (Python)

Cuando la grabación de contenido está habilitada, el SDK realiza el seguimiento de los identificadores de archivo y los nombres de archivo de forma predeterminada. Para incluir direcciones URL de imágenes completas (incluidos URI de datos en base64) y los datos de archivo en segmentos, establezca AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA en true.

import os

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

Advertencia

Habilitar AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA puede aumentar significativamente el tamaño de la carga útil del seguimiento. Algunos back-end de seguimiento tienen limitaciones en el tamaño máximo de los datos de intervalo. Compruebe que el back-end de observabilidad admite los tamaños de carga esperados antes de habilitar esta configuración.

Habilitación de la propagación del contexto de seguimiento (Python)

La propagación del contexto de seguimiento permite que los intervalos del lado cliente se correlacionan con los intervalos del lado servidor de Azure OpenAI y otros servicios de Azure. Cuando está habilitado, el SDK inserta automáticamente los encabezados W3C Trace Context (traceparent y tracestate) en las solicitudes HTTP realizadas por los clientes de OpenAI obtenidos a través de get_openai_client().

La propagación del contexto de seguimiento está habilitada de forma predeterminada cuando el seguimiento está habilitado. Para deshabilitarla, establezca el valor de la variable de entorno AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION a false, o pase el parámetro directamente:

from azure.ai.projects.telemetry import AIProjectInstrumentor

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

Los cambios en esta configuración solo afectan a los clientes de OpenAI obtenidos get_openai_client()después del cambio. Los clientes adquiridos anteriormente no se ven afectados.

Control de la propagación del equipaje (Python)

De forma predeterminada, solo se propagan los encabezados traceparent y tracestate. Para incluir también el baggage encabezado, establezca AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE en true.

Importante

El baggage encabezado puede contener pares clave-valor arbitrarios, incluidos identificadores de usuario, información de sesión u otros datos potencialmente confidenciales. Antes de habilitar la retropropagación:

Audite qué datos agrega su aplicación y las bibliotecas de terceros al bagaje de OpenTelemetry.
Comprenda que el equipaje se envía a Azure OpenAI y puede ser registrado por Azure servicios.
Nunca agregue información confidencial al equipaje cuando se habilite la propagación.

Nota

El SDK de C# se basa en la propagación estándar .NET System.Diagnostics.Activity. La inserción explícita de contexto de seguimiento por solicitud no se expone como una característica independiente del SDK.

Seguimiento de funciones personalizadas

Python — usa el decorador `@trace_function`

El decorador trace_function crea un intervalo de OpenTelemetry para cada llamada a su función. Los parámetros se registran como code.function.parameter.<name> y el valor devuelto 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 un nombre de intervalo personalizado en lugar del nombre de la función, páselo 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"

El decorador registra:

Parámetros como atributos de .
Devuelve valores como code.function.return.value.
Tipos admitidos: str, int, float, booly colecciones (list, dict, tuple, ). set Se omiten los tipos de objeto.

Nota

La OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT variable de entorno no afecta al seguimiento de funciones personalizadas. El @trace_function decorador siempre rastrea los parámetros y los valores de retorno.

C# — usar `ActivitySource` manualmente

El SDK de C# no incluye un decorador de seguimiento. Utilice el estándar .NET ActivitySource para instrumentar sus propias funciones:

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

Registre el origen personalizado junto con el origen del SDK en el proveedor de seguimiento:

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

Configurar la instrumentación mediante programación (Python)

Como alternativa a las variables de entorno, pase los parámetros de configuración directamente a 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 de variable de entorno	Valor predeterminado
`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`

* El valor predeterminado es True cuando el seguimiento está habilitado.

Cuando se establece un parámetro y su variable de entorno correspondiente, el valor del parámetro tiene prioridad.

Cree un elemento personalizado SpanProcessor para insertar metadatos como los identificadores de sesión en cada segmento:

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 el procesador con el proveedor global de seguimiento:

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())

Cree un CustomAttributeProcessor.cs archivo con un procesador que agregue atributos cuando se inicie cada actividad:

using System.Diagnostics;
using OpenTelemetry;

sealed class CustomAttributeProcessor : BaseProcessor<Activity>
{
    public override void OnStart(Activity activity)
    {
        activity.SetTag("session.id", "user-session-abc");
    }
}

Registre el procesador en Program.cs al compilar el proveedor de seguimiento:

var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSource("Azure.AI.Projects.*")
    .AddProcessor(new CustomAttributeProcessor())
    .AddConsoleExporter()
    .Build();

Referencia: BaseProcessor<T>

Control del comportamiento de seguimiento con variables de entorno

En la tabla siguiente se enumeran todas las variables de entorno que puede usar para configurar el comportamiento de seguimiento:

Variable	Idioma	Valor predeterminado	Descripción
`AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING`	Python, C#	`false`	Habilite la instrumentación de seguimiento de GenAI.
`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`	Python, C#	`false`	Capture el contenido del mensaje y los parámetros de llamada de herramienta.
`AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION`	Python	`true`*	Inserte los encabezados de W3C Trace Context en las solicitudes.
`AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE`	Python	`false`	Incluya el encabezado de `baggage` en la propagación del contexto de seguimiento.
`AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API`	Python	`true`	Instrumente de manera automática las API de respuestas y conversaciones.
`AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA`	Python	`false`	Incluya datos de imagen y archivo en segmentos (no solo los identificadores de archivo).

* El valor predeterminado es true cuando el seguimiento está habilitado.

Para obtener la lista completa de variables de entorno y su comportamiento, consulte Tracing en el SDK de Azure AI Projects README.

Seguridad y privacidad

El seguimiento del lado cliente puede capturar información confidencial. Siga estos procedimientos para reducir el riesgo:

Grabación de contenido: captura entradas de usuario, respuestas de modelo y argumentos de llamada de herramienta. Deshabilite en producción a menos que sea necesario.
Propagación del equipaje: puede exponer información personal e información de la sesión. Deshabilitado de forma predeterminada.
Propagación del contexto de trazas: envía identificadores de seguimiento a servicios de Azure. Si los requisitos de cumplimiento prohíben compartir identificadores de seguimiento, deshabilite.
Secretos: no almacene secretos, credenciales ni tokens en mensajes, argumentos de herramienta o atributos span.
Control de acceso: trate los datos de seguimiento como telemetría de producción. Aplique los mismos controles de acceso y directivas de retención que use para los registros y las métricas.

Solución de problemas

Problema	Resolución
El seguimiento no genera ningún intervalo	Compruebe que `AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING` está establecido en `true`antes de llamar a `AIProjectInstrumentor().instrument()` (Python) o antes de crear el proveedor de trazas (C#).
El contenido del mensaje no aparece en intervalos.	Establezca `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` en `true`.
Las trazas no aparecen en Azure Monitor	Compruebe que el cadena de conexión de Application Insights es correcto y que el recurso es accesible. Compruebe que su cuenta tiene el rol de lector Log Analytics Reader. Si las tablas están protegidas, asigne también lector de datos de supervisión con privilegios.
Los intervalos del lado cliente y del lado servidor no están correlacionados	(Python) Compruebe que la propagación del contexto de seguimiento está habilitada y que los clientes de OpenAI se obtienen a través de `get_openai_client()`después de la instrumentación.
Los rastros aparecen con un retraso	Los rastros suelen tardar entre 2 y 5 minutos en aparecer en el portal de Foundry y Azure Monitor. Espere y actualice.

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-09-03

Adición del seguimiento del lado del cliente a agentes de Foundry (versión preliminar)

Requisitos previos

Requisitos previos específicos del idioma

Instalación de paquetes de seguimiento

Habilitación del seguimiento de GenAI

Exportación de rastros a Azure Monitor

Exportar trazas a la consola

Habilitación de la grabación de contenido

Deshabilitar la instrumentación automática (Python)

Seguimiento de datos binarios (Python)

Habilitación de la propagación del contexto de seguimiento (Python)

Control de la propagación del equipaje (Python)

Seguimiento de funciones personalizadas

Python — usa el decorador @trace_function

C# — usar ActivitySource manualmente

Configurar la instrumentación mediante programación (Python)

Añadir atributos personalizados a spans

Control del comportamiento de seguimiento con variables de entorno

Seguridad y privacidad

Solución de problemas

Contenido relacionado

Comentarios

Recursos adicionales

Python — usa el decorador `@trace_function`

C# — usar `ActivitySource` manualmente