Exception semantic conventions: Add example & more explanation for exception.escaped. #946

Oberon00 · 2020-09-14T10:48:35Z

Follow up for #784 that recovers parts of #761. No semantic changes intended, just adds an example (with link from semantic conventions to recordException API) and an expanded explanation.

specification/trace/semantic_conventions/exceptions.md

Co-authored-by: Tigran Najaryan <[email protected]>

carlosalberto · 2020-09-14T15:22:25Z

specification/trace/semantic_conventions/exceptions.md

+Span span = myTracer.startSpan(/*...*/);
+try {
+  // Code that does the actual work which the Span represents
+} catch (Throwable e) {


Wondering whether we should hold up adding this example till the actual API change hits OTel Java ;)

@carlosalberto OTel Java already supports this API. But the actual API has more boilerplate (I think I would have to write AttributeValue.booleanAttribute(true) for the second parameter). See https://github.com/open-telemetry/opentelemetry-java/blob/v0.8.0/api/src/main/java/io/opentelemetry/trace/Span.java#L232-L239 (open-telemetry/opentelemetry-java#1599)

I think the example is easier to read for non-Java users without that boilerplate, but I could add it too, if you prefer. Then I can write "Java" instead of "pseudo-Java" above.

I'd be personally more comfortable with the exact code we need (i.e. through Attributes). Else, go full pseudo code way :)

@carlosalberto Now (d359f47) it's using the real OTel-Java API (at some version; seems like the Attributes are recently often changed)

We are trying to get the last changes through before GA, but Attributes should settle down here quite soon. :)

Please continue at #946 (comment)

yurishkuro · 2020-09-14T21:45:44Z

specification/trace/semantic_conventions/exceptions.md

+  // Code that does the actual work which the Span represents
+} catch (Throwable e) {
+  span.recordException(e, Attributes.of(
+    "exception.escaped", AttributeValue.booleanAttributeValue(true)));


AttributeValue.booleanAttributeValue ? Could it not be just AttributeValue.of(true)?

"exception.escaped" - in OpenTracing we usually had strongly typed constants for semantic conventions. E.g. something like this would be much more user friendly:

span.recordException(e, Attribute.Exception.Escaped(true))`

Actually it should be possible to use (soon) SemanticAttributes.EXCEPTION_ESCAPED.set(span, true).

@yurishkuro This example should be easy to read. Then @carlosalberto said in #946 (comment) I should use the actual Java API, so I added the boilerplate. Now you are saying the boilerplate looks verbose. Please decide this among you two, personally I would prefer readability over "real code" here. And for that matter, I think a literal string is far less confusing than a constant.

@carlosalberto This won't work for event attributes that way. I would probably have to call getKey(), wouldn't I?

I added f78003e to simplify the code again. It is now readable pseudo-Java and I prefer it that way.

This reverts commit d359f47.

CHANGELOG.md

Oberon00 · 2020-09-15T16:37:35Z

Whoops, it seems I need to switch to YAML now 😅 Since I don't have Docker installed, this may take a while to get rebased...

CHANGELOG.md

Conflicts: specification/trace/semantic_conventions/exceptions.md

Oberon00 · 2020-09-18T14:20:51Z

Rebased and moved the new subsection to the "note" of exception.escaped. @carlosalberto @yurishkuro please check if the example is OK now.

Co-authored-by: Armin Ruech <[email protected]>

yurishkuro · 2020-09-18T19:55:52Z

semantic_conventions/trace/exception.yaml

+          See the [example above](#exception-end-example). It follows that an exception
+          may still escape the scope of the span even if the `exception.escaped` attribute
+          was not set or set to false, since that event might have been recorded at a time
+          where it was not clear whether the exception will escape.


Sorry, I find this paragraph exceedingly confusing. The first sentence says "difficult to say X, but trivial to say X" (X==X). The terms "in flight" and "escape" are undefined (and not a particularly common lingo). "in flight" exception, specifically, is not observable by the code, whereas a caught exception is not "in flight".

Terms that are not ambiguous: catch exception, re-throw exception.

These terms are not ambiguous but also not appropriate here. If you look at the code without the auto-instrumentation in place, the exception would indeed be currently in a state where it was thrown but not yet caught.

@yurishkuro I tried to clarify in 350ff89 although I think it would also be OK to be more vague here. WDYT?

…ception.escaped. (open-telemetry#946) * Add example & explanation for exception.escaped. * Reshuffle paragraphs. * Remove potentially controversial changes. * Fill in CHANGELOG link. * Address review comments. * Wording Co-authored-by: Tigran Najaryan <[email protected]> * Use actual OTel-Java API. * Revert "Use actual OTel-Java API." This reverts commit d359f47. * Clarify CHANGELOG * Re-generate tables. * Typo in CHANGELOG.md Co-authored-by: Armin Ruech <[email protected]> * Clarify exception escaped description. Co-authored-by: Tigran Najaryan <[email protected]> Co-authored-by: Armin Ruech <[email protected]>

Oberon00 added 3 commits September 14, 2020 12:24

Add example & explanation for exception.escaped.

f8eb5e7

Reshuffle paragraphs.

9d1f304

Remove potentially controversial changes.

06f7c55

Oberon00 requested review from a team September 14, 2020 10:48

github-actions bot assigned yurishkuro Sep 14, 2020

Fill in CHANGELOG link.

a47ecee

Oberon00 added area:error-reporting Related to error reporting area:semantic-conventions Related to semantic conventions spec:trace Related to the specification/trace directory labels Sep 14, 2020

Oberon00 changed the title ~~Escaped example~~ exception semantic conventions: Add example & more explanation for exception.escaped. Sep 14, 2020

tigrannajaryan approved these changes Sep 14, 2020

View reviewed changes

specification/trace/semantic_conventions/exceptions.md Outdated Show resolved Hide resolved

specification/trace/semantic_conventions/exceptions.md Outdated Show resolved Hide resolved

specification/trace/semantic_conventions/exceptions.md Outdated Show resolved Hide resolved

Oberon00 and others added 2 commits September 14, 2020 17:11

Address review comments.

7f9ed35

Wording

370759b

Co-authored-by: Tigran Najaryan <[email protected]>

carlosalberto reviewed Sep 14, 2020

View reviewed changes

Use actual OTel-Java API.

d359f47

yurishkuro reviewed Sep 14, 2020

View reviewed changes

Revert "Use actual OTel-Java API."

f78003e

This reverts commit d359f47.

Oberon00 changed the title ~~exception semantic conventions: Add example & more explanation for exception.escaped.~~ Exception semantic conventions: Add example & more explanation for exception.escaped. Sep 15, 2020

arminru approved these changes Sep 15, 2020

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

Clarify CHANGELOG

e363eaf

arminru reviewed Sep 16, 2020

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

Oberon00 added 2 commits September 18, 2020 15:58

Merge remote-tracking branch 'upstream/master' into escaped-example

d42831d

Conflicts: specification/trace/semantic_conventions/exceptions.md

Re-generate tables.

83ab7b6

Typo in CHANGELOG.md

b4fa424

Co-authored-by: Armin Ruech <[email protected]>

arminru approved these changes Sep 18, 2020

View reviewed changes

yurishkuro reviewed Sep 18, 2020

View reviewed changes

Clarify exception escaped description.

350ff89

Oberon00 requested review from tigrannajaryan, arminru, yurishkuro, jkwatson and carlosalberto September 19, 2020 11:06

yurishkuro approved these changes Sep 19, 2020

View reviewed changes

yurishkuro merged commit c3982b5 into open-telemetry:master Sep 19, 2020

Oberon00 mentioned this pull request Sep 23, 2020

Add exception.escaped, clean up exception attributes javadoc. open-telemetry/opentelemetry-java#1672

Merged

Oberon00 deleted the escaped-example branch December 18, 2020 10:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Exception semantic conventions: Add example & more explanation for exception.escaped. #946

Exception semantic conventions: Add example & more explanation for exception.escaped. #946

Oberon00 commented Sep 14, 2020 •

edited

Loading

carlosalberto Sep 14, 2020

Oberon00 Sep 14, 2020 •

edited

Loading

Oberon00 Sep 14, 2020 •

edited

Loading

carlosalberto Sep 14, 2020

Oberon00 Sep 14, 2020 •

edited

Loading

jkwatson Sep 14, 2020

Oberon00 Sep 15, 2020

yurishkuro Sep 14, 2020

yurishkuro Sep 14, 2020

carlosalberto Sep 14, 2020

Oberon00 Sep 15, 2020 •

edited

Loading

Oberon00 Sep 15, 2020

Oberon00 Sep 15, 2020

Oberon00 commented Sep 15, 2020

Oberon00 commented Sep 18, 2020

yurishkuro Sep 18, 2020

Oberon00 Sep 19, 2020

Oberon00 Sep 19, 2020 •

edited

Loading

Exception semantic conventions: Add example & more explanation for exception.escaped. #946

Exception semantic conventions: Add example & more explanation for exception.escaped. #946

Conversation

Oberon00 commented Sep 14, 2020 • edited Loading

Choose a reason for hiding this comment

Oberon00 Sep 14, 2020 • edited Loading

Choose a reason for hiding this comment

Oberon00 Sep 14, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Oberon00 Sep 14, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Oberon00 Sep 15, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Oberon00 commented Sep 15, 2020

Oberon00 commented Sep 18, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Oberon00 Sep 19, 2020 • edited Loading

Choose a reason for hiding this comment

Oberon00 commented Sep 14, 2020 •

edited

Loading

Oberon00 Sep 14, 2020 •

edited

Loading

Oberon00 Sep 14, 2020 •

edited

Loading

Oberon00 Sep 14, 2020 •

edited

Loading

Oberon00 Sep 15, 2020 •

edited

Loading

Oberon00 Sep 19, 2020 •

edited

Loading