feat(logger): Support for external observability providers (#1511)

* Updated formatAttributes for additional parameters and LogItem return type

* Updated the unit tests to pass with new formatter

* Updated Powertool named objects to Powertools

* Updated tests to match new naming consistency

* Updated for tests for new naming consistency

* Updated formatter for new design decisions

* Update Logger for ephemeral attributes

* Update bringYourOwnFormatter documentation to match new formatter

---------

Co-authored-by: erikayao93 <[email protected]>

Author: erikayao93

Diff for: packages/logger/src/Logger.ts

@@ -640,8 +640,8 @@ class Logger extends Utility implements LoggerInterface {
         item instanceof Error
           ? { error: item }
           : typeof item === 'string'
-            ? { extra: item }
-            : item;
+          ? { extra: item }
+          : item;
 
       additionalLogAttributes = merge(additionalLogAttributes, attributes);
     });

Diff for: packages/logger/src/formatter/LogFormatterInterface.ts

@@ -0,0 +1,29 @@
+import { LogAttributes, UnformattedAttributes } from '../types';
+import { LogItem } from '../log';
+
+/**
+ * @interface
+ */
+interface LogFormatterInterface {
+  /**
+   * It formats key-value pairs of log attributes.
+   *
+   * @param {UnformattedAttributes} attributes
+   * @param {LogAttributes} additionalLogAttributes
+   * @returns {LogItem}
+   */
+  formatAttributes(
+    attributes: UnformattedAttributes,
+    additionalLogAttributes: LogAttributes
+  ): LogItem;
+
+  /**
+   * It formats a given Error parameter.
+   *
+   * @param {Error} error
+   * @returns {LogAttributes}
+   */
+  formatError(error: Error): LogAttributes;
+}
+
+export { LogFormatterInterface };

Diff for: packages/logger/src/formatter/index.ts

@@ -0,0 +1,3 @@
+export * from './LogFormatter';
+export * from './LogFormatterInterface';
+export * from './PowertoolsLogFormatter';

Diff for: packages/logger/src/types/formats/PowertoolsLog.ts

@@ -0,0 +1,93 @@
+import type { LogAttributes, LogLevel } from '..';
+
+type PowertoolsLog = LogAttributes & {
+  /**
+   * timestamp
+   *
+   * Description: Timestamp of actual log statement.
+   * Example: "2020-05-24 18:17:33,774"
+   */
+  timestamp?: string;
+
+  /**
+   * level
+   *
+   * Description: Logging level
+   * Example: "INFO"
+   */
+  level?: LogLevel;
+
+  /**
+   * service
+   *
+   * Description: Service name defined.
+   * Example: "payment"
+   */
+  service: string;
+
+  /**
+   * sampling_rate
+   *
+   * Description: The value of the logging sampling rate in percentage.
+   * Example: 0.1
+   */
+  sampling_rate?: number;
+
+  /**
+   * message
+   *
+   * Description: Log statement value. Unserializable JSON values will be cast to string.
+   * Example: "Collecting payment"
+   */
+  message?: string;
+
+  /**
+   * xray_trace_id
+   *
+   * Description: X-Ray Trace ID when Lambda function has enabled Tracing.
+   * Example: "1-5759e988-bd862e3fe1be46a994272793"
+   */
+  xray_trace_id?: string;
+
+  /**
+   * cold_start
+   *
+   * Description: Indicates whether the current execution experienced a cold start.
+   * Example: false
+   */
+  cold_start?: boolean;
+
+  /**
+   * lambda_function_name
+   *
+   * Description: The name of the Lambda function.
+   * Example: "example-powertools-HelloWorldFunction-1P1Z6B39FLU73"
+   */
+  lambda_function_name?: string;
+
+  /**
+   * lambda_function_memory_size
+   *
+   * Description: The memory size of the Lambda function.
+   * Example: 128
+   */
+  lambda_function_memory_size?: number;
+
+  /**
+   * lambda_function_arn
+   *
+   * Description: The ARN of the Lambda function.
+   * Example: "arn:aws:lambda:eu-west-1:012345678910:function:example-powertools-HelloWorldFunction-1P1Z6B39FLU73"
+   */
+  lambda_function_arn?: string;
+
+  /**
+   * lambda_request_id
+   *
+   * Description: The request ID of the current invocation.
+   * Example: "899856cb-83d1-40d7-8611-9e78f15f32f4"
+   */
+  lambda_request_id?: string;
+};
+
+export type { PowertoolsLog };

Diff for: packages/logger/src/types/formats/index.ts

@@ -0,0 +1 @@
+export * from './PowertoolsLog';