diff options
author | Bogdan Drutu <bdrutu@google.com> | 2018-08-07 02:45:49 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-08-07 02:45:49 +0300 |
commit | c943c6c63637cc866e92b90dae0e48dccd488130 (patch) | |
tree | 68f0a61d108a368fb6dd076054958107e2e2b606 /api | |
parent | b0c487b09287f7734f46d7b84afbd07d6c025f28 (diff) | |
download | opencensus-java-c943c6c63637cc866e92b90dae0e48dccd488130.tar.gz |
Add a warning about try-with-resource to auto-close spans. (#1362)
Diffstat (limited to 'api')
-rw-r--r-- | api/src/main/java/io/opencensus/trace/SpanBuilder.java | 10 |
1 files changed, 10 insertions, 0 deletions
diff --git a/api/src/main/java/io/opencensus/trace/SpanBuilder.java b/api/src/main/java/io/opencensus/trace/SpanBuilder.java index 1a4e29e9..f3a436a6 100644 --- a/api/src/main/java/io/opencensus/trace/SpanBuilder.java +++ b/api/src/main/java/io/opencensus/trace/SpanBuilder.java @@ -233,6 +233,16 @@ public abstract class SpanBuilder { * } * }</pre> * + * <p>WARNING: The try-with-resources feature to auto-close spans as described above can sound + * very tempting due to its convenience, but it comes with an important and easy-to-miss + * trade-off: the span will be closed before any {@code catch} or {@code finally} blocks get a + * chance to execute. So if you need to catch any exceptions and log information about them (for + * example), then you do not want to use the try-with-resources shortcut because that logging will + * not be tagged with the span info of the span it logically falls under, and if you try to + * retrieve {@code Tracer.getCurrentSpan()} then you'll either get the parent span if one exists + * or {@code BlankSpan} if there was no parent span. This can be confusing and seem + * counter-intuitive, but it's the way try-with-resources works. + * * @return an object that defines a scope where the newly created {@code Span} will be set to the * current Context. * @since 0.5 |