Deprecate error.message in favor of domain-specific attributes

[lmolkova]

Fixes #3307

[github-actions]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• error
• error
• feature-flags
• feature-flags

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

[askpt]

Added a couple of suggestions and a minor question. Thanks!

[beeme1mr]

After reviewing the linked issue, it's still not clear to me why exception.message is okay, but error.message is too generic. When we were putting together the feature flag SemCon, it was recommended to use a shared attribute, which seemed reasonable. I could honestly go either way, but I'd prefer not to depreciate an attribute to avoid unnecessary thrashing unless there's a very strong reason to make the change.

[dyladan]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• error
• error
• feature-flags
• feature-flags

I think the tooling here is a bit aggressive. It's expected that sigs wind down after doing their work. There isn't any reason for the feature flag sig to continue to meet when regular changes are not expected.

it's still not clear to me why exception.message is okay, but error.message is too generic

I agree with @beeme1mr it seems like this is a documentation issue. I found an attempt to document this at #2296 which was closed as stale, but I don't see any unresolvable issues with it.

To me the biggest issue with using a generic attribute is what happens if multiple semconv areas need to use it on the same span. So far this has been avoided with error.message because it is really only used in feature flagging, and we are using it in an event which sidesteps this error because other semconv/instrumentations would emit separate events.

[lmolkova]

@dyladan @beeme1mr thanks for the feedback.

We've chatted about it in the SemConv call, documenting additional context here:

The error.message is not grounded in anything, unlike exception.message, which captures common property across most languages, is a stable and actively used attribute.
Aside from its name (error.message), it is fully convention-specific. When working on #2296 and #3256, we realized that it:

• would never appear on spans, as the message would become the span status description
• would never appear on metrics due to cardinality
• could only appear on logs / events. There, it could be confused with logger.error(message) - the log body, and exception.message (would be marginally different from error.message in many cases). Most importantly, there seems to be no point in grouping by error.message across all logs or showing this attribute on a generic log dashboard

So the practical benefit of having one attribute across conventions is low, while the ambiguity it introduces is high.

This is the only attribute that is in development state in feature flags and, at least in my head, was the main blocker preventing FF from going stable. While I understand it introduces churn, it also opens up a path forward for FF to stabilize at any time.

[michaelsafyan]

would never appear on spans, as the message would become the span status description

What about in the case of client errors, where span status is left unset, but where there is an error message (the client error)?

[michaelsafyan]

One other concern about domain-specific error attributes: visualization. Won't this require visualization UIs to now look for "the error message" in more places? Wouldn't it be better if UIs could easily find a single attribute for "the error message"?

[lmolkova]

One other concern about domain-specific error attributes: visualization. Won't this require visualization UIs to now look for "the error message" in more places? Wouldn't it be better if UIs could easily find a single attribute for "the error message"?

@michaelsafyan do you have a suggestion of the specific user experience that would need it? We've been trying to come up with generic logs dashboard and came up with something like

• Timestamp
• Severity
• Maybe scope name
• Event name
• Maybe error.type - good grouping key
• Body (makes sense for logs dashboard but not for events)

So what would be the case when UX needs to visualize something around error message and would it make sense across all conventions?

[lmolkova]

What about in the case of client errors, where span status is left unset, but where there is an error message (the client error)?

it sounds like it wasn't an error if status was unset and it'd be a log record with appropriate severity. warn.message (or exception.message) if you will.

[michaelsafyan]

In the case of a SERVER span with a client error (e.g. 4xx), error.message is a convenient way to pass the error, while not marking the entire span operation as an error (not setting the status).

Such an operation could have multiple logs correlated with the span of an appropriate severity, but there is no way to know if the log represents the message of the overall operation vs just a warning that happened within it.

One could imagine a view of the span which elevates error information to bring it front and center. While perhaps there are cases where domain-specific errors are appropriate (errors that are "fail open" and do not fail the operation), deprecating error.type (and specifically recommending many different attributes rather than a single attribute with common meaning) is inconvenient with respect to being able to trivially pull out the "operation-level error message".

[lmolkova]

In the case of a SERVER span with a client error (e.g. 4xx), error.message is a convenient way to pass the error, while not marking the entire span operation as an error (not setting the status).

Such an operation could have multiple logs correlated with the span of an appropriate severity, but there is no way to know if the log represents the message of the overall operation vs just a warning that happened within it.

One could imagine a view of the span which elevates error information to bring it front and center. While perhaps there are cases where domain-specific errors are appropriate (errors that are "fail open" and do not fail the operation), deprecating error.type (and specifically recommending many different attributes rather than a single attribute with common meaning) is inconvenient with respect to being able to trivially pull out the "operation-level error message".

@michaelsafyan I see your point and I think this scenario makes sense. Note that error.message was not intended to be that kind of thing though. What you're suggesting is something like operation-ending-messaage, not necessarily an error (which error.message would imply).

[michaelsafyan]

Would it be possible to simply expand the meaning/scope of error.message (or add clarifying examples of when to use error.message vs exception.message) rather than deprecating it?

Note that OTel SemConv is not comprehensive or complete. There are uses of OTel SemConv in vendor-specific conventions that may not necessarily be documented in the OTel SemConv repo. That is, it is incorrect to conclude that lack of references within OTel SemConv necessarily means that the attribute is unused for the given meaning/purpose.

[lmolkova]

Would it be possible to simply expand the meaning/scope of error.message (or add clarifying examples of when to use error.message vs exception.message) rather than deprecating it?

Note that OTel SemConv is not comprehensive or complete. There are uses of OTel SemConv in vendor-specific conventions that may not necessarily be documented in the OTel SemConv repo. That is, it is incorrect to conclude that lack of references within OTel SemConv necessarily means that the attribute is unused for the given meaning/purpose.

As you can see, we tried to define this attribute and failed. Please create an issue and it'd also be a good change to rename this attribute to match the use-case.

We don't recommend external semconv registries to take dependency on experimental parts of OTel semconv.

[lmolkova]

@open-telemetry/semconv-feature-flag-approvers Could you please take another look?