@ogcio/nextjs-logging-wrapper 14.2.5

package/README.md

@@ -0,0 +1,61 @@
+# NextJs Logging Wrapper
+
+This logging wrapper goal is to standardize the records written by our NextJs services.
+
+## How to
+
+To use this package three steps are needed:
+
+- add `"nextjs-logging-wrapper": "*",` to your dependencies
+- based on the needs, you can use one of the two available methods:
+  - `getServerLogger()`, that must be used to log entries on the server side
+  - `getClientLogger()`, used to log entries on the client side
+
+_Server example_
+
+```
+import { getServerLogger } from "nextjs-logging-wrapper";
+.....
+"use server"
+.....
+getServerLogger().debug("Welcome to the server side!");
+```
+
+_Client example_
+
+```
+"use client"
+import { getClientLogger } from "nextjs-logging-wrapper";
+.....
+getClientLogger().debug("Welcome to the client side!");
+```
+
+## Log entries format
+
+### Client Side
+
+The entry for the client logger will be something similar to
+
+```
+{"level":30,"level_name":"INFO","timestamp":1719322306071,"request":{"path":"/en/the-page","params":{"locale":"en"},"query_params":{}},"message":"Welcome to the client side"}
+```
+
+### Server Side
+
+The entry for the server logger will be something similar to
+
+```
+ {"level":30,"level_name":"INFO","hostname":"SSalvatico-ITMAC24","timestamp":1719323762474,"request_id":"50572f1b-a789-459d-9770-c525b69a221e","request":{"scheme":"http","method":"GET","path":"/en/the-backend-route","hostname":"localhost:3002","language":"en","user_agent":"the user agent"},"message":"Welcome to the server side"}
+```
+
+## Minimum Log Level
+
+The minimum log level is decided, in order of priority, by:
+
+- optional `minimumLevel` parameter passed when the logger instance is created
+- `LOG_LEVEL` env variable
+- otherwise `debug` is set as default value
+
+## Docker
+
+Remember to copy and build the package to the container in your Dockerfile!

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ogcio/nextjs-logging-wrapper",
+  "version": "14.2.5",
+  "description": "",
+  "type": "module",
+  "exports": {
+    "./client-logger": "./dist/client-logger.js",
+    "./common-logger": "./dist/common-logger.js",
+    "./server-logger": "./dist/server-logger.js"
+  },
+  "typesVersions": {
+    "*": {
+      "client-logger": ["./dist/client-logger.d.ts"],
+      "common-logger": ["./dist/common-logger.d.ts"],
+      "server-logger": ["./dist/server-logger.d.ts"]
+    }
+  },
+  "scripts": {
+    "dev": "rm -rf dist && tsc -w -p tsconfig.prod.json",
+    "build": "rm -rf dist && tsc -p tsconfig.prod.json",
+    "test": "echo \"Error: no test specified\" && exit 0",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix"
+  },
+  "keywords": [],
+  "author": "samuele.salvatico@nearform.com",
+  "license": "ISC",
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.4",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "next": "^14.2.5",
+    "pino": "^9.5.0",
+    "@ogcio/shared-errors": "^1.0.0"
+  }
+}

package/src/client-logger.ts

@@ -0,0 +1,38 @@
+import { useParams, usePathname, useSearchParams } from "next/navigation.js";
+import type { Level, Logger } from "pino";
+import { getPinoInstance } from "./shared.js";
+
+export const REDACTED_PATHS = [];
+
+let logger: Logger;
+export const getClientLogger = (minimumLevel?: Level): Logger => {
+  if (!logger) {
+    logger = getPinoInstance({
+      minimumLevel,
+      loggingContext: getLoggingContext(),
+      pathsToRedact: REDACTED_PATHS,
+    });
+  }
+
+  return logger;
+};
+
+interface ClientLoggingRequest {
+  params: { [x: string]: string };
+  path: string;
+  query_params: { [x: string]: string };
+}
+
+const getLoggingContext = (): {
+  [x: string]: unknown;
+  request: ClientLoggingRequest;
+} => {
+  const search: { [x: string]: string } = {};
+  useSearchParams().forEach((value, key) => {
+    search[key] = value;
+  });
+
+  return {
+    request: { path: usePathname(), params: useParams(), query_params: search },
+  };
+};

package/src/common-logger.ts

@@ -0,0 +1,17 @@
+import type { Level, Logger } from "pino";
+import { getPinoInstance } from "./shared.js";
+
+export const REDACTED_PATHS = [];
+
+let logger: Logger;
+export const getCommonLogger = (minimumLevel?: Level): Logger => {
+  if (!logger) {
+    logger = getPinoInstance({
+      minimumLevel,
+      loggingContext: { request: {} },
+      pathsToRedact: REDACTED_PATHS,
+    });
+  }
+
+  return logger;
+};

package/src/server-logger.ts

@@ -0,0 +1,69 @@
+import { hostname } from "os";
+import { REQUEST_ID_HEADER } from "@ogcio/shared-errors";
+import { headers } from "next/headers.js";
+import type { Level, Logger } from "pino";
+import { REQUEST_ID_LOG_LABEL, getPinoInstance } from "./shared.js";
+
+export interface LoggingRequest {
+  scheme: string | undefined;
+  method: string | undefined;
+  path: string | undefined;
+  hostname: string | undefined;
+  query_params: unknown | undefined;
+  [key: string]: unknown;
+}
+
+export const REDACTED_PATHS = [];
+
+let logger: Logger;
+export const getServerLogger = (minimumLevel?: Level): Logger => {
+  if (!logger) {
+    logger = getPinoInstance({
+      minimumLevel,
+      loggingContext: getLoggingContext(),
+      baseProperties: { hostname: hostname() },
+      pathsToRedact: REDACTED_PATHS,
+    });
+  }
+
+  return logger;
+};
+
+const getRequestInfo = (mappedHeaders: {
+  [x: string]: unknown;
+}): LoggingRequest => {
+  const getHeaderAsStringIfSet = (headerName: string): string | undefined =>
+    mappedHeaders[headerName] && typeof mappedHeaders[headerName] === "string"
+      ? (mappedHeaders[headerName] as string)
+      : undefined;
+
+  return {
+    scheme: getHeaderAsStringIfSet("x-forwarded-proto"),
+    method: "GET",
+    path: getHeaderAsStringIfSet("x-pathname"),
+    hostname: getHeaderAsStringIfSet("host"),
+    language: getHeaderAsStringIfSet("x-next-intl-locale"),
+    query_params: undefined,
+    user_agent: getHeaderAsStringIfSet("user-agent"),
+  };
+};
+
+const getLoggingContext = (): {
+  [x: string]: unknown;
+  request: LoggingRequest;
+} => {
+  const requestHeaders = headers();
+  const requestId = requestHeaders.has(REQUEST_ID_HEADER)
+    ? (requestHeaders.get(REQUEST_ID_HEADER) as string)
+    : crypto.randomUUID();
+
+  const outputHeaders: { [x: string]: unknown } = {};
+  requestHeaders.forEach((value, key) => {
+    outputHeaders[key] = value;
+  });
+
+  return {
+    [REQUEST_ID_LOG_LABEL]: requestId,
+    request: getRequestInfo(outputHeaders),
+  };
+};

package/src/shared.ts

@@ -0,0 +1,60 @@
+import {
+  type Level,
+  type Logger,
+  type LoggerOptions,
+  levels,
+  pino,
+} from "pino";
+
+export const MESSAGE_KEY = "message";
+
+export const REQUEST_ID_LOG_LABEL = "request_id";
+
+export const REDACTED_VALUE = "[redacted]";
+
+export const getPinoInstance = <T>(params: {
+  pathsToRedact: string[];
+  baseProperties?: { [x: string]: string };
+  loggingContext: {
+    [x: string]: unknown;
+    request: T;
+  };
+  minimumLevel?: Level;
+}): Logger => {
+  const toCheckLevel = params.minimumLevel ?? process.env.LOG_LEVEL;
+  const level = isValidLevel(toCheckLevel) ? toCheckLevel : "debug";
+
+  return pino(getLoggerConfiguration({ ...params, minimumLevel: level }));
+};
+
+const isValidLevel = (level: string | undefined): level is Level =>
+  level !== undefined && Object.keys(levels.values).includes(level);
+
+const getLoggerConfiguration = <T>(params: {
+  minimumLevel: Level;
+  pathsToRedact: string[];
+  baseProperties?: { [x: string]: string };
+  loggingContext: {
+    [x: string]: unknown;
+    request: T;
+  };
+}): LoggerOptions => ({
+  base: params.baseProperties,
+  messageKey: MESSAGE_KEY,
+  mixin: () => ({
+    timestamp: Date.now(),
+    ...params.loggingContext,
+  }),
+  redact: {
+    paths: params.pathsToRedact,
+    censor: REDACTED_VALUE,
+  },
+  timestamp: false,
+  formatters: {
+    level: (name: string, levelVal: number) => ({
+      level: levelVal,
+      level_name: name.toUpperCase(),
+    }),
+  },
+  level: params.minimumLevel,
+});

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "dist",
+  },
+  "include": ["src", "__tests__"],
+  "references": [
+    { "path": "../shared-errors" }
+  ]
+}

package/tsconfig.prod.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig",
+  "exclude": ["__tests__", "dist"],
+}