> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/ecosystem/nodes/rust/logs-config",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# How to configure logging YAML file

export const Aside = ({type = "note", title = "", icon = "", iconType = "regular", children}) => {
  const asideVariants = ["note", "tip", "caution", "danger"];
  const asideComponents = {
    note: {
      outerStyle: "border-sky-500/20 bg-sky-50/50 dark:border-sky-500/30 dark:bg-sky-500/10",
      innerStyle: "text-sky-900 dark:text-sky-200",
      calloutType: "note",
      icon: <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="w-4 h-4 text-sky-500" aria-label="Note">
          <path fill-rule="evenodd" clip-rule="evenodd" d="M7 1.3C10.14 1.3 12.7 3.86 12.7 7C12.7 10.14 10.14 12.7 7 12.7C5.48908 12.6974 4.0408 12.096 2.97241 11.0276C1.90403 9.9592 1.30264 8.51092 1.3 7C1.3 3.86 3.86 1.3 7 1.3ZM7 0C3.14 0 0 3.14 0 7C0 10.86 3.14 14 7 14C10.86 14 14 10.86 14 7C14 3.14 10.86 0 7 0ZM8 3H6V8H8V3ZM8 9H6V11H8V9Z"></path>
        </svg>
    },
    tip: {
      outerStyle: "border-emerald-500/20 bg-emerald-50/50 dark:border-emerald-500/30 dark:bg-emerald-500/10",
      innerStyle: "text-emerald-900 dark:text-emerald-200",
      calloutType: "tip",
      icon: <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" className="text-emerald-600 dark:text-emerald-400/80 w-3.5 h-auto" aria-label="Tip">
          <path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path>
        </svg>
    },
    caution: {
      outerStyle: "border-amber-500/20 bg-amber-50/50 dark:border-amber-500/30 dark:bg-amber-500/10",
      innerStyle: "text-amber-900 dark:text-amber-200",
      calloutType: "warning",
      icon: <svg className="flex-none w-5 h-5 text-amber-400 dark:text-amber-300/80" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2" aria-label="Warning">
          <path stroke-linecap="round" stroke-linejoin="round" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path>
        </svg>
    },
    danger: {
      outerStyle: "border-red-500/20 bg-red-50/50 dark:border-red-500/30 dark:bg-red-500/10",
      innerStyle: "text-red-900 dark:text-red-200",
      calloutType: "danger",
      icon: <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="currentColor" className="text-red-600 dark:text-red-400/80 w-4 h-4" aria-label="Danger">
          <path d="M17.1 292c-12.9-22.3-12.9-49.7 0-72L105.4 67.1c12.9-22.3 36.6-36 62.4-36l176.6 0c25.7 0 49.5 13.7 62.4 36L494.9 220c12.9 22.3 12.9 49.7 0 72L406.6 444.9c-12.9 22.3-36.6 36-62.4 36l-176.6 0c-25.7 0-49.5-13.7-62.4-36L17.1 292zm41.6-48c-4.3 7.4-4.3 16.6 0 24l88.3 152.9c4.3 7.4 12.2 12 20.8 12l176.6 0c8.6 0 16.5-4.6 20.8-12L453.4 268c4.3-7.4 4.3-16.6 0-24L365.1 91.1c-4.3-7.4-12.2-12-20.8-12l-176.6 0c-8.6 0-16.5 4.6-20.8 12L58.6 244zM256 128c13.3 0 24 10.7 24 24l0 112c0 13.3-10.7 24-24 24s-24-10.7-24-24l0-112c0-13.3 10.7-24 24-24zM224 352a32 32 0 1 1 64 0 32 32 0 1 1 -64 0z"></path>
        </svg>
    }
  };
  let variant = type;
  let gotInvalidVariant = false;
  if (!asideVariants.includes(type)) {
    gotInvalidVariant = true;
    variant = "danger";
  }
  const iconVariants = ["regular", "solid", "light", "thin", "sharp-solid", "duotone", "brands"];
  if (!iconVariants.includes(iconType)) {
    iconType = "regular";
  }
  return <>
      <div className={`callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border ${asideComponents[variant].outerStyle}`} data-callout-type={asideComponents[variant].calloutType}>
        <div className="mt-0.5 w-4" data-component-part="callout-icon">
          {}
          {icon === "" ? asideComponents[variant].icon : <Icon icon={icon} iconType={iconType} size={14} />}
        </div>
        <div className={`text-sm prose min-w-0 w-full ${asideComponents[variant].innerStyle}`} data-component-part="callout-content">
          {gotInvalidVariant ? <p>
              <span className="font-bold">
                Invalid <code>type</code> passed!
              </span>
              <br />
              <span className="font-bold">Received: </span>
              {type}
              <br />
              <span className="font-bold">Expected one of: </span>
              {asideVariants.join(", ")}
            </p> : <>
              {title && <p className="font-bold">{title}</p>}
              {children}
            </>}
        </div>
      </div>
    </>;
};

The TON node uses the [`log4rs` framework](https://docs.rs/log4rs/1.3.0/log4rs/) for logging.

Logging is configured using a YAML file specified in the `log_config_name` field of the [node configuration](/ecosystem/nodes/rust/node-config). In the Helm chart, this file is mounted at `/main/logs.config.yml`.

A default configuration is bundled with the chart at [`files/logs.config.yml`](https://github.com/RSquad/ton-rust-node/blob/master/helm/ton-rust-node/files/logs.config.yml) and is used if no custom configuration is provided. It can be overridden in one of the following ways:

* inline in `values.yaml`;
* from local file `--set-file logsConfig=path`;
* by referencing an existing [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/).

## Hot reload

The `refresh_rate` field instructs `log4rs` to periodically re-read the configuration file. This allows log levels to be changed without restarting the node – updates are applied within the specified interval.

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
refresh_rate: 30 seconds
```

Supported units: `seconds`, `minutes`, `hours`. If the field is omitted, the config is read only once at startup.

This feature can be used during production debugging: temporarily increase a logger’s level to `debug`, observe the output, then restore the original level without restarting the node.

## Appenders

Appenders define where logs are written. Each appender has a unique name, the YAML key, and a `kind`. Three kinds are supported: `rolling_file`, `console`, and `file`.

A TON node can generate a large volume of logs, especially during synchronization, elections, and catch-up. Appender configuration and log levels should be selected accordingly.

### `rolling_file`

The `rolling_file` appender is the default and recommended option for production. It writes logs to a file with automatic size-based rotation.

The chart creates a dedicated `logs` [`PersistentVolumeClaim`](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) for this appender, ensuring logs remain available locally. Rotation prevents uncontrolled disk usage.

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
appenders:
  rolling_logfile:
    kind: rolling_file
    path: /logs/output.log
    encoder:
      pattern: "{d(%Y-%m-%d %H:%M:%S.%f)} {l} [{t}] {I}: {m}{n}"
    policy:
      kind: compound
      trigger:
        kind: size
        limit: 25 gb
      roller:
        kind: fixed_window
        pattern: '/logs/output_{}.log'
        base: 1
        count: 4
```

* The `policy` section defines when and how rotation occurs.

* Trigger: `size`

  Rotates the log file when it reaches the configured size.

  | Field   | Description                                                                       |
  | ------- | --------------------------------------------------------------------------------- |
  | `limit` | Maximum file size. Supported suffixes: `b`, `kb`, `mb`, `gb`, `tb`; e.g. `25 gb`. |

* Roller: `fixed_window`

  Renames archived files using a pattern with a sliding index.

  | Field     | Required        | Description                                                                                  |
  | --------- | --------------- | -------------------------------------------------------------------------------------------- |
  | `pattern` | yes             | Archive filename template. `{}` is replaced by the index. Append `.gz` to compress archives. |
  | `base`    | no; default `0` | Starting index                                                                               |
  | `count`   | yes             | Maximum number of archive files                                                              |

  Example configuration:

  * `pattern: "/logs/output_{}.log"`
  * `base: 1`
  * `count: 4`

  On rotation:

  1. `output.log` is renamed to `output_1.log`
  2. `output_1.log` → `output_2.log`
  3. `output_2.log` → `output_3.log`
  4. `output_3.log` → `output_4.log`
  5. The previous `output_4.log` is deleted

  Add `.gz` to the pattern to enable compression of archived logs:

  ```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
  pattern: '/logs/output_{}.log.gz'
  ```

Storage sizing:

The Helm value `storage.logs.size` defines the size of the PVC mounted at `/logs`. Rotation settings must fit within this limit. Example of default configuration:

* `limit: 25 gb`
* `count: 4`

Maximum disk usage is 1 active file + 4 archived files = 5 × 25 GB = 125 GB

The default `storage.logs.size` is `150Gi` (\~161 GB), providing headroom. If rotation limits are reduced, for example, 1 GB × 10 archives with `.gz` compression, actual disk usage is lower, allowing a smaller volume size.

### `console`

The `console` appender writes logs to `stdout` or `stderr`. It is suitable when the cluster uses a log collection stack such as Loki, Fluentd, or Elasticsearch, and log storage is handled externally.

At `debug` or `trace` levels, log volume can be high and may overload the collector. Log levels should be configured accordingly. When using console-only logging, disable the logs volume by setting `storage.logs.enabled` to `false`.

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
appenders:
  stdout:
    kind: console
    target: stdout          # or "stderr"
    encoder:
      pattern: "{d(%Y-%m-%d %H:%M:%S.%f)} {l} [{t}] {I}: {m}{n}"
```

### `file`

The `file` appender writes logs to a file without rotation. The file grows indefinitely and may exhaust disk space. Use `rolling_file` instead.

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
appenders:
  logfile:
    kind: file
    path: /logs/output.log
    append: true            # default: true
    encoder:
      pattern: "..."
```

### `filters`

`filters` may be attached to any appender for additional message filtering. Here, threshold filter discards messages below the specified level.

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
appenders:
  stdout:
    kind: console
    filters:
      - kind: threshold
        level: warn
    encoder:
      pattern: "..."
```

## Encoder (log format)

Each appender uses an `encoder` to format log entries. The default encoder kind is `pattern`:

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
encoder:
  pattern: "{d(%Y-%m-%d %H:%M:%S.%f)} {l} [{t}] {I}: {m}{n}"
```

### Format specifiers

| Specifier          | Name       | Description                                                                                           |
| ------------------ | ---------- | ----------------------------------------------------------------------------------------------------- |
| `{d}` / `{d(fmt)}` | date       | Timestamp. Default format is ISO 8601. Custom format uses chrono syntax: `{d(%Y-%m-%d %H:%M:%S.%f)}`. |
| `{l}`              | level      | Log levels: `error`, `warn`, `info`, `debug`, `trace`                                                 |
| `{m}`              | message    | Log message body                                                                                      |
| `{n}`              | newline    | Platform-dependent newline                                                                            |
| `{t}`              | target     | Logger target; module name or explicit `target:` in the log macro.                                    |
| `{I}`              | thread\_id | Numeric thread ID                                                                                     |
| `{T}`              | thread     | Thread name                                                                                           |
| `{f}`              | file       | Source file name                                                                                      |
| `{L}`              | line       | Source line number                                                                                    |
| `{M}`              | module     | Module path                                                                                           |
| `{P}`              | pid        | Process ID                                                                                            |
| `{h(..)}`          | highlight  | Colorizes enclosed text by log levels; applies to console output only.                                |

### Example output

```
2025-01-15 14:30:45.123456 INFO [validator] 140234567890: Block validated successfully
```

<Aside type="note">
  Do not use `{h(...)}` in file appenders. It writes ANSI escape codes to the log output, which makes the file harder to read and search.
</Aside>

## Loggers

### Root logger

The root logger is the default logger. All log records not matched by a named logger are processed by it.

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
root:
  level: error
  appenders:
    - rolling_logfile
```

| Field       | Required | Description                                                  |
| ----------- | -------- | ------------------------------------------------------------ |
| `level`     | yes      | Log level: `off`, `error`, `warn`, `info`, `debug`, `trace`. |
| `appenders` | yes      | List of appender names defined in the appenders section.     |

### Named loggers

Named loggers configure log levels for specific components. The logger name must match the `target` used in the node code.

```yaml theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
loggers:
  validator:
    level: info
```

| Field       | Required | Default               | Description                                                               |
| ----------- | -------- | --------------------- | ------------------------------------------------------------------------- |
| `level`     | no       | inherited from parent | Log level                                                                 |
| `appenders` | no       | `[]`                  | Appenders assigned to this logger.                                        |
| `additive`  | no       | `true`                | If `true`, messages also propagate to the parent logger appenders (root). |

Loggers form a hierarchy using `::`. For example:

* `node`;
* `node::network` is a child of `node`.

If `additive: true`, messages logged by `node::network` are written to:

* the appenders configured for `node::network`;
* the appenders of `node`;
* the appenders of the root logger.

### Log levels

Ordered from most to least verbose:

| Level   | Description                                           |
| ------- | ----------------------------------------------------- |
| `trace` | Most detailed level. Used for execution flow tracing. |
| `debug` | Debug information.                                    |
| `info`  | Informational messages about normal operation.        |
| `warn`  | Indication of a potential problem.                    |
| `error` | Errors that don't stop the node.                      |
| `off`   | Logging disabled.                                     |

### Available logger targets

The following targets can be configured in the `loggers` section:

| Target                      | Description                              |
| --------------------------- | ---------------------------------------- |
| `node`                      | Core node messages                       |
| `boot`                      | Node bootstrap and initialization        |
| `sync`                      | Block synchronization                    |
| `node::network`             | Node networking                          |
| `node::network::neighbours` | Neighbor tracking (high log volume)      |
| `node::network::liteserver` | Liteserver request handling              |
| `node::validator::collator` | Block collation                          |
| `adnl`                      | ADNL network protocol                    |
| `adnl_query`                | ADNL query processing                    |
| `overlay`                   | Overlay networks                         |
| `overlay_broadcast`         | Overlay broadcast messages               |
| `rldp`                      | RLDP protocol (reliable large datagrams) |
| `dht`                       | Distributed hash table                   |
| `block`                     | Block structure and config parsing       |
| `executor`                  | Transaction execution                    |
| `tvm`                       | TON Virtual Machine                      |
| `validator`                 | Validation (general)                     |
| `validator_manager`         | Validator management                     |
| `validate_query`            | Block and query validation               |
| `validate_reject`           | Rejected block and query validation      |
| `catchain`                  | Catchain consensus protocol              |
| `catchain_adnl_overlay`     | ADNL overlay for catchain                |
| `catchain_network`          | Catchain network transport               |
| `validator_session`         | Validator sessions                       |
| `consensus_common`          | Shared consensus logic                   |
| `storage`                   | Data storage                             |
| `index`                     | Data indexing                            |
| `ext_messages`              | External message handling                |
| `telemetry`                 | Telemetry and metrics                    |

<Aside type="note">
  HTTP requests such as JSON-RPC and metrics endpoints are not logged by the node. There is no logger target for HTTP request tracing.
</Aside>