Add rationale.md to document design decisions that people may be curi… (#1627)

* Add rationale.md to document design decisions that people may be curious about later.

* Formatting

* OT -> OTel
This commit is contained in:
Anuraag Agrawal 2020-09-09 23:52:08 +09:00 committed by GitHub
parent d42d4cd9e2
commit 7bce323700
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 26 additions and 0 deletions

26
docs/rationale.md Normal file
View File

@ -0,0 +1,26 @@
# OpenTelemetry Rationale
When creating a library, often times designs and decisions are made that get lost over time. This
document tries to collect information on design decisions to answer common questions that may come
up when you explore the SDK.
## Span not `Closeable`
Because a `Span` has a lifecycle, where it is started and MUST be ended, it seems intuitive that a
`Span` should implement `Closeable` or `AutoCloseable` to allow usage with Java try-with-resources
construct. However, `Span`s are unique in that they must still be alive when handling exceptions,
which try-with-resources does not allow. Take this example:
```java
Span span = tracer.spanBuilder("someWork").startSpan();
try (Scope scope = tracer.withSpan(span)) {
// Do things.
} catch (Exception ex) {
span.recordException(ex);
} finally {
span.end();
}
```
It would not be possible to call `recordException` if `span` was also using try-with-resources.
Because this is a common usage for spans, we do not support try-with-resources.