refactor(docs): improve docs for metrics

docs/methoddocs/cluster.md

@@ -0,0 +1,28 @@
+# silverback.cluster
+
+The `silverback.cluster` module contains several submodules intended to work directly with
+hosted (and local) Silverback Clusters, and assist in integration with the Silverback Platform.
+
+```{eval-rst}
+.. automodule:: silverback.cluster.client
+    :members:
+    :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: silverback.cluster.mcp
+    :members:
+    :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: silverback.cluster.settings
+    :members:
+    :show-inheritance:
+```
+
+```{eval-rst}
+.. automodule:: silverback.cluster.types
+    :members:
+    :show-inheritance:
+```

docs/methoddocs/recorder.md

@@ -0,0 +1,10 @@
+# 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.
+
+```{eval-rst}
+.. automodule:: silverback.recorder
+    :members:
+    :show-inheritance:
+```

docs/methoddocs/settings.md

@@ -0,0 +1,10 @@
+# silverback.settings
+
+The `silverback.settings` module contains configuration settings to be used whe executing a
+Silverback bot, including configuring the broker system, RPC connection and signer.
+
+```{eval-rst}
+.. automodule:: silverback.settings
+    :members:
+    :show-inheritance:
+```

docs/methoddocs/state.md

@@ -0,0 +1,10 @@
+# silverback.state
+
+The `silverback.state` module contains modules for loading an unloading the shared memory for a
+Silverback bot, which can be loaded from a persistent store and snapshotted at regular intervals.
+
+```{eval-rst}
+.. automodule:: silverback.state
+    :members:
+    :show-inheritance:
+```

docs/methoddocs/types.md

@@ -0,0 +1,7 @@
+# silverback.types
+
+```{eval-rst}
+.. automodule:: silverback.types
+    :members:
+    :show-inheritance:
+```

docs/userguides/development.md

@@ -153,6 +153,32 @@ def every_hour():
 
 For more information see [the linux handbook section on the crontab syntax](https://linuxhandbook.com/crontab/#understanding-crontab-syntax) or the [crontab.guru](https://crontab.guru/) generator.
 
+## Defining Metrics
+
+Silverback has a built-in metrics collection system which can capture measurements made by your bots, which can assist you in debugging or performance monitoring.
+To capture a measurement of a metric datapoint, simply return boolean values or numeric data from your function handlers, or use any of our defined [Datapoint types](../methoddocs/types).
+When you return a datapoint measurement directly, the datapoint is stored using the label of it's function handler to append to a timeseries for the metric.
+When you return a dictionary containing multiple measurements, the string key corresponds to label of the metric you are capturing a datapoint for.
+
+Note that metric labels are tracked globally across your bot.
+If you generate metrics in two different function handlers that have the same string keys in the dictionary, they will both be appended to the same metric timeseries.
+
+For example, both of the following handlers `handlerA` and `handlerB` generate the `block_time` metric, along with the `block_time` handler which also generates a matching metric of the same name (because it does not return a dict):
+
+```python
+@bot.on_(my_contract.MyEvent)
+async def handlerA(log):
+    return dict(block_time=log.timestamp)
+
+@bot.cron("* * * * *")
+async def handlerB(time):
+    return {"block_time": int(time.timestamp())}
+
+@bot.on_(chain.blocks)
+async def block_time(block):
+    return block.timestamp
+```
+
 ## Startup and Shutdown
 
 ### Worker Events
@@ -316,6 +342,13 @@ It is highly suggested to use a dedicated cloud signer plugin, such as [`ape-aws
 Use segregated keys and limit your risk by controlling the amount of funds that key has access to at any given time.
 ```
 
+### Metrics Collection
+
+To configure your bot for metrics collection, define the `SILVERBACK_RECORDER_CLASS=...` environment variable.
+All recorders should be a subclass of the [`silverback.recorder.BaseRecorder`](../methoddocs/recorder#silverback.recorder.BaseRecorder) abstract base class.
+Currently, the only available Recorder class is the [`silverback.recorder.JSONLineRecorder`](../methoddocs/recorder#silverback.recorder.JSONLineRecorder) class, which journals your bot session's results to disk under timestamped files in `./.silverback-sessions/<bot name>/<ecosystem>/<network>/`.
+To assist in loading the metrics for things like analyzing them with Dataframe libraries, use the [`silverback.recorder.get_metrics`](../methoddocs/recorder#silverback.recorder.get_metrics) function.
+
 ### Distributed Execution
 
 Using only the `silverback run ...` command in a default configuration executes everything in one process and the job queue is completely in-memory with a shared state.

silverback/recorder.py

@@ -73,7 +73,7 @@ class BaseRecorder(ABC):
     """
 
     @abstractmethod
-    async def init(self, app_id: SilverbackID):
+    async def init(self, bot_id: SilverbackID):
         """
         Handle any async initialization from Silverback settings (e.g. migrations).
         """
@@ -88,15 +88,15 @@ class JSONLineRecorder(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_APP_NAME`
+    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/
-          <app-name>/
+          <bot-name>/
             <network choice>/
-              session-<timestamp>.json  # start time of each app session
+              session-<timestamp>.json  # start time of each bot session
 
-    Each app "session" (everytime the Runner is started up via `silverback run`) is recorded
+    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
@@ -110,15 +110,15 @@ class JSONLineRecorder(BaseRecorder):
 
     - `SILVERBACK_RECORDER_CLASS`: `"silverback.recorder:JSONLineRecorder"`
 
-    You may also want to give your app a unique name so the data does not get overwritten,
-    if you are using multiple apps from the same directory:
+    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_APP_NAME`: Any alphabetical string valid as a folder name
+    - `SILVERBACK_BOT_NAME`: Any alphabetical string valid as a folder name
     """
 
-    async def init(self, app_id: SilverbackID):
+    async def init(self, bot_id: SilverbackID):
         data_folder = (
-            Path.cwd() / ".silverback-sessions" / app_id.name / app_id.ecosystem / app_id.network
+            Path.cwd() / ".silverback-sessions" / bot_id.name / bot_id.ecosystem / bot_id.network
         )
         data_folder.mkdir(parents=True, exist_ok=True)