feat: reworks logging (#10)

Author: dgoerdes

.gitignore

@@ -2,6 +2,7 @@
 
 # environment files
 .env*
+.otel_token
 
 # compiled output
 dist

deno.lock

@@ -40,8 +40,7 @@ export type AccountAddedEvent = z.infer<typeof AccountAddedEvent>;
 ```
 
 ```typescript [Shell]
-import { RouteHandler } from "@nimbus/core";
-import * as log from "@std/log";
+import { getLogger, RouteHandler } from "@nimbus/core";
 import {
     AccountAddedData,
     AccountAddedEvent,
@@ -53,7 +52,9 @@ export const accountAddedHandler: RouteHandler<
 > = async (event) => {
     await new Promise((resolve) => setTimeout(resolve, 1000));
 
-    log.info({ msg: `New account was added: ${event.data.account.name}` });
+    getLogger().info({
+        message: `New account was added: ${event.data.account.name}`,
+    });
 
     // This is just an example.
     // Change the code to do what has to be done after an account got added.

docs/guide/core/events.md

@@ -1,66 +1,126 @@
 # Logging
 
-For logging Nimbus uses the [`@std/log`](https://jsr.io/@std/log) library.
+Nimbus provides a very simple logger that enables you to log messages for different severity levels to the console.
 
-## Default setup
+It is basically a wrapper around the `console` object and the `console.debug()`, `console.info()`, `console.warn()`, `console.error()` and `console.critical()` methods.
 
-Nimbus provides a simple function to setup the logger. You can pass in the log level and the format you want to use.
+It helps to have consistent logs with important meta information (timestamp, log level,category, error stack traces, etc) across your application.
 
-The `pretty` format is recommended for development environments only. In production you should use the `json` format.
+No other transports or sinks are supported. As we want to keep the core as lightweight as possible and encourage the use of tools like [OpenTelemetry](https://opentelemetry.io/) to transport logs for monitoring and tracing.
 
-::: code-group
+As [Deno supports OpenTelemetry](https://docs.deno.com/runtime/fundamentals/open_telemetry/) out of the box, you can easily transport logs to any other monitoring system without the need to change the code of the application.
 
-```typescript [main.ts]
-import { setupLog } from "@nimbus/core";
+## Log Levels
 
-setupLog({
-    logLevel: process.env.LOG_LEVEL,
-    format: process.env.NODE_ENV === "development" ? "pretty" : "json",
-});
-```
+Nimbus supports the following log levels for logging messages.
 
-```typescript [logExample.ts]
-import * as log from "@std/log";
+-   `debug` - Outputs a `console.debug()`
+-   `info` - Outputs a `console.info()`
+-   `warn` - Outputs a `console.warn()`
+-   `error` - Outputs a `console.error()`
+-   `critical` - Outputs a `console.error()`
 
-log.info({ msg: "Hello World!" });
+Also `silent` can be used in the setup to completely disable log output.
 
-log.warn({ msg: "Ding Dong!" });
+## Setup
 
-log.error({ msg: "Ohh no!", error: new Error("Something went wrong!") });
+Nimbus provides a simple function to setup the logger. You can pass in the log level and the formatter you want to use.
 
-log.critical({
-    msg: "It is over, run!",
-    error: new Error("Something is burning!"),
+The `prettyLogFormatter` is recommended for development environments only. In production you should use the `jsonLogFormatter`.
+
+For the pretty formatter the `useConsoleColors` option can be used to enable colors in the console output.
+
+::: code-group
+
+```typescript [main.ts]
+import {
+    jsonLogFormatter,
+    parseLogLevel,
+    prettyLogFormatter,
+    setupLogger,
+} from "@nimbus/core";
+
+setupLogger({
+    logLevel: parseLogLevel(process.env.LOG_LEVEL),
+    formatter:
+        process.env.NODE_ENV === "development"
+            ? prettyLogFormatter
+            : jsonLogFormatter,
+    useConsoleColors: process.env.NODE_ENV === "development",
 });
 ```
 
 :::
 
-## Advanced Setup
+## Usage
+
+The logger can be accessed via the `getLogger` function.
+The logger is a singleton and will return the same instance every time it is called.
 
-In case you want to configure the logger in another way you can use the `setup` function from the `@std/log` library. And add `Nimbus` to the loggers object.
+To create a new log you can use the `info`, `warn`, `error` or `critical` methods depending on the severity of the message.
 
-View the [@std/log docs](https://jsr.io/@std/log) for all configuration options.
+The log input is an object that can contain the following properties:
+
+-   `message` - The message to log.
+-   `correlationId` - An optional correlation ID to keep track of commands, queries, and events that are related to each other.
+-   `category` - An optional category of the log, useful for grouping logs together.
+-   `data` - Optional additional data to log, can be an object with any properties.
+-   `error` - Optional error object to log.
+
+The error object is specified as a dedicated property and not as part of the `data` object to make sure all error properties and the stack trace are preserved and logged correctly.
 
 ::: code-group
 
-```typescript [main.ts]
-import * as log from "@std/log";
+```typescript [logExample.ts]
+import { getLogger } from "@nimbus/core";
 
-log.setup({
-    handlers: {
-        default: new log.ConsoleHandler("INFO", {
-            formatter: log.formatters.jsonFormatter,
-        }),
-    },
+const logger = getLogger();
+
+logger.debug({
+    message: "Hello World!",
+    correlationId: "1234567890",
+    data: { foo: "bar" },
+});
+
+logger.info({ message: "Hello World!" });
+
+logger.warn({
+    category: "MyCategory",
+    message: "Ding Dong!",
+});
+
+logger.error({
+    message: "Ohh no!",
+    error: new Error("Something went wrong!"),
+});
 
-    loggers: {
-        Nimbus: {
-            level: "INFO",
-            handlers: ["default"],
-        },
+logger.critical({
+    category: "MyCategory",
+    message: "It is over, run!",
+    error: new Error("Something is burning!"),
+    data: {
+        accountId: "1234567890",
+        foo: "bar",
     },
 });
 ```
 
 :::
+
+## Nimbus Logs
+
+As the various Nimbus features have implemented log statements as well it uses the same logger provided by the `getLogger()` function.
+
+Therefore all log statements from Nimbus will respect the log level and formatter you have configured for the application.
+
+In case you do not configure the logger in your application the Nimbus logs will use the default settings.
+
+## Default Settings
+
+```typescript
+const defaultSettings = {
+    logLevel: "silent",
+    formatter: jsonLogFormatter,
+    useConsoleColors: false,
+};
+```

docs/guide/core/logging.md

@@ -6,8 +6,7 @@ To get started with Nimbus you need to install the [@nimbus/core](https://jsr.io
 
 Nimbus tries to keep dependencies as low as possible, but there are some packages that are necessary to run Nimbus.
 
-For type validations Nimbus relies on [Zod](https://zod.dev/).  
-And for logging the [@std/log](https://jsr.io/@std/log) package is used.
+For type safety at runtime Nimbus relies on [Zod](https://zod.dev/).
 
 ## Installation
 
@@ -16,19 +15,19 @@ Depending on your runtime you can install Nimbus with the following commands.
 ### Deno
 
 ```bash
-deno add jsr:@nimbus/core npm:zod jsr:@std/log
+deno add jsr:@nimbus/core npm:zod
 ```
 
 ### NPM
 
 ```bash
 npm install zod
-npx jsr add @nimbus/core @std/log
+npx jsr add @nimbus/core
 ```
 
 ### Bun
 
 ```bash
 bun add zod
-bunx jsr add @nimbus/core @std/log
+bunx jsr add @nimbus/core
 ```

docs/guide/quickstart.md

@@ -1,6 +1,7 @@
 {
   "tasks": {
     "dev": "deno run -A --watch src/main.ts",
+    "dev:otel": "sh start-with-otel.sh",
     "test": "deno test -A",
     "database:seed": "deno run -A src/seedCollections.ts"
   },
@@ -28,7 +29,6 @@
   },
   "imports": {
     "@oak/oak": "jsr:@oak/oak@^17.1.4",
-    "@std/log": "jsr:@std/log@^0.224.13",
     "@tajpouria/cors": "jsr:@tajpouria/cors@^1.2.1",
     "mongodb": "npm:mongodb@^6.12.0",
     "zod": "npm:zod@^3.24.1"

examples/the-expense/deno.json

@@ -1,5 +1,4 @@
-import { RouteHandler } from '@nimbus/core';
-import * as log from '@std/log';
+import { getLogger, RouteHandler } from '@nimbus/core';
 import {
     AccountAddedData,
     AccountAddedEvent,
@@ -13,7 +12,9 @@ export const accountAddedHandler: RouteHandler<
 ) => {
     await new Promise((resolve) => setTimeout(resolve, 1000));
 
-    log.info({ msg: `New account was added: ${event.data.account.name}` });
+    getLogger().info({
+        message: `New account was added: ${event.data.account.name}`,
+    });
 
     return {
         statusCode: 200,

examples/the-expense/src/account/shell/events/accountAdded.handler.ts

@@ -1,7 +1,6 @@
-import { AuthContext } from '@nimbus/core';
+import { AuthContext, getLogger } from '@nimbus/core';
 import type { Context } from '@oak/oak/context';
 import type { Next } from '@oak/oak/middleware';
-import * as log from '@std/log';
 
 /**
  * ! NOT FOR PRODUCTION USE
@@ -39,8 +38,11 @@ export const exampleAuthMiddleware = async (
             }
 
             await next();
-        } catch (error) {
-            log.error(error);
+        } catch (error: any) {
+            getLogger().error({
+                message: 'Failed to authenticate user',
+                error,
+            });
 
             ctx.response.status = 401;
             ctx.response.body = {