From 3c194ef2c34db9af5d5938a714185b50ce78d98f Mon Sep 17 00:00:00 2001
From: Jan Teske <jteske@posteo.net>
Date: Fri, 9 Dec 2022 13:13:13 +0100
Subject: [PATCH] doc/developer: update tokio-console guide docs

---
 Cargo.lock                           |  4 ++--
 doc/developer/guide-tokio-console.md | 31 ++++++++++++++++++++--------
 src/ore/Cargo.toml                   |  2 +-
 src/ore/src/tracing/mod.rs           |  2 +-
 4 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 03dfae74e7b7d..d21bfa9a4e59e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1175,7 +1175,7 @@ dependencies = [
 [[package]]
 name = "console-api"
 version = "0.4.0"
-source = "git+https://github.com/benesch/tokio-console.git?branch=uds#b409aa1a262f9196630c21406c8d11e61277cdcd"
+source = "git+https://github.com/MaterializeInc/console.git#bac69ecb570b7e466b2a254a9f9bf28ac0f3d95b"
 dependencies = [
  "prost",
  "prost-types",
@@ -1186,7 +1186,7 @@ dependencies = [
 [[package]]
 name = "console-subscriber"
 version = "0.1.8"
-source = "git+https://github.com/benesch/tokio-console.git?branch=uds#b409aa1a262f9196630c21406c8d11e61277cdcd"
+source = "git+https://github.com/MaterializeInc/console.git#bac69ecb570b7e466b2a254a9f9bf28ac0f3d95b"
 dependencies = [
  "console-api",
  "crossbeam-channel",
diff --git a/doc/developer/guide-tokio-console.md b/doc/developer/guide-tokio-console.md
index 9438f5cee4670..dc83716d8071b 100644
--- a/doc/developer/guide-tokio-console.md
+++ b/doc/developer/guide-tokio-console.md
@@ -1,32 +1,45 @@
 # Developer guide: `tokio-console`
 
-This guide details how to run `tokio-console` with `materialized`
+This guide details how to run `tokio-console` with Materialize.
 
 ## Overview
 
-First, install `tokio-console`:
+First, install `tokio-console`. We require support for Unix domain sockets, [which is still pending
+upstream][uds-pr], so we need to install from a fork for now.
 
-```
-cargo install tokio-console
+```text
+cargo install tokio-console --git https://github.com/MaterializeInc/console.git
 ```
 
 Then run `environmentd`:
 
-```
+```text
 ./bin/environmentd --tokio-console
 ```
 
-(note that this may slow down `environmentd` a lot, as it increases the amount of tracing by a lot,
-and may inadvertently turn on debug logging for `rdkafka`)
+(Note that this may slow down `environmentd` a lot, as it increases the amount of tracing by a lot,
+and may inadvertently turn on debug logging for `rdkafka`.)
 
-Then, in a different tmux pane/terminal, run:
+In the output of the above command, take note of the `tokio-console` listen addresses for the
+different processes, e.g.:
 
+```text
+environmentd: [...]  INFO mz_ore::tracing: starting tokio console on http://127.0.0.1:6669
+compute-cluster-u1-replica-1: [...]  INFO mz_ore::tracing: starting tokio console on /var/folders/30/[...]3ee9
+compute-cluster-s1-replica-2: [...]  INFO mz_ore::tracing: starting tokio console on /var/folders/30/[...]f5b6
+compute-cluster-s2-replica-3: [...]  INFO mz_ore::tracing: starting tokio console on /var/folders/30/[...]7af2
 ```
-tokio-console
+
+Then, in a different tmux pane/terminal, run the `tokio-console` command with the listen address of
+your process of interest:
+
+```text
+tokio-console <listen-address>
 ```
 
 This [README] has some docs on how to navigate the ui.
 
+[uds-pr]: https://github.com/tokio-rs/console/pull/388
 [README]: https://github.com/tokio-rs/console/tree/main/tokio-console
 
 ### Notes on compilation times:
diff --git a/src/ore/Cargo.toml b/src/ore/Cargo.toml
index 335f43679019e..a22a5013ddcf0 100644
--- a/src/ore/Cargo.toml
+++ b/src/ore/Cargo.toml
@@ -56,7 +56,7 @@ hyper = { version = "0.14.23", features = ["http1", "server"], optional = true }
 hyper-tls = { version = "0.5.0", optional = true }
 opentelemetry = { git = "https://github.com/MaterializeInc/opentelemetry-rust.git", features = ["rt-tokio", "trace"], optional = true }
 opentelemetry-otlp = { git = "https://github.com/MaterializeInc/opentelemetry-rust.git", optional = true }
-console-subscriber = { git = "https://github.com/benesch/tokio-console.git", branch = "uds", optional = true }
+console-subscriber = { git = "https://github.com/MaterializeInc/console.git", optional = true }
 sentry-tracing = { version = "0.29.0", optional = true }
 
 [dev-dependencies]
diff --git a/src/ore/src/tracing/mod.rs b/src/ore/src/tracing/mod.rs
index 5e8f861369740..d0e82ff0e1012 100644
--- a/src/ore/src/tracing/mod.rs
+++ b/src/ore/src/tracing/mod.rs
@@ -381,7 +381,7 @@ where
     if let Some(console_config) = config.tokio_console {
         let endpoint = match console_config.listen_addr {
             SocketAddr::Inet(addr) => format!("http://{addr}"),
-            SocketAddr::Unix(addr) => addr.to_string(),
+            SocketAddr::Unix(addr) => format!("file://localhost{addr}"),
         };
         tracing::info!("starting tokio console on {endpoint}");
     }