include module type of struct include Tezos_event_logging.Internal_event.Simple end
This module provides wrappers to declare events without having to declare a module and apply the Make
functor. They are pretty-printed as <DOC> (<PARAMETER> = <VALUE>, ...)
(unless there is no parameter at all, in which case they are printed as <DOC>
). You may also use braces to inline some parameters in <DOC>
. In the example below, hash
is inlined.
For consistency, it is suggested that log messages do not start with a capital letter and do not end with a period. For instance, write ~msg: "started something important"
instead of ~msg: "Started something important."
. The reason is that messages that do not inline all of their parameters are followed by the remaining parameters in parentheses, and a period does not (arguably) look great in those cases. If it does not end with a period, it is not a sentence and thus capitalizing the first word does not make much sense either.
Declare events with one of the declare
functions, for instance:
let inject =
Internal_event.Simple.declare_2
~name: "inject"
~msg: "injected block {hash}"
("level", int)
("hash", string)
You must declare events only once for a given name. Usually you should thus declare them as global variables.
There is one declare_n
function for each number n
of parameters. For instance, the above example uses declare_2
because it has two parameters: level
and hash
.
Each parameter has a default pretty-printer that you can override using the ?ppX
parameters. For instance, to override the default pretty-printer of the second parameter, pass a ~pp2
argument. This allows to, for instance, print only the first element of a list, remove quotes for strings, decide how many decimal digits are printed for floats, etc.
The default pretty-printer behaves as follows:
- for base types (booleans, integers, strings, floats), it uses OCaml syntax;
- for strings which are longer than 64 characters, it prints only the first characters followed by an ellipsis
[...]
; - for null or similar encodings, it prints
N/A
; - for unions of
Null
and another encoding e
(this is the encoding of options), it prints null
for Null
and uses e
to decide how to print the value otherwise; - for other constructed values (arrays, lists, objects, tuples, unions, and recursive types), it prints a placeholder like
<list>
or <obj>
(see remark below).
Because constructed values such as lists and objects are printed as placeholders such as <list>
and <obj>
and thus do not give any information, those parameters are not automatically added in parentheses at the end of the messages. You can override the default pretty-printer of those parameters to override this behavior. In that case, values will be printed if your pretty-printer does not output an empty string. Note that you should also override the default pretty-printer of constructed types that you inline using braces, as they would be printed using the placeholder otherwise.
Then emit this event with some parameters like this: Internal_event.Simple.emit inject (42, "BL654654654645654654564")
This event will be printed as: injected block BL654654654645654654564 (level = 42)
For all declare
functions, the default value for level
is Info
.
Event declarations where 'a
is the type of the event parameters.
val emit : 'a t -> 'a -> unit Lwt.t
Emit an instance of an event.
val emit__dont_wait__use_with_care : 'a t -> 'a -> unit
Emit an instance of an event but do not wait for completion. Only use if you really need to not wait for logging resolution before continuing. May cause increased memory usage and out-of-order log messages.
Declare an event with no parameters.
Declare an event with one parameter.
Declare an event with two parameters.
Declare an event with three parameters.
Declare an event with four parameters.
Declare an event with five parameters.
Declare an event with six parameters.
Declare an event with seven parameters.
val declare_8 :
?section:string list ->
name:string ->
msg:string ->
?level:Tezos_event_logging.Internal_event.level ->
?pp1:(Stdlib.Format.formatter -> 'a -> unit) ->
(string * 'a Data_encoding.t) ->
?pp2:(Stdlib.Format.formatter -> 'b -> unit) ->
(string * 'b Data_encoding.t) ->
?pp3:(Stdlib.Format.formatter -> 'c -> unit) ->
(string * 'c Data_encoding.t) ->
?pp4:(Stdlib.Format.formatter -> 'd -> unit) ->
(string * 'd Data_encoding.t) ->
?pp5:(Stdlib.Format.formatter -> 'e -> unit) ->
(string * 'e Data_encoding.t) ->
?pp6:(Stdlib.Format.formatter -> 'f -> unit) ->
(string * 'f Data_encoding.t) ->
?pp7:(Stdlib.Format.formatter -> 'g -> unit) ->
(string * 'g Data_encoding.t) ->
?pp8:(Stdlib.Format.formatter -> 'h -> unit) ->
(string * 'h Data_encoding.t) ->
('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h) t
Declare an event with eight parameters.