feat(logger): create a child method (#1833)

.changeset/long-moose-change.md

@@ -0,0 +1,6 @@
+---
+'@ogma/logger': minor
+'@ogma/nestjs-module': minor
+---
+
+Create a child method to allow for creating new loggers with existing options

apps/docs/src/pages/en/logger.md

@@ -88,6 +88,7 @@ This option is available in `@ogma/logger@^2.5.0`
 | context | string optional | a context for the Ogma class to work with. |
 | application | string optional | an application name for Ogma to print |
 | levelMap | an object with the above levels as the keys and strings as the vales | a way to provide custom log levels in the event that there are mappings the developer wants to support |
+| levelKey | string optional | A specific key to print the level as when in JSON mode. Useful for things like GCP which use `severity` instead of `level` |
 | masks | string[] | An array of words that should be replaced while logging. useful for sensitive information like passwords. |
 | logPid | boolean | An optional property you can set if you don't want to log the PID. |
 | logApplication | boolean | An optional property you can set if you don't want to the the application name. |
@@ -137,6 +138,10 @@ Using the non-JSON mode, color is attempted to be applied by default. This is de
 
 There may be times, like with [OpenTelemetry](https://opentelemetry.io) or with adding a correlation id, that you need to add dynamic values to each log. Rather than making a new wrapper around the Ogma instance, Ogma provides an optional `mixin` property that can be used to add extra data to each log without being in `verbose` mode. This property is a function, that takes in the current log level and the Ogma instance, and should return an object of any shape.
 
+### Child Loggers
+
+There may be times where you have a default logging configuration that you want to use across multiple a project without having to save the configuration to a variable. If that ever becomes the case, you can call `ogma.child()` and pass in a partial object of new options which will merge with the original options passed to the first `new Ogma()` call. This will return a new logger instance that will have the combined options, so you can change things like the log level or the context easily, without having to create new `levelMap` or `masks`.
+
 ## Example of what the logs look like
 
 I said the logs were beautiful, and to me they absolutely are. Each log is matched with a timestamp in ISO format, the log level, a pipe character, and then the message, for easier searching if needed. If a JSON is passed to Ogma, a new line will separate the JSON and the original log line, but the timestamp and level will not be duplicated. Ogma also will print `'[Function]'` if a function is found or `'[Circular]'` is a circular reference is found.

packages/logger/src/logger/ogma.ts

@@ -374,6 +374,15 @@ export class Ogma {
     return new Date().toISOString();
   }
 
+  /**
+   * Create a new instance of ogma using pre-existing options while being able to pass in new options to override specific values. Useful for when there's a default configuration you'd like to make use of with slightly different modifications elsewhere
+   * @param newOptions overriding options for the new logger instance
+   * @returns a new ogma instance using the original logger's options, merged with the new options passed
+   */
+  child(newOptions: Partial<OgmaOptions>): Ogma {
+    return new Ogma({ ...this.options, ...newOptions });
+  }
+
   /**
    * Change the set log level for the Ogma logger
    * @param the new log level

packages/nestjs-module/src/ogma.service.ts

@@ -187,7 +187,10 @@ export class OgmaService implements LoggerService {
 
   private printMessage(
     message: any,
-    levelString: Exclude<keyof Ogma, 'printMessage' | 'printError' | 'setLogLevel' | 'style'>,
+    levelString: Exclude<
+      keyof Ogma,
+      'printMessage' | 'printError' | 'setLogLevel' | 'style' | 'child'
+    >,
     meta: OgmaServiceMeta = {},
   ): void {
     meta.context = meta.context ?? this.context;