@seek/logger - npm Package Compare versions

Comparing version 4.4.7 to 5.0.0

lib-types/destination/index.d.ts

@@ -1,2 +0,2 @@
-import { DestinationStream } from 'pino';
-export declare const withRedaction: (dest: DestinationStream) => DestinationStream;
+import pino from 'pino';
+export declare const withRedaction: (dest: pino.DestinationStream) => pino.DestinationStream;

lib-types/index.d.ts

@@ -1,6 +0,6 @@
-import pino, { DestinationStream } from 'pino';
+import pino from 'pino';
 import { FormatterOptions } from './formatters';
 export { pino };
 export declare type LoggerOptions = pino.LoggerOptions & FormatterOptions;
-declare const _default: (opts?: LoggerOptions, destination?: DestinationStream) => pino.Logger;
+declare const _default: (opts?: LoggerOptions, destination?: pino.DestinationStream) => pino.Logger;
 /**
@@ -7,0 +7,0 @@ * Creates a logger that can enforce a strict logged object shape.

package.json

@@ -9,6 +9,5 @@ {
   "dependencies": {
-    "@types/pino": "^6.3.2",
     "dtrim": "^1.9.0",
-    "pino": "^6.7.0",
-    "pino-std-serializers": "^2.5.0"
+    "pino": "^7.0.2",
+    "pino-std-serializers": "^4.0.0"
   },
@@ -62,3 +61,3 @@ "description": "Standardized logging",
   "types": "./lib-types/index.d.ts",
-  "version": "4.4.7"
+  "version": "5.0.0"
 }

README.md

@@ -8,14 +8,27 @@ # @seek/logger
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
-[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 
-Standardized application Logging
+**@seek/logger** is a JSON logger for Node.js applications.
+It implements several SEEK customisations over [Pino], including:
 
-This allows us consistently query request and response across all apps.
+- Human-readable `timestamp`s for Splunk compatibility
+- Redaction of sensitive data
+- Trimming deep objects to reduce cost and unintended disclosure
 
-## Sample Usage
+## Table of contents
 
+- [Usage](#usage)
+  - [Standardised fields](#standardised-fields)
+  - [Typed fields](#typed-fields)
+- [Features](#features)
+  - [Redaction](#redaction)
+  - [Trimming](#trimming)
+  - [Pino customisation](#pino-customisation)
+  - [Pretty printing](#pretty-printing)
+
+## Usage
+
 ```typescript
 import createLogger from '@seek/logger';
 
-// Initialize - by default logs to Console Stream
+// Initialize the logger. By default, this will log to stdout.
 const logger = createLogger({
@@ -25,37 +38,70 @@ name: 'my-app',
 
-// Import logged object interfaces from a shared module OR
-// declare logged object interfaces
-interface MessageContext {
+// Write an informational (`level` 30) log with a `msg`.
+logger.info('Something good happened');
+
+// Create a child logger that automatically includes the `requestId` field.
+const childLogger = logger.child({ requestId });
+
+// Write an error (`level` 50) log with `err`, `msg` and `requestId`.
+childLogger.error({ err }, 'Something bad happened');
+```
+
+### Standardised fields
+
+**@seek/logger** bundles custom `req` and `res` serializers along with [Pino]'s standard set.
+User-defined serializers will take precedence over predefined ones.
+
+Use the following standardised logging fields to benefit from customised serialization:
+
+- `err` for errors.
+
+  The [Error] is serialized with its message, name, stack and additional properties.
+  Notice that this is not possible with e.g. `JSON.stringify(new Error())`.
+
+- `req` for HTTP requests.
+
+  The request object is trimmed to a set of essential fields.
+
+- `res` for HTTP responses.
+
+  The response object is trimmed to a set of essential fields.
+
+All other fields will be logged directly.
+
+### Typed fields
+
+You can type common sets of fields to enforce consistent logging across your application(s).
+Compatibility should be maintained with the existing [serializer functions](src/serializers/index.ts).
+
+```typescript
+// Declare a TypeScript type for your log fields.
+interface Fields {
   activity: string;
-  err?: Error | { message: string };
-  req?: {
-    method: 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    url: string;
-  };
+  err?: Error;
 }
 
-// Specify the interface and benefit from enforced structure and code completion.
-logger.trace<MessageContext>({
-  activity: 'Getting all the things',
-  req: { method: 'GET', url: 'https://example.com/things' },
-});
+// Supply it as a type parameter for code completion and compile-time checking.
+logger.trace<Fields>(
+  {
+    activity: 'Getting all the things',
+  },
+  'Request initiated',
+);
 
-logger.error<MessageContext>({
-  activity: 'Getting all the things',
-  req: { method: 'GET', url: 'https://example.com/things' },
-  err: {
-    message: 'Unexpected error getting things',
+logger.error<Fields>(
+  {
+    activity: 'Getting all the things',
+    err,
   },
-});
+  'Request failed',
+);
 ```
 
-If logger is used with an object as first argument, please use `req`, `res` and `err` to log request, response and error respectively.
+## Features
 
-`req` and `res` objects are trimmed to contain only essential logging data.
+### Redaction
 
-All other objects passed will be logged directly.
-
 Bearer tokens are redacted regardless of their placement in the log object.
 
-For suggestions on enforcing logged object structures for consistency, see [below](#enforcing-logged-object-structures).
+### Trimming
 
@@ -75,5 +121,5 @@ The following trimming rules apply to all logging data:
 
-### Pino
+### Pino customisation
 
-**@seek/logger** uses Pino under the hood.
+**@seek/logger** uses [Pino] under the hood.
 You can customise your logger by providing [Pino options] like so:
@@ -117,13 +163,5 @@
 
-## Serializers
-
-Library is utilizing standard pino serializers with custom `req` and `res` serialializers.
-If other serializers with same keys are provided to the library, they will take precedence over predefined ones.
-
-## Enforcing Logged Object Structures
-
-If you would like to enforce the structure of objects being logged, define the interface to log and specify it as the generic type in the logger functions.
-Compatibility should be maintained with the existing [`serializer functions`](src/serializers/index.ts).
-
+[error]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
+[pino]: https://github.com/pinojs/pino
 [pino options]: https://github.com/pinojs/pino/blob/master/docs/api.md#options
 [pino-pretty]: https://github.com/pinojs/pino-pretty

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

25508

increased by2.07%

Dependency count

3

decreased by-25%

Number of lines in readme file

164

increased by30.16%

Dependency changes

• + Addedon-exit-leak-free@0.2.0(transitive)

• + Addedpino@7.11.0(transitive)

• + Addedpino-std-serializers@4.0.0(transitive)

• + Addedreal-require@0.1.0(transitive)

• + Addedsafe-stable-stringify@2.5.0(transitive)

• + Addedthread-stream@0.15.2(transitive)

• - Removed@types/pino@^6.3.2

• - Removed@types/node@22.10.6(transitive)

• - Removed@types/pino@6.3.12(transitive)

• - Removed@types/pino-pretty@5.0.0(transitive)

• - Removed@types/pino-std-serializers@4.0.0(transitive)

• - Removedcolorette@2.0.20(transitive)

• - Removeddateformat@4.6.3(transitive)

• - Removedend-of-stream@1.4.4(transitive)

• - Removedfast-copy@3.0.2(transitive)

• - Removedfast-safe-stringify@2.1.1(transitive)

• - Removedflatstr@1.0.12(transitive)

• - Removedhelp-me@5.0.0(transitive)

• - Removedjoycon@3.1.1(transitive)

• - Removedminimist@1.2.8(transitive)

• - Removedon-exit-leak-free@2.1.2(transitive)

• - Removedonce@1.4.0(transitive)

• - Removedpino@6.14.0(transitive)

• - Removedpino-abstract-transport@2.0.0(transitive)

• - Removedpino-pretty@13.0.0(transitive)

• - Removedpino-std-serializers@2.5.03.2.0(transitive)

• - Removedpump@3.0.2(transitive)

• - Removedsecure-json-parse@2.7.0(transitive)

• - Removedsonic-boom@1.4.14.2.0(transitive)

• - Removedsplit2@4.2.0(transitive)

• - Removedstrip-json-comments@3.1.1(transitive)

• - Removedundici-types@6.20.0(transitive)

• - Removedwrappy@1.0.2(transitive)

• Updatedpino@^7.0.2

• Updatedpino-std-serializers@^4.0.0