Log v0.1.0

Installation

Add Log to the [Dependencies] table of your package's Rux.toml:

[Dependencies]
Log = { Namespace = "Rux", Version = "0.1.0" }

Standard packages are declared by hand: the registry does not serve them, so rux add Rux/Log cannot add them.

Dependencies

• Allocator 0.1.0
• Core 0.1.0
• FileSystem 0.1.0
• Format 0.1.0
• Io 0.1.0
• Path 0.1.0
• Sync 0.1.0
• Text 0.1.0
• Time 0.1.0

Guide

Structured logging: levels, typed fields, one line of text or JSON per record, a process-wide log that every thread can write to, and log files that rotate by size.

What it provides

The module names describe where each declaration comes from; they are not part of an import path.

Example

import Log::{ Field, Info, LogFormat, SetFormat, Warn };

func Serve(port: uint64) {
    SetFormat(LogFormat::JsonLines);
    Info("listening", [Field::Unsigned("port", port)]);
    Warn("no certificate configured");
}

Design

A record has a level, a message, and fields whose values keep their types. As text it is one line: the time, the level, the message, then key=value for each field, with a value that holds spaces, quotes or = in quotes. As JSON lines it is one object per line, with time, level and message members followed by the fields, and a number that is not finite written as null. Line breaks and other control characters are escaped in both formats, so a record never spans lines. Times are RFC 3339 in UTC to the millisecond. They can be turned off for a destination that adds its own, such as a service manager's journal.

Each record is built whole and handed to its destination in a single write. The process-wide functions write to standard error. Their level, format and time settings are read and written atomically, and a lock is held only for the write of a finished record, so threads build records at the same time and their lines never interleave. A Logger writes to any Io::Writer, such as a file or a socket, and is used by one thread at a time. Logging never fails: a Logger keeps the first failure to write for Failure to report, and the process-wide log drops a record it cannot write.

A RotatingFile is a Writer over a path that keeps a log from growing without end. Before a write would take the current file past its limit, the file is renamed to path.1, after an older path.1 becomes path.2 and so on up to the number of older files kept, and an empty file takes its place. Rotation happens only between writes, and a Logger writes each record in one call, so no record is ever split across two files; a record larger than the limit gets a file of its own. Hand one to a Logger with (@file).Stream(), keeping the file in place while the logger uses it.

The LogLevel build define sets the least severe level a build keeps: trace, debug, info, warn or error. A record below it is dropped before any of it is built, whatever level a logger is set to. So a release build defined with LogLevel = "info" does no tracing work, while the process-wide level, which starts at Info, and each logger's own level are changed at run time.

Index

Types

Functions