chore(er): capture exception API

[P403n1x87]

We add a new programmatic API for Exception Replay to allow users to capture caught exceptions explicitly.

Checklist

• The PR description includes an overview of the change
• The PR description articulates the motivation for the change
• The change includes tests OR the PR description describes a testing strategy
• The PR description notes risks associated with the change, if any
• Newly-added code is easy to change
• The change follows the library release note guidelines
• The change includes or references documentation updates if necessary
• Backport labels are set (if applicable)

Reviewer Checklist

• Title is accurate
• All changes are related to the pull request's stated goal
• Avoids breaking API changes
• Testing strategy adequately addresses listed risks
• Newly-added code is easy to change
• Release note makes sense to a user of the library
• If necessary, author has acknowledged and discussed the performance implications of this PR as reported in the benchmarks PR comment
• Backport labels are set in a manner that is consistent with the release branch maintenance policy

[EWachnowezki]

just checked the API method name and looks good to me :)

[shatzi]

This is awesome. I think there are two things missing:

1. we need documentation both on change log here and on exception replay docs to expose this feature
2. figure out if capture_exception() works on non service entry spans with Error Tracking. if that not the case - make sure we document this as known limitation or have a follow up PR to find a solution

[shatzi]

how this works when

1. a user call capture_exception() multiple times? will the first one/last one win? do we capture all snapshots multiple times?
2. how this works if the exception also propagate to the span it self? is that same as call "capture_exception" twice?

[P403n1x87]

Multiple calls would cause the data to be emitted multiple times. We could probably guard against this by checking if the span has error already set, and skip.

how this works if the exception also propagate to the span

I'm not quite sure I understand this. With this call we are setting an error on the span. However, we don't expect this to be used when the exceptions are not handled. This will only work in an exception handler, as anywhere else in the code there won't be an exception to attach to a span. If the exception is re-raised within an exception block however, then the tracer will trigger the capturing of debug data a second time.

[shatzi]

You got it. Therefore, I think this logic is little broken and should emit debug info only the last/first error that was assigned to the span.

[shatzi]

if trace._current_span() is not the service entry, will this still work?

I heard there is a tag ET support to index that span error if it not the service entry. maybe this should also set that tag. However, I can't seem to find it on their docs. so maybe this should add tags to service entry span (or both entry and current) or simple abort for non-entry?

[P403n1x87]

if trace._current_span() is not the service entry, will this still work?

This will put debug info on the current span, regardless of what the span is. So any limitations are probably not due to "us" I'd expect

[shatzi]

yup. this is broken as non entry spans are not get indexed and there is no way for the user to query on that and it would not appear in Error tracking. so not sure why we allow the user to do it in the first place.

cc @EWachnowezki

[P403n1x87]

Closing in favour of #10430.