silverback.recorder

The silverback.recorder module contains classes that hook into the Runner’s recording features when executing a Silverback bot, which is meant to journal runtime metrics to a persistent store.

class silverback.recorder.BaseRecorder

Bases: ABC

Base class used for serializing task results to an external data recording process.

Recorders are configured using the following environment variable:

SILVERBACK_RECORDER_CLASS: Any fully qualified subclass of BaseRecorder as a string

abstract async add_result(result: TaskResult): Store a result for a Silverback instance’s handler

abstract async init(bot_id: SilverbackID): Handle any async initialization from Silverback settings (e.g. migrations).

class silverback.recorder.JSONLineRecorder

Bases: BaseRecorder

Very basic implementation of BaseRecorder used to handle results by appending to a file containing newline-separated JSON entries (https://jsonlines.org/).

The file structure that this Recorder uses leverages the value of SILVERBACK_BOT_NAME as well as the configured network to determine the location where files get saved:

./.silverback-sessions/

<bot-name>/

<network choice>/
session-<timestamp>.json # start time of each bot session

Each bot “session” (everytime the Runner is started up via silverback run) is recorded in a separate file with the timestamp of the first handled task in its filename.

Note that this format can be read by basic means (even in a JS frontend), or read efficiently via Apache Arrow for more efficient big data processing:

https://arrow.apache.org/docs/python/json.html

Usage:

To use this recorder, you must configure the following environment variable:

SILVERBACK_RECORDER_CLASS: “silverback.recorder:JSONLineRecorder”

You may also want to give your bot a unique name so the data does not get overwritten, if you are using multiple bots from the same directory:

SILVERBACK_BOT_NAME: Any alphabetical string valid as a folder name

async add_result(result: TaskResult): Store a result for a Silverback instance’s handler

async init(bot_id: SilverbackID): Handle any async initialization from Silverback settings (e.g. migrations).

class silverback.recorder.TaskResult(*, task_name: str, execution_time: float, error: str | None = None, completed: ~datetime.Annotated[~datetime.datetime, ~pydantic.functional_serializers.PlainSerializer(func=~silverback.types.iso_format, return_type=str, when_used=always)] = <factory>, block_number: int | None = None, metrics: ~silverback.types.Datapoints): Bases: BaseModel

silverback.recorder.get_metrics(session: Path, task_name: str) → Iterator[dict]: Useful function for fetching results and loading them for display.