Corutines, concurrency and exception handling

[EmanueleIannuzzi]

This pull request introduces several important changes to the LogTide SDK, focusing on simplifying trace ID handling, improving coroutine compatibility, enhancing error serialization, and updating configuration patterns. The most notable improvements are the removal of the autoTraceId option, refactoring periodic flush logic to use coroutines, and providing more robust error handling and logging. Additionally, the configuration interfaces have been updated for better usability, and documentation/examples have been revised to reflect these changes.

Trace ID Handling & Coroutine Compatibility

• Removed the autoTraceId option from LogTideClientOptions, centralizing trace ID generation and normalization logic within the client. Trace IDs are now always generated if missing, with improved logging for missing IDs. [1] [2] [3] [4] [5]
• Refactored TraceIdElement to a data class and improved coroutine context handling for trace IDs, ensuring compatibility and correct propagation in coroutine-based environments. [1] [2] [3] [4]
• Updated trace ID normalization logic to always generate a UUID if the provided value is blank or invalid, and improved debug logging for trace ID issues.

Error Handling & Serialization

• Introduced a new structured error serialization method that recursively serializes exceptions, including stack traces, causes, and language metadata, for improved debugging and observability.
• Added a helper function metadataOrErrorToMap to streamline metadata and error handling in log entries, reducing code duplication. [1] [2] [3]

Configuration & Initialization

• Changed LogTideClientOptions fields from val to var to allow mutable configuration, and removed the autoTraceId property.
• Updated middleware and example usage patterns to use the new logtideClientOptions block for configuration, reflecting the removal of autoTraceId and improving clarity. [1] [2] [3] [4] [5]

Periodic Flush & Shutdown

• Refactored periodic flush logic to use coroutines instead of a scheduled executor, improving resource management and coroutine compatibility. [1] [2] [3]

Logging & Debugging

• Enhanced error logging during HTTP failures, including payload and response body details when debug mode is enabled, for easier troubleshooting.

These changes collectively improve the reliability, usability, and maintainability of the LogTide SDK.