Background

The OpenTelemetry semantic conventions have added a new gen_ai.client.operation.exception event for recording exceptions during Generative AI client operations. This was merged in open-telemetry/semantic-conventions#3436.

The new convention specifies:

• Event name: gen_ai.client.operation.exception
• When: SHOULD be recorded when an exception occurs during GenAI client operations
• Severity: SHOULD be WARN (severity number 13)
• Attributes:
  • exception.type (conditionally required) — fully-qualified exception class name
  • exception.message (conditionally required) — the exception message
  • exception.stacktrace (recommended) — stack trace as a string

This is part of a broader initiative to migrate exception recording from span events to log-based events. The convention notes that exception.message may contain sensitive information.

What needs to change

1. All four OpenTelemetry instrumentation classes need to emit the exception event

The following classes all have ILogger? logger parameters in their constructors that are currently unused (suppressed with #pragma warning disable IDE0060):

• OpenTelemetryChatClient in src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryChatClient.cs
• OpenTelemetryEmbeddingGenerator<TInput, TEmbedding> in src/Libraries/Microsoft.Extensions.AI/Embeddings/OpenTelemetryEmbeddingGenerator.cs
• OpenTelemetrySpeechToTextClient in src/Libraries/Microsoft.Extensions.AI/SpeechToText/OpenTelemetrySpeechToTextClient.cs
• OpenTelemetryImageGenerator in src/Libraries/Microsoft.Extensions.AI/ChatCompletion/OpenTelemetryImageGenerator.cs

For each class:

a. Store and use the ILogger parameter

• Add a private readonly ILogger? _logger; field
• Store the logger parameter in the constructor: _logger = logger;
• Remove the #pragma warning disable/restore IDE0060 around the constructor since the parameter is now used
• Remove any comments that say the parameter is unused / exists for backwards compatibility

b. Emit the exception event in the TraceResponse method

In each class's TraceResponse method, when error is not null, in addition to the existing span status/tag logic, emit the exception event using Activity.AddEvent. Use Activity.AddEvent because the .NET ILogger does not natively support the OTel event model with event names in the way the convention requires (the event name must be gen_ai.client.operation.exception, and ILogger doesn't map cleanly to OTel log events with specific event names in the current .NET OTel SDK). Using Activity.AddEvent is the pragmatic choice that matches how .NET OTel instrumentation works today.

The event should be added to the activity like this:

if (error is not null && activity is not null)
{
    var exceptionTags = new ActivityTagsCollection
    {
        { "exception.type", error.GetType().FullName },
        { "exception.message", error.Message },
        { "exception.stacktrace", error.ToString() },
    };

    activity.AddEvent(new ActivityEvent(
        "gen_ai.client.operation.exception",
        tags: exceptionTags));
}

This should be placed inside the existing if (error is not null) block in TraceResponse, alongside (not replacing) the existing error.type tag and SetStatus(ActivityStatusCode.Error) calls.

c. Add the event name constant to OpenTelemetryConsts

In src/Libraries/Microsoft.Extensions.AI/OpenTelemetryConsts.cs, add to the GenAI.Client class:

public static class Operation
{
    public const string ExceptionEventName = "gen_ai.client.operation.exception";
}

And add exception attribute constants:

public static class Exception
{
    public const string Type = "exception.type";
    public const string Message = "exception.message";
    public const string Stacktrace = "exception.stacktrace";
}

Use these constants in all four classes instead of string literals.

2. Existing code reference for each class

OpenTelemetryChatClient — current error handling in TraceResponse (lines 710-715):

if (error is not null)
{
    _ = activity?
        .AddTag(OpenTelemetryConsts.Error.Type, error.GetType().FullName)
        .SetStatus(ActivityStatusCode.Error, error.Message);
}

OpenTelemetryEmbeddingGenerator — similar pattern in its TraceResponse method:

if (error is not null)
{
    _ = activity
        .AddTag(OpenTelemetryConsts.Error.Type, error.GetType().FullName)
        .SetStatus(ActivityStatusCode.Error, error.Message);
}

OpenTelemetrySpeechToTextClient — similar pattern in its TraceResponse method.

OpenTelemetryImageGenerator — similar pattern in its TraceResponse method.

3. Tests

Add or update tests for each class to verify that when an exception occurs:

• The existing error.type tag and error status are...