logging.md

Logging

The software system is built with logging and observability in mind. This applies to all services. Frontend logs are captured by running a dedicated service for logging and tracking.

Each log event will capture the following information if available:

• Log level
• Request correlation id
• Request id
• User id

Exceptions are logged with a unique exception id to help tracking down and pinning errors.

Logging SDK

The application (mainly the api service) should output logs in JSON format to stdout/stderr. This is done via the Pino library. Documentation for the different used libraries are found here

• Fastify
• NestJS
• TypeORM docs

Infrastructure

Logging aggregation

Log aggregation is handled by Loki which is handled by Grafana cloud. Logs are shipped there using the Loki docker plugin.

Log level guidelines

This project use the following log levels:

• Trace: The lowest log level, reserved for extremely detailed information aiding in debugging or tracing program flow. Use trace messages sparingly to avoid generating a large volume of logs. Examples include tracking function entry and exit points or logging variable values during critical operations.
• Debug: Debug-level logs provide specific information helpful for debugging and diagnosing issues during development. Log events, conditions, or variable values to assist in identifying and resolving problems. Debug logs are typically disabled in production environments.
• Info: Info-level logs offer general information about the application's progress and important milestones. Use them to track overall execution flow and significant events. Capture important state changes, initialization messages, or the start and completion of significant operations.
• Warn: Warn-level logs indicate potentially harmful situations or conditions that may not lead to errors or failures but require attention. Identify issues that can impact application performance or behavior. For instance, report deprecated API usage or configuration settings deviating from recommended values.
• Error: Error-level logs represent actual errors or exceptions encountered during software execution. Log problems preventing the application from functioning as intended or resulting in incorrect results. Provide sufficient information to understand the cause and context of errors, facilitating diagnosis and resolution.
• Fatal: Fatal-level logs denote critical errors leading to an unrecoverable state or application termination. Use them for severe failures impacting system stability or data integrity. Log fatal events just before the application exits or shuts down abruptly.

Guide

Backend

The logger can be utilized as shown in the example below. Notice that there should always be a msg field with a message describing the loggedevent.

import { Injectable } from "@nestjs/common";

import { Logger } from "src/core/logging";

@Injectable()
export class MonkeyService {
  private logger = new Logger(CommandLogger.name);

  pingMonkey(name: string) {
    this.logger.debug("Monkey was pinged", {
      name,
    });
  }
}

Frontend

Logging is handled similarly in the frontend as in the backend. Events that are logged in the frontend are shipped to the system tracking service and can be queried in the same manner as other logs.

import React from "react";

import { useLogger } from "src/core/logging";

export function MonkeyComponent(): React.ReactElement {
  const logger = useLogger(MonkeyComponent.name);

  function handleClick(): void {
    logger.debug("I was clicked");
  }

  return <span onClick={handleClick}>Click me!</span>;
}