Progress.Observability.Instrumentation 1.2.2

Progress Observability Instrumentation for .NET

AI agent telemetry for .NET applications built with IChatClient or IAgent from Microsoft AI libraries .

Installation

1. Add the package directly using the dotnet CLI command:

dotnet add <YourProject.csproj> package Progress.Observability.Instrumentation

1. Add the package using a local NuGet source:

# copy the Progress.Observability.Instrumentation.X.X.X.nupkg package to the location of your local source - e.g. c:\packages

# if you have not yet created the local source, you can do so by executing the following command
dotnet nuget add source c:\packages --name LocalFeed

# you can verify the source exists by executing
dotnet nuget list source

# finally add the package by executing the following command in your project directory
dotnet add package Progress.Observability.Instrumentation --source LocalFeed

Usage

1. For Agents using IChatClient:

Call the .AddObservability() extension method of your IChatClient for LLM instrumentation. And the .AddToolObservability() extension method of your ChatOptions instance for tool instrumentation. Example using the Microsoft.Extensions.AI.OpenAI package:

using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;
using Progress.Observability.Extensions.AI;

try
{
    // ... Set up your chat client and MCP tools 
    IChatClient chatClient = new OpenAI.Chat.ChatClient("gpt-5-nano", openAIApiKey)
        .AsIChatClient();

    // Adding Progress Observability for LLM calls
    chatClient = chatClient.AddObservability((options) => {
        options.AppName = "Awesome Agent";
        options.ApiKey = "ac_p_001_.....";
        // Optional: custom attributes to be added to all spans and traces
        options.AdditionalAttributes = new Dictionary<string, object>
        {
            { "project.id", 2182374 },
            { "environment", "dev" },
        };
        // Optional: tags for filtering spans in the Progress Observability portal
        options.AdditionalTags = new List<string>
        {
            "customer.id:12345",
            "NewCustomer",
        };
    });

    // Set up MCP client and tools
    chatClient = new ChatClientBuilder(chatClient)
        .UseFunctionInvocation()
        .Build();

    McpClient mcpClient = await McpClient.CreateAsync(
        new HttpClientTransport(new()
        {
            Endpoint = new Uri("http://localhost:3001/sse"),
            Name = "Weather MCP Server",
        }));

    IList<McpClientTool> tools = await mcpClient.ListToolsAsync();
    ChatOptions options = new() { Tools = [..tools] };

    // Adding Progress Observability for tool calls
    options.AddToolObservability();

    // Optional: create custom activities for better observability of your agent's execution
    using (var weatherActivity = ObservabilityActivitySource.Instance.StartActivity("weather agent call"))
    {
        // Optional: Add custom attributes to your activity that will be visible in the observability dashboard
        weatherActivity?.SetTag("date", DateTime.Now.ToString("yyyy-MM-dd"));

        // ... Use the chat client with observability enabled
        var response = await chatClient.GetResponseAsync("What is the weather like in Paris?", options);
    }
}
finally
{
    // Call the Shutdown() method before exiting your agent to flush any remaining data.
    Progress.Observability.Extensions.AI.ObservabilityTracer.Shutdown();
}

1. For Agents using IAgent:

Create a Progress Observability tracer and then use the .UseOpenTelemetry() method of the IAgentBuilder interface to instrument your agent.

using Progress.Observability.Extensions.AI;

try
{
    var agentName = "Awesome AI Agent";
    // Configure Progress Observability exporter with the default trace source "Progress.Observability.AgentMonitoring"
    ObservabilityTracer.Initialize(new ObservabilityOptions()
    {
        AppName = agentName,
        ApiKey = "ac_p_001_.....",
        AdditionalAttributes = new Dictionary<string, object>()
        {
            { "customer.id", Guid.NewGuid().ToString() },
            { "customer.quota", 2026 },
            { "customer.active", true },
        },
        AdditionalTags = new List<string>()
        {
            "customer.id:12345",
            "NewCustomer",
        }
    });

    // Configure your tools. Optionally, you can call the .AddToolObservability() extension method of the List<AiTool> object to manually instrument observability for tool calls
    List<AITool> tools = [AIFunctionFactory.Create(AwesomeTool)];

    // Create your agent
    var aiAgent = new AzureOpenAIClient(new(endpoint),new AzureKeyCredential(azureApiKey))
        .GetChatClient("gpt-4.1")
        .AsAIAgent(instructions: "You are an assistant that helps users Microsoft .NET related trivia. Keep your answers concise and accurate. Use only text (no markdown).", name: agentName, tools: tools)
        .AsBuilder()
        // Configure the agent to use the Progress Observability exporter with the same trace source "Progress.Observability.AgentMonitoring"
        .UseOpenTelemetry(sourceName: ObservabilityTracer.SourceName, configure: agent =>
        {
            // Enable this to include the content of inputs and outputs in the telemetry. Set to false if you don't want to send potentially sensitive data.
            agent.EnableSensitiveData = true;
        })
        .Build();

    // Optional: create custom activities for better observability of your agent's execution
    using (var weatherActivity = ObservabilityActivitySource.Instance.StartActivity("weather agent call"))
    {
        // Optional: Add custom attributes to your activity that will be visible in the observability dashboard
        weatherActivity.SetTag("date", DateTime.Now.ToString("yyyy-MM-dd"));

        // ... Use the agent
        var response = aiAgent.RunAsync(message);
    }
}
finally
{
    // Call the Shutdown() method before exiting your agent to flush any remaining data.
    ObservabilityTracer.Shutdown();
}

Configuration

There are two required properties that must be set to enable the observability instrumentation - AppName and ApiKey. Options can be set directly in code or using environment variables.

1. Using the configure function in your code

chatClient = chatClient.AddObservability((options) =>
{
    // (required) the Application name to be used in the observability dashboards
    options.AppName = "Weather Agent";
    // (required) your Progress Observability API key
    options.ApiKey = "ac_p_001_.....";
    // (optional) the OpenTelemetry endpoint where data will be sent. 
    options.Endpoint = "https://collector.observability.progress.com:443";
    // (optional) for Extensions.AI agents: should LLM inputs be sent - default is true
    options.RecordInputs = true;
    // (optional) for Extensions.AI agents: should LLM responses be sent - default is true
    options.RecordOutputs = true;
    // (optional) enable debug logging - default is false
    options.Debug = false;
    // (optional) custom attributes to be added to all spans and traces sent by this agent. You can use different values including string/number/boolean for the attributes. Defaults to an empty dictionary.
    options.AdditionalAttributes = new Dictionary<string, object>
    {
        { "project.id", 2182374 },
        { "environment", "dev" },
    };
    // (optional) tags for filtering spans in the Progress Observability portal. Defaults to an empty list.
    options.AdditionalTags = new List<string>
    {
        "customer.id:12345",
        "NewCustomer",
    };
});

1. Using environment variables. In this case the configuration will be applied automatically when you instrument observability for your application.

$env:PROGRESS__OBSERVABILITY__APPNAME="Weather Agent"
$env:PROGRESS__OBSERVABILITY__APIKEY="ac_p_001_....."
# Optional
$env:PROGRESS__OBSERVABILITY__ENDPOINT="https://collector.observability.progress.com:443"

Shutdown

// call this method on application shutdown to flush any pending spans and traces. Using a try/catch block will ensure that you get telemetry even if the application crashes.
try {
    // code to run the application here
}
finally {
    Progress.Observability.Extensions.AI.ObservabilityTracer.Shutdown();
}