| Overview |  |
The logging extension.
Sends device log lines to NervesHub, which stores them against the device and makes them searchable. One direction only: nothing is ever sent back.
logging:send #{level, message, meta} device -> server
NervesHub does not stamp a log line on arrival. LogLine.changeset/1 takes
timestamp if it is there, otherwise reads meta.time, and otherwise leaves
the line without one — where it fails a required-field validation and is
dropped silently.
meta.time must be a **string** holding **microseconds** since the epoch:
the server calls String.to_integer/1` then `DateTime.from_unix(:microsecond)`,
so an integer is not accepted and milliseconds land in 1970. `line/2` builds
it, which is the point of this module — the shape is easy to get wrong and
wrong is invisible from the device.
A device whose clock is not set has no honest timestamp to give, so no line
is sent rather than a line dated 1970. See `nh_ext_health:timestamp/0 for
the same rule.
| event/0 | The scoped event a log line is sent as. |
| line/2 | Equivalent to line(Level, Message, #{}).
|
| line/3 | Build a log line NervesHub will accept. |
| line_at/4 | Build a log line stamped with a time the caller already has. |
event() -> binary()
The scoped event a log line is sent as.
line(Level::binary(), Message::binary()) -> {ok, map()} | {error, no_clock}
Equivalent to line(Level, Message, #{}).
line(Level::binary(), Message::binary(), Meta::map()) -> {ok, map()} | {error, no_clock}
Build a log line NervesHub will accept.
Meta is merged under the timestamp rather than over it, so a caller cannot
accidentally replace the one field that decides whether the line is kept.
line_at(Level::binary(), Message::binary(), Meta::map(), Micros::integer()) -> {ok, map()} | {error, no_clock}
Build a log line stamped with a time the caller already has.
logger hands a handler the moment the event was created, in microseconds,
which is exactly what NervesHub wants. Using it rather than reading the clock
again keeps a line stamped when it happened rather than when it was sent.
Generated by EDoc