annotation Logbuch::Annotations::LogAs

Overview

Sets how a parameter or field is logged. Its positional arguments, in any order:

• a detail, :omit, :id, :summary or :full, or a Logbuch::Detail member such as Logbuch::Detail::Full: a parameter is logged at that detail, whatever the method's; a field is included from that detail up, and an :omit one never;
• :redacted: the value is always logged as "***", and a converter: next to it fails the build; a converter that masks a value goes without it. Without a detail next to it, the parameter or field is logged where it would be without the annotation;
• items(...), on a collection: how each of its items is logged (see below).

Its named options: converter:, a block in arrow notation with one parameter whose result is logged instead of the value, and the limits cap: and length:. They can go without a positional argument, as in @[LogAs(length: 80)]; the parameter or field then keeps the detail it has without the annotation. Crystal takes positional arguments before named ones, so items(...) goes before them.

The limits apply to the value, or to what converter: returns:

• cap: limits the items of the annotated array, deque, set, slice or hash itself; a tuple is logged whole;
• length: cuts the annotated string itself, the keys of the annotated hash, an exception's message, the inspect text of an object logged with inspect, or the identity of an object logged as its identity.

How deep the values below the value nest is the max_depth setting only (see Logbuch.configure).

items(...) sets how each item of the annotated collection is logged: the values of an array, deque, set, slice, hash or named tuple, and the elements of a tuple. It takes a detail, :id, :summary or :full or a Logbuch::Detail member, which the item and what is inside it are logged at, higher or lower than the collection's own, and the named options cap:, length: and converter:, which apply to each item as they would to the value: @[LogAs(:summary, items(:id, length: 20), cap: 10)] logs ten items at most, each at :id with its strings cut to 20 characters. A converter: of the collection runs first, and items(...) applies to what it returns; the item converter runs for each item while the collection is converted. A hash's keys are logged at :id whatever it says, and inside an identity, where every value is logged at :id, it has no effect. It fails the build on :omit, next to :redacted, and on a value that is none of those collections.

The strings and collections inside the value get the settings again, not cap: and length:; items(...) sets them for its items. Without a converter, cap: on a type that is not one of those collections, and length: on a type it cannot cut, such as a number, a character, Bool, a symbol, an enum, an array or tuple, or an object logged by its fields, fail the build, and so do the options of items(...) that cannot change how its items are logged, unless it has a converter of its own. A union, a parameter without a type, and a type with its own to_trace are not checked.

At :id, every object is logged as its identity, such as "o-17", which is the same at any depth. So on a parameter logged at :id, by its own detail or the method's, length: cuts each string of it, also for an object logged by its fields. A field's detail only sets from which detail it is shown; its value is logged at the detail of the object around it, so length: on a field marked :id cuts the identity the field shows at :id.

Defined in:

logbuch/annotations.cr