From 4253f442f3ce775bf2ed75fac7b5da46e4a9394e Mon Sep 17 00:00:00 2001 From: Dustin Pauze Date: Sat, 27 Jul 2024 15:47:11 -0400 Subject: [PATCH] Update README.md --- README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4fdbb71..a101788 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,25 @@ # contextual_message -Provides the `ContextualMessage` object which is useful for client-side logging in Dart. +The standard [Dart Logging package](https://pub.dev/packages/logging) doesn't support structured logs out of the box. +This often results in log messages that include contextual information embedded within them, often frustrating and complicating efforts to aggregate logs. +This library allows context to be captured separately from the log message by way of the `ContextualMessage` object. -The log reporter (currently done by the `app_intelligence_dart` package) uses this object -to add context dimensions to log messages. +> [!IMPORTANT] +> **Please note**: The log reporter will need to be modified to accept a ContextualMessage and separate out the message from the context into the format your logging system supports. It is better to use a consistent log message string, and use `ContextualMessage` to add useful -variables to the log's context. This allows for log messages to be counted/alerted on without the +key-value pairs to the log's context. This allows for log messages to be counted/alerted on without the use of regex, and generally makes consuming the log output less chaotic. For example: Instead of writing: ```dart -logger.info('Document ID failed validation'); +logger.info('Document ID ABC failed validation for user 123'); ``` ...you should write: ```dart -logger.info(ContextualMessage("Document failed validation", context: {"docId": })); +logger.info(ContextualMessage("Document failed validation", context: {"docId":"ABC", "userId":"123"})); ```