error handling proposal

specification/error-handling.md

@@ -0,0 +1,87 @@
+# Error handling in OpenTelemetry
+
+OpenTelemetry generates telemetry data to help users monitor application code.
+In most cases, the work that the library performs is not essential from the
+perspective of application business logic. We assume that users would prefer to
+lose telemetry data rather than have the library significantly change the
+behavior of the instrumented application.
+
+OpenTelemetry may be enabled via platform extensibility mechanisms, or
+dynamically loaded at runtime. This makes the use of the library non-obvious for
+end users, and may even be outside of the application developer's control. This
+makes for some unique requirements with respect to error handling.
+
+## Basic error handling principles
+
+OpenTelemetry implementations MUST NOT throw unhandled exceptions at run time.
+
+1. API methods MUST NOT throw unhandled exceptions when used incorrectly by end
+   users. The API and SDK SHOULD provide safe defaults for missing or invalid
+   arguments. For instance, a name like `empty` may be used if the user passes
+   in `null` as the span name argument during `Span` construction.
+2. The API or SDK may _fail fast_ and cause the application to fail on
+   initialization, e.g. because of bad user config or a environment, but MUST
+   NOT cause the application to fail at run time, e.g. due to dynamic config
+   settings received from the Collector.
+3. The SDK MUST NOT throw unhandled exceptions for errors in their own
+   operations. For example, an exporter should not throw an exception when it
+   cannot reach the endpoint to which it sends telemetry data.
+
+## Guidance
+
+1. API methods that accept external callbacks MUST handle all errors.
+2. Background tasks (e.g. threads, asynchronous tasks, and spawned processes)
+   should run in the context of a global error handler to ensure that exceptions
+   do not affect the end user application.
+3. Long-running background tasks should not fail permanently in response to
+   internal errors. In general, internal exceptions should only affect the
+   execution context of the request that caused the exception.
+4. Internal error handling should follow language-specific conventions. In
+   general, developers should minimize the scope of error handlers and add
+   special processing for expected exceptions.
+5. Beware external callbacks and overrideable interfaces: Expect them to throw.
+6. Beware to call any methods that wasn't explicitly provided by API and SDK
+   users as a callbacks. Method `ToString` that SDK may decide to call on user
+   object may be badly implemented and lead to stack overflow. It is common that
+   the application never calls this method and this bad implementation would
+   never be caught by an application owner.
+7. Whenever API call returns values that is expected to be non-`null` value - in
+   case of error in processing logic - SDK MUST return a "no-op" or any other
+   "default" object that was (_ideally_) pre-allocated and readily available.
+   This way API call sites will not crash on attempts to access methods and
+   properties of a `null` objects.
+
+## Error handling and performance
+
+Error handling and extensive input validation may cause performance degradation,
+especially on dynamic languages where the input object types are not guaranteed
+in compile time. Runtime type checks will impact performance and are error
+prone, exceptions may occur despite the best effort.
+
+It is recommended to have a global exception handling logic that will guarantee
+that exceptions are not leaking to the user code. And make a reasonable trade
+off of the SDK performance and fullness of type checks that will provide a
+better on-error behavior and SDK errors troubleshooting.
+
+## Self-diagnostics
+
+All OpenTelemetry libraries -- the API, SDK, exporters, instrumentation
+adapters, etc. -- are encouraged to expose self-troubleshooting metrics, spans,
+and other telemetry that can be easily enabled and filtered out by default.
+
+One good example of such telemetry is a `Span` exporter that indicates how much
+time exporters spend uploading telemetry. Another example may be a metric
+exposed by a `SpanProcessor` that describes the current queue size of telemetry
+data to be uploaded.
+
+Whenever the library suppresses an error that would otherwise have been exposed
+to the user, the library SHOULD log the error using language-specific
+conventions. SDKs MAY expose callbacks to allow end users to handle
+self-diagnostics separately from application code.
+
+## Exceptions to the rule
+
+SDK authors MAY supply settings that allow end users to change the library's
+default error handling behavior. Application developers may want to run with
+strict error handling in a staging environment to catch invalid uses of the API,
+or malformed config.