Standard Library: std.log
● Intermediate5 min
Every type, method and function of std.log: what the spec lists, then each declaration in its source, with its examples and the line that declares it.
Spec 14.12 · learn it in Logging.
A declaration below shows what a program writes against: a type's fields, a function's parameters, what it gives, its contracts (require, ensure) and its examples. kavach test runs every example, so each one is true of the code.
What the spec lists
| Function | Level | For |
|---|---|---|
log.debug(event) | debug | Details for finding a problem |
log.info(event) | info | What the program did |
log.warn(event) | warn | Something unexpected that the program handled |
log.error(event) | error | Something that failed |
Numbers a program counts or measures go to the collector every 10 seconds as OpenTelemetry metrics (POST <endpoint>/v1/metrics), when [log.otlp] is set:
| Function | Sends |
|---|---|
log.count(name, n) | A sum: n added to the counter name. n is 0 or more (a require) |
log.gauge(name, value) | The latest value of name, such as a queue's length |
log.histogram(name, value) | How the values of name spread, such as each request's time in milliseconds: how many, their sum, the smallest, the largest, and how many fall in each bucket (OpenTelemetry's default bounds: 0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000) |
std.log · log.kav
use std.log: 1 type and 10 functions. stdlib/log/log.kav
LogEvent interface
A type whose values can be logged: type OrderPlaced: LogEvent { … }. An event is written in its printed form (spec 1.11), so secret fields show as <secret>, and a type can choose its own form with Display.
pub interface LogEvent {}debug function
Writes event at level debug: details for finding a problem. Left out unless kavach.toml sets the level to debug.
pub fn debug<E: LogEvent>(event: E)info function
Writes event at level info: what the program did.
pub fn info<E: LogEvent>(event: E)warn function
Writes event at level warn: something unexpected that the program handled.
pub fn warn<E: LogEvent>(event: E)error function
Writes event at level error: something failed.
pub fn error<E: LogEvent>(event: E)count function
Adds n to the counter name, sent as an OpenTelemetry sum; each set of attributes is a series of its own.
pub fn count(name: String, n: Int, attributes: [String: String] = [:])
require n >= 0gauge function
The latest value of name, such as a queue's length.
pub fn gauge(name: String, value: Float, attributes: [String: String] = [:])histogram function
One more value of name, whose spread is sent as a histogram.
pub fn histogram(name: String, value: Float, attributes: [String: String] = [:])name_span function
Renames the current span, once the code knows what it does (a route's pattern, GET /orders/{id}, never a path with ids in it); outside a span it does nothing.
pub fn name_span(name: String)trace_id function
The current trace's id, 32 hexadecimal digits; none outside a span.
pub fn trace_id() -> String?traceparent function
The current span's W3C traceparent header; none outside a span.
pub fn traceparent() -> String?