dotnet / dotnet/diagnostics

Support for OpenTelemetry events in .NET

Open
#4,778 2 comments 0 reactions 1 assignee Claimed by @samsp-msft View on GitHub
enhancement
Dominant language
C++
Stars
1.3k
Forks
404
Avg merge
2d 3h
Merged PRs (30d)
38

Description

>Note: I am creating this issue as a placeholder to track conversations and discussion for where & how exactly this feature should land.
>This is not a feature for .NET 9

OpenTelemetry Events are a concept that have been in progress for a while, originally primarily driven from the scenario of tracking browser events client, they have been extended to be considered as a replacement for Events in Traces.

The data for [events](https://opentelemetry.io/docs/specs/semconv/general/events/) is a specialization of logging, and uses the OTel specification for logs as the basis. An event is essentially a log message with an AnyValue body, and an event.name property.

# Approach

We probably want to have a .NET implementation based off of ILogger. It can have an extension method(s) to log events in addition to log messages. It will require a new TState payload to be able to handle the schema for events - primarily that the body is defined as an AnyValue.

## ILogger
Events are supposed to be a variation on logging and using the underlying logging infrastructure. It seems like Events should be exposed as:
- New extension methods on top of ILogger such as
``` csharp
public static void LogEvent(this ILogger logger, string eventName, AnyValue body, params KeyValuePair[] attributes)
```
- A variation on `LoggerMessage.Define` to create strongly typed Events
- A variation on `LoggerMessage` attribute for annotating methods to create Events

The main challenge with `ILogger` is the `TState` object. Events can have their own `TState` object that can support `ToString()` and `IReadOnlyCollection>` which seem to be the main methods that log implementations use to read the data. An Event needs to support an AnyValue as the body, so that needs to be "flattened". Serializing `AnyValue` to JSON can solve this problem, and enable compatibility with legacy providers.

## AnyValue

OTel/OTLP has the concept of an [`AnyValue`](https://github.com/open-telemetry/opentelemetry-dotnet/blob/46265e3379ed71ef01666af3e13e6f3803510d61/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/Implementation/opentelemetry/proto/common/v1/common.proto#L28), which is like a traditional OLE variant. It can contain bools, ints, doubles, strings, arrays and maps. The specifications for Attributes in OTel are generally using `AnyValue`, but we have usually used string or object in our APIs.

We will need to have an implementation of `AnyValue` that can be used by the OTLP exporter and other parts of OpenTelemetry.NET.

The main concern with `AnyValue` is how to enable conversion of any random POCO objects in applications that developers are going to want to pass in as state. Creating our own serialization mechanism is problematic and expensive, and we need to consider NativeAOT which limits reflection etc.

The spec for `AnyValue` has a high overlap with JSON - especially for being able to handle arbitrary combinations of arrays and maps. We should see if we can use the existing JSON serialization as a mechanism for converting arbitrary objects to `AnyValue`. Having the objects be JSON serializable is also useful for being able to represent the objects when using other exporters or `ILogger` implementations that are not aware of `AnyValue` and need to be able to handle the richer data.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.