module Logbuch::Annotations

Overview

The annotations that trace methods and control how values are logged.

A program that includes this module at its top level writes them without a prefix in every file, such as @[Logged] instead of @[Logbuch::Annotations::Logged]; logbuch never includes it there itself, so its names cannot clash with a program's or another shard's. A shard that uses logbuch writes the full names, or includes the module into its own types, so it works in any program. logbuch includes Logbuch::Tracing into each type with a traced method.

Including this module in a class, struct or module gives that type the short names and includes Logbuch::Tracing into it, which a private type needs, since logbuch cannot reopen it from outside its file. A private top-level module, the modules inside it, and a type defined in the program's own macro finished need it too: logbuch cannot see them, so without it their methods are not traced, and the build does not fail.

require "logbuch"

include Logbuch::Annotations

class Shop
  @[Logged("placing the order", :debug)]
  @[LogError(IO::Error, :warn, stacktrace: false)]
  def place(order : Order, @[LogAs(:redacted)] coupon : String) : Receipt
  end
end

Wherever an annotation takes a level, it is a symbol, :trace to :fatal, or the Log::Severity member, such as Log::Severity::Warn or ::Log::Severity::Warn. Wherever it takes a detail, it is a symbol, :omit to :full, or the Logbuch::Detail member, such as Logbuch::Detail::Full.

Defined in:

logbuch/annotations.cr