birch/erlang_logger

Erlang :logger integration for birch.

This module provides optional integration with Erlang’s built-in :logger system, allowing birch to:

Forward to :logger: Create a handler that sends birch records to Erlang’s :logger system (useful for integrating with OTP applications)
Receive from :logger: Install birch as an Erlang :logger handler to receive logs from OTP applications and process them with birch handlers

Note: These features are only available on the Erlang target. On JavaScript, the functions will return errors indicating the feature is unavailable.

Example: Forward logs to Erlang :logger

import birch as log
import birch/erlang_logger

pub fn main() {
  // Configure birch to forward to Erlang's :logger
  log.configure([
    log.config_handlers([erlang_logger.forward_to_logger()]),
  ])

  // Logs will now go to Erlang's :logger system
  log.info("Hello from Gleam!")
}

Example: Receive logs from OTP applications

import birch/erlang_logger

pub fn main() {
  // Install birch as an Erlang :logger handler
  case erlang_logger.install_logger_handler() {
    Ok(Nil) -> {
      // Logs from OTP applications will now be processed by birch
    }
    Error(reason) -> {
      // Handle error (e.g., on JavaScript target)
    }
  }
}

Types

ErlangLevel

</>

Erlang :logger log levels.

Erlang uses syslog-style levels which are more granular than birch levels. These are mapped to/from birch levels as follows:

Erlang Level	Gleam Level
emergency	Fatal
alert	Fatal
critical	Fatal
error	Err
warning	Warn
notice	Info
info	Info
debug	Debug/Trace

pub type ErlangLevel {
  ErlangEmergency
  ErlangAlert
  ErlangCritical
  ErlangError
  ErlangWarning
  ErlangNotice
  ErlangInfo
  ErlangDebug
}

Constructors

```
ErlangEmergency
```
```
ErlangAlert
```
```
ErlangCritical
```
```
ErlangError
```
```
ErlangWarning
```
```
ErlangNotice
```
```
ErlangInfo
```
```
ErlangDebug
```

Values

default_handler_id

</>

pub const default_handler_id: String

Default handler ID used when installing birch as a :logger handler.

erlang_level_to_atom

</>

pub fn erlang_level_to_atom(erlang_level: ErlangLevel) -> String

Convert an Erlang level to its atom representation (for FFI).

erlang_level_to_gleam

</>

pub fn erlang_level_to_gleam(
  erlang_level: ErlangLevel,
) -> level.Level

Convert an Erlang :logger level to a Gleam log level.

forward_to_logger

</>

pub fn forward_to_logger() -> handler.Handler

Create a handler that forwards birch records to Erlang’s :logger system.

This allows birch to integrate with existing OTP logging infrastructure, including any :logger handlers already configured (default handler, file handlers, etc.).

On JavaScript, this creates a handler that writes to console instead, since :logger is not available.

Example

import birch as log
import birch/erlang_logger
import birch/handler/console

pub fn main() {
  // Use both console and :logger output
  log.configure([
    log.config_handlers([
      console.handler(),
      erlang_logger.forward_to_logger(),
    ]),
  ])
}

forward_to_logger_raw

</>

pub fn forward_to_logger_raw() -> handler.Handler

Create a handler that forwards birch records to :logger with proper level mapping (not just the formatted message).

This handler passes the full LogRecord to :logger, preserving the log level and metadata. Use this when you want :logger to receive structured log data.

forward_to_logger_with_formatter

</>

pub fn forward_to_logger_with_formatter(
  format: fn(record.LogRecord) -> String,
) -> handler.Handler

Create a handler that forwards to :logger with a custom formatter.

gleam_level_to_erlang

</>

pub fn gleam_level_to_erlang(
  gleam_level: level.Level,
) -> ErlangLevel

Convert a Gleam log level to an Erlang :logger level.

install_logger_handler

</>

pub fn install_logger_handler() -> Result(Nil, String)

Install birch as an Erlang :logger handler.

Once installed, logs from OTP applications (and Erlang code using :logger) will be processed by birch’s configured handlers.

Returns Ok(Nil) on success, or Error(reason) if installation fails. On JavaScript, always returns Error("erlang:logger is not available on JavaScript target").

Example

import birch/erlang_logger

pub fn main() {
  case erlang_logger.install_logger_handler() {
    Ok(Nil) -> io.println("Installed birch as :logger handler")
    Error(reason) -> io.println("Failed: " <> reason)
  }
}

install_logger_handler_with_id

</>

pub fn install_logger_handler_with_id(
  handler_id: String,
) -> Result(Nil, String)

Install birch as an Erlang :logger handler with a custom handler ID.

This is useful if you want to install multiple instances or avoid conflicts with other handlers.

uninstall_logger_handler

</>

pub fn uninstall_logger_handler() -> Result(Nil, String)

Uninstall the birch :logger handler.

Removes the handler installed by install_logger_handler(). Returns Ok(Nil) on success, or Error(reason) if removal fails.

uninstall_logger_handler_with_id

</>

pub fn uninstall_logger_handler_with_id(
  handler_id: String,
) -> Result(Nil, String)

Uninstall a birch :logger handler with a specific ID.