Progress.Observability.Instrumentation 1.4.1

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. If either required value is missing (or endpoint is invalid), instrumentation is skipped. Configuration failures are only logged when debug is enabled.

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 and sanitized trace-delivery errors - 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"
$env:PROGRESS__OBSERVABILITY__DEBUG="true"

OTLP trace-delivery failures do not terminate the application. They remain silent by default and are written to standard error only when debug logging is enabled via <c>options.Debug = true</c> or the <c>PROGRESS__OBSERVABILITY__DEBUG</c> environment variable (accepts <c>1</c>, <c>true</c>, or <c>yes</c>). Configuration failures (missing API key/app name or invalid endpoint) follow the same behavior. Delivery messages never include API keys, authorization headers, or telemetry payloads.

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