From 0af7bd8e7ca6210c6058bb4e1ae30dc1015c8c16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?William=20Chuang=20Sk=C3=B6ld?=
 <william.chuang@bonniernews.se>
Date: Wed, 30 Oct 2024 10:35:05 +0100
Subject: [PATCH] Added logger docs

---
 README.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 63 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 26fc77c..407ed86 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,26 @@
 # @bonniernews/logger
 
+Bonnier News logger library, that makes it easier to unify logging. It is pre-configured for GCP and includes tracing capabilities for Express servers.
+
+```sh
+npm install @bonniernews/logger
+```
+
 ## Usage
 
+Here is an example server with log tracing enabled.
+
 ```js
 import {
   fetchGcpProjectId,
   getHttpTraceHeader,
-  getLoggingTraceData,
   middleware,
-} from "@bonniernews/bn-log-tracer";
+  logger as BNLogger
+} from "@bonniernews/logger";
 import express from "express";
 import pino from "pino";
 
-const logger = pino({ mixin: getLoggingTraceData });
+const logger = BNLogger();
 const app = express();
 
 app.use(middleware);
@@ -31,3 +39,55 @@ app.get("/", async (req, res) => {
   ...
 });
 ```
+
+### Logger Interface
+
+#### Options
+
+This library uses the [Pino logger](https://github.com/pinojs/pino), and instances are created using the same options. In most cases this is not needed, and you can use the defaults:
+
+- Uses `info` as the minimum log level
+- JSON logging with `severity` and `message` fields for non-local environments - in line with [GCP structured logging](https://cloud.google.com/logging/docs/structured-logging) standards
+- Pretty logging enabled for local development and test environments
+
+#### Log Levels
+
+The logger has the following levels, with their corresponding GCP `severity` mapping:
+
+| Log level | GCP severity |
+| --------- | ------------ |
+| `trace`   | `DEBUG`      |
+| `debug`   | `DEBUG`      |
+| `info`    | `INFO`       |
+| `warn`    | `WARNING`    |
+| `error`   | `ERROR`      |
+| `fatal`   | `CRITICAL`   |
+
+#### Log messages
+
+Here are a few examples on how to use the logger:
+
+```js
+import { logger } from "@bonniernews/logger";
+
+const log = logger({ level: "debug" });
+
+log.debug("This is just a message");
+
+log.info("This is how to use %s strings: %d", "template", 123);
+
+log.info({ any: { additional: "data" } }, "I'm attaching relevant data");
+
+const error = new Error("Oops!");
+
+// This will set error.message as the log message,
+// and add a serialized error object under the `err` key:
+log.warn(error);
+
+// The `err` key is special, and triggers error serialization:
+log.error({ err: error }, "This message takes precedence over err.message");
+```
+
+#### Tracing
+
+If you want to decorate logs with tracing fields for incoming requests, use the library's `middleware`, which will use Node async hooks to store and decorate all logs using the [standardized](https://www.w3.org/TR/trace-context/) `traceparent` header.