tokio-console: ver en vivo la población de tareas del runtime

La primera lección dejó una carencia concreta: un depurador de pila no puede listar las diez mil tareas dormidas de un servidor, ni decirte cuánto tarda cada sondeo, ni cuál se auto-despierta en bucle quemando un hilo. Si la información no está en la pila sino en el runtime, la herramienta tiene que interrogar al runtime. Eso es tokio-console: un instrumento que se conecta al scheduler de Tokio y muestra, en una interfaz de terminal viva y refrescándose, la población completa de tareas —cada una con su estado, su tiempo total ocupada, su número de poll, su poll time máximo y sus wakeups— junto con los recursos que retienen, como mutexes y semáforos. Es, casi literalmente, el top de las tareas async: donde top te enseña los procesos que compiten por la CPU, tokio-console te enseña las tareas que compiten por tus hilos trabajadores. Y con esa vista, patologías que eran invisibles se vuelven obvias de un vistazo: la tarea que nunca cede, la que se despierta a sí misma sin avanzar, la que se durmió y jamás volvió.

Conectar la consola al runtime

tokio-console tiene dos mitades: una subscriber que vive dentro de tu proceso y publica métricas por gRPC, y un cliente TUI aparte que se conecta y las dibuja. La instrumentación se apoya en el mismo tracing de la lección anterior, más contadores internos que Tokio solo expone bajo una bandera de compilación inestable:

[dependencies]
console-subscriber = "0.4"
tokio = { version = "1", features = ["full", "tracing"] }

#[tokio::main]
async fn main() {
    console_subscriber::init(); // publica en el puerto 6669 por defecto
    // ... tu aplicacion ...
}

La pieza que se olvida siempre es el flag: Tokio solo emite la instrumentación de tareas si compilas con tokio_unstable activo. Sin él, la consola arranca pero no ve ninguna tarea.

RUSTFLAGS="--cfg tokio_unstable" cargo run
# en otra terminal:
tokio-console            # se conecta a http://127.0.0.1:6669

Las métricas por tarea, y qué cuenta cada una

La vista principal es una tabla con una fila por tarea. Cada columna responde a una pregunta que el depurador no podía:

La consola también resalta con avisos las tareas cuyo comportamiento es sospechoso: marca las que han tenido polls anormalmente largos (“this task has lost its waker” o avisos de poll time elevado) y las que acumulan self-wakes. No tienes que calcular nada: la herramienta subraya la anomalía y tú vas a mirar esa fila.

Cazar la tarea que no coopera

El modelo async es un pacto de cooperación: cada tarea debe ceder con frecuencia en un .await para que las demás avancen. tokio-console es el instrumento que audita ese pacto y señala a quien lo rompe. Dos delitos son los más comunes.

El primero es no ceder nunca: una tarea que ejecuta un bucle de CPU largo o llama a una API bloqueante dentro de un poll. No hay .await que la suspenda, así que retiene el hilo trabajador de principio a fin. En la consola aparece con un poll time máximo enorme —el poll que nunca termina— y con el busy disparado. Todas las tareas que compartían ese hilo se ven hambrientas, sin culpa propia.

// Delito: un poll que no cede. Su poll time maximo sera enorme en la consola.
async fn agregar(datos: &[u64]) -> u64 {
    let mut acc = 0;
    for &x in datos {          // millones de iteraciones sin un solo await
        acc = acc.wrapping_add(fib(x)); // CPU pura: nunca cede el hilo
    }
    acc
}

El segundo es auto-despertarse en bucle: una tarea, a menudo un Future escrito a mano, que devuelve Poll::Ready de un waker sin haber progresado, o que se reprograma cada vez que la sondean. En la consola se delata por un número de polls que sube como la espuma y una cifra alta de self-wakes, mientras el trabajo real no avanza. Consume CPU fingiendo estar ocupada.

flowchart LR
APP[Tu app con console-subscriber] -->|metricas por gRPC| SRV[Puerto 6669]
SRV --> TUI[tokio-console TUI]
TUI --> T1[Tarea sana casi todo idle]
TUI --> T2[Tarea con poll time enorme no cede]
TUI --> T3[Tarea con self-wakes en bucle]
style APP fill:#89b4fa,color:#11111b
style T1 fill:#a6e3a1,color:#11111b
style T2 fill:#f38ba8,color:#11111b
style T3 fill:#fab387,color:#11111b

Más allá de las tareas, la consola tiene una vista de recursos: cada Mutex, RwLock o Semaphore de Tokio aparece con cuántas tareas esperan por él y cuánto llevan esperando. Si una operación va lenta y sospechas de contención, aquí ves de un vistazo qué candado tiene cola y qué tareas están detenidas en ella. Es la antesala del profiling de la lección cinco: la consola no solo te dice que algo va mal, sino dónde se están acumulando las tareas.