logging

Modern structured logging for Kit with JSON, pretty, and compact formats

Files

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-logging.git

Usage

import Kit.Logging

License

MIT License - see LICENSE for details.

Exported Functions & Types

ConsoleLogger

Console logger type.

Logs messages to stdout or stderr with configurable level filtering and output formatting. Wraps a configuration record.

The config record contains: level: Minimum log level threshold (Debug, Info, Warn, Error) format: Output format (JsonFmt, PrettyFmt, CompactFmt) output: Output target (ToStdout, ToStderr) context: Context fields included in all log entries

console-logger

Create a console logger with the given configuration.

Parameters:

• config - Logger configuration record with fields:
• - level - Minimum log level (Debug, Info, Warn, Error)
• - format - Output format (JsonFmt, PrettyFmt, CompactFmt)
• - output - Output target (ToStdout, ToStderr)
• - context - Context fields for all log entries

Returns: A ConsoleLogger instance

Config -> ConsoleLogger Config

config = {level: Info, format: JsonFmt, output: ToStderr, context: {service: "api"}}
logger = console-logger config

with-context

Create a console logger with additional context.

Returns a new ConsoleLogger with the provided context merged.

Parameters:

• logger - Existing ConsoleLogger
• new-context - Additional context fields to add

Returns: A new ConsoleLogger with merged context

ConsoleLogger a -> Record -> ConsoleLogger Record

base = console-logger default-config
request-logger = with-context base {request-id: "abc-123"}

event

Create a new request-scoped event with initial fields.

Initializes an event builder that accumulates context throughout a request lifecycle. The event starts with the provided initial fields and can be enriched with additional context before emission.

Parameters:

• initial-fields - Record - Initial fields to include in the event
• Common fields - trace-id, request-id, method, path, user-id

Returns: Event record that can be enriched and emitted

Record -> Record

event = Logging.event {
  trace-id: "xyz-789",
  method: "POST",
  path: "/api/orders"
}

event-with-config

Create an event with custom configuration.

Like event but allows specifying log level, format, and output target.

Parameters:

• config - Record with level, format, output fields
• initial-fields - Record - Initial fields to include

Returns: Configured event record

Record -> Record -> Record

event = Logging.event-with-config {level: Debug, format: PrettyFmt, output: ToStderr} {
  trace-id: "abc-123"
}

add-field

Add a single field to the event.

Enriches the event with additional context. Fields are accumulated and included in the final log entry when emitted.

Parameters:

• evt - Event - The event to enrich
• key - String - Field name
• value - Any - Field value

Returns: Updated event with the new field

Record -> String -> a -> Record

event = event |> Logging.add-field "user-id" 42
event = event |> Logging.add-field "cache-hit" true

add-fields

Add multiple fields to the event at once.

Merges a record of fields into the event. Useful for adding related context in a single operation.

Parameters:

• evt - Event - The event to enrich
• new-fields - Record - Fields to add

Returns: Updated event with merged fields

Record -> Record -> Record

event = event |> Logging.add-fields {
  user-id: 42,
  account-type: "premium",
  region: "us-west"
}

add-timing

Add a timing measurement to the event.

Records a duration for a named operation. Timings are stored separately and included in the final log entry under a "timings" key.

Parameters:

• evt - Event - The event to enrich
• name - String - Name of the timed operation (e.g., "db-query-ms")
• duration-ms - Number - Duration in milliseconds

Returns: Updated event with the timing recorded

Record -> String -> Int -> Record

start = Time.now
result = db.query "SELECT * FROM users"
duration = Time.now - start
event = event |> Logging.add-timing "db-query-ms" duration

with-request

Add request metadata to the event.

Convenience function for adding common request fields.

Parameters:

• evt - Event - The event to enrich
• request - Record - Request metadata with id, method, path, etc.

Returns: Updated event with request context

Record -> Record -> Record

event = event |> Logging.with-request {
  id: "req-123",
  method: "POST",
  path: "/api/orders",
  ip: "192.168.1.1"
}

with-user

Add user context to the event.

Convenience function for adding user-related fields. Useful for debugging user-specific issues.

Parameters:

• evt - Event - The event to enrich
• user - Record - User context with id, role, tier, etc.

Returns: Updated event with user context

Record -> Record -> Record

event = event |> Logging.with-user {
  id: 42,
  role: "admin",
  tier: "enterprise",
  org-id: "org-789"
}

with-error

Add error context to the event.

Convenience function for recording error information. Automatically sets the event level to Error.

Parameters:

• evt - Event - The event to enrich
• err - Record - Error details with message, code, stack, etc.

Returns: Updated event with error context and Error level

Record -> Record -> Record

event = event |> Logging.with-error {
  message: "Connection refused",
  code: "ECONNREFUSED",
  retriable: true
}

set-level

Set the log level for this event.

Override the default Info level for this event.

Parameters:

• evt - Event - The event to modify
• level - Level - New log level (Debug, Info, Warn, Error)

Returns: Updated event with new level

Record -> Level -> Record

event = event |> Logging.set-level Logging.Warn

emit-event

Emit the event as a single log entry.

Finalizes the event by calculating total duration, merging all accumulated fields and timings, and outputting a single structured log entry. This is the "canonical log line" that captures the complete context of the request.

Parameters:

• evt - Event - The accumulated event
• message - String - Summary message for the log entry
• final-fields - Record - Additional fields to include (e.g., status, result)

Returns: Unit (performs side effect of logging)

Record -> String -> Record -> Unit

event |> Logging.emit-event "Request completed" {
  status: 200,
  response-size: 1024
}

emit-info

Emit the event with Info level.

Convenience function that emits the event at Info level.

Parameters:

• evt - Event - The accumulated event
• message - String - Summary message
• final-fields - Record - Additional fields

Returns: Unit

Record -> String -> Record -> Unit

event |> Logging.emit-info "Request successful" {status: 200}

emit-error

Emit the event with Error level.

Convenience function that emits the event at Error level.

Parameters:

• evt - Event - The accumulated event
• message - String - Summary message
• final-fields - Record - Additional fields

Returns: Unit

Record -> String -> Record -> Unit

event |> Logging.emit-error "Request failed" {status: 500, error: "Internal error"}

emit-warn

Emit the event with Warn level.

Convenience function that emits the event at Warn level.

Parameters:

• evt - Event - The accumulated event
• message - String - Summary message
• final-fields - Record - Additional fields

Returns: Unit

Record -> String -> Record -> Unit

event |> Logging.emit-warn "Request slow" {status: 200, threshold-exceeded: true}

timed

Time an operation and add the duration to the event.

Executes a function, measures its duration, and adds the timing to the event under the specified name.

Parameters:

• evt - Event - The event to enrich
• name - String - Name for the timing (e.g., "db-query-ms")
• operation - Function - Zero-argument function to time

Returns: Tuple of (updated-event, operation-result)

Record -> String -> (Unit -> a) -> (Record, a)

(event, users) = Logging.timed evt "db-query-ms" (fn() => db.query "SELECT * FROM users")

emit

Emit a log entry with given configuration.

Performs level filtering, adds timestamps, merges context, formats the entry, and writes to the configured output. This is the core logging function that powers all log methods.

Parameters:

• - level - Minimum log level to emit
• - format - Output format (JsonFmt, PrettyFmt, CompactFmt)
• - output - Output target (ToStdout, ToStderr)
• - context - Context fields to include in all logs

Returns:

Config -> Entry -> Unit

config = {level: Info, format: PrettyFmt, output: ToStdout, context: {}}
emit-fn = emit config
emit-fn {level: Info, message: "Hello", fields: {}, context: {}}

make-logger

Create a logger with given configuration.

Constructs a logger instance with methods for each log level (debug, info, warn, error) and a with-context method for creating child loggers.

Parameters:

• - level - Minimum log level (Debug, Info, Warn, Error)
• - format - Output format (JsonFmt, PrettyFmt, CompactFmt)
• - output - Output target (ToStdout, ToStderr)
• - context - Context fields to include in all logs

Returns:

Config -> Record

config = {level: Info, format: PrettyFmt, output: ToStdout, context: {service: "api"}}
log = make-logger config
log.info "Started" {}
child = log.with-context {request_id: "123"}
child.info "Processing" {duration: 42}

with-level

Set the minimum log level for a configuration.

Parameters:

Returns:

Config -> Level -> Config

config = default-config |> with-level Info

with-format

Set the output format for a configuration.

Parameters:

Returns:

Config -> Format -> Config

config = default-config |> with-format JsonFmt

with-output

Set the output target for a configuration.

Parameters:

Returns:

Config -> Output -> Config

config = default-config |> with-output ToStderr

with-context

Set the context fields for a configuration.

Parameters:

Returns:

Config -> Record -> Config

config = default-config |> with-context {service: "api", version: "1.0"}

FileLogger

File logger type.

Logs messages by appending to a file with configurable level filtering and output formatting. Wraps a configuration record.

The config record contains: path: File path to append logs to level: Minimum log level threshold (Debug, Info, Warn, Error) format: Output format (JsonFmt, PrettyFmt, CompactFmt) context: Context fields included in all log entries

file-logger

Create a file logger with the given configuration.

Parameters:

• config - Logger configuration record with fields:
• - path - File path to append logs to
• - level - Minimum log level (Debug, Info, Warn, Error)
• - format - Output format (JsonFmt, PrettyFmt, CompactFmt)
• - context - Context fields for all log entries

Returns: A FileLogger instance

Record -> FileLogger Record

config = {path: "/var/log/app.log", level: Info, format: JsonFmt, context: {}}
logger = file-logger config

default-file-config

Default file logger configuration.

Returns: {path: "app.log", level: Info, format: JsonFmt, context: {}}

Record

with-context

Create a file logger with additional context.

Returns a new FileLogger with the provided context.

Parameters:

• logger - Existing FileLogger
• new-context - Additional context fields to add

Returns: A new FileLogger with the new context

FileLogger a -> Record -> FileLogger Record

base = file-logger default-file-config
request-logger = with-context base {request-id: "abc-123"}

Debug

Debug log level - Most verbose, for detailed diagnostic information.

Level

Info

Info log level - Normal informational messages about application progress.

Level

Warn

Warn log level - Warning messages for potentially harmful situations.

Level

Error

Error log level - Error messages for serious problems.

Level

JsonFmt

JSON format - Single-line JSON output for log aggregation systems.

Format

PrettyFmt

Pretty format - Colored, human-readable output for development.

Format

CompactFmt

Compact format - Minimal, uncolored output for space efficiency.

Format

ToStdout

Output to stdout - Write logs to standard output stream.

Output

ToStderr

Output to stderr - Write logs to standard error stream.

Output

ConsoleLogger

ConsoleLogger type - Logs to stdout/stderr.

ConsoleLogger a

FileLogger

FileLogger type - Appends logs to a file.

FileLogger a

NoOpLogger

NoOpLogger type - Discards all log messages.

NoOpLogger

console-logger

Create a console logger with the given configuration.

Parameters:

Returns:

Config -> ConsoleLogger Config

console = console-logger default-config
log-info console "Server started" {port: 8080}

file-logger

Create a file logger with the given configuration.

Parameters:

Returns:

Record -> FileLogger Record

file = file-logger {path: "app.log", level: Info, format: JsonFmt, context: {}}
log-info file "Event occurred" {user: 42}

default-file-config

Default file logger configuration.

Returns:

Record

no-op-logger

Create a no-op logger that discards all messages.

Returns:

Unit -> NoOpLogger

noop = no-op-logger()
log-info noop "This is discarded" {}  # No output

logger

Create a logger with given configuration.

Parameters:

• - level - Minimum log level (Debug, Info, Warn, Error)
• - format - Output format (JsonFmt, PrettyFmt, CompactFmt)
• - output - Output target (ToStdout, ToStderr)
• - context - Context fields to include in all logs

Returns:

Config -> Record

config = {level: Info, format: JsonFmt, output: ToStderr, context: {service: "api"}}
log = logger config
log.info "Request received" {path: "/users"}

default

Create logger with default configuration.

Returns:

Record

log = default
log.debug "Debugging info" {}

default-config

Default logger configuration.

Returns:

Config

with-level

Set the minimum log level for a configuration.

Parameters:

Returns:

Config -> Level -> Config

config = default-config |> with-level Info

with-format

Set the output format for a configuration.

Parameters:

Returns:

Config -> Format -> Config

config = default-config |> with-format JsonFmt

with-output

Set the output target for a configuration.

Parameters:

Returns:

Config -> Output -> Config

config = default-config |> with-output ToStderr

with-context

Set the context fields for a configuration.

Parameters:

Returns:

Config -> Record -> Config

config = default-config |> with-context {service: "api", version: "1.0"}

debug

Log a debug message with optional fields.

Parameters:

Returns:

String -> Record -> Unit

debug "Variable value" {x: 42, y: 100}

info

Log an info message with optional fields.

Parameters:

Returns:

String -> Record -> Unit

info "Server started" {port: 8080, env: "production"}

warn

Log a warning message with optional fields.

Parameters:

Returns:

String -> Record -> Unit

warn "Deprecated API used" {endpoint: "/old-api", caller: "client-v1"}

error

Log an error message with optional fields.

Parameters:

Returns:

String -> Record -> Unit

error "Database connection failed" {host: "db.example.com", error: "timeout"}

json-logger

Create JSON logger.

Returns:

Unit -> Record

log = json-logger
log.info "Event" {user_id: 123}
# Output: {"timestamp":"...","level":"info","message":"Event","fields":{"user_id":123},...}

production-logger

Create production logger (JSON to stderr, Info level).

Optimized for production environments with structured logging to stderr and filtering out debug-level messages.

Returns:

Unit -> Record

log = production-logger
log.info "Service started" {port: 8080}
log.debug "This won't be logged" {}  # Filtered out

dev-logger

Create development logger (Pretty format, Debug level).

Optimized for development with colored output and verbose logging.

Returns:

Unit -> Record

log = dev-logger
log.debug "Detailed diagnostic info" {state: "connecting"}
# Output: 2024-01-15 10:30:45.123 DEBUG Detailed diagnostic info state=connecting

event

Create a new request-scoped event with initial fields.

Starts an event builder that accumulates context throughout a request. Call add-field, add-timing, etc. to enrich the event, then emit-event to output a single comprehensive log entry.

Parameters:

Returns:

Record -> Record

evt = Logging.event {trace-id: "abc-123", method: "GET", path: "/api/users"}
evt = evt |> Logging.add-field "user-id" 42
evt |> Logging.emit-event "Request completed" {status: 200}

event-with-config

Create an event with custom configuration.

Like event but allows specifying log level, format, and output target.

Parameters:

Returns:

Record -> Record -> Record

evt = Logging.event-with-config {level: Debug, format: PrettyFmt, output: ToStderr} {
  trace-id: "abc-123"
}

add-field

Add a single field to an event.

Enriches the event with additional context.

Parameters:

Returns:

Record -> String -> a -> Record

evt = evt |> Logging.add-field "user-id" 42
evt = evt |> Logging.add-field "cache-hit" true

add-fields

Add multiple fields to an event at once.

Merges a record of fields into the event.

Parameters:

Returns:

Record -> Record -> Record

evt = evt |> Logging.add-fields {user-id: 42, account-type: "premium"}

add-timing

Add a timing measurement to an event.

Records a duration for a named operation. Timings are included in the final log entry under a "timings" key.

Parameters:

Returns:

Record -> String -> Int -> Record

evt = evt |> Logging.add-timing "db-query-ms" 42

with-request

Add request metadata to an event.

Convenience function for adding common request fields.

Parameters:

Returns:

Record -> Record -> Record

evt = evt |> Logging.with-request {id: "req-123", method: "POST", path: "/api/orders"}

with-user

Add user context to an event.

Convenience function for adding user-related fields.

Parameters:

Returns:

Record -> Record -> Record

evt = evt |> Logging.with-user {id: 42, role: "admin", tier: "enterprise"}

with-error

Add error context to an event.

Records error information and sets the event level to Error.

Parameters:

Returns:

Record -> Record -> Record

evt = evt |> Logging.with-error {message: "Connection refused", code: "ECONNREFUSED"}

set-level

Set the log level for an event.

Override the default Info level for this event.

Parameters:

Returns:

Record -> Level -> Record

evt = evt |> Logging.set-level Logging.Warn

emit-event

Emit the event as a single log entry.

Finalizes the event by calculating total duration, merging all accumulated fields and timings, and outputting a single structured log entry. This is the "canonical log line" that captures the complete context of the request.

Parameters:

Returns:

Record -> String -> Record -> Unit

evt |> Logging.emit-event "Request completed" {status: 200, response-size: 1024}

emit-info

Emit the event at Info level.

Convenience function that emits the event at Info level.

Record -> String -> Record -> Unit

evt |> Logging.emit-info "Request successful" {status: 200}

emit-error

Emit the event at Error level.

Convenience function that emits the event at Error level.

Record -> String -> Record -> Unit

evt |> Logging.emit-error "Request failed" {status: 500, error: "Internal error"}

emit-warn

Emit the event at Warn level.

Convenience function that emits the event at Warn level.

Record -> String -> Record -> Unit

evt |> Logging.emit-warn "Request slow" {status: 200, threshold-exceeded: true}

timed

Time an operation and add the duration to an event.

Executes a function, measures its duration, and adds the timing.

Parameters:

Returns:

Record -> String -> (Unit -> a) -> (Record, a)

(evt, users) = Logging.timed evt "db-query-ms" (fn() => db.query "SELECT * FROM users")

Logger

Logger Trait

Defines the core interface for all logger implementations.

The Logger trait enables polymorphic logging - code can work with any logger type (ConsoleLogger, FileLogger, NoOpLogger, etc.) through this common interface.

import Logging

# Any logger implementing the trait can be used
log-message = fn(logger, msg) =>
  log-info logger msg {}

console = Logging.console-logger Logging.default-config
file = Logging.file-logger {path: "/var/log/app.log", level: Info, format: JsonFmt}
noop = Logging.no-op-logger()

log-message console "Hello"  # Logs to console
log-message file "Hello"     # Logs to file
log-message noop "Hello"     # Discarded (no-op)

Logger trait - core interface for all logger implementations.

All loggers must implement these four methods for logging at different
severity levels. Each method takes the logger instance, a message string,
and a record of additional fields.

Type Parameters:
  a - The concrete logger type implementing this trait

Required Methods:
  log-debug: Log a debug-level message (most verbose)
  log-info: Log an info-level message (normal operations)
  log-warn: Log a warning-level message (potential issues)
  log-error: Log an error-level message (failures)

format-json

Format entry as JSON (single line).

Produces structured JSON output suitable for log aggregation systems like Elasticsearch, Splunk, or CloudWatch.

Parameters:

• - timestamp - Time value
• - level - Log level (Debug, Info, Warn, Error)
• - message - Log message string
• - fields - Record of additional fields
• - context - Record of context fields

Returns:

Entry -> String

entry = {timestamp: Time.now, level: Info, message: "Hello", fields: {}, context: {}}
json = format-json entry
# => {"timestamp":"2024-01-15 10:30:45.123","level":"info","message":"Hello",...}

format-pretty

Format entry with colors and structure.

Produces human-readable output with ANSI colors and structured fields. Ideal for development and interactive terminal use.

Parameters:

• - timestamp - Time value
• - level - Log level (Debug, Info, Warn, Error)
• - message - Log message string
• - fields - Record of additional fields
• - context - Record of context fields

Returns:

Entry -> String

entry = {timestamp: Time.now, level: Info, message: "Request completed", fields: {duration: 42}, context: {}}
pretty = format-pretty entry
# => "2024-01-15 10:30:45.123 \u001b[32mINFO\u001b[0m Request completed duration=42"

format-compact

Format entry in compact format (no colors, minimal spacing).

Produces minimal output without ANSI colors, suitable for file logging or environments that don't support colors.

Parameters:

• - timestamp - Time value
• - level - Log level (Debug, Info, Warn, Error)
• - message - Log message string
• - fields - Record of additional fields
• - context - Record of context fields

Returns:

Entry -> String

entry = {timestamp: Time.now, level: Error, message: "Connection failed", fields: {host: "db.example.com"}, context: {}}
compact = format-compact entry
# => "2024-01-15 10:30:45.123 error: Connection failed {host: db.example.com}"

format-entry

Format entry based on format type.

Dispatcher function that selects the appropriate formatter based on the format type.

Parameters:

Returns:

Format -> Entry -> String

formatter = format-entry PrettyFmt
output = formatter entry

NoOpLogger

No-op logger type.

A simple unit type that implements Logger by discarding all messages. All logging methods use the no-op keyword for zero overhead.

no-op-logger

Create a no-op logger.

Returns: A NoOpLogger instance that discards all log messages

Unit -> NoOpLogger

noop = no-op-logger()
log-info noop "This is discarded" {}

Level

Logger Types

Core type definitions for the Kit logging system.

This module defines the fundamental types used throughout the logging framework: - Log levels (Debug, Info, Warn, Error) with severity ordering - Output formats (JSON, Pretty, Compact) for different use cases - Output targets (Stdout, Stderr) for directing log output - Configuration and entry records for logger state and log messages

The type system ensures type-safe logging operations and enables pattern matching on log levels and formats.

Log levels as algebraic data type.

Represents the severity of a log message, ordered from least to most severe: - Debug: Detailed diagnostic information for development - Info: General informational messages about application flow - Warn: Warning messages for potentially harmful situations - Error: Error messages for failure conditions

Levels are compared numerically to determine if a message should be logged based on the configured minimum level threshold.

Debug

Debug log level constructor.

Lowest severity level for detailed diagnostic information. Used during development to trace program execution.

Info

Info log level constructor.

Standard severity level for general informational messages. Default level for production logging.

Warn

Warn log level constructor.

Elevated severity level for potentially harmful situations. Indicates issues that don't prevent operation but warrant attention.

Error

Error log level constructor.

Highest severity level for error conditions. Indicates failures that may affect application correctness.

Format

Output format types as algebraic data type.

Defines how log entries are formatted for output: - JsonFmt: Machine-readable single-line JSON - PrettyFmt: Human-readable colored output with structure - CompactFmt: Minimal uncolored output for constrained environments

JsonFmt

JSON format constructor.

Outputs log entries as single-line JSON objects. Best for production environments where logs are parsed by tools.

PrettyFmt

Pretty format constructor.

Outputs log entries with ANSI colors and structured formatting. Best for development and interactive terminal use.

CompactFmt

Compact format constructor.

Outputs log entries in minimal format without colors. Best for resource-constrained environments or file logging.

Output

Output target types as algebraic data type.

Defines where log output is written: - ToStdout: Standard output stream - ToStderr: Standard error stream

ToStdout

Stdout output constructor.

Directs log output to standard output stream. Default target for most logging scenarios.

ToStderr

Stderr output constructor.

Directs log output to standard error stream. Recommended for production to separate logs from application output.

should-log?

Check if a level should be logged based on configured minimum level.

Determines whether a log entry at a given level should be emitted based on the logger's configured minimum level threshold. Messages at or above the minimum level pass the filter.

Parameters:

• min-level - Level - The minimum configured log level
• entry-level - Level - The level of the log entry being checked

Returns: Bool - true if entry should be logged, false if it should be filtered

Level -> Level -> Bool

should-log? Info Debug  # Returns false (Debug < Info)
should-log? Info Warn   # Returns true (Warn >= Info)

level-to-string

Convert level to uppercase string.

Produces uppercase string representation of log level, suitable for display in logs and user interfaces.

Parameters:

• level - Level - The log level to convert

Returns: String - Uppercase level name ("DEBUG", "INFO", "WARN", "ERROR")

Level -> String

level-to-string Info   # Returns "INFO"
level-to-string Error  # Returns "ERROR"

level-to-string-lower

Convert level to lowercase string.

Produces lowercase string representation of log level, suitable for JSON output and machine-readable formats.

Parameters:

• level - Level - The log level to convert

Returns: String - Lowercase level name ("debug", "info", "warn", "error")

Level -> String

level-to-string-lower Info   # Returns "info"
level-to-string-lower Error  # Returns "error"

default-config

Default logger configuration.

Provides sensible defaults for logger creation: - Info level: Filters out Debug messages - PrettyFmt: Colored, human-readable output - ToStdout: Output to standard output - Empty context: No global contextual fields

This configuration is suitable for development and can be customized using the with-* builder functions.

Returns: Config - Default configuration record

Config

logger default-config              # Use defaults
logger (with-level default-config Debug)  # Override level