Provide clarity around `OperationName` and `DisplayName` properties on `Activity`

[swythan]

Type of issue

Missing information

Description

I was rather suprised to find that if you create an Activity and set both the OperationName (via the constructor) and DisplayName properties, then it is the DisplayName that ends up as the name of the span exported by the OtlpExporter, and OperationName is not present in the output at all.

https://github.com/open-telemetry/opentelemetry-dotnet/blob/ceebd456f14220a460a9257dbbd22ad7611afdd6/src/OpenTelemetry.Exporter.OpenTelemetryProtocol/Implementation/Serializer/ProtobufOtlpTraceSerializer.cs#L232

Looking in to this further, I think this is intentional. The DisplayName is to all intents and purposes the actual name of the span, whilst the OperationName is presumably there for doing advanced filtering, enrichment, etc inside the process.

Could you get some clarity from the authors and add this usage info to the docs. At the moment they read more like both properties will appear, and that OperationName is more likely to end up as the name.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity.displayname?view=net-9.0#system-diagnostics-activity-displayname

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Diagnostics/Activity.xml

Document Version Independent Id

09fad89b-f334-4588-0adf-bdefda4ae08b

Platform Id

90a5639e-a7f2-4ed2-10b6-651df86945da

Article author

@dotnet-bot

[tarekgh]

The Activity.DisplayName remarks is already mentioning:

Remarks
DisplayName is intended to be used in a user interface and need not be the same as OperationName.

If the DisplayName property is not set, it will return the same value as OperationName.

While the Activity.OperationName Remarks mention the following:

Remarks
An operation name is the coarsest name that is useful for grouping/filtering. The name is typically a compile-time constant. Names of Rest APIs are reasonable, but arguments (such as specific accounts) should not be in the name but rather in the tags.

What more clarification do you think we need to add? Feel free to submit a PR with your suggestion and we'll be happy to look at.

[swythan]

The OperationName isn't used at all in OTEL scenarios, which I'd expect to be the vast majority of usages, but this isn't clear in the docs. That means that high cardinality values shouldn't really be put in DisplayName either (if I'm understanding OTEL best practices correctly).

[tarekgh]

CC @rajkumar-rangaraj

OTel has a single concept of Span Name, which is expected to be the low cardinality Span-name, also used for UI. The name can be changed after span creation. Activity.DisplayName is what maps to this. (Operation-name exists as legacy on Activity, not used by OTel).

The current remark sections on the properties telling:

When adding distributed tracing instrumentation, use DisplayName to set a meaningful name for the activity that will be displayed in tracing tools. This helps in identifying and understanding the trace more easily.
Use OperationName for internal grouping and filtering if needed but prioritize DisplayName for any user-facing or diagnostic tools.

For clarity, what exactly do you want to add?