Skip to content

Debugging Worker Events

Jump to bottom
Jason Jerome edited this page Jan 10, 2024 · 24 revisions

Debugging Methods

This page will describe the two primary methods of debugging events by using the yggctl cli tool packaged with yggdrasil:

  • Dynamic observation using the listen command
  • Static observation using the message-journal command.

Dynamic observation

Worker events can be tracked in a minimal text-based format by using the listen command in the yggctl cli tool to observe worker events as they are emitted.
Unlike using the message journal, this method streams worker events and does not provide options to filter events or display them in other formats.

Example - Streaming worker events to the console
$ yggctl listen --worker "<worker_name>"
> <worker-name>: <message-id>: <event>: <response-to-id>: <event-data>
Example - Streaming worker events to a file
$ touch ~/example.txt
$ yggctl listen --worker "<worker_name>" &> ~/example.txt

Static observation

Worker events can be tracked by using the message-journal command in the yggctl cli tool.
The message journal displays a static list of events emitted by workers in multiple formats (table/text/json) and provides ways to filter the displayed worker events. This method also persistently stores worker events in a local database file to maintain records of emitted events across multiple yggdrasil sessions.

$ yggctl message-journal <opts>

Additional information about the usage and configuration of the message journal display can be found below.

Debugging With The Message Journal

Enabling The Journal

The message journal can be enabled with yggd by specifying a file path to create and store a message journal sqlite database.

$ yggd ... --message-journal ~/myjournal.db

Displaying The Journal

The message journal can be interacted with using the yggctl cli tool to display the message journal with filters and formatting options applied.

$ yggctl message-journal

Filtering Journal Data

The message journal can be filtered in multiple ways when being displayed.
The current supported filtering operations are listed below:

Filtering By Session

The journal database stores worker events persistently between sessions.
By default the message journal will display events from only the active session, but using the --persistent flag will output worker events from the active session and all previous sessions.

$ yggctl message-journal --persistent

Filtering By Worker

The journal can be filtered by a specific worker name using --worker or
by a worker message id using --message-id.

$ yggctl message-journal --worker "<name>"
$ yggctl message-journal --message-id "<id>"

Filtering By Time

The journal can be filtered to only display messages before/after/between UTC timestamps
with a combination of the --since and --until options. The UTC timestamps use the YYYY-MM-DD HH:MM:SS format.

Example - Display messages since a UTC timestamp
$ yggctl message-journal --since "2024-01-01 00:00:00"
Example - Display messages up until a UTC timestamp
$ yggctl message-journal --until "2025-01-01 00:00:00"
Example - Display messages between two UTC timestamps
$ yggctl message-journal --since "2024-01-01 00:00:00" --until "2025-01-01 00:00:00"

Combining Filters

The message journal filtering options can be used together to create more useful journal outputs.

Example - Filtering by worker and message id.
$ yggctl message-journal --worker "<name>" --message-id "<id>"
Example - Filtering by worker and time.
$ yggctl message-journal --worker "<name>" --since "2023-01-01 00:00:00" --until "2024-01-01 00:00:00"

Message Journal Formatting

The message journal can be displayed in the following formats:

  • Table Formatting (Default)
  • Text Formatting
  • JSON Formatting

Table Formatting

$ yggctl message-journal --format=table
  MESSAGE # | MESSAGE ID    | SENT            | WORKER NAME   | RESPONSE TO      | WORKER EVENT | WORKER DATA
  0         | <message-id>  | <UTC timestamp> | <worker_name> | <response-to-id> | <event>      | <data> 
  1         | ...           | ...             | ...           | ...              | ...          | ...

Text Formatting

$ yggctl message-journal --format=text

> <message-id> : <sent> : <UTC timestamp> : <worker_name> : <response-to-id> : <event> : <data>
> ...

JSON Formatting

$ yggctl message-journal --format=json
> [
     {
         "message-id": "<message-id>",
         "response_to": "<response-to-id>",
         "sent": "<UTC time>",
         "worker_data": "<data>",
         "worker_event": "<event>",
         "worker_name": "<name>",
     },
     ...
 ]

Additional Resources

For additional usage information for message journal commands, please refer to the --help section of the message journal command using yggctl.

$ yggctl message-journal --help
Clone this wiki locally