Rand Stats

Log::Timeline

zef:jnthn

Log::Timeline

When building an application with many ongoing, potentially overlapping, tasks, we may find ourselves wishing to observe what is going on. We'd like to log, but with a focus on things that happen over time rather than just individual events. The Log::Timeline module provides a means to do that.

As well as annotating your own applications with Log::Timeline tasks and events, the module can provide various events relating to the Raku standard library, and has already been integrated in some modules, such as Cro.

Key features

Planned:

Turning on Raku built-ins logging

Set the LOG_TIMELINE_RAKU_EVENTS environment variable to a comma-separated list of events to log. For example:

LOG_TIMELINE_RAKU_EVENTS=file,thread,socket,process,start,await

The events available are:

Providing tasks and events in a distribution

Providing tasks and events in your application involves the following steps:

  1. Make sure that your META6.json contains a depends entry for Log::Timeline.
  2. Create one or more modules whose final name part is LogTimelineSchema, which declares the available tasks and events. This will be used for tools to introspect the available set of tasks and events that might be logged, and to provide their metadata.
  3. Use the schema module and produce timeline tasks and events in your application code.

The schema module

Your application or module should specify the types of tasks and events it wishes to log. These are specified in one or more modules, which should be registered in the provides section of the META6.json. The module name's final component should be LogTimelineSchema. For example, Cro::HTTP provides Cro::HTTP::LogTimelineSchema. You may provide more than one of these per distribution.

Every task or event has a 3-part name:

These are specified when doing the role for the event or task.

To declare an event (something that happens at a single point in time), do the Log::Timeline::Event. To declare an task (which happens over time) do the Log::Timeline::Task role.

unit module MyApp::Log::LogTimelineSchema;
use Log::Timeline;

class CacheExpired does Log::Timeline::Event['MyApp', 'Backend', 'Cache Expired'] { }

class Search does Log::Timeline::Task['MyApp', 'Backend', 'Search'] { }

Produce tasks and events

Use the module in which you placed the events and/or tasks you wish to log.

use MyApp::Log::LogTimelineSchema;

To log an event, simply call the log method:

MyApp::Log::LogTimelineSchema::CacheExpired.log();

Optionally passing extra data as named arguments:

MyApp::Log::LogTimelineSchema::CacheExpired.log(:$cause);

To log a task, also call log, but pass a block that will execute the task:

MyApp::Log::LogTimelineSchema::Search.log: -> {
    # search is performed here
}

Named parameters may also be passed to provide extra data:

MyApp::Log::LogTimelineSchema::Search.log: :$query -> {
    # search is performed here
}

Collecting data

Logging to a file in JSON lines format

Set the LOG_TIMELINE_JSON_LINES environment variable to the name of a file to log to. Each line is an object with the following keys:

A task start (kind 1) and task end (2) will also have:

An event (kind 0) or task start (kind 1) may also have:

Logging to a file as a CBOR sequence

Set the LOG_TIMELINE_CBOR_SEQUENCE environment variable to the name of a file to log into. The schema matches that of the JSON lines output.

Socket logging

Set the LOG_TIMELINE_SERVER environment variable to either:

Warning: Don't expose the socket server to the internet directly; there is no authentication or encryption. If really wishing to expose it, bind it to a local port and then use an SSH tunnel.

Handshake

Upon connection the client must send a JSON line consisting of an object that includes the keys:

The client may include other keys in the object speculatively (for example, if protocol version 3 supports a key "foo", but it speaks anything from 1 to 3, then it may include the key "foo", knowing that a previous version of the server will simply ignore it).

In response to this, the server must send a JSON line consisting of an object that includes at most one of the following:

In the case of sending an err, the server should close the connection.

If the initial communication from the client to the server:

Then the server may send a may send a JSON line with an object containing err and then close the connection.

Protocol version 1

No additional configuration keys from the client are recognized in this version of the protocol.

Beyond the initial handshake line, the client should not send anything to the server. The client may close the connection at any time.

The server sends JSON lines to the client. This lines are the same as specified for the JSON lines file format.

Checking if logging is active

Call Log::Timeline.has-output to see if some kind of logging output is set up in this process, This is useful for avoiding introducing logging if it will never take place.