Ajouter le traçage côté client aux agents Foundry (aperçu)

• Python 3.10 ou version ultérieure.
• La version azure-ai-projects du paquet 2.0.0 ou ultérieure.

• .NET 8.0 ou version ultérieure.
• Package NuGet Azure.AI.Projects.

• Node.js 20 LTS ou version ultérieure.
• Le package @azure/ai-projects, version 2.4.0 ou ultérieure.

Installez le SDK Microsoft Foundry, OpenTelemetry et l’exportateur Azure Monitor :

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

Pour l’exportation de console uniquement ou OTLP (par exemple, Aspire Dashboard), installez l’exportateur OTLP :

pip install opentelemetry-exporter-otlp

Ajoutez les packages NuGet requis :

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

Pour les applications ASP.NET Core, Azure.Monitor.OpenTelemetry.AspNetCore est le package préféré. Le package Azure.Monitor.OpenTelemetry.Exporter présenté ici fonctionne pour tous les types d’applications .NET.

Installez le SDK Microsoft Foundry, OpenTelemetry et l’exportateur Azure Monitor :

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

Pour l’exportation console uniquement, vous avez également besoin des packages du Kit de développement logiciel (SDK) OpenTelemetry :

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

Définissez la variable d’environnement sur AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACINGtrue d’appeler 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 n’est pas définie ou n’est pas true (totalement insensible à la casse), l'instrumentation de traçage ne s'active pas et un avertissement est enregistré.

Utilisez un commutateur ou la même variable d’environnement AppContext :

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

Lorsque vous activez Azure.Experimental.EnableGenAITracing, le Kit de développement logiciel (SDK) active automatiquement l’indicateur Azure.Experimental.EnableActivitySource, requis pour que l’instrumentation OpenTelemetry fonctionne.

Si le commutateur et la AppContext variable d’environnement sont définis, le AppContext commutateur a la priorité.

Passez experimental: true dans tracingOptions lorsque vous créez le AIProjectClient. Contrairement aux kits SDK Python et C#, le Kit de développement logiciel (SDK) JavaScript/TypeScript active le suivi par instance cliente au lieu d’un appel d’instrumentation distinct :

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

Vous pouvez également définir la AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING variable d’environnement à true la place de passer l’option. La tracingOptions propriété est prioritaire sur la variable d’environnement. Pour obtenir un exemple complet, consultez Exporter les traces vers 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)

Référence : 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);
    }
}

Référence : 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();

Référence : classe AIProjectClient, telemetry.getApplicationInsightsConnectionString

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

Vous pouvez également utiliser Le tableau de bord Aspire comme visionneuse compatible OTLP locale. Installez l’exportateur OTLP (pip install opentelemetry-exporter-otlp) et configurez-le en tant qu’exportateur au lieu de ConsoleSpanExporter.

Référence : 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();

Référence : classe AIProjectClient

Définissez la variable d’environnement avant d’instrumenter :

import os

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

Utilisez un commutateur ou la variable d’environnement AppContext :

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

Ou définissez la variable d’environnement OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT sur true. Si le commutateur et la AppContext variable d’environnement sont définis, le AppContext commutateur a la priorité.

Définissez tracingOptions dans contentRecording: true lorsque vous créez le AIProjectClient :

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

Vous pouvez également définir la OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT variable d’environnement à true la place de passer l’option. La tracingOptions propriété est prioritaire sur la variable d’environnement.

Créez un code personnalisé SpanProcessor pour injecter des métadonnées telles que des ID de session dans chaque étendue :

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

Inscrivez le processeur auprès du fournisseur de suivi 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())

Créez un CustomAttributeProcessor.cs fichier avec un processeur qui ajoute des attributs au démarrage de chaque activité :

using System.Diagnostics;
using OpenTelemetry;

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

Enregistrez le processeur dans Program.cs lorsque vous créez le fournisseur de traceurs :

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

Référence : BaseProcessor<T>