Module tokio_console::config_reference

source ·
Expand description

§Configuration Reference

tokio-console’s behavior can be configured in two ways: via command-line arguments, or using a TOML config file.

§Command-Line Arguments

The following is the complete list of command-line arguments accepted by tokio-console:

The Tokio console: a debugger for async Rust.

Usage: tokio-console[EXE] [OPTIONS] [TARGET_ADDR] [COMMAND]

Commands:
  gen-config      Generate a `console.toml` config file with the default
                  configuration values, overridden by any provided
                  command-line arguments
  gen-completion  Generate shell completions
  help            Print this message or the help of the given
                  subcommand(s)

Arguments:
  [TARGET_ADDR]
          The address of a console-enabled process to connect to.
          
          This may be an IP address and port, or a DNS name.
          
          On Unix platforms, this may also be a URI with the `file`
          scheme that specifies the path to a Unix domain socket, as in
          `file://localhost/path/to/socket`.
          
          [default: http://127.0.0.1:6669]

Options:
      --log <LOG_FILTER>
          Log level filter for the console's internal diagnostics.
          
          Logs are written to a new file at the path given by the
          `--log-dir` argument (or its default value), or to the system
          journal if `systemd-journald` support is enabled.
          
          If this is set to 'off' or is not set, no logs will be
          written.
          
          [default: off]
          
          [env: RUST_LOG=]

  -W, --warn <WARNINGS>...
          Enable lint warnings.
          
          This is a comma-separated list of warnings to enable.
          
          Each warning is specified by its name, which is one of:
          
          * `self-wakes` -- Warns when a task wakes itself more than a
          certain percentage of its total wakeups. Default percentage is
          50%.
          
          * `lost-waker` -- Warns when a task is dropped without being
          woken.
          
          * `never-yielded` -- Warns when a task has never yielded.
          
          * `auto-boxed-future` -- Warnings when the future driving a
          task was automatically boxed by the runtime because it was
          large.
          
          * `large-future` -- Warnings when the future driving a task
          occupies a large amount of stack space.
          
          [default: self-wakes lost-waker never-yielded
          auto-boxed-future large-future]
          [possible values: self-wakes, lost-waker, never-yielded,
          auto-boxed-future, large-future]

  -A, --allow <ALLOW_WARNINGS>...
          Allow lint warnings.
          
          This is a comma-separated list of warnings to allow.
          
          Each warning is specified by its name, which is one of:
          
          * `self-wakes` -- Warns when a task wakes itself more than a
          certain percentage of its total wakeups. Default percentage is
          50%.
          
          * `lost-waker` -- Warns when a task is dropped without being
          woken.
          
          * `never-yielded` -- Warns when a task has never yielded.
          
          * `auto-boxed-future` -- Warnings when the future driving a
          task was automatically boxed by the runtime because it was
          large.
          
          * `large-future` -- Warnings when the future driving a task
          occupies a large amount of stack space.
          
          If this is set to `all`, all warnings are allowed.
          
          [possible values: all, self-wakes, lost-waker, never-yielded,
          large-future, auto-boxed-future]

      --log-dir <LOG_DIRECTORY>
          Path to a directory to write the console's internal logs to.
          
          [default: /tmp/tokio-console/logs]

      --lang <LANG>
          Overrides the terminal's default language
          
          [env: LANG=en_US.UTF-8]

      --ascii-only <ASCII_ONLY>
          Explicitly use only ASCII characters
          
          [possible values: true, false]

      --no-colors
          Disable ANSI colors entirely

      --colorterm <truecolor>
          Overrides the value of the `COLORTERM` environment variable.
          
          If this is set to `24bit` or `truecolor`, 24-bit RGB color
          support will be enabled.
          
          [env: COLORTERM=truecolor]
          [possible values: 24bit, truecolor]

      --palette <PALETTE>
          Explicitly set which color palette to use
          
          [possible values: 8, 16, 256, all, off]

      --no-duration-colors <COLOR_DURATIONS>
          Disable color-coding for duration units
          
          [possible values: true, false]

      --no-terminated-colors <COLOR_TERMINATED>
          Disable color-coding for terminated tasks
          
          [possible values: true, false]

      --retain-for <RETAIN_FOR>
          How long to continue displaying completed tasks and dropped
          resources after they have been closed.
          
          This accepts either a duration, parsed as a combination of
          time spans (such as `5days 2min 2s`), or `none` to disable
          removing completed tasks and dropped resources.
          
          Each time span is an integer number followed by a suffix.
          Supported suffixes are:
          
          * `nsec`, `ns` -- nanoseconds
          
          * `usec`, `us` -- microseconds
          
          * `msec`, `ms` -- milliseconds
          
          * `seconds`, `second`, `sec`, `s`
          
          * `minutes`, `minute`, `min`, `m`
          
          * `hours`, `hour`, `hr`, `h`
          
          * `days`, `day`, `d`
          
          * `weeks`, `week`, `w`
          
          * `months`, `month`, `M` -- defined as 30.44 days
          
          * `years`, `year`, `y` -- defined as 365.25 days
          
          [default: 6s]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

This text can also be displayed by running tokio-console help.

§Configuration File

In addition to command-line arguments, the console can also be configured by a TOML configuration file. All settings that can be configured by the command line (with the exception of the target address to connect to) can also be set by the config file.

The tokio-console gen-config subcommand generates a config file based on the default configuration, overridden by any command-line arguments passed by the user.

§Examples

The default configuration:

default_target_addr = 'http://127.0.0.1:6669/'
log = 'off'
warnings = [
    'self-wakes',
    'lost-waker',
    'never-yielded',
    'auto-boxed-future',
    'large-future',
]
log_directory = '/tmp/tokio-console/logs'
retention = '6s'

[charset]
lang = 'en_US.UTF-8'
ascii_only = false

[colors]
enabled = true
truecolor = true
palette = 'all'

[colors.enable]
durations = true
terminated = true

§Config File Locations

Configuration files are read from two locations:

  1. A tokio-console directory in the system default configuration directory (as determined by the dirs crate). This directory depends on the operating system:

    PlatformValue
    Linux$XDG_CONFIG_HOME/tokio-console or $HOME/.config/tokio-console
    macOS$HOME/Library/Application Support/tokio-console
    Windows{FOLDERID_RoamingAppData}\tokio-console

  2. The current working directory.

    If both the current working directory and the system default config directory contain a console.toml file, any values set in the current working directory will override those set in the system config directory. This allows overriding the user-level default configuration with project specific configurations. Some projects may wish to check project-specific configurations into source control so that they may be shared by multiple developers.

Any command-line arguments will override the configuration set in both config files.