@bothive/session-logger/README.md

Pino session logger

# Session logger

Session logger is a logging package wrapt around the popular Pino logger to help you trace your logs through a session.

**Version:** 0.1.0

## Start

When you app starts you need to register the Session logger before you can use it

```
import { SessionLogger, ELogLevel } from "@bothive/session-logger";

SessionLogger.register({
    environment: "development",
    logLevel: ELogLevel.info,
    enableTraceId: true,
    prettyPrint: true,
    masking: true,
});
```

After this you can use the logger through out your app like this

```
import logger from "@bothive/session-logger";

logger().error("log error", { meta: "meta information" })
```

## HttpMiddleware

One of the main purposes of this package is the ease to use it to trace logs in an http session

```
import logger, { SessionLogger } from "@bothive/session-logger";
...

app.use(SessionLogger.HttpMiddleware);

app.get('/', (req, res, next) => {
   logger().info('Trace ID logging included', { context: 'MyApp' });

    next();
});
...
```

if the request headers contains `x-request-id` and/or `x-session-id` these id's will be used in the logs

**Outputs:**

```
[2021-07-16 16:53:12] INFO: [MyApp]: Trace ID logging included
    environment: "development"
    traceId: "JBzNjRQTghKNrTuqMxbUeSE51"
    session: "F5vnJm7sj65AGhPGhKgRBiSpy"
    context: "MyApp",
```

## EventMiddleware

One of the main purposes of this package is the ease to use it to trace logs in an event based service

```
import logger, { SessionLogger } from "@bothive/session-logger";
...

function callback(event) {
   logger().info('Trace ID logging included', { meta: "meta information" });
}

kafka
    .getTopicSubject({ topic: topicName, loadBalanced: true })
    .subscribe((event) => SessionLogger.EventMiddleware(event, callback));
...
```

if the event contains an headers object with `traceId` and/or `sessionId` these id's will be used in the logs

**example event**

```
{
    "headers": {
        "context": "get user",
        "traceId": "JBzNjRQTghKNrTuqMxbUeSE51",
        "sessionId": "F5vnJm7sj65AGhPGhKgRBiSpy",
    },
    ...
}
```

**Outputs:**

```
[2021-07-16 16:53:12] INFO: [get user]: Trace ID logging included
    environment: "development"
    traceId: "JBzNjRQTghKNrTuqMxbUeSE51"
    session: "F5vnJm7sj65AGhPGhKgRBiSpy"
   {  meta: "meta information" }
```

### Config

| name          | type      | default                                        |
| ------------- | --------- | ---------------------------------------------- |
| environment   | String    | ENVIRONMENT NOT SET                            |
| logLevel      | ELogLevel | silent, trace, debug, info, warn, error, fatal |
| enableTraceId | Boolean   | false                                          |
| masking       | Boolean   | false                                          |
| prettyPrint   | Boolean   | true                                           |

#### Environment

Define which environment should be shown in the logs

#### Log level

The `logLevel` setting can contain one of the values below:

```
type LogLevel =
    | 'silent'
    | 'trace'
    | 'debug'
    | 'info'
    | 'warn'
    | 'error'
    | 'fatal';
```

When you set a log level, only the logs with a more serious log level are displayed. For example, setting `warn` will only display the logs with levels `warn`, `error` and `fatal`.

The log levels `trace`, `debug` or `info` are commonly used for development environments.
The log level `warn` is mostly used for production environments.

#### Masking

To redact/remove sensitive information from the logs you can set the `masking` setting to `true`.

Currently these nested properties will be removed from the logs:

```
[
    '*.password',
    '*.newPassword',
    '*.oldPassword',
    '*.accessToken',
    '*.refreshToken',
    '*.token',
    '*.jwtToken',
    '*.apiKey',
]
```

#### Pretty print

When turned on, pretty, multi-line logs will be output. When turned off, one-line stringified JSON will be output.
Advised to turn this off in staging or production environments.

## Definition

| name      | description                                                                                                                                                                                                       |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| context   | context can be used to trace a specific action through multiple logs, sessions and traces. for example when you fetch a user account, context can be *get user* so you can find all logs related to fetching a user  |
| sessionId | An id used to trace multiple event / http call's for example in the frontend you create a user session that uses this id until user ends the session to trace back all logs this user logged during their session |
| traceId   | An id used to trace an event / http call from start to finish              

## Contribution guidelines

Follow the Bothive code and review guidelines

## Who do I talk to?

### Repo owner or admin

-   [Thuur vandeplassche](mailto:thuur.vandeplassche@bothive.be)