birch/handler

Handler interface for log output destinations.

Handlers receive log records and write them to various destinations (console, files, external services, etc.).

Types

ErrorCallback

Callback function invoked when a handler encounters an error.

pub type ErrorCallback =
  fn(HandlerError) -> Nil

Handler

opaque </>

A handler that processes log records.

pub opaque type Handler

HandlerError

</>

Error details passed to error callbacks when a handler fails.

pub type HandlerError {
  HandlerError(
    handler_name: String,
    error: String,
    record: record.LogRecord,
  )
}

Constructors

```
HandlerError(
  handler_name: String,
  error: String,
  record: record.LogRecord,
)
```
Arguments

handler_name

Name of the handler that failed

error

Error message describing what went wrong

record

The log record that was being processed when the error occurred

OutputTarget

</>

Output target for console handlers.

pub type OutputTarget {
  Stdout
  Stderr
}

Constructors

```
Stdout
```
Write to standard output
```
Stderr
```
Write to standard error

Values

get_error_callback

</>

pub fn get_error_callback(
  handler: Handler,
) -> option.Option(fn(HandlerError) -> Nil)

Get the error callback from a handler, if one is set.

handle

</>

pub fn handle(handler: Handler, record: record.LogRecord) -> Nil

Write a log record to a handler.

If the handler has an error callback attached and the write fails, the error callback will be invoked with details about the failure. Handler failures never crash the application.

handle_all

</>

pub fn handle_all(
  handlers: List(Handler),
  record: record.LogRecord,
) -> Nil

Write a log record to multiple handlers.

name

</>

pub fn name(handler: Handler) -> String

Get the name of a handler.

new

</>

pub fn new(
  name name: String,
  write write: fn(String) -> Nil,
  format format: fn(record.LogRecord) -> String,
) -> Handler

Create a new handler with a custom write function.

new_with_record_write

</>

pub fn new_with_record_write(
  name name: String,
  write write: fn(record.LogRecord) -> Nil,
) -> Handler

Create a handler with a raw write function that receives the full LogRecord. This is used by async handlers that need access to the full record.

null

</>

pub fn null() -> Handler

Create a null handler that discards all logs. Useful for testing or explicitly disabling logging.

should_handle

</>

pub fn should_handle(
  handler: Handler,
  record_level: level.Level,
) -> Bool

Check if a handler should process a log record at the given level.

with_error_callback

</>

pub fn with_error_callback(
  handler: Handler,
  callback: fn(HandlerError) -> Nil,
) -> Handler

Attach an error callback to a handler.

The callback will be invoked when the handler encounters an error during write operations. This allows for monitoring and alerting on handler failures without crashing the application.

Example:

let handler =
  console.handler()
  |> handler.with_error_callback(fn(err) {
    io.println("Handler failed: " <> err.error)
  })

with_min_level

</>

pub fn with_min_level(
  handler: Handler,
  level: level.Level,
) -> Handler

Create a handler with a minimum level filter.

Constructors

Arguments

Constructors