@apify/log - npm Package Compare versions

Comparing version 1.0.2 to 1.0.3

log.d.ts

 import { Logger } from './logger';
 import { LogLevel } from './log_consts';
 export interface LoggerOptions {
-    level: number;
-    maxDepth: number;
-    maxStringLength: number;
-    prefix: string | null;
-    suffix: string | null;
-    logger: Logger;
-    data: Record<string, unknown>;
+    /**
+     * Sets the log level to the given value, preventing messages from less important log levels
+     * from being printed to the console. Use in conjunction with the `log.LEVELS` constants.
+     */
+    level?: number;
+    /** Max depth of data object that will be logged. Anything deeper than the limit will be stripped off. */
+    maxDepth?: number;
+    /** Max length of the string to be logged. Longer strings will be truncated. */
+    maxStringLength?: number;
+    /** Prefix to be prepended the each logged line. */
+    prefix?: string | null;
+    /** Suffix that will be appended the each logged line. */
+    suffix?: string | null;
+    /**
+     * Logger implementation to be used. Default one is log.LoggerText to log messages as easily readable
+     * strings. Optionally you can use `log.LoggerJson` that formats each log line as a JSON.
+     */
+    logger?: Logger;
+    /** Additional data to be added to each log line. */
+    data?: Record<string, unknown>;
 }
+/**
+ * The log instance enables level aware logging of messages and we advise
+ * to use it instead of `console.log()` and its aliases in most development
+ * scenarios.
+ *
+ * A very useful use case for `log` is using `log.debug` liberally throughout
+ * the codebase to get useful logging messages only when appropriate log level is set
+ * and keeping the console tidy in production environments.
+ *
+ * The available logging levels are, in this order: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `OFF`
+ * and can be referenced from the `log.LEVELS` constant, such as `log.LEVELS.ERROR`.
+ *
+ * To log messages to the system console, use the `log.level(message)` invocation,
+ * such as `log.debug('this is a debug message')`.
+ *
+ * To prevent writing of messages above a certain log level to the console, simply
+ * set the appropriate level. The default log level is `INFO`, which means that
+ * `DEBUG` messages will not be printed, unless enabled.
+ *
+ * **Example:**
+ * ```js
+ * const Apify = require('apify');
+ * const { log } = Apify.utils;
+ *
+ * log.info('Information message', { someData: 123 }); // prints message
+ * log.debug('Debug message', { debugData: 'hello' }); // doesn't print anything
+ *
+ * log.setLevel(log.LEVELS.DEBUG);
+ * log.debug('Debug message'); // prints message
+ *
+ * log.setLevel(log.LEVELS.ERROR);
+ * log.debug('Debug message'); // doesn't print anything
+ * log.info('Info message'); // doesn't print anything
+ *
+ * log.error('Error message', { errorDetails: 'This is bad!' }); // prints message
+ * try {
+ *   throw new Error('Not good!');
+ * } catch (e) {
+ *   log.exception(e, 'Exception occurred', { errorDetails: 'This is really bad!' }); // prints message
+ * }
+ *
+ * log.setOptions({ prefix: 'My actor' });
+ * log.info('I am running!'); // prints "My actor: I am running"
+ *
+ * const childLog = log.child({ prefix: 'Crawler' });
+ * log.info('I am crawling!'); // prints "My actor:Crawler: I am crawling"
+ * ```
+ *
+ * Another very useful way of setting the log level is by setting the `APIFY_LOG_LEVEL`
+ * environment variable, such as `APIFY_LOG_LEVEL=DEBUG`. This way, no code changes
+ * are necessary to turn on your debug messages and start debugging right away.
+ *
+ * To add timestamps to your logs, you can override the default logger settings:
+ * ```js
+ * log.setOptions({
+ *     logger: new log.LoggerText({ skipTime: false }),
+ * });
+ * ```
+ * You can customize your logging further by extending or replacing the default
+ * logger instances with your own implementations.
+ */
 export declare class Log {
+    /**
+     * Map of available log levels that's useful for easy setting of appropriate log levels.
+     * Each log level is represented internally by a number. Eg. `log.LEVELS.DEBUG === 5`.
+     */
     readonly LEVELS: typeof LogLevel;
@@ -18,24 +96,62 @@ private options;
     private _limitDepth;
+    /**
+     * Returns the currently selected logging level. This is useful for checking whether a message
+     * will actually be printed to the console before one actually performs a resource intensive operation
+     * to construct the message, such as querying a DB for some metadata that need to be added. If the log
+     * level is not high enough at the moment, it doesn't make sense to execute the query.
+     */
     getLevel(): number;
+    /**
+     * Sets the log level to the given value, preventing messages from less important log levels
+     * from being printed to the console. Use in conjunction with the `log.LEVELS` constants such as
+     *
+     * ```
+     * log.setLevel(log.LEVELS.DEBUG);
+     * ```
+     *
+     * Default log level is INFO.
+     */
     setLevel(level: LogLevel): void;
     internal(level: LogLevel, message: string, data?: any, exception?: any): void;
+    /**
+     * Configures logger.
+     */
     setOptions(options: Partial<LoggerOptions>): void;
-    getOptions(): {
-        level: number;
-        maxDepth: number;
-        maxStringLength: number;
-        prefix: string | null;
-        suffix: string | null;
-        logger: Logger;
-        data: Record<string, unknown>;
-    };
+    /**
+     * Returns the logger configuration.
+     */
+    getOptions(): Required<LoggerOptions>;
+    /**
+     * Creates a new instance of logger that inherits settings from a parent logger.
+     */
     child(options: Partial<LoggerOptions>): Log;
-    error(message: string, data?: any): void;
-    exception(exception: any, message: string, data?: any): void;
-    softFail(message: string, data?: any): void;
-    warning(message: string, data?: any): void;
-    info(message: string, data?: any): void;
-    debug(message: string, data?: any): void;
-    perf(message: string, data?: any): void;
     /**
+     * Logs an `ERROR` message. Use this method to log error messages that are not directly connected
+     * to an exception. For logging exceptions, use the `log.exception` method.
+     */
+    error(message: string, data?: Record<string, any>): void;
+    /**
+     * Logs an `ERROR` level message with a nicely formatted exception. Note that the exception is the first parameter
+     * here and an additional message is only optional.
+     */
+    exception(exception: Error, message: string, data?: Record<string, any>): void;
+    softFail(message: string, data?: Record<string, any>): void;
+    /**
+     * Logs a `WARNING` level message. Data are stringified and appended to the message.
+     */
+    warning(message: string, data?: Record<string, any>): void;
+    /**
+     * Logs an `INFO` message. `INFO` is the default log level so info messages will be always logged,
+     * unless the log level is changed. Data are stringified and appended to the message.
+     */
+    info(message: string, data?: Record<string, any>): void;
+    /**
+     * Logs a `DEBUG` message. By default, it will not be written to the console. To see `DEBUG`
+     * messages in the console, set the log level to `DEBUG` either using the `log.setLevel(log.LEVELS.DEBUG)`
+     * method or using the environment variable `APIFY_LOG_LEVEL=DEBUG`. Data are stringified and appended
+     * to the message.
+     */
+    debug(message: string, data?: Record<string, any>): void;
+    perf(message: string, data?: Record<string, any>): void;
+    /**
      * Logs given message only once as WARNING. It's used to warn user that some feature he is using has been deprecated.
@@ -42,0 +158,0 @@ */

log.js

@@ -16,4 +16,69 @@ "use strict";
 });
+/**
+ * The log instance enables level aware logging of messages and we advise
+ * to use it instead of `console.log()` and its aliases in most development
+ * scenarios.
+ *
+ * A very useful use case for `log` is using `log.debug` liberally throughout
+ * the codebase to get useful logging messages only when appropriate log level is set
+ * and keeping the console tidy in production environments.
+ *
+ * The available logging levels are, in this order: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `OFF`
+ * and can be referenced from the `log.LEVELS` constant, such as `log.LEVELS.ERROR`.
+ *
+ * To log messages to the system console, use the `log.level(message)` invocation,
+ * such as `log.debug('this is a debug message')`.
+ *
+ * To prevent writing of messages above a certain log level to the console, simply
+ * set the appropriate level. The default log level is `INFO`, which means that
+ * `DEBUG` messages will not be printed, unless enabled.
+ *
+ * **Example:**
+ * ```js
+ * const Apify = require('apify');
+ * const { log } = Apify.utils;
+ *
+ * log.info('Information message', { someData: 123 }); // prints message
+ * log.debug('Debug message', { debugData: 'hello' }); // doesn't print anything
+ *
+ * log.setLevel(log.LEVELS.DEBUG);
+ * log.debug('Debug message'); // prints message
+ *
+ * log.setLevel(log.LEVELS.ERROR);
+ * log.debug('Debug message'); // doesn't print anything
+ * log.info('Info message'); // doesn't print anything
+ *
+ * log.error('Error message', { errorDetails: 'This is bad!' }); // prints message
+ * try {
+ *   throw new Error('Not good!');
+ * } catch (e) {
+ *   log.exception(e, 'Exception occurred', { errorDetails: 'This is really bad!' }); // prints message
+ * }
+ *
+ * log.setOptions({ prefix: 'My actor' });
+ * log.info('I am running!'); // prints "My actor: I am running"
+ *
+ * const childLog = log.child({ prefix: 'Crawler' });
+ * log.info('I am crawling!'); // prints "My actor:Crawler: I am crawling"
+ * ```
+ *
+ * Another very useful way of setting the log level is by setting the `APIFY_LOG_LEVEL`
+ * environment variable, such as `APIFY_LOG_LEVEL=DEBUG`. This way, no code changes
+ * are necessary to turn on your debug messages and start debugging right away.
+ *
+ * To add timestamps to your logs, you can override the default logger settings:
+ * ```js
+ * log.setOptions({
+ *     logger: new log.LoggerText({ skipTime: false }),
+ * });
+ * ```
+ * You can customize your logging further by extending or replacing the default
+ * logger instances with your own implementations.
+ */
 class Log {
     constructor(options = {}) {
+        /**
+         * Map of available log levels that's useful for easy setting of appropriate log levels.
+         * Each log level is represented internally by a number. Eg. `log.LEVELS.DEBUG === 5`.
+         */
         this.LEVELS = log_consts_1.LogLevel; // for BC
@@ -40,5 +105,21 @@ this.deprecationsReported = {};
     }
+    /**
+     * Returns the currently selected logging level. This is useful for checking whether a message
+     * will actually be printed to the console before one actually performs a resource intensive operation
+     * to construct the message, such as querying a DB for some metadata that need to be added. If the log
+     * level is not high enough at the moment, it doesn't make sense to execute the query.
+     */
     getLevel() {
         return this.options.level;
     }
+    /**
+     * Sets the log level to the given value, preventing messages from less important log levels
+     * from being printed to the console. Use in conjunction with the `log.LEVELS` constants such as
+     *
+     * ```
+     * log.setLevel(log.LEVELS.DEBUG);
+     * ```
+     *
+     * Default log level is INFO.
+     */
     setLevel(level) {
@@ -60,8 +141,17 @@ if (!log_consts_1.LogLevel[level])
     }
+    /**
+     * Configures logger.
+     */
     setOptions(options) {
         this.options = Object.assign(Object.assign({}, this.options), options);
     }
+    /**
+     * Returns the logger configuration.
+     */
     getOptions() {
         return Object.assign({}, this.options);
     }
+    /**
+     * Creates a new instance of logger that inherits settings from a parent logger.
+     */
     child(options) {
@@ -80,5 +170,13 @@ let { prefix } = this.options;
     }
+    /**
+     * Logs an `ERROR` message. Use this method to log error messages that are not directly connected
+     * to an exception. For logging exceptions, use the `log.exception` method.
+     */
     error(message, data) {
         this.internal(log_consts_1.LogLevel.ERROR, message, data);
     }
+    /**
+     * Logs an `ERROR` level message with a nicely formatted exception. Note that the exception is the first parameter
+     * here and an additional message is only optional.
+     */
     exception(exception, message, data) {
@@ -90,8 +188,21 @@ this.internal(log_consts_1.LogLevel.ERROR, message, data, exception);
     }
+    /**
+     * Logs a `WARNING` level message. Data are stringified and appended to the message.
+     */
     warning(message, data) {
         this.internal(log_consts_1.LogLevel.WARNING, message, data);
     }
+    /**
+     * Logs an `INFO` message. `INFO` is the default log level so info messages will be always logged,
+     * unless the log level is changed. Data are stringified and appended to the message.
+     */
     info(message, data) {
         this.internal(log_consts_1.LogLevel.INFO, message, data);
     }
+    /**
+     * Logs a `DEBUG` message. By default, it will not be written to the console. To see `DEBUG`
+     * messages in the console, set the log level to `DEBUG` either using the `log.setLevel(log.LEVELS.DEBUG)`
+     * method or using the environment variable `APIFY_LOG_LEVEL=DEBUG`. Data are stringified and appended
+     * to the message.
+     */
     debug(message, data) {
@@ -98,0 +209,0 @@ this.internal(log_consts_1.LogLevel.DEBUG, message, data);

package.json

 {
     "name": "@apify/log",
-    "version": "1.0.2",
+    "version": "1.0.3",
     "description": "Tools and constants shared across Apify projects.",
@@ -49,3 +49,3 @@ "main": "index.js",
     },
-    "gitHead": "7071acd8fc3e192e46dda958aff9127835b090ec"
+    "gitHead": "f6fa7bf10885753da15c8da601e7d82dfd8ebfc3"
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

45855

increased by28.43%

Lines of code

755

increased by42.99%

No dependency changes