@aws-lambda-powertools/logger/lib/cjs/formatter/LogFormatter.d.ts

The logging package for the Powertools for AWS Lambda (TypeScript) library

import type { EnvironmentVariablesService } from '../config/EnvironmentVariablesService.js';
import type { LogAttributes } from '../types/Logger.js';
import type { LogFormatterOptions } from '../types/formatters.js';
import type { UnformattedAttributes } from '../types/logKeys.js';
import type { LogItem } from './LogItem.js';
/**
 * Class that defines and implements common methods for the formatting of log attributes.
 *
 * When creating a custom log formatter, you should extend this class and implement the
 * {@link formatAttributes | formatAttributes()} method to define the structure of the log item.
 *
 * @abstract
 */
declare abstract class LogFormatter {
    #private;
    /**
     * Instance of the {@link EnvironmentVariablesService} to use for configuration.
     */
    protected envVarsService?: EnvironmentVariablesService;
    constructor(options?: LogFormatterOptions);
    /**
     * Format key-value pairs of log attributes.
     *
     * You should implement this method in a subclass to define the structure of the log item
     * and instantiate a new {@link LogItem} object with the formatted attributes.
     *
     * Note that when implementing this method, you should avoid mutating the `attributes` and
     * `additionalLogAttributes` objects directly. Instead, create a new object with the desired
     * structure and return it.
     *
     * If mutation is necessary, you can create a `structuredClone` of the object to avoid side effects.
     *
     * @example
     * ```typescript
     * import { LogFormatter, LogItem } from '@aws-lambda-powertools/logger';
     * import type {
     *   LogAttributes,
     *   UnformattedAttributes,
     * } from '@aws-lambda-powertools/logger/types';
     *
     * class MyCompanyLogFormatter extends LogFormatter {
     *   public formatAttributes(
     *     attributes: UnformattedAttributes,
     *     additionalLogAttributes: LogAttributes
     *   ): LogItem {
     *     const baseAttributes = {
     *       message: attributes.message,
     *       service: attributes.serviceName,
     *       environment: attributes.environment,
     *       awsRegion: attributes.awsRegion,
     *       correlationIds: {
     *         awsRequestId: attributes.lambdaContext?.awsRequestId,
     *         xRayTraceId: attributes.xRayTraceId,
     *       },
     *       lambdaFunction: {
     *         name: attributes.lambdaContext?.functionName,
     *         arn: attributes.lambdaContext?.invokedFunctionArn,
     *         memoryLimitInMB: attributes.lambdaContext?.memoryLimitInMB,
     *         version: attributes.lambdaContext?.functionVersion,
     *         coldStart: attributes.lambdaContext?.coldStart,
     *       },
     *       logLevel: attributes.logLevel,
     *       timestamp: this.formatTimestamp(attributes.timestamp), // You can extend this function
     *       logger: {
     *         sampleRateValue: attributes.sampleRateValue,
     *       },
     *     };
     *
     *     const logItem = new LogItem({ attributes: baseAttributes });
     *     // add any attributes not explicitly defined
     *     logItem.addAttributes(additionalLogAttributes);
     *
     *     return logItem;
     *   }
     * }
     *
     * export { MyCompanyLogFormatter };
     * ```
     *
     * @param attributes - Unformatted attributes
     * @param additionalLogAttributes - Additional log attributes
     */
    abstract formatAttributes(attributes: UnformattedAttributes, additionalLogAttributes: LogAttributes): LogItem;
    /**
     * Format an error into a loggable object.
     *
     * @example
     * ```json
     * {
     *   "name": "Error",
     *   "location": "file.js:1",
     *   "message": "An error occurred",
     *   "stack": "Error: An error occurred\n    at file.js:1\n    at file.js:2\n    at file.js:3",
     *   "cause": {
     *     "name": "OtherError",
     *     "location": "file.js:2",
     *     "message": "Another error occurred",
     *     "stack": "Error: Another error occurred\n    at file.js:2\n    at file.js:3\n    at file.js:4"
     *   }
     * }
     * ```
     *
     * @param error - Error to format
     */
    formatError(error: Error): LogAttributes;
    /**
     * Format a date into an ISO 8601 string with the configured timezone.
     *
     * If the log formatter is passed an {@link EnvironmentVariablesService} instance
     * during construction, the timezone is read from the `TZ` environment variable, if present.
     *
     * Otherwise, the timezone defaults to ':UTC'.
     *
     * @param now - The date to format
     */
    formatTimestamp(now: Date): string;
    /**
     * Get the location of an error from a stack trace.
     *
     * @param stack - stack trace to parse
     */
    getCodeLocation(stack?: string): string;
}
export { LogFormatter };
//# sourceMappingURL=LogFormatter.d.ts.map