diff --git a/docs/pages/running/_meta.json b/docs/pages/running/_meta.json new file mode 100644 index 00000000..bf115694 --- /dev/null +++ b/docs/pages/running/_meta.json @@ -0,0 +1,4 @@ +{ + "modes": "Operation Modes", + "logging": "Logging" +} diff --git a/docs/pages/running/daemon.mdx b/docs/pages/running/daemon.mdx deleted file mode 100644 index 39a65a38..00000000 --- a/docs/pages/running/daemon.mdx +++ /dev/null @@ -1,9 +0,0 @@ -# `daemon` mode - -The `daemon` command starts Dolos with all of its main functions enabled (syncing from upstream, updating the ledger, etc) which includes the client endpoint server - -To start Dolos in `daemon` mode run the following command from the terminal: - -``` -dolos daemon -``` diff --git a/docs/pages/running/eval.mdx b/docs/pages/running/eval.mdx deleted file mode 100644 index 5b0ffaa0..00000000 --- a/docs/pages/running/eval.mdx +++ /dev/null @@ -1,18 +0,0 @@ -# `eval` command - -The `eval` is an utility for evaluating transactions. It takes tx data from an external source and uses the current ledger state to evaluate phase-1 validation rules. - -## Usage - -To execute the evaluation, run the following command from your terminal: - -```bash -dolos eval --file --era --magic --slot -``` - -The args should be interpreted as: - -- `--file `: the path to the file containing the tx data as hex-encoded cbor. -- `--era `: the id of the era that should be used to interpret the transaction data. -- `--magic `: the protocol magic of the network. -- `--slot `: the slot that should be used for retrieving protocol parameters. \ No newline at end of file diff --git a/docs/pages/running/logging.mdx b/docs/pages/running/logging.mdx new file mode 100644 index 00000000..f822c325 --- /dev/null +++ b/docs/pages/running/logging.mdx @@ -0,0 +1,57 @@ +# Logging + +Dolos outputs a LOT of logs through stdout. Internally, it uses a tracing mechanism that groups logs into hierarchical blocks called _spans_ that holds data describing the context where the event (aka: log) ocurred. + +Depending on your use-case, the amount and detail of this logs might be overwhelming. _Dolos_ provides a set of configuration values that allows you to opt-in into different levels of detail. + +## Log Levels + +Dolos follow a very common convention around log levels. These levels describe discrete categories of decreasing severity (broadly speaking). + +The following table describes the available options and what they are used within our context: + +| level | description | +| ------- | ---------------------------------------------------------------------------- | +| `error` | unexpected errors, stuff that shouldn't occur | +| `warn` | warning about things that are expected but require attention | +| `info` | normal operation events that are relevant for day-to-day operations | +| `debug` | normal operation events with a level of detail useful for debugging problems | +| `trace` | extreme level of detail, usually including data being processed | + +## Sub-components + +There are some sub-components within _Dolos_ that are more verbose than others. Depending on your use-case or debugging needs, you might one to mute some components and not others. + +We have identified a few components that make sense to isolate from the rest of the logs to provide extra flexibility. These components are: + +| component | description | +| --------- | ----------------------------------------------------------------------------------------------------- | +| Pallas | The library that deals with low-level Ouroboros interactions (eg: mini-protocols, cbor decoding, etc) | +| Tonic | The library that deals with gRPC communication | + +## Configuration + +Now that we understand the different dimensions involved in the logging process, we can describe the relevant configuration. + +The configuration section within the `dolos.toml` file that controls the logging options is called `logging` (I know, impossible to guess). The schema for the configuration values is the following: + +| property | type | example | +| -------------- | ------ | --------------------------------------------- | +| max_level | option | `error` / `warn` / `info` / `debug` / `trace` | +| include_pallas | option | `true` / `false` | +| include_tonic | option | `true` / `false` | + +- `max_level`: the maximum severity level of events to include in the output. By selecting a specific level, you're effectively including that level and every other levels of higher severity. +- `include_pallas`: a flag that indicate if the output should include logs from the Pallas sub-component. +- `include_tonic`: a flag that indicate if the output should include logs from the Tonic sub-component. + +The following is an example of a logging configuration: + +```toml +[logging] +max_level = "INFO" +include_pallas = true +include_tonic = true +``` + +You can find more detailed info about configuration in the [configuration schema section](../configuration/schema) diff --git a/docs/pages/running/modes.mdx b/docs/pages/running/modes.mdx new file mode 100644 index 00000000..f2e84b9c --- /dev/null +++ b/docs/pages/running/modes.mdx @@ -0,0 +1,42 @@ +# Operation Modes + +_Dolos_ has many operation modes dependending on your requirements. Choose the one that fits your need. + +## `daemon` mode + +This is the normal operation mode. When running in this mode, Dolos will perform all operations as specified in the configuration file. + +To start _Dolos_ in `daemon` mode, use the following command: + +```sh +dolos daemon +``` + +## `sync` mode + +When running in this mode, Dolos will focus on a single task: synchronizing its state from the upstream node. + +To start _Dolos_ in `sync` mode, use the following command: + +```sh +dolos sync +``` + +## `serve` mode + +When running in this mode, Dolos will focus on a single task: serving data through the configured API endpoints. + +To start _Dolos_ in `serve` mode, use the following command: + +```sh +dolos serve +``` + +## Sumary of Modes + +| feature | daemon | sync | serve | +| ------------------------------ | ------ | ---- | ----- | +| sync from upstream peer | ✅ | ✅ | ❌ | +| relay ouroboros node-to-node | ✅ | ❌ | ❌ | +| serve ouroboros node-to-client | ✅ | ❌ | ✅ | +| serve gRPC | ✅ | ❌ | ✅ | \ No newline at end of file diff --git a/docs/pages/running/sync.mdx b/docs/pages/running/sync.mdx deleted file mode 100644 index 132e65a2..00000000 --- a/docs/pages/running/sync.mdx +++ /dev/null @@ -1,9 +0,0 @@ -# `sync` mode - -The `sync` command starts Dolos in mode where it only perform upstream synchronization. This involves connecting to the upstream node to pull chain updates and update local state. In this mode Dolos will not expose any API to the outside. - -To start Dolos in `daemon` mode run the following command from the terminal: - -``` -dolos daemon -```