RFC: graceful error/exceptions handling and documentation

[saragerion]

Key information

• RFC PR: (leave this empty)
• Related issue(s), if known: n/a
• Area: all
• Meet tenets: Yes
• Approved by: ''
• Reviewed by: ''

Summary

Revisit the exceptions/errors currently thrown by the utilities, and document them to raise awareness and visibility for developers using the powertools at scale in production.

One paragraph explanation of the feature.

Motivation

Currently, the libraries throw exceptions/errors if unwanted behaviour happens, as it's expected. However, not all developers getting started might be aware of this for a lack of familiarity with the tools.
It would be good to raise visibility about this behaviour so that developers can take action on this and handle exceptions thrown by the powertools gracefully.

Why are we doing this? What use cases does it support? What is the expected outcome?

This is especially relevant when the developer needs to decide whether this invocation should be retried or not.
It would be good to understand if errors make sense at all.
Do we want the whole Lambda function invocation to fail if an observability-related step such as logging or tracing fails? We should take this into account.

Proposal

As in the summary:

• Revisit the exceptions/errors currently thrown by the utilities, and decide on a different behaviour when it makes more sense;
• Document error/exceptions thrown (via code comments or docs) to raise awareness and visibility for developers using the powertools at scale in production;

This is the bulk of the RFC.

Explain the design in enough detail for somebody familiar with Powertools to understand it, and for somebody familiar with the implementation to implement it.

If this feature should be available in other runtimes (e.g. Java), how would this look like to ensure consistency?

User Experience

How would customers use it?

Any configuration or corner cases you'd expect?

Demonstration of before and after on how the experience will be better

Drawbacks

Why should we not do this?

Do we need additional dependencies? Impact performance/package size?

Rationale and alternatives

• What other designs have been considered? Why not them?
• What is the impact of not doing this?

Unresolved questions

Optional, stash area for topics that need further development e.g. TBD

[michaelbrewer]

@saragerion - Sounds interesting.

• Ensure runtime errors are clearly documented
• Default behavior for non-critical features should be not to raise an error like raise_on_empty_metrics, raise_on_no_idempotency_key and raise_on_transform_error.
• Document how to use the middleware to handle errors (especially in decorators)
• Potentially removed errors like InvalidLoggerSamplingRateError and replace with warnings