# Getting started

# Install the package

First, open a terminal at the root of the application and install the following package:

pnpm add @workleap/logging

# Write console logs

A logger can output log entries with different levels (debug, information, warning, error, critical). This allows to filter logs according to a minimum severity:

import { BrowserConsoleLogger, LogLevel } from "@workleap/logging";

const logger = new BrowserConsoleLogger({
    logLevel: LogLevel.error
});

In the previous example, the logger instance would process only error and critical entries ☝️

# Basic text logs

The simplest form is logging plain text directly at the desired level:

import { BrowserConsoleLogger } from "@workleap/logging";

const logger = new BrowserConsoleLogger();

logger.debug("Application started!");

# Complex logs

Segments can be chained to build richer log entries that include text, errors and objects:

import { BrowserConsoleLogger } from "@workleap/logging";

const logger = new BrowserConsoleLogger();

logger
    .withText("Failed to process order")
    .withObject({ orderId: 12345 })
    .withError(new Error("Payment declined"))
    .error();

# Styled logs

When using a logger that supports styling, individual text segments can be styled:

import { BrowserConsoleLogger } from "@workleap/logging";

const logger = new BrowserConsoleLogger();

logger
    .withText("Build completed", {
        style: {
            color: "green",
            fontWeight: "bold"
        }
    })
    .withText("in")
    .withText("250ms", { 
        style: {
            color: "gray"
        } 
    })
    .information();

If styling is not supported by the logger, the text is logged without any styling.

When styling is applied to any text segment, all error or object segments are appended at the end of the log entry.

# Create a logging scope

Scopes group related log entries under a shared label or context. This is useful for tracing operations, request or correlating events:

import { BrowserConsoleLogger } from "@workleap/logging";

const logger = new BrowserConsoleLogger();
const scope = logger.startScope("User signup");

scope.information("Form loaded");
scope.debug("User entered email");

scope.
    .withText("Failed to create account")
    .withError(new Error("Email is already used."))
    .error();

scope.end();

# LogRocket session replays

By default, LogRocket session replays exclude console output. To send log entries to LogRocket, use the LogRocketLogger class from the @workleap/logrocket:

import { LogRocketLogger } from "@workleap/logrocket";

const logger = new LogRocketLogger();

logger.debug("Application started!");

# Compose loggers

You can forward the same log entry to multiple destinations by composing loggers:

import { BrowserConsoleLogger, CompositeLogger } from "@workleap/logging";
import { LogRocketLogger } from "@workleap/logrocket";

const logger = new CompositeLogger([
    new BrowserConsoleLogger(),
    new LogRocketLogger()
]);

logger.debug("Application started!");

In the previous example, Application started! will be processed by both logger instances ☝️

# Filter log entries

A minimum severity of entries to process can be configured as an option. Messages with a lower severity than the configured level will then be ignored.

import { BrowserConsoleLogger, LogLevel } from "@workleap/logging";

const logger = new BrowserConsoleLogger({
    logLevel: LogLevel.error
});

// Will be ignored because "debug" is lower than the "error" severity.
logger.debug("Hello world!");

For reference, here's a description of each level:

# Debug

Very detailed, often verbose, logs used mainly during development.
Example: API request/response bodies, lifecycle hooks, variable state.

# Information

General events that show the normal flow of the application.
Example: User login, component mounted, scheduled task started.

# Warning

Non-critical issues that might need attention but don’t break functionality.
Example: Deprecated API usage, retries after a failed network call.

# Error

Failures that prevent part of the system from working as intended.
Example: Unhandled exceptions, failed database query, API call failed with 500.

# Critical

Severe errors that cause the application to stop functioning or risk data integrity.
Example: Application crash, loss of critical service connection.