{"id":13471722,"url":"https://github.com/tokio-rs/console","last_synced_at":"2025-05-13T15:04:48.095Z","repository":{"id":39514866,"uuid":"363245888","full_name":"tokio-rs/console","owner":"tokio-rs","description":"a debugger for async rust!","archived":false,"fork":false,"pushed_at":"2025-04-14T21:28:06.000Z","size":10130,"stargazers_count":3902,"open_issues_count":86,"forks_count":158,"subscribers_count":29,"default_branch":"main","last_synced_at":"2025-05-05T22:41:46.257Z","etag":null,"topics":["async","console","debugger","rust","tokio","tokio-console"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tokio-rs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["tokio-rs","hawkw"]}},"created_at":"2021-04-30T19:59:38.000Z","updated_at":"2025-05-02T12:27:28.000Z","dependencies_parsed_at":"2024-03-30T13:22:39.571Z","dependency_job_id":"cb8100de-0a84-4048-afa7-cf56ff0a4b88","html_url":"https://github.com/tokio-rs/console","commit_stats":{"total_commits":423,"total_committers":83,"mean_commits":5.096385542168675,"dds":0.5200945626477541,"last_synced_commit":"ae1723091fcc76597e78bae39129a48d8cd515c9"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokio-rs%2Fconsole","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokio-rs%2Fconsole/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokio-rs%2Fconsole/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokio-rs%2Fconsole/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tokio-rs","download_url":"https://codeload.github.com/tokio-rs/console/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252742583,"owners_count":21797271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","console","debugger","rust","tokio","tokio-console"],"created_at":"2024-07-31T16:00:48.677Z","updated_at":"2025-05-13T15:04:43.085Z","avatar_url":"https://github.com/tokio-rs.png","language":"Rust","readme":"# tokio-console\n\n[![API Documentation(`main`)](https://img.shields.io/netlify/0e5ffd50-e1fa-416e-b147-a04dab28cfb1?label=docs%20%28main%29)][main-docs]\n[![MIT licensed][mit-badge]][mit-url]\n[![Build Status][actions-badge]][actions-url]\n[![Discord chat][discord-badge]][discord-url]\n\n[Chat][discord-url] | [API Documentation (`main` branch)][main-docs]\n\n[main-docs]: https://tokio-console.netlify.app\n[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg\n[mit-url]: LICENSE\n[actions-badge]: https://github.com/tokio-rs/console/workflows/CI/badge.svg\n[actions-url]:https://github.com/tokio-rs/console/actions?query=workflow%3ACI\n[discord-badge]: https://img.shields.io/discord/500028886025895936?logo=discord\u0026label=discord\u0026logoColor=white\n[discord-url]: https://discord.gg/EeF3cQw\n\n## what's all this, then?\n\nthis repository contains an implementation of TurboWish/tokio-console,\na diagnostics and debugging tool for asynchronous Rust programs. the diagnostic\ntoolkit consists of multiple components:\n\n* a **wire protocol for streaming diagnostic data** from instrumented applications\n  to diagnostic tools. the wire format is defined using [gRPC] and [protocol\n  buffers], for efficient transport on the wire and interoperability between\n  different implementations of data producers and consumers.\n\n  the [`console-api`] crate contains generated code for this wire format for\n  projects using the [`tonic`] gRPC implementation. additionally, projects using\n  other gRPC code generators (including those in other languages!) can depend on\n  [the protobuf definitions] themselves.\n\n* **instrumentation for collecting diagnostic data** from a process and exposing\n  it over the wire format. the [`console-subscriber`] crate in this repository\n  contains **an implementation of the instrumentation-side API as a\n  [`tracing-subscriber`] [`Layer`]**, for projects using [Tokio] and\n  [`tracing`].\n\n* tools for **displaying and exploring diagnostic data**, implemented as gRPC\n  clients using the console wire protocol. the [`tokio-console`] crate\n  implements an **an interactive command-line tool** that consumes this data,\n  but **other implementations**, such as graphical or web-based tools, are\n  also possible.\n\n[gRPC]: https://grpc.io/\n[protocol buffers]: https://developers.google.com/protocol-buffers\n[the protobuf definitions]: https://github.com/tokio-rs/console/tree/main/console-api/proto\n[`tonic`]: https://lib.rs/crates/tonic\n[Tokio]: https://tokio.rs\n\n## extremely cool and amazing screenshots\n\nwow! whoa! it's like `top(1)` for tasks!\n\n![task list view](assets/readme/top-for-tasks.png)\n\nviewing details for a single task:\n\n![task details view](assets/readme/task-details.png)\n\n## on the shoulders of giants\n\nthe console is **part of a much larger effort** to improve debugging tooling for\nasync Rust. **a [2019 Google Summer of Code project][gsoc] by Matthias Prechtl**\n([**@matprec**]) implemented an initial prototype, with a focus on interactive log\nviewing. more recently, both **the [Tokio team][tokio-blog] and the [async\nfoundations working group][shiny-future]** have made diagnostics and debugging\ntools a priority for async Rust in 2021 and beyond. in particular, a\n[series][tw-1] of [blog][tw-2] [posts][tw-3] by [**@pnkfelix**] lay out much of\nthe vision that this project seeks to eventually implement.\n\nfurthermore, we're indebted to our antecedents in other programming languages\nand environments for inspiration. this includes tools and systems such as\n[`pprof`], Unix [`top(1)`] and [`htop(1)`], XCode's [Instruments], and many\nothers.\n\n[gsoc]: https://github.com/tokio-rs/console-gsoc\n[tokio-blog]: https://tokio.rs/blog/2020-12-tokio-1-0#tracing\n[shiny-future]: https://rust-lang.github.io/wg-async/vision/submitted_stories/shiny_future/barbara_makes_a_wish.html\n[tw-1]: http://blog.pnkfx.org/blog/2021/04/26/road-to-turbowish-part-1-goals/\n[tw-2]: http://blog.pnkfx.org/blog/2021/04/27/road-to-turbowish-part-2-stories/\n[tw-3]: http://blog.pnkfx.org/blog/2021/05/03/road-to-turbowish-part-3-design/\n[`pprof`]: https://github.com/google/pprof\n[`top(1)`]: https://man7.org/linux/man-pages/man1/top.1.html\n[`htop(1)`]: https://htop.dev/\n[Instruments]: https://developer.apple.com/library/archive/documentation/ToolsLanguages/Conceptual/Xcode_Overview/MeasuringPerformance.html\n[**@matprec**]: https://github.com/matprec\n[**@pnkfelix**]: https://github.com/pnkfelix\n\n## using it\n\n### instrumenting your program\n\nto **instrument an application using Tokio**, add a dependency on the\n[`console-subscriber`] crate, and **add this one-liner** to the top of your\n`main` function:\n\n```rust\nconsole_subscriber::init();\n```\n\nnotes:\n\n* in order to collect task data from Tokio, **the `tokio_unstable` cfg must be\n  enabled**. for example, you could build your project with\n\n  ```shell\n  RUSTFLAGS=\"--cfg tokio_unstable\" cargo build\n  ```\n\n  or add the following to your `.cargo/config.toml` file:\n\n  ```toml\n  [build]\n  rustflags = [\"--cfg\", \"tokio_unstable\"]\n  ```\n\n  For more information on the appropriate location of your `.cargo/config.toml` file,\n  especially when using workspaces, see the\n  [console-subscriber readme](console-subscriber/README.md#enabling-tokio-instrumentation).\n* the `tokio` and `runtime` [`tracing` targets] must be enabled at the [`TRACE`\n  level].\n\n  * if you're using the [`console_subscriber::init()`][init] or\n  [`console_subscriber::Builder`][builder] APIs, these targets are enabled\n  automatically.\n\n  * if you are manually configuring the `tracing` subscriber using the\n  [`EnvFilter`] or [`Targets`] filters from [`tracing-subscriber`], add\n  `\"tokio=trace,runtime=trace\"` to your filter configuration.\n\n  * also, ensure you have not enabled any of the [compile time filter\n    features][compile_time_filters] in your `Cargo.toml`.\n\n### running the console\n\nto **run the console command-line tool**, install `tokio-console` from [crates.io](https://crates.io/crates/tokio-console)\n\n```shell\ncargo install --locked tokio-console\n```\n\nand run locally\n\n```shell\ntokio-console\n```\n\n\u003e **alternative method:** run the tool from a local checkout of this repository\n\u003e\n\u003e ```shell\n\u003e $ cargo run\n\u003e ```\n\nby default, this will attempt to connect to an instrumented application running\non localhost on port 6669. if the application is running somewhere else, or is\nserving the console endpoint on a different port, a target address can be passed\nas an argument to the console (either as an `\u003cIP\u003e:\u003cPORT\u003e` or\n`\u003cDNS_NAME\u003e:\u003cPORT\u003e`). for example:\n\n```shell\ncargo run -- http://my.great.console.app.local:5555\n```\n\nThe console command-line tool supports a number of additional flags to configure\nits behavior. The `help` command will print a list of supported command-line\nflags and arguments:\n\n```console\n$ tokio-console --help\nThe Tokio console: a debugger for async Rust.\n\nUsage: tokio-console[EXE] [OPTIONS] [TARGET_ADDR] [COMMAND]\n\nCommands:\n  gen-config      Generate a `console.toml` config file with the default\n                  configuration values, overridden by any provided\n                  command-line arguments\n  gen-completion  Generate shell completions\n  help            Print this message or the help of the given\n                  subcommand(s)\n\nArguments:\n  [TARGET_ADDR]\n          The address of a console-enabled process to connect to.\n          \n          This may be an IP address and port, or a DNS name.\n          \n          On Unix platforms, this may also be a URI with the `file`\n          scheme that specifies the path to a Unix domain socket, as in\n          `file://localhost/path/to/socket`.\n          \n          When the `vsock` feature is enabled, this may also be a URI\n          with the `vsock` scheme that specifies a vsock connection, as\n          in `vsock://2:6669` to connect to CID 2 port 6669.\n          \n          [default: http://127.0.0.1:6669]\n\nOptions:\n      --log \u003cLOG_FILTER\u003e\n          Log level filter for the console's internal diagnostics.\n          \n          Logs are written to a new file at the path given by the\n          `--log-dir` argument (or its default value), or to the system\n          journal if `systemd-journald` support is enabled.\n          \n          If this is set to 'off' or is not set, no logs will be\n          written.\n          \n          [default: off]\n          \n          [env: RUST_LOG=]\n\n  -W, --warn \u003cWARNINGS\u003e...\n          Enable lint warnings.\n          \n          This is a comma-separated list of warnings to enable.\n          \n          Each warning is specified by its name, which is one of:\n          \n          * `self-wakes` -- Warns when a task wakes itself more than a\n          certain percentage of its total wakeups. Default percentage is\n          50%.\n          \n          * `lost-waker` -- Warns when a task is dropped without being\n          woken.\n          \n          * `never-yielded` -- Warns when a task has never yielded.\n          \n          * `auto-boxed-future` -- Warnings when the future driving a\n          task was automatically boxed by the runtime because it was\n          large.\n          \n          * `large-future` -- Warnings when the future driving a task\n          occupies a large amount of stack space.\n          \n          [default: self-wakes lost-waker never-yielded\n          auto-boxed-future large-future]\n          [possible values: self-wakes, lost-waker, never-yielded,\n          auto-boxed-future, large-future]\n\n  -A, --allow \u003cALLOW_WARNINGS\u003e...\n          Allow lint warnings.\n          \n          This is a comma-separated list of warnings to allow.\n          \n          Each warning is specified by its name, which is one of:\n          \n          * `self-wakes` -- Warns when a task wakes itself more than a\n          certain percentage of its total wakeups. Default percentage is\n          50%.\n          \n          * `lost-waker` -- Warns when a task is dropped without being\n          woken.\n          \n          * `never-yielded` -- Warns when a task has never yielded.\n          \n          * `auto-boxed-future` -- Warnings when the future driving a\n          task was automatically boxed by the runtime because it was\n          large.\n          \n          * `large-future` -- Warnings when the future driving a task\n          occupies a large amount of stack space.\n          \n          If this is set to `all`, all warnings are allowed.\n          \n          [possible values: all, self-wakes, lost-waker, never-yielded,\n          large-future, auto-boxed-future]\n\n      --log-dir \u003cLOG_DIRECTORY\u003e\n          Path to a directory to write the console's internal logs to.\n          \n          [default: /tmp/tokio-console/logs]\n\n      --lang \u003cLANG\u003e\n          Overrides the terminal's default language\n          \n          [env: LANG=en_US.UTF-8]\n\n      --ascii-only \u003cASCII_ONLY\u003e\n          Explicitly use only ASCII characters\n          \n          [possible values: true, false]\n\n      --no-colors\n          Disable ANSI colors entirely\n\n      --colorterm \u003ctruecolor\u003e\n          Overrides the value of the `COLORTERM` environment variable.\n          \n          If this is set to `24bit` or `truecolor`, 24-bit RGB color\n          support will be enabled.\n          \n          [env: COLORTERM=truecolor]\n          [possible values: 24bit, truecolor]\n\n      --palette \u003cPALETTE\u003e\n          Explicitly set which color palette to use\n          \n          [possible values: 8, 16, 256, all, off]\n\n      --no-duration-colors \u003cCOLOR_DURATIONS\u003e\n          Disable color-coding for duration units\n          \n          [possible values: true, false]\n\n      --no-terminated-colors \u003cCOLOR_TERMINATED\u003e\n          Disable color-coding for terminated tasks\n          \n          [possible values: true, false]\n\n      --retain-for \u003cRETAIN_FOR\u003e\n          How long to continue displaying completed tasks and dropped\n          resources after they have been closed.\n          \n          This accepts either a duration, parsed as a combination of\n          time spans (such as `5days 2min 2s`), or `none` to disable\n          removing completed tasks and dropped resources.\n          \n          Each time span is an integer number followed by a suffix.\n          Supported suffixes are:\n          \n          * `nsec`, `ns` -- nanoseconds\n          \n          * `usec`, `us` -- microseconds\n          \n          * `msec`, `ms` -- milliseconds\n          \n          * `seconds`, `second`, `sec`, `s`\n          \n          * `minutes`, `minute`, `min`, `m`\n          \n          * `hours`, `hour`, `hr`, `h`\n          \n          * `days`, `day`, `d`\n          \n          * `weeks`, `week`, `w`\n          \n          * `months`, `month`, `M` -- defined as 30.44 days\n          \n          * `years`, `year`, `y` -- defined as 365.25 days\n          \n          [default: 6s]\n\n  -h, --help\n          Print help (see a summary with '-h')\n\n  -V, --version\n          Print version\n\n```\n\n#### running the console on windows\n\nThe console uses the UTF-8 character set to display graphs and other visual\nfeatures in the terminal. In order to display this rich terminal UI on Windows,\nit's necessary to use a UTF-8-enabled terminal emulator, such as the new\n[Windows Terminal](https://learn.microsoft.com/en-us/windows/terminal/install).\n\nIf you're using a terminal that supports UTF-8, make sure to explicitly call\ntokio-console with the UTF-8 language flag set:\n```shell\ntokio-console --lang en_US.UTF-8\n```\n\n## for development\n\nthe `console-subscriber/examples` directory contains **some potentially useful\ntools**:\n\n* `app.rs`: a very simple example program that spawns a bunch of tasks in a loop\n  forever\n* `dump.rs`: a simple CLI program that dumps the data stream from a `Tasks`\n  server\n\nExamples can be executed with:\n\n```shell\ncargo run --example $name\n```\n\n[`tracing`]: https://lib.rs/crates/tracing\n[`tracing-subscriber`]: https://lib.rs/crates/tracing-subscriber\n[`console-api`]: ./console-api\n[`console-subscriber`]: ./console-subscriber\n[`tokio-console`]: ./tokio-console\n[`Layer`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/layer/trait.Layer.html\n[`tracing` targets]: https://docs.rs/tracing/latest/tracing/struct.Metadata.html\n[`TRACE` level]: https://docs.rs/tracing/latest/tracing/struct.Level.html#associatedconstant.TRACE\n[builder]: https://docs.rs/console-subscriber/latest/console_subscriber/struct.Builder.html\n[init]: https://docs.rs/console-subscriber/latest/console_subscriber/fn.init.html\n[`EnvFilter`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html\n[`Targets`]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/targets/struct.Targets.html\n[compile_time_filters]: https://docs.rs/tracing/latest/tracing/level_filters/index.html#compile-time-filters\n","funding_links":["https://github.com/sponsors/tokio-rs","https://github.com/sponsors/hawkw"],"categories":["Rust","\u003ca name=\"Rust\"\u003e\u003c/a\u003eRust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokio-rs%2Fconsole","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftokio-rs%2Fconsole","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokio-rs%2Fconsole/lists"}