diff --git a/CHANGELOG.md b/CHANGELOG.md index 795d9df2267..ad189f9dac8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ release. New: +- Add `error.hint` semantic convention + ([#822](https://github.com/open-telemetry/opentelemetry-specification/pull/822)) - Add resource semantic conventions for operating systems ([#693](https://github.com/open-telemetry/opentelemetry-specification/pull/693)) - Clarification of the behavior of the Trace API, re: context propagation, in diff --git a/specification/trace/api.md b/specification/trace/api.md index 0955248406a..34acff72f05 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -515,11 +515,18 @@ The method MUST record an exception as an `Event` with the conventions outlined the [exception semantic conventions](semantic_conventions/exceptions.md) document. The minimum required argument SHOULD be no more than only an exception object. -If `RecordException` is provided, the method MUST accept an optional parameter -to provide any additional event attributes -(this SHOULD be done in the same way as for the `AddEvent` method). -If attributes with the same name would be generated by the method already, -the additional attributes take precedence. +If `RecordException` is provided, it MUST accept the following optional +parameters: + +- Additional event attributes (this SHOULD be done in the same way + as for the `AddEvent` method). If attributes with the same name would be + generated by the method already, the additional attributes take precedence. + +- A boolean error hint, as defined by the + [`error.hint` semantic convention](semantic_conventions/exceptions.md#attributes). + A matching `error.hint` attribute MUST be recorded on both the span and + corresponding event. Once a span has `error.hint` set to true, subsequent + calls to `RecordException` MUST not change the value of the span attribute. Note: `RecordException` may be seen as a variant of `AddEvent` with additional exception-specific parameters and all other parameters being optional diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 877e52e3342..5b244abcea4 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -157,3 +157,20 @@ Examples of where `thread.id` and `thread.name` can be extracted from: | Ruby | | `Thread.current.name` | | C++ | `std::this_thread::get_id()` | | | Erlang | `erlang:system_info(scheduler_id)` | | + +## Error Attributes + +A span or event can be annotated with an `error.hint` attribute to indicate that +an error condition was observed. + +If there are [exception events](exceptions.md) on a span, the span attribute `error.hint` +SHOULD be set to `true`, if at least one of the event's `error.hint` attribute is `true`. +It's possible for more than one exception +event to have an `error.hint` attribute set. An `error.hint` represents an +instrumentation author's best judgement as to whether or not an error condition +was encountered. Tracing backends can use the `error.hint` attribute as a cue +for further analysis and can ultimately choose to honor or ignore the hint. + +| Attribute name | Notes and examples | +| :------------- | :----------------------------------------------------------------------------------------------------------------------- | +| error.hint | A boolean value that represents an instrumentation author's best judgement as to whether an error condition was observed. |