DEV Community: Juan Gómez

Construye un agente de desarrollo .NET, Parte 2: dale voz

Juan Gómez — Thu, 22 Oct 2026 14:00:00 +0000

Construye un agente de desarrollo .NET, Parte 2: dale voz

La primera vez que mi agente de desarrollo me respondió en voz alta, tardó sesenta y ocho segundos en decirme que habían fallado cuatro tests.

La respuesta era correcta, y completa: los cuatro nombres de test leídos enteros, AddedLines_reports_new_file_numbers_across_hunks incluido, cada uno con su número de línea y su valor esperado, y al final un párrafo ofreciendo revisar el parser. En pantalla, esa respuesta se lee de un vistazo. Con audífonos, es un minuto entero quieto, esperando la única frase que importaba, que llegó al final: todos los fallos estaban desfasados por uno.

Conectar dictado y síntesis de voz a un agente lleva una tarde. Este post trata de lo que pasa después de esa tarde, cuando descubres dos cosas. Una respuesta escrita para leerse tiene la forma equivocada para escucharse. Y la transcripción que recibe tu agente se equivoca más o menos en una de cada dos palabras. Los dos son problemas de diseño, no de audio, y todo lo que sigue está medido sobre el agente de la Parte 1.

Dónde dejó la Parte 1 al agente

Construye un agente de desarrollo .NET, Parte 1: enséñale tu flujo de trabajo real montó tres herramientas tipadas sobre un ciclo de tool_use de Claude: git_status, dotnet_build y dotnet_test, cada una filtrando la salida de su comando hasta dejar solo lo que un modelo necesita. Las tres pasan tal cual, con una excepción: el método RunAsync de la Parte 1 tenía un bug que solo aparece en una máquina con dos SDKs de .NET, y escribir este post lo destapó. La Parte 1 ya tiene la corrección; los detalles están cerca del final.

Este es el ciclo completo:

Mantienes una tecla, hablas, sueltas.
Un Whisper local convierte el audio en texto.
El agente trabaja con las herramientas de la Parte 1 y una nueva.
Una voz de Piper, también local, lee la respuesta, y lo que no conviene leer va a la pantalla.

Todo lo que toca audio corre en tu máquina, con modelos de código abierto, y no necesitas cuenta en ningún servicio salvo el de Claude.

Dos contenedores

El dictado lo hace whisper-server, de whisper.cpp: recibe un WAV por HTTP y devuelve JSON. La síntesis la hace Piper, cuyo servidor HTTP recibe JSON y devuelve un WAV. Los dos corren en CPU.

services:
  whisper:
    # v1.9.5. La imagen se etiqueta por commit; ":main" cambia todos los días.
    image: ghcr.io/ggml-org/whisper.cpp:main-d1be6fde11ac6e0407606b4e42fe72d34add8037
    # El entrypoint de la imagen es `bash -c`, que solo ejecuta su PRIMER argumento. Un
    # texto plano se parte en palabras: cada flag después de "whisper-server" se pierde en
    # silencio, y arranca con el modelo que trae la imagen, escuchando en 127.0.0.1.
    # Una lista de un solo elemento mantiene la línea de comando entera como ese argumento.
    command: ["whisper-server --host 0.0.0.0 --port 8080 --model /models/ggml-${WHISPER_MODEL:-tiny.en}.bin --threads 4"]
    volumes:
      - ./models:/models:ro
    ports:
      - "127.0.0.1:8080:8080"

  piper:
    build: ./piper
    ports:
      - "127.0.0.1:5000:5000"

Piper no tiene una imagen oficial con su servidor HTTP, así que le toca un piper/Dockerfile de cinco líneas. La voz se descarga al construir la imagen, para que el contenedor arranque sin red:

FROM python:3.12-slim
RUN pip install --no-cache-dir "piper-tts[http]==1.8.0"
WORKDIR /voices
# La voz queda dentro de la imagen, así el contenedor arranca sin red.
RUN python -m piper.download_voices en_US-lessac-medium --data-dir /voices
EXPOSE 5000
CMD ["python", "-m", "piper.http_server", "--host", "0.0.0.0", "--port", "5000", "--data-dir", "/voices", "-m", "en_US-lessac-medium"]

El modelo de Whisper es un archivo que descargas una vez en models/:

curl -L -o models/ggml-tiny.en.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin
docker compose up -d

El comentario sobre command: está ahí porque me costó una hora. La imagen de whisper.cpp usa bash -c como entrypoint, y bash -c solo ejecuta su primer argumento. Si escribes el comando como texto plano, Compose lo parte en palabras: bash -c recibe whisper-server como script y el resto de los flags como parámetros que nadie lee. El servidor arranca igual, con el modelo que trae la imagen y escuchando en 127.0.0.1, donde nada fuera del contenedor puede alcanzarlo. Si lo escribes como texto de varias líneas, falla de forma más discreta: el salto de línea termina el comando, así que el servidor escucha donde le pediste, pero carga el modelo de la imagen. Mi primera prueba pidió large-v3-turbo, recibió base.en, y pasé un buen rato culpando a mi acento. La lista de un solo elemento mantiene la línea de comando entera.

Fija también la imagen por commit. :main se reconstruye a diario, y la etiqueta de arriba es la que se construyó desde la versión v1.9.5.

Captura: pulsar para hablar, en el formato que pide Whisper

Del lado de .NET hace falta una sola dependencia nativa para el audio. PortAudioSharp2 trae los binarios de PortAudio para Windows, Linux y macOS dentro del paquete, así que no hay nada que instalar:

dotnet new console -n VoiceDevAgent
dotnet add package Anthropic --version 12.57.0
dotnet add package PortAudioSharp2 --version 1.0.6

La grabación es a 16 kHz, mono y 16 bits, exactamente lo que consume Whisper, así que nadie remuestrea nada. PortAudio entrega el audio desde su propio hilo mediante un callback, y ese callback tiene un único trabajo: copiar las muestras a algún lado y volver, sin esperar nunca al resto del programa. Un Channel<T> es el lugar indicado, porque escribir en uno sin límite nunca bloquea.

using System.Buffers.Binary;
using System.Runtime.InteropServices;
using System.Threading.Channels;
using PortAudioSharp;
using PaStream = PortAudioSharp.Stream;

/// <summary>Captura al pulsar para hablar: 16 kHz, mono, 16 bits, el formato que pide Whisper, así nadie remuestrea.</summary>
sealed class Microphone
{
    public const int SampleRate = 16_000;

    public static async Task<byte[]> RecordAsync(Func<CancellationToken, Task> waitForStop, CancellationToken ct)
    {
        // El callback corre en el hilo de audio de PortAudio. Nunca debe esperar a nada de lo
        // que hace el resto del programa, así que solo copia las muestras a un canal sin
        // límite, cuyas escrituras nunca bloquean.
        Channel<short[]> chunks = Channel.CreateUnbounded<short[]>(new() { SingleReader = true, SingleWriter = true });

        PaStream.Callback callback = (IntPtr input, IntPtr output, uint frameCount,
            ref StreamCallbackTimeInfo timeInfo, StreamCallbackFlags flags, IntPtr userData) =>
        {
            short[] chunk = new short[frameCount];
            Marshal.Copy(input, chunk, 0, (int)frameCount);
            chunks.Writer.TryWrite(chunk);
            return StreamCallbackResult.Continue;
        };

        int device = PortAudio.DefaultInputDevice;
        if (device == PortAudio.NoDevice) throw new InvalidOperationException("No hay dispositivo de entrada.");

        StreamParameters parameters = new()
        {
            device = device,
            channelCount = 1,
            sampleFormat = SampleFormat.Int16,
            suggestedLatency = PortAudio.GetDeviceInfo(device).defaultLowInputLatency,
            hostApiSpecificStreamInfo = IntPtr.Zero,
        };

        using (PaStream stream = new(parameters, null, SampleRate, 0, StreamFlags.ClipOff, callback, null!))
        {
            stream.Start();
            try
            {
                await waitForStop(ct);
            }
            finally
            {
                stream.Stop();          // espera a que termine el último callback
                chunks.Writer.Complete();
            }
        }

        List<short> samples = [];
        await foreach (short[] chunk in chunks.Reader.ReadAllAsync(CancellationToken.None))
            samples.AddRange(chunk);

        return Wav.Encode([.. samples], SampleRate);
    }
}

/// <summary>Reproduce PCM mono de 16 bits y se detiene en cuanto se cancela el token.</summary>
static class Speaker
{
    static readonly short[] Silence = new short[4096];

    public static async Task PlayAsync(byte[] wav, CancellationToken ct)
    {
        (short[] samples, int sampleRate) = Wav.Decode(wav);
        int position = 0;
        TaskCompletionSource finished = new(TaskCreationOptions.RunContinuationsAsynchronously);

        PaStream.Callback callback = (IntPtr input, IntPtr output, uint frameCount,
            ref StreamCallbackTimeInfo timeInfo, StreamCallbackFlags flags, IntPtr userData) =>
        {
            int remaining = samples.Length - position;
            int count = Math.Min(remaining, (int)frameCount);
            if (count > 0) Marshal.Copy(samples, position, output, count);

            // Rellena el último búfer con silencio en vez de reproducir memoria vieja,
            // sin asignar memoria en el hilo de audio.
            for (int padded = count; padded < frameCount; )
            {
                int n = Math.Min(Silence.Length, (int)frameCount - padded);
                Marshal.Copy(Silence, 0, output + padded * sizeof(short), n);
                padded += n;
            }

            position += count;
            return position >= samples.Length ? StreamCallbackResult.Complete : StreamCallbackResult.Continue;
        };

        int device = PortAudio.DefaultOutputDevice;
        if (device == PortAudio.NoDevice) throw new InvalidOperationException("No hay dispositivo de salida.");

        StreamParameters parameters = new()
        {
            device = device,
            channelCount = 1,
            sampleFormat = SampleFormat.Int16,
            suggestedLatency = PortAudio.GetDeviceInfo(device).defaultHighOutputLatency,
            hostApiSpecificStreamInfo = IntPtr.Zero,
        };

        using PaStream stream = new(null, parameters, sampleRate, 0, StreamFlags.ClipOff, callback, null!);
        stream.SetFinishedCallback(_ => finished.TrySetResult());
        stream.Start();

        try
        {
            await finished.Task.WaitAsync(ct);
        }
        catch (OperationCanceledException)
        {
            // Interrupción: descarta el audio del búfer en vez de reproducirlo hasta el final.
            // El callback de fin igual se dispara después; completar una tarea ya abandonada
            // no tiene efecto.
            stream.Abort();
        }
    }
}

static class Wav
{
    public static byte[] Encode(short[] samples, int sampleRate)
    {
        byte[] wav = new byte[44 + samples.Length * 2];
        Span<byte> h = wav;
        "RIFF"u8.CopyTo(h);
        BinaryPrimitives.WriteInt32LittleEndian(h[4..], wav.Length - 8);
        "WAVEfmt "u8.CopyTo(h[8..]);
        BinaryPrimitives.WriteInt32LittleEndian(h[16..], 16);              // tamaño del chunk fmt
        BinaryPrimitives.WriteInt16LittleEndian(h[20..], 1);               // PCM
        BinaryPrimitives.WriteInt16LittleEndian(h[22..], 1);               // mono
        BinaryPrimitives.WriteInt32LittleEndian(h[24..], sampleRate);
        BinaryPrimitives.WriteInt32LittleEndian(h[28..], sampleRate * 2);  // bytes por segundo
        BinaryPrimitives.WriteInt16LittleEndian(h[32..], 2);               // alineación de bloque
        BinaryPrimitives.WriteInt16LittleEndian(h[34..], 16);              // bits por muestra
        "data"u8.CopyTo(h[36..]);
        BinaryPrimitives.WriteInt32LittleEndian(h[40..], samples.Length * 2);
        MemoryMarshal.AsBytes(samples.AsSpan()).CopyTo(h[44..]);
        return wav;
    }

    /// <summary>Recorre los chunks en vez de suponer una cabecera de 44 bytes: la de Piper lo es, otras no.</summary>
    public static (short[] Samples, int SampleRate) Decode(byte[] wav)
    {
        ReadOnlySpan<byte> s = wav;
        if (!s[..4].SequenceEqual("RIFF"u8) || !s[8..12].SequenceEqual("WAVE"u8))
            throw new InvalidDataException("No es un archivo RIFF/WAVE.");

        int sampleRate = 0, offset = 12;
        while (offset + 8 <= s.Length)
        {
            ReadOnlySpan<byte> id = s.Slice(offset, 4);
            // Quien escribe en streaming pone aquí 0xFFFFFFFF ("desconocido"): toma el resto.
            uint declared = BinaryPrimitives.ReadUInt32LittleEndian(s[(offset + 4)..]);
            int size = (int)Math.Min(declared, (uint)(s.Length - offset - 8));
            ReadOnlySpan<byte> body = s.Slice(offset + 8, size);

            if (id.SequenceEqual("fmt "u8))
            {
                if (body.Length < 16) throw new InvalidDataException("Chunk fmt demasiado corto.");
                short channels = BinaryPrimitives.ReadInt16LittleEndian(body[2..]);
                short bits = BinaryPrimitives.ReadInt16LittleEndian(body[14..]);
                if (channels != 1 || bits != 16) throw new InvalidDataException($"Se esperaba mono de 16 bits; llegó {bits} bits x{channels}.");
                sampleRate = BinaryPrimitives.ReadInt32LittleEndian(body[4..]);
            }
            else if (id.SequenceEqual("data"u8))
            {
                if (sampleRate == 0) throw new InvalidDataException("Chunk data antes del chunk fmt.");
                return (MemoryMarshal.Cast<byte, short>(body).ToArray(), sampleRate);
            }
            offset += 8 + size + (size & 1);    // los chunks se alinean a 2 bytes
        }
        throw new InvalidDataException("No hay chunk data.");
    }

    public static TimeSpan Duration(byte[] wav)
    {
        (short[] samples, int rate) = Decode(wav);
        return TimeSpan.FromSeconds((double)samples.Length / rate);
    }
}

Tres detalles de ese archivo merecen una frase. stream.Stop() espera a que termine el último callback, así que el canal puede cerrarse justo después sin perder el último bloque. El callback de captura sigue asignando un arreglo pequeño por cada búfer. .NET no da garantías de tiempo real de ninguna forma; si las necesitas, graba en un búfer circular preasignado. La reproducción rellena su último búfer con un bloque de silencio preasignado. Y no hay GC.KeepAlive sobre los callbacks porque PortAudioSharp2 fija cada delegado con un GCHandle mientras vive el stream. Si escribes tu propio binding de PortAudio, fijarlos te toca a ti, o el siguiente callback salta a memoria liberada.

Speaker.PlayAsync recibe un token de cancelación para poder interrumpir (barge-in): cuando ya oíste suficiente, Enter detiene el audio con Abort(), que descarta lo que quedaba en el búfer en lugar de reproducirlo hasta el final.

Por qué pulsar para hablar y no escuchar siempre

Un micrófono siempre abierto parece más amable, y para esta herramienta es peor en tres aspectos que se pueden medir:

Se oye a sí mismo. Con los altavoces de la laptop, la respuesta vuelve directo al micrófono y llega como una pregunta nueva.
Whisper falla en los bordes del habla. Con mis ocho frases grabadas, tiny.en devolvió [BLANK_AUDIO] para dos que se oían perfectamente, y base.en convirtió una de ellas, una pregunta sobre CS1061, en "Peace. See you in the next video. Bye." Para ser justos con Whisper, se entrenó con mucho YouTube. Un micrófono siempre abierto le entrega muchos más bordes que una tecla.
Pierdes los límites. Al pulsar dices ahora te hablo a ti, y al soltar dices terminé. Escuchando siempre, necesitas detección de actividad de voz para adivinar las dos cosas, y cada error de esa detección es un turno.

Por eso el arnés filtra las marcas de silencio de Whisper antes de que lleguen al modelo; lo verás más abajo en VoiceAgent.IsBlank. Pulsar la tecla sin querer no cuesta nada ni ejecuta nada.

Dictado: mal en una de cada dos palabras

Los clientes HTTP son cortos:

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json.Serialization;

/// <summary>whisper-server de whisper.cpp: POST /inference, multipart, devuelve {"text": "..."}.</summary>
sealed class WhisperClient(HttpClient http)
{
    public async Task<string> TranscribeAsync(byte[] wav, string? vocabulary, string? language, CancellationToken ct)
    {
        using MultipartFormDataContent form = new();
        ByteArrayContent file = new(wav);
        file.Headers.ContentType = new MediaTypeHeaderValue("audio/wav");
        form.Add(file, "file", "speech.wav");
        form.Add(new StringContent("json"), "response_format");
        form.Add(new StringContent("0.0"), "temperature");
        if (vocabulary is not null) form.Add(new StringContent(vocabulary), "prompt");
        if (language is not null) form.Add(new StringContent(language), "language");

        using HttpResponseMessage response = await http.PostAsync("/inference", form, ct);
        response.EnsureSuccessStatusCode();
        WhisperResult result = await response.Content.ReadFromJsonAsync<WhisperResult>(ct)
            ?? throw new InvalidDataException("whisper-server devolvió una respuesta vacía.");
        return result.Text.Trim();
    }

    sealed record WhisperResult([property: JsonPropertyName("text")] string Text);
}

/// <summary>Servidor HTTP de Piper: POST /synthesize con {"text": "..."}, devuelve un WAV.</summary>
sealed class PiperClient(HttpClient http)
{
    public async Task<byte[]> SynthesizeAsync(string text, CancellationToken ct)
    {
        using HttpResponseMessage response = await http.PostAsJsonAsync("/synthesize", new { text }, ct);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsByteArrayAsync(ct);
    }
}

prompt es el prompt inicial de Whisper: texto que trata como si hubiera sonado justo antes del audio. Pasarle ahí el vocabulario del proyecto es la mejora de precisión más barata que existe, y actúa justo sobre las palabras que se rompen.

Para saber cuánto se rompen, grabé los ocho pedidos que de verdad le hago al agente (Why is the build red?, Is CS1061 coming from the rename I did in ChangedFile?, Don't run the tests yet, just build.) con mi voz, mi acento y un headset USB, a velocidad normal. Después pasé cada clip por cuatro modelos de Whisper, con y sin el prompt de vocabulario. Es una sola voz y son ocho frases: tómalo como una anécdota medida, no como un benchmark.

La máquina es una laptop con un i7-1165G7 de 4 núcleos limitado a 1,69 GHz por energía, Docker en Windows y 4 hilos. La latencia es la mediana por frase; la columna del encoder sale del propio whisper-bench de whisper.cpp:

Modelo	Tasa de error por palabra (sin prompt / con prompt)	Encoder, una ventana	Mediana por frase
`tiny.en`	0,76 / 0,68	1,4 s	1,8 s
`base.en`	0,66 / 0,59	3,8 s	5,6 s
`small.en`	0,64 / 0,48	12,3 s	13,4 s
`large-v3-turbo` (q5_0)	0,48 / 0,41	77,6 s	sin medir, más de un minuto

Según la tasa de error por palabra, ningún modelo transcribió bien ni una sola de las ocho frases, aunque algunos fallos fueron tan pequeños como "test" por "tests". Why is the build red? volvió como "What is the view right?" en tres de los cuatro. Lo que se rompió fueron las palabras del propio proyecto: ClaudeReviewBot se volvió "cloud review bot" y "Cloud Review", ChangedFile se volvió "change flight" y "Change. Fight.", origin main se volvió "originally". El prompt arregló varias de esas, y tuvo su costo: en un clip, small.en devolvió pedazos del prompt, "CS1061, nullable, origin main, IDP, ChangedFile.", en lugar de lo que dije.

La columna del encoder explica casi toda la latencia. El encoder de Whisper siempre procesa una ventana completa de 30 segundos, así que a él una frase de cuatro segundos le cuesta lo mismo que una de treinta. El resto es la decodificación, y de ahí salen los casos extremos: cuando el decodificador alucina, sigue y sigue. Ese clip con prompt le llevó 31,2 segundos a tiny.en y 38,6 a small.en. En este hardware, solo tiny.en y base.en responden a ritmo de conversación, y son justo los dos menos precisos.

Un resultado más, que no estaba en el plan. En la prueba en vivo dije mi primer pedido en español sin pensarlo. tiny.en solo entiende inglés, y no falló de forma visible: "¿Por qué está rojo el build?" volvió como "Okay, let's start from a little bit." Este no me avisó de que no me entendía. Me devolvió una frase fluida en su propio idioma.

Diseña para la transcripción que vas a recibir

Si en una laptop el dictado no se puede volver preciso, el agente tiene que arreglárselas con lo que llega. Así que le pasé al agente cada transcripción distinta de esa tabla y anoté qué herramienta pedía primero, sin ejecutar nada: 64 transcripciones, tres corridas cada una, con Claude Haiku 5.5.

Transcripciones de	Herramienta correcta	Preguntó o no hizo nada	Herramienta equivocada	Silencio, filtrado
Las frases exactas	8	0	0	0
`large-v3-turbo` + prompt	8	0	0	0
`large-v3-turbo`, sin prompt	7	1	0	0
`small.en` + prompt	7	0	1	0
`small.en`, sin prompt	6	2	0	0
`base.en` + prompt	6	0	1	1
`base.en`, sin prompt	5	1	1	1
`tiny.en` + prompt	6	1	0	1
`tiny.en`, sin prompt	5	1	0	2

Cada celda cuenta frases, según el veredicto en el que coincidieron la mayoría de las tres corridas.

"What is the view right?" ejecutó dotnet_build todas las veces. "Bravo to test, until which ones failed" ejecutó dotnet_test. "We did a changed size minus minus moment" ejecutó git_status, que es lo más cerca de "qué cambié desde mi último commit" que uno podría esperar. Cuando la transcripción podía significar dos cosas, preguntó: "Did you want me to run the build, or are you just letting me know what you're working on?"

El pedido con negación, Don't run the tests yet, just build, no ejecutó dotnet_test en ninguna variante. Era el que más me preocupaba.

Los fallos fueron fallos de verdad, no un criterio demasiado estricto. "Did any nullable warnings show up" perdió la palabra warnings en seis transcripciones (en cinco se oyó "nullable coordinates"), y sin ella, el agente a veces entendió la pregunta como si fuera sobre cambios o sobre tests. "What is the new thread?" ejecutó git_status tres veces de tres.

Nada de esto funciona porque el modelo sea listo con el audio. Funciona porque el system prompt le dice que la transcripción viene mal, le da dos ejemplos de cómo, y le dice qué hacer cuando dos lecturas llevan a acciones distintas. Y porque el arnés imprime heard: "..." en cada turno: cuando una sola palabra mal oída cambia la pregunta, lo ves antes de creerte la respuesta.

Lo primero que se rompe: todo lo que dice

Esta es la respuesta del principio, completa. Es el system prompt de la Parte 1, sin cambios, con la respuesta enviada al altavoz:

4 of 91 tests failed, all in `PatchParserTests` (`tests/ClaudeReviewBot.Tests/PatchParserTests.cs`):

1. **`AddedLines_reports_new_file_numbers_across_hunks`** (line 29): expected `[15, 19, 20, 21]`, got `[15, 20, 21, 22]`.
2. **`ParseUnifiedDiff_splits_per_file_and_strips_the_b_prefix`** (line 109): expected first element `1`, got `2`.
3. **`AddedLines_removed_lines_do_not_advance_the_counter`** (line 43): expected first element `2`, got `3`.
4. **`AddedLines_ignores_no_newline_marker_and_crlf`** (line 62): expected first element `2`, got `3`.

The failures are all in line-number tracking, and the actual values are consistently one higher or shifted by one. That suggests an off-by-one in how the parser counts new-file line numbers, but I haven't read the parser code to confirm. I can look at the parser in `src/ClaudeReviewBot.Core` next if you want.

Como respuesta escrita está muy bien. Piper la lee en 67,9 segundos. El diagnóstico, desfasado por uno, empieza después del cuarto nombre de test. Si en cambio le pides que lea la salida cruda de dotnet_test de la Parte 1, los 1.600 caracteres con stack frames, tarda 109,4 segundos.

El arreglo tiene dos mitades, y la que importa es la segunda.

Dale al agente otro lugar donde poner las cosas. Una cuarta herramienta, show_on_screen, solo imprime. Con ella, "no leas rutas en voz alta" deja de ser una simple prohibición: el agente tiene adónde mandarlas.

Reescribe el system prompt para alguien que escucha. Dos frases como máximo. Nunca digas una ruta, un stack frame, un hash ni un identificador completo. Empieza por la respuesta. Esta es la misma pregunta, el mismo repositorio y el mismo modelo, con el prompt nuevo:

Four tests failed, all in PatchParserTests, and they all show line numbers off by one. Details are on screen.

Los cuatro nombres de test, las líneas y los arreglos fueron a show_on_screen. Probé los dos prompts dos veces, con dos estados rotos del repositorio:

Escenario	Prompt de la Parte 1, hablado	Prompt de voz, hablado
Cuatro tests fallando	88–105 palabras, 57,2–67,9 s	19–21 palabras, 6,5–7,2 s
Un error de compilación	103–120 palabras, 46,7–53,2 s	20 palabras, 7,1–7,2 s

Y el diagnóstico pasó del último párrafo a la primera frase, porque "empieza por la respuesta" también obliga a encontrar la respuesta antes de hablar. No sale gratis. Cada turno hace una llamada más a la API, la de show_on_screen, y envía entre dos y tres mil tokens más de entrada, que con Haiku es menos de una décima de centavo. Y tarda más en empezar a hablar: los turnos con el prompt de voz tomaron entre 8,3 y 19,9 segundos, contra 6,1 a 12,2 con el de la Parte 1, herramientas incluidas. Esperas unos segundos más, y después escuchas siete segundos en lugar de un minuto.

El agente

Este es el agente completo. El ciclo es el de la Parte 1, las tres herramientas son las de la Parte 1, y lo nuevo es el prompt, show_on_screen, el filtro de silencio y el límite de longitud del final. El system prompt queda en inglés a propósito: la voz de Piper es inglesa, y este prompt, tal cual, es el que medí. Traducido, el agente seguramente respondería en español (en mis pruebas responde en el idioma en que le hablas), y una voz inglesa leyendo español sería otro experimento.

using System.ComponentModel;
using System.Text.Json;
using System.Text.RegularExpressions;
using Anthropic;
using Anthropic.Models.Messages;

/// <summary>
/// El ciclo de tool_use de la Parte 1 con dos canales de salida: el texto final se dice en voz
/// alta, y lo que no se puede escuchar va a la pantalla mediante la herramienta show_on_screen.
/// </summary>
sealed class VoiceAgent(AnthropicClient client, string repo)
{
    const string Model = "claude-haiku-5-5";

    // Unos diez segundos de escucha al ritmo de Piper. Lo más largo va a la pantalla.
    const int MaxSpokenWords = 30;

    const string SystemPrompt = """
        You are a development assistant for the ClaudeReviewBot repository, and the
        developer is TALKING to you. Their words arrive through speech-to-text, and your
        reply is read aloud by a text-to-speech voice.

        Three projects. src/ClaudeReviewBot.Core holds the logic and is the one that
        matters. src/ClaudeReviewBot is a thin CLI wrapper. tests/ is xUnit.
        TreatWarningsAsErrors is on. CS1591 is noise; nullable warnings are real defects.

        The transcript is often wrong. Speech-to-text mangles identifiers and jargon:
        "ChangedFile" may arrive as "changed file" or "unchanged file", "build red" as
        "view right". Read for intent. If you can tell what was meant, act on it. If two
        readings would lead to different actions, ask one short question instead of guessing.

        Your reply is heard, not read. So:
        - Speak at most two short sentences. No lists, no markdown, no code.
        - Never say a file path, stack frame, hash, or full identifier aloud. Put them on
          the screen with show_on_screen, then say what matters and "details on screen".
        - Lead with the answer: "Build's red, three errors, all from your rename."

        Check state before answering. If the question is about the build, build. If it is
        about what changed, call git_status. Do not speculate.
        """;

    static readonly List<ToolUnion> Tools =
    [
        new Tool
        {
            Name = "git_status",
            Description = "Branch, ahead/behind counts, and changed and untracked files in the working copy.",
            InputSchema = new() { Properties = new Dictionary<string, JsonElement>() },
        },
        new Tool
        {
            Name = "dotnet_build",
            Description = "Builds the solution, or one project, and returns deduplicated errors and warnings.",
            InputSchema = new()
            {
                Properties = new Dictionary<string, JsonElement>
                {
                    ["project"] = JsonSerializer.SerializeToElement(new
                    {
                        type = "string",
                        description = "Optional project path relative to the repository root.",
                    }),
                },
            },
        },
        new Tool
        {
            Name = "dotnet_test",
            Description = "Runs the test suite and returns pass/fail counts plus each failure's message and own-code frames.",
            InputSchema = new() { Properties = new Dictionary<string, JsonElement>() },
        },
        new Tool
        {
            Name = "show_on_screen",
            Description = "Shows text on the developer's screen without reading it aloud. Use for paths, " +
                          "diagnostics, stack frames, lists: anything too long or too precise to listen to.",
            InputSchema = new()
            {
                Properties = new Dictionary<string, JsonElement>
                {
                    ["text"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                },
                Required = ["text"],
            },
        },
    ];

    readonly List<MessageParam> messages = [];

    /// <summary>
    /// Whisper marca el silencio y el ruido con etiquetas entre corchetes: [BLANK_AUDIO],
    /// [inaudible], (silence), [Music]. Una transcripción que solo tiene etiquetas no es un
    /// pedido: pulsar la tecla sin querer no debe costar una llamada ni ejecutar herramientas.
    /// </summary>
    public static bool IsBlank(string transcript) =>
        Regex.Replace(transcript, @"\[[^\]]*\]|\([^)]*\)", "").Trim().Trim('.', ' ', '>').Length == 0;

    /// <summary>Entra un pedido hablado, sale una respuesta hablada. Lo de pantalla va a <paramref name="screen"/>.</summary>
    public async Task<string> AskAsync(string transcript, Action<string> screen, CancellationToken ct)
    {
        if (IsBlank(transcript)) return "";

        int turnStart = messages.Count;
        messages.Add(new() { Role = Role.User, Content = transcript });

        try
        {
            string? reply = await RunTurnAsync(screen, ct);
            if (reply is not null) return reply;
        }
        catch
        {
            // Una petición fallida puede dejar un tool_use sin su tool_result al final del
            // historial, y todas las peticiones siguientes serían rechazadas. Se descarta el turno.
            messages.RemoveRange(turnStart, messages.Count - turnStart);
            throw;
        }

        messages.RemoveRange(turnStart, messages.Count - turnStart);
        return "I went in circles on that one. Try asking differently.";
    }

    /// <summary>Devuelve la respuesta hablada, o null si se agotó el límite de pasos.</summary>
    async Task<string?> RunTurnAsync(Action<string> screen, CancellationToken ct)
    {
        for (int step = 0; step < 8; step++)
        {
            Message response = await client.Messages.Create(new MessageCreateParams
            {
                Model = Model,
                MaxTokens = 4096,
                System = new List<TextBlockParam> { new() { Text = SystemPrompt, CacheControl = new CacheControlEphemeral() } },
                Tools = Tools,
                OutputConfig = new OutputConfig { Effort = Effort.Low },
                Messages = messages,
            }, ct);

            if (response.StopReason == "refusal")
            {
                // Haiku 5.5 no tiene respaldo en el servidor: la petición queda rechazada.
                throw new RefusalException();
            }

            // Devuelve cada bloque sin cambios, incluidos los de thinking aunque su texto
            // venga vacío, o la siguiente petición no pasa la validación del historial.
            List<ContentBlockParam> echo = [];
            List<ContentBlockParam> results = [];
            string spoken = "";

            foreach (ContentBlock block in response.Content)
            {
                if (block.TryPickThinking(out ThinkingBlock? thinking))
                {
                    echo.Add(new ThinkingBlockParam { Thinking = thinking.Thinking, Signature = thinking.Signature });
                }
                else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted))
                {
                    echo.Add(new RedactedThinkingBlockParam { Data = redacted.Data });
                }
                else if (block.TryPickText(out TextBlock? text))
                {
                    echo.Add(new TextBlockParam { Text = text.Text });
                    spoken += text.Text;
                }
                else if (block.TryPickToolUse(out ToolUseBlock? use))
                {
                    echo.Add(new ToolUseBlockParam { ID = use.ID, Name = use.Name, Input = use.Input });
                    (string content, bool isError) = await RunToolAsync(use, screen, ct);
                    results.Add(new ToolResultBlockParam { ToolUseID = use.ID, Content = content, IsError = isError });
                }
            }

            messages.Add(new() { Role = Role.Assistant, Content = echo });

            if (results.Count == 0) return GuardSpoken(spoken.Trim(), screen);

            // Todos los resultados de un turno vuelven en UN solo mensaje de usuario.
            messages.Add(new() { Role = Role.User, Content = results });
        }

        return null;
    }

    async Task<(string Content, bool IsError)> RunToolAsync(ToolUseBlock use, Action<string> screen, CancellationToken ct)
    {
        try
        {
            switch (use.Name)
            {
                case "git_status":
                    return (await DevTools.GitStatusAsync(repo, ct), false);
                case "dotnet_build":
                    string? project = use.Input.TryGetValue("project", out JsonElement p) && p.ValueKind == JsonValueKind.String
                        ? p.GetString()
                        : null;
                    return (await DevTools.DotnetBuildAsync(repo, project, ct), false);
                case "dotnet_test":
                    return (await DevTools.DotnetTestAsync(repo, ct), false);
                case "show_on_screen":
                    screen(use.Input["text"].GetString() ?? "");
                    return ("Shown.", false);
                default:
                    return ($"Unknown tool {use.Name}.", true);
            }
        }
        // Una herramienta que no puede correr es una respuesta para el modelo ("no pude
        // compilar"), no un cierre del programa. Process.Start lanza Win32Exception si falta
        // el ejecutable o el directorio de trabajo no existe.
        catch (Exception ex) when (ex is TimeoutException or InvalidOperationException or KeyNotFoundException
                                       or Win32Exception or IOException)
        {
            return (ex.Message, true);
        }
    }

    /// <summary>
    /// El prompt pide respuestas cortas; esto lo garantiza. Una respuesta demasiado larga para
    /// escucharla va a la pantalla, y solo se dice su primera frase.
    /// </summary>
    static string GuardSpoken(string spoken, Action<string> screen)
    {
        string[] words = spoken.Split(' ', StringSplitOptions.RemoveEmptyEntries);
        if (words.Length <= MaxSpokenWords) return spoken;

        screen(spoken);
        // Una frase termina en . ? ! seguido de un espacio o del final, no dentro de
        // "ChangedFile.cs" ni de "1.8 seconds".
        Match end = Regex.Match(spoken, @"[.?!](\s|$)");
        string first = end.Success ? spoken[..(end.Index + 1)] : spoken;
        string[] firstWords = first.Split(' ', StringSplitOptions.RemoveEmptyEntries);
        if (firstWords.Length > MaxSpokenWords) first = string.Join(' ', firstWords.Take(MaxSpokenWords)) + "...";
        return $"{first} The rest is on screen.";
    }
}

sealed class RefusalException() : Exception("El modelo rechazó esta petición.");

DevTools son las tres funciones de herramienta de la Parte 1 y su método RunAsync, dentro de static partial class DevTools y marcadas como public, junto con la clase de regex BuildOutput y los records Diagnostic y ProcessResult de la Parte 1.

El prompt es un pedido; GuardSpoken es una garantía. En los cuatro turnos de voz de la prueba de arriba, el prompt solo bastó para que ninguna respuesta pasara de 30 palabras, y el límite nunca se activó. Después, en la sesión en vivo, hice una pregunta abierta, "What do I need to do to fix it?", y la respuesta se alargó. El límite la mandó a la pantalla y dijo una frase y "The rest is on screen." Una regla que solo vive en el prompt aguanta hasta la primera pregunta que nadie probó.

Si una herramienta falla, el error vuelve al modelo. Si dotnet no puede arrancar, por un SDK que falta o una ruta mala, Process.Start lanza una Win32Exception. Mi primera versión no la atrapaba, y la primera vez que pasó, el agente entero se cayó a mitad de frase. Ahora la excepción se convierte en un tool_result con IsError = true, y el agente lo dice. Apuntado a un directorio que no existe, respondió: "I couldn't tell whether it's red. The build tool failed twice before compiling, because it's pointed at a working directory that doesn't exist. Details on screen."

Una petición fallida no puede ensuciar el historial. Si una petición falla después de un paso con herramientas (un límite de peticiones, la API sobrecargada, una conexión caída), messages termina en un tool_use sin su tool_result, y todas las peticiones siguientes se rechazan. Por eso AskAsync descarta el turno entero ante cualquier excepción, y también cuando se le acaban los pasos, y el ciclo de abajo atrapa el error, lo dice y mantiene la sesión. Con una key inválida, dos turnos seguidos fallaron, se anunciaron, y la sesión siguió.

El ciclo

using System.Diagnostics;
using Anthropic;
using Anthropic.Exceptions;
using PortAudioSharp;

// uso: dotnet run -- <ruta del repo> [--text]
//   --text  escribir en vez de hablar (la respuesta se sigue diciendo en voz alta)
if (args.Length == 0)
{
    Console.Error.WriteLine("uso: dotnet run -- <ruta del repo> [--text]");
    return 2;
}

string repo = args[0];
bool typed = args.Contains("--text");

// Prompt inicial de Whisper: pistas de escritura para las palabras que más falla.
const string Vocabulary =
    "dotnet build, dotnet test, git status, xUnit, ClaudeReviewBot, ChangedFile, CS1061, nullable, origin main.";

// Falla antes de abrir el micrófono, no después de la primera grabación.
if (string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")))
{
    Console.Error.WriteLine("ANTHROPIC_API_KEY no está definida.");
    return 1;
}

using HttpClient whisperHttp = new() { BaseAddress = new Uri("http://localhost:8080"), Timeout = TimeSpan.FromMinutes(2) };
using HttpClient piperHttp = new() { BaseAddress = new Uri("http://localhost:5000"), Timeout = TimeSpan.FromMinutes(2) };
WhisperClient whisper = new(whisperHttp);
PiperClient piper = new(piperHttp);

try
{
    await piper.SynthesizeAsync("ready", CancellationToken.None);
    if (!typed)
        await whisper.TranscribeAsync(Wav.Encode(new short[Microphone.SampleRate / 2], Microphone.SampleRate), null, "en", CancellationToken.None);
}
catch (HttpRequestException ex)
{
    Console.Error.WriteLine($"Primero levanta los contenedores (docker compose up -d): {ex.Message}");
    return 1;
}

PortAudio.Initialize();
try
{
    VoiceAgent agent = new(new AnthropicClient(), repo);
    Console.WriteLine(typed ? "Escribe un pedido; línea vacía para salir." : "Enter para hablar, Enter otra vez para terminar. Ctrl+C para salir.");
    bool alreadyPressed = false;

    while (true)
    {
        string heard;
        if (typed)
        {
            Console.Write("\n> ");
            heard = Console.ReadLine() ?? "";
            if (heard.Length == 0) break;
        }
        else
        {
            if (!alreadyPressed)
            {
                Console.Write("\n[Enter para hablar] ");
                Console.ReadLine();
            }
            alreadyPressed = false;
            Console.Write("escuchando... ");
            byte[] wav = await Microphone.RecordAsync(ct => Task.Run(() => Console.ReadLine(), ct), CancellationToken.None);

            Stopwatch stt = Stopwatch.StartNew();
            try
            {
                heard = await whisper.TranscribeAsync(wav, Vocabulary, "en", CancellationToken.None);
            }
            catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
            {
                Console.WriteLine($"\n  falló el dictado: {ex.Message}");
                continue;
            }
            // Muestra siempre lo que se oyó: una palabra mal oída puede cambiar la pregunta.
            Console.WriteLine($"\n  oyó: \"{heard}\"  ({stt.ElapsedMilliseconds} ms)");
        }

        Stopwatch thinking = Stopwatch.StartNew();
        string reply;
        try
        {
            reply = await agent.AskAsync(heard, text => Console.WriteLine($"  ┌ pantalla\n  │ {text.Replace("\n", "\n  │ ")}\n  └"), CancellationToken.None);
        }
        catch (RefusalException)
        {
            reply = "I can't help with that one.";
        }
        catch (Exception ex) when (ex is AnthropicException or HttpRequestException or TaskCanceledException)
        {
            // Límite de peticiones, sobrecarga, conexión caída: lo dice y la sesión sigue.
            Console.WriteLine($"  falló la petición: {ex.Message}");
            reply = "I couldn't reach the model. Try again in a moment.";
        }
        Console.WriteLine($"  ({thinking.ElapsedMilliseconds} ms)");
        if (reply.Length == 0) continue;

        Console.WriteLine($"  dice: \"{reply}\"");
        byte[] speech;
        try
        {
            speech = await piper.SynthesizeAsync(reply, CancellationToken.None);
        }
        catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
        {
            Console.WriteLine($"  falló la síntesis de voz: {ex.Message}");
            continue;
        }

        if (typed)
        {
            await Speaker.PlayAsync(speech, CancellationToken.None);
            continue;
        }

        // Enter mientras habla la interrumpe. Enter cuando termina empieza la siguiente
        // grabación, así que en los dos casos una sola tecla hace avanzar la conversación.
        using CancellationTokenSource stop = new();
        Task<string?> press = Task.Run(Console.ReadLine);
        Task playback = Speaker.PlayAsync(speech, stop.Token);
        if (await Task.WhenAny(press, playback) == press) stop.Cancel();
        await playback;
        if (!press.IsCompleted) Console.Write("  [Enter para hablar] ");
        await press;
        alreadyPressed = true;
    }
}
finally
{
    PortAudio.Terminate();
}
return 0;

Una sola tecla controla todo. Enter mientras habla la interrumpe; Enter cuando termina empieza la siguiente grabación. --text cambia el micrófono por el teclado y mantiene la voz. Sirve en una oficina abierta, y para probar el ciclo sin tener que hablarle.

Por qué Haiku y no el modelo de la Parte 1

La Parte 1 usaba Claude Opus 5. Este post usa Claude Haiku 5.5, y la razón es que ahora la respuesta queda en medio de otras dos cosas lentas: el dictado antes y la síntesis después.

Le pasé a Claude Opus 5.5, el Opus actual, las doce transcripciones en las que Haiku había preguntado, fallado o cambiado de respuesta entre corridas. Opus corrió una vez cada una, contra tres de Haiku, así que la muestra es pequeña. Opus resolvió más: las cuatro preguntas con "nullable coordinates" terminaron en builds. Pero también actuó donde Haiku preguntaba. Con "What is the field print?", Haiku preguntó tres veces de tres; Opus, en su única corrida, ejecutó el build y los tests. En un agente al que le hablas, preguntar cuando la transcripción no tiene sentido es justo lo que quieres.

Con esas mismas doce transcripciones, una llamada a Opus costó unas treinta veces lo que una a Haiku, con una mediana de 2,5 segundos contra 1,8. Un turno lleva entre una y tres llamadas, así que son hasta dos segundos más en un ciclo que ya tarda entre siete y doce. El diseño de arriba (mostrar lo que se oyó, preguntar ante la duda) cubre casi toda la diferencia de precisión. El costo y los segundos se quedan.

Haiku 5.5 trae tres diferencias de API que dan forma al código. Rechaza cualquier temperature distinta de la de por defecto, así que no puedes fijar su salida, y la misma transcripción puede recibir otra herramienta en otra corrida: pasó con 8 de mis 64. Su razonamiento es adaptativo y viene activado por defecto, así que los bloques thinking hay que devolverlos intactos aunque su texto venga vacío. Y el effort es la palanca de latencia: con las transcripciones de los tres pedidos más fáciles (build, tests y estado), low y medium eligieron la misma herramienta en 21 de 22, así que el agente corre en low. En los casos difíciles no los comparé.

¿Y si le hablo en español?

Con lo medido aquí, todavía no en esta laptop. Los tres modelos rápidos son .en: solo entienden inglés, y ya viste lo que hacen con el español. El único multilingüe que probé, large-v3-turbo, transcribió bien buena parte de mis seis frases en español, con un error de 0,50 por palabra, pero tarda más de un minuto por frase en este CPU.

Lo que sí funciona es el agente. Con las seis frases exactas en español, Haiku eligió la herramienta correcta 18 veces de 18, incluida "Todavía no corras los tests, solo compila", que nunca ejecutó tests. Con las transcripciones de large-v3-turbo, también acertó casi siempre ("El CSS1061 viene del rename que hice en change file" terminó en build y git_status), y cuando dudó, preguntó en español: "¿Compilo src/ClaudeReviewBot, la CLI, o src/ClaudeReviewBot.Core?" Lo que falta para hablarle en español es un dictado multilingüe rápido y una voz de Piper en español, no un agente distinto.

Una sesión real

Cuatro turnos hablados, con un repositorio en el que renombré ChangedFile.Patch a Diff y olvidé un uso. Las transcripciones son las que oyó Whisper, con tiny.en y el prompt de vocabulario:

Oyó	Herramientas	Dijo
"What is the build, great?"	`dotnet_build`, pantalla	"The build's red with one error: ReviewOrchestrator is calling a Patch property that ChangedFile doesn't have. Details on screen."
"Why did I change?"	`git_status`, pantalla	"I can't see your reasons, only the edits. Three files changed, and ChangedFile.cs is the likely cause of the Patch error. The list is on screen."
"Run the test."	`dotnet_test`	"The tests didn't run because the build is still failing, so there are no results yet. Fixing the Patch error in ReviewOrchestrator should unblock them."
"What I need to do to fix it."	ninguna	"I can't read the code from here, so I can't say the exact fix yet. The rest is on screen."

La segunda fila resume el problema de la transcripción en una línea. Yo dije what; Whisper oyó why; y el agente contestó la pregunta que recibió, en tono filosófico, antes de darme igual la lista de archivos. La cuarta fila es una herramienta que falta, y es material para la Parte 3.

Las etapas que medí entre soltar Enter y la primera palabra de la respuesta suman entre 7 y 12 segundos por turno: 2,6–3,6 s de dictado, 2,1–7,4 s de agente (entre una y tres llamadas, más el build mismo) y 2,3–2,9 s de Piper sintetizando la respuesta completa antes de que suene nada. A eso se suman la decodificación del WAV y la latencia propia del dispositivo de audio, que no medí. Ese último número es el más barato de recortar: sintetizar la primera frase, empezar a reproducirla y sintetizar el resto por detrás.

El bug que traía la Parte 1

A mitad de este post, una actualización instaló el SDK de .NET 11 RC junto al de .NET 10. Desde ese momento, el agente reportaba cada build como roto con MSB4216, un error del task host de las entrañas de MSBuild, incluso con código que compilaba bien desde una terminal.

dotnet run sobre un proyecto exporta MSBuildSDKsPath y MSBuildExtensionsPath, apuntando al SDK que compiló el agente. Cada dotnet build que lanza el agente las hereda. El global.json del repositorio elige .NET 10, las variables heredadas cargan los targets de .NET 11, y el build muere antes de llegar a una línea de código. Lanzado contra un build con un único CS1061 real, el método original de la Parte 1 devolvió seis errores MSB4216 y seis MSB4027, y ningún CS1061. Curiosamente, dotnet run app.cs sobre una app de un solo archivo no exporta esas dos variables, y por eso el bug se esconde en unas configuraciones y en otras no.

La corrección son tres líneas en RunAsync, que la Parte 1 ya incluye. Quita todas las variables MSBuild*, también las que hayas definido a propósito, como MSBUILDDEBUGPATH; si dependes de alguna, quita solo MSBuildSDKsPath y MSBuildExtensionsPath por nombre.

foreach (string key in psi.Environment.Keys
             .Where(k => k.StartsWith("MSBuild", StringComparison.OrdinalIgnoreCase)).ToList())
    psi.Environment.Remove(key);

Cuándo no darle voz a tu agente

Si estás en tu escritorio con las manos en el teclado, escribir es más rápido y más preciso que hablar. Todos los números de arriba lo dicen: entre 7 y 12 segundos por turno, y una transcripción que se equivoca en más de la mitad de las palabras.

La voz se gana su lugar cuando tienes las manos o los ojos ocupados en otra cosa: seguir una corrida de tests mientras lees un diff en el otro monitor, o preguntar "¿ya está en verde?" desde el otro lado del cuarto mientras termina un build lento. También encaja con preguntas cortas de respuesta corta, que es casi todo lo que le preguntas a un agente de build.

Es la herramienta equivocada para cualquier cosa que escriba, borre o haga push. Las herramientas de la Parte 1 son de solo lectura a propósito, y ahora eso importa más: en el peor caso, un pedido mal oído ejecuta un build. Antes de darle a un agente de voz una herramienta con efectos, haz que pida confirmación en el código, no en el prompt.

Si prefieres no correr modelos en tu máquina, los servicios de dictado y síntesis alojados corren en GPU y se ahorran la latencia de CPU de arriba, a cambio de mandarle tu voz a un tercero. No los medí aquí. Todo el diseño sigue valiendo con ellos; solo cambiaría la tabla de latencias.

Puntos clave

Las respuestas de tu agente están escritas para leerse. Leída en voz alta, la misma respuesta tardó entre 57 y 68 segundos. Un prompt de voz con un canal en pantalla la bajó a 7, con el diagnóstico primero.
Diseña para la transcripción que vas a recibir. En el CPU de una laptop, los dos modelos de Whisper lo bastante rápidos para conversar erraron entre el 59 y el 76 por ciento de mis palabras. Dile al modelo que la transcripción viene mal, haz que pregunte cuando dos lecturas difieran, y muestra siempre lo que se oyó.
Una regla del prompt necesita una garantía en el código. El límite de 30 palabras nunca se activó en las pruebas y se activó con la primera pregunta abierta de uso real. Lo mismo con el silencio: fíltralo antes de que cueste una llamada.
Elige el modelo para el ciclo completo, no para la respuesta. Con mis doce transcripciones más difíciles, Opus recuperó más pedidos mal transcritos, pero costó unas treinta veces más por llamada, sumó tiempo a un ciclo que ya es lento y actuó donde Haiku preguntaba. Para este agente, Haiku con buen diseño fue la mejor opción.
Mide con la configuración que usa tu lector. El escape del SDK solo aparece con dotnet run sobre un proyecto, y los flags de Compose solo fallan en silencio. Las dos cosas parecían bien hasta que las medí de la forma correcta.

El código completo está en GitHub, listo para clonar y ejecutar: Juxn89/dotnet-voice-dev-agent. Es el código de este post, con las herramientas de la Parte 1 y sus dos correcciones. El README está en inglés.

Siguiente en la serie: Construye un agente de desarrollo .NET, Parte 3: haz que te recuerde, memoria de sesión, para que el agente deje de preguntarte cada mañana qué proyecto importa, y para que "¿qué estaba haciendo ayer?" sea una pregunta que pueda responder.

Building a .NET Dev Agent, Part 2: Give It a Voice

Juan Gómez — Tue, 20 Oct 2026 14:00:00 +0000

Building a .NET Dev Agent, Part 2: Give It a Voice

The first time my dev agent answered out loud, it took sixty-eight seconds to tell me that four tests had failed.

It was correct, and it was thorough: four test names read out in full, AddedLines_reports_new_file_numbers_across_hunks included, each with its line number and its expected value, and a closing paragraph offering to look at the parser. On screen that answer is a glance. Through headphones it is a minute of standing still, waiting to hear the one sentence that mattered, which came last: every failure was off by one.

Wiring speech-to-text and text-to-speech onto an agent takes an afternoon. This post is about what happens after that afternoon, when you discover that an answer written to be read is the wrong shape to be heard, and that the transcript your agent receives is wrong roughly every other word. Both problems turn out to be design problems, not audio problems, and everything below is measured on the agent from Part 1.

Where Part 1 left the agent

Building a .NET Dev Agent, Part 1: Teach It Your Actual Workflow built three typed tools on top of a Claude tool_use loop: git_status, dotnet_build and dotnet_test, each one filtering its command's output down to what a model needs. Those three tools come over unchanged, with one exception: Part 1's RunAsync helper had a bug that only shows up on a machine with two .NET SDKs, and building this post found it. Part 1 now carries the fix; the details are near the end of this post.

Here is the whole loop:

Hold a key, talk, release.
A local Whisper turns the audio into text.
The agent runs, with Part 1's tools plus one new one.
A local Piper voice reads the reply back, and anything that should not be read goes to the screen.

Everything that touches audio runs locally, from open-source models, with no account needed for anything but Claude itself.

Two containers

Speech-to-text is whisper.cpp's whisper-server, which takes a WAV file over HTTP and returns JSON. Text-to-speech is Piper, whose HTTP server takes JSON and returns a WAV file. Both run on CPU.

services:
  whisper:
    # v1.9.5. The image is tagged by commit; ":main" moves every day.
    image: ghcr.io/ggml-org/whisper.cpp:main-d1be6fde11ac6e0407606b4e42fe72d34add8037
    # The image's entrypoint is `bash -c`, which runs only its FIRST argument. A plain
    # string gets split into words, so every flag after "whisper-server" is silently
    # dropped and it starts on the image's bundled model, bound to 127.0.0.1.
    # A one-element list keeps the whole command line as that first argument.
    command: ["whisper-server --host 0.0.0.0 --port 8080 --model /models/ggml-${WHISPER_MODEL:-tiny.en}.bin --threads 4"]
    volumes:
      - ./models:/models:ro
    ports:
      - "127.0.0.1:8080:8080"

  piper:
    build: ./piper
    ports:
      - "127.0.0.1:5000:5000"

Piper has no official image with its HTTP server, so it gets a five-line piper/Dockerfile. The voice is downloaded at build time, so the container starts without the network:

FROM python:3.12-slim
RUN pip install --no-cache-dir "piper-tts[http]==1.8.0"
WORKDIR /voices
# Bake the voice into the image so the container starts offline.
RUN python -m piper.download_voices en_US-lessac-medium --data-dir /voices
EXPOSE 5000
CMD ["python", "-m", "piper.http_server", "--host", "0.0.0.0", "--port", "5000", "--data-dir", "/voices", "-m", "en_US-lessac-medium"]

The Whisper model is a file you download once into models/:

curl -L -o models/ggml-tiny.en.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin
docker compose up -d

The comment on command: is there because I lost an hour to it. whisper.cpp's image uses bash -c as its entrypoint, and bash -c only runs its first argument. Written as a plain string, Compose splits the command into words, so bash -c receives whisper-server as its script and every flag after it as an ignored positional parameter: the server starts on the model bundled inside the image, bound to 127.0.0.1, where nothing outside the container can reach it. Written as a folded multi-line string it fails more quietly. The line break ends the command, so the server listens where you asked but loads the bundled model. My first run asked for large-v3-turbo, got base.en, and I spent a while blaming my accent. The one-element list keeps the whole command line together.

Pin the image by commit, too. :main is rebuilt daily, and the tag above is the one built from the v1.9.5 release.

Capture: push-to-talk, at the format Whisper wants

The .NET side needs one native dependency for audio. PortAudioSharp2 ships PortAudio's binaries for Windows, Linux and macOS inside the package, so there is nothing to install:

dotnet new console -n VoiceDevAgent
dotnet add package Anthropic --version 12.57.0
dotnet add package PortAudioSharp2 --version 1.0.6

Recording happens at 16 kHz, mono, 16-bit, which is exactly what Whisper consumes, so nothing gets resampled on either side. PortAudio delivers audio on its own thread through a callback, and that callback has one job: copy the samples somewhere and return, without ever waiting on the rest of the program. A Channel<T> is the right somewhere, because writing to an unbounded one never blocks.

using System.Buffers.Binary;
using System.Runtime.InteropServices;
using System.Threading.Channels;
using PortAudioSharp;
using PaStream = PortAudioSharp.Stream;

/// <summary>Push-to-talk capture: 16 kHz, mono, 16-bit — the format Whisper wants, so nothing resamples.</summary>
sealed class Microphone
{
    public const int SampleRate = 16_000;

    public static async Task<byte[]> RecordAsync(Func<CancellationToken, Task> waitForStop, CancellationToken ct)
    {
        // The callback runs on PortAudio's audio thread. It must never wait on anything the
        // rest of the program does, so it only copies samples into an unbounded channel,
        // whose writes never block.
        Channel<short[]> chunks = Channel.CreateUnbounded<short[]>(new() { SingleReader = true, SingleWriter = true });

        PaStream.Callback callback = (IntPtr input, IntPtr output, uint frameCount,
            ref StreamCallbackTimeInfo timeInfo, StreamCallbackFlags flags, IntPtr userData) =>
        {
            short[] chunk = new short[frameCount];
            Marshal.Copy(input, chunk, 0, (int)frameCount);
            chunks.Writer.TryWrite(chunk);
            return StreamCallbackResult.Continue;
        };

        int device = PortAudio.DefaultInputDevice;
        if (device == PortAudio.NoDevice) throw new InvalidOperationException("No input device found.");

        StreamParameters parameters = new()
        {
            device = device,
            channelCount = 1,
            sampleFormat = SampleFormat.Int16,
            suggestedLatency = PortAudio.GetDeviceInfo(device).defaultLowInputLatency,
            hostApiSpecificStreamInfo = IntPtr.Zero,
        };

        using (PaStream stream = new(parameters, null, SampleRate, 0, StreamFlags.ClipOff, callback, null!))
        {
            stream.Start();
            try
            {
                await waitForStop(ct);
            }
            finally
            {
                stream.Stop();          // blocks until the last callback has returned
                chunks.Writer.Complete();
            }
        }

        List<short> samples = [];
        await foreach (short[] chunk in chunks.Reader.ReadAllAsync(CancellationToken.None))
            samples.AddRange(chunk);

        return Wav.Encode([.. samples], SampleRate);
    }
}

/// <summary>Plays 16-bit mono PCM, and stops the moment the token is cancelled.</summary>
static class Speaker
{
    static readonly short[] Silence = new short[4096];

    public static async Task PlayAsync(byte[] wav, CancellationToken ct)
    {
        (short[] samples, int sampleRate) = Wav.Decode(wav);
        int position = 0;
        TaskCompletionSource finished = new(TaskCreationOptions.RunContinuationsAsynchronously);

        PaStream.Callback callback = (IntPtr input, IntPtr output, uint frameCount,
            ref StreamCallbackTimeInfo timeInfo, StreamCallbackFlags flags, IntPtr userData) =>
        {
            int remaining = samples.Length - position;
            int count = Math.Min(remaining, (int)frameCount);
            if (count > 0) Marshal.Copy(samples, position, output, count);

            // Pad the final buffer with silence instead of replaying stale memory,
            // without allocating on the audio thread.
            for (int padded = count; padded < frameCount; )
            {
                int n = Math.Min(Silence.Length, (int)frameCount - padded);
                Marshal.Copy(Silence, 0, output + padded * sizeof(short), n);
                padded += n;
            }

            position += count;
            return position >= samples.Length ? StreamCallbackResult.Complete : StreamCallbackResult.Continue;
        };

        int device = PortAudio.DefaultOutputDevice;
        if (device == PortAudio.NoDevice) throw new InvalidOperationException("No output device found.");

        StreamParameters parameters = new()
        {
            device = device,
            channelCount = 1,
            sampleFormat = SampleFormat.Int16,
            suggestedLatency = PortAudio.GetDeviceInfo(device).defaultHighOutputLatency,
            hostApiSpecificStreamInfo = IntPtr.Zero,
        };

        using PaStream stream = new(null, parameters, sampleRate, 0, StreamFlags.ClipOff, callback, null!);
        stream.SetFinishedCallback(_ => finished.TrySetResult());
        stream.Start();

        try
        {
            await finished.Task.WaitAsync(ct);
        }
        catch (OperationCanceledException)
        {
            // Barge-in: drop the buffered audio instead of draining it. The finished
            // callback still fires after this; completing an already-abandoned task is harmless.
            stream.Abort();
        }
    }
}

static class Wav
{
    public static byte[] Encode(short[] samples, int sampleRate)
    {
        byte[] wav = new byte[44 + samples.Length * 2];
        Span<byte> h = wav;
        "RIFF"u8.CopyTo(h);
        BinaryPrimitives.WriteInt32LittleEndian(h[4..], wav.Length - 8);
        "WAVEfmt "u8.CopyTo(h[8..]);
        BinaryPrimitives.WriteInt32LittleEndian(h[16..], 16);              // fmt chunk size
        BinaryPrimitives.WriteInt16LittleEndian(h[20..], 1);               // PCM
        BinaryPrimitives.WriteInt16LittleEndian(h[22..], 1);               // mono
        BinaryPrimitives.WriteInt32LittleEndian(h[24..], sampleRate);
        BinaryPrimitives.WriteInt32LittleEndian(h[28..], sampleRate * 2);  // byte rate
        BinaryPrimitives.WriteInt16LittleEndian(h[32..], 2);               // block align
        BinaryPrimitives.WriteInt16LittleEndian(h[34..], 16);              // bits per sample
        "data"u8.CopyTo(h[36..]);
        BinaryPrimitives.WriteInt32LittleEndian(h[40..], samples.Length * 2);
        MemoryMarshal.AsBytes(samples.AsSpan()).CopyTo(h[44..]);
        return wav;
    }

    /// <summary>Walks the chunks instead of assuming a 44-byte header: Piper's is, other writers' aren't.</summary>
    public static (short[] Samples, int SampleRate) Decode(byte[] wav)
    {
        ReadOnlySpan<byte> s = wav;
        if (!s[..4].SequenceEqual("RIFF"u8) || !s[8..12].SequenceEqual("WAVE"u8))
            throw new InvalidDataException("Not a RIFF/WAVE file.");

        int sampleRate = 0, offset = 12;
        while (offset + 8 <= s.Length)
        {
            ReadOnlySpan<byte> id = s.Slice(offset, 4);
            // Streaming writers put 0xFFFFFFFF here ("unknown"), which reads as -1: take the rest.
            uint declared = BinaryPrimitives.ReadUInt32LittleEndian(s[(offset + 4)..]);
            int size = (int)Math.Min(declared, (uint)(s.Length - offset - 8));
            ReadOnlySpan<byte> body = s.Slice(offset + 8, size);

            if (id.SequenceEqual("fmt "u8))
            {
                if (body.Length < 16) throw new InvalidDataException("fmt chunk too short.");
                short channels = BinaryPrimitives.ReadInt16LittleEndian(body[2..]);
                short bits = BinaryPrimitives.ReadInt16LittleEndian(body[14..]);
                if (channels != 1 || bits != 16) throw new InvalidDataException($"Expected 16-bit mono, got {bits}-bit x{channels}.");
                sampleRate = BinaryPrimitives.ReadInt32LittleEndian(body[4..]);
            }
            else if (id.SequenceEqual("data"u8))
            {
                if (sampleRate == 0) throw new InvalidDataException("data chunk before fmt chunk.");
                return (MemoryMarshal.Cast<byte, short>(body).ToArray(), sampleRate);
            }
            offset += 8 + size + (size & 1);    // chunks are word-aligned
        }
        throw new InvalidDataException("No data chunk.");
    }

    public static TimeSpan Duration(byte[] wav)
    {
        (short[] samples, int rate) = Decode(wav);
        return TimeSpan.FromSeconds((double)samples.Length / rate);
    }
}

Three details in there earn a sentence. stream.Stop() blocks until the last callback has returned, so the channel can be completed after it without losing the final buffer. The capture callback still allocates a small array per buffer. .NET makes no real-time guarantees either way; if you need them, record into a preallocated ring buffer instead. Playback pads its last buffer from a preallocated block of silence. And there is no GC.KeepAlive on the callbacks because PortAudioSharp2 pins each delegate with a GCHandle for as long as the stream lives. If you bind PortAudio yourself, that pinning is your job, or the next callback jumps into freed memory.

Speaker.PlayAsync takes a cancellation token for barge-in: when you have heard enough, Enter stops the audio with Abort(), which drops what is buffered instead of draining it.

Why push-to-talk, and not always listening

An always-on microphone looks friendlier and is worse in three measurable ways for this tool:

It hears the agent. On laptop speakers, the reply goes straight back into the microphone and arrives as a new request.
Whisper is unreliable at the edges of speech. On my eight recorded sentences, tiny.en returned [BLANK_AUDIO] for two that were perfectly audible, base.en turned one of them, a question about CS1061, into "Peace. See you in the next video. Bye." To be fair to Whisper, it was trained on a lot of YouTube. An always-on microphone feeds it far more edges than a key press does.
You lose the edges. With push-to-talk, the press says now I'm talking to you, and the release says I'm done. With always-on you need voice-activity detection to guess both, and every wrong guess is a turn.

So the harness filters Whisper's silence markers before the model ever sees them, which you will see in VoiceAgent.IsBlank below. An accidental key press costs nothing and runs nothing.

Speech-to-text: wrong roughly every other word

The HTTP clients are short:

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json.Serialization;

/// <summary>whisper.cpp's whisper-server: POST /inference, multipart, returns {"text": "..."}.</summary>
sealed class WhisperClient(HttpClient http)
{
    public async Task<string> TranscribeAsync(byte[] wav, string? vocabulary, string? language, CancellationToken ct)
    {
        using MultipartFormDataContent form = new();
        ByteArrayContent file = new(wav);
        file.Headers.ContentType = new MediaTypeHeaderValue("audio/wav");
        form.Add(file, "file", "speech.wav");
        form.Add(new StringContent("json"), "response_format");
        form.Add(new StringContent("0.0"), "temperature");
        if (vocabulary is not null) form.Add(new StringContent(vocabulary), "prompt");
        if (language is not null) form.Add(new StringContent(language), "language");

        using HttpResponseMessage response = await http.PostAsync("/inference", form, ct);
        response.EnsureSuccessStatusCode();
        WhisperResult result = await response.Content.ReadFromJsonAsync<WhisperResult>(ct)
            ?? throw new InvalidDataException("Empty response from whisper-server.");
        return result.Text.Trim();
    }

    sealed record WhisperResult([property: JsonPropertyName("text")] string Text);
}

/// <summary>Piper's HTTP server: POST /synthesize with {"text": "..."}, returns a WAV.</summary>
sealed class PiperClient(HttpClient http)
{
    public async Task<byte[]> SynthesizeAsync(string text, CancellationToken ct)
    {
        using HttpResponseMessage response = await http.PostAsJsonAsync("/synthesize", new { text }, ct);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadAsByteArrayAsync(ct);
    }
}

prompt is Whisper's initial prompt: text it treats as if it came just before the audio. Passing the project's vocabulary there is the cheapest accuracy fix available, and it works on exactly the words that break.

To see how often they break, I recorded the eight requests I actually make (Why is the build red?, Is CS1061 coming from the rename I did in ChangedFile?, Don't run the tests yet, just build.) in my own voice and accent, on a USB headset, at normal speed. Then I ran each clip through four Whisper models, with and without the vocabulary prompt. This is one speaker and eight sentences, so read it as a measured anecdote, not a benchmark.

The machine is a laptop with a 4-core i7-1165G7 running at a 1.69 GHz power limit, Docker on Windows, 4 threads. Latency is the median per sentence; the encoder column is whisper.cpp's own whisper-bench:

Model	Word error rate (no prompt / with prompt)	Encoder, one window	Median per sentence
`tiny.en`	0.76 / 0.68	1.4 s	1.8 s
`base.en`	0.66 / 0.59	3.8 s	5.6 s
`small.en`	0.64 / 0.48	12.3 s	13.4 s
`large-v3-turbo` (q5_0)	0.48 / 0.41	77.6 s	not measured, over a minute

By word error rate, not one model transcribed a single one of the eight sentences perfectly, though some misses were as small as "test" for "tests". Why is the build red? came back as "What is the view right?" from three of the four. The words that broke were the project's own: ClaudeReviewBot became "cloud review bot" and "Cloud Review", ChangedFile became "change flight" and "Change. Fight.", origin main became "originally". The prompt fixed several of those, and it cost something: on one clip, small.en returned fragments of the prompt, "CS1061, nullable, origin main, IDP, ChangedFile.", instead of what I said.

The encoder column explains most of the latency. Whisper's encoder always processes a full 30-second window, so a four-second sentence costs the encoder as much as a thirty-second one. The rest is decoding, and that is where the tail comes from: when the decoder hallucinates, it keeps going. That one prompted clip took tiny.en 31.2 seconds and small.en 38.6. On this hardware only tiny.en and base.en answer at a conversational pace, and those are the two least accurate.

One more result, unplanned. During the live test I spoke my first request in Spanish without thinking about it. tiny.en is English-only, and it did not fail: "¿Por qué está rojo el build?" came back as "Okay, let's start from a little bit." This one did not tell me it could not understand me. It handed me a fluent sentence in its own language.

Design for the transcript you will get

If the speech-to-text cannot be made accurate on a laptop, the agent has to work with what arrives. So I gave every distinct transcript from that table to the agent and recorded which tool it reached for first, without running anything: 64 transcripts, three runs each, on Claude Haiku 5.5.

Transcripts from	Right tool	Asked or did nothing	Wrong tool	Silence, filtered
The exact sentences	8	0	0	0
`large-v3-turbo` + prompt	8	0	0	0
`large-v3-turbo`, no prompt	7	1	0	0
`small.en` + prompt	7	0	1	0
`small.en`, no prompt	6	2	0	0
`base.en` + prompt	6	0	1	1
`base.en`, no prompt	5	1	1	1
`tiny.en` + prompt	6	1	0	1
`tiny.en`, no prompt	5	1	0	2

Each cell counts sentences, by the verdict most of the three runs agreed on.

"What is the view right?" ran dotnet_build every time. "Bravo to test, until which ones failed" ran dotnet_test. "We did a changed size minus minus moment" ran git_status, which is as close to "what did I change since my last commit" as anyone could hope for. When the transcript could mean two things, it asked: "Did you want me to run the build, or are you just letting me know what you're working on?"

The negated request, Don't run the tests yet, just build, never ran dotnet_test in any variant. That was the one I was most worried about.

The failures were real failures, not a strict scorer. "Did any nullable warnings show up" lost the word warnings in six transcripts (five of them heard "nullable coordinates"), and without it, the agent sometimes read the question as being about changes or tests. "What is the new thread?" ran git_status three times out of three.

None of this works because the model is clever about audio. It works because the system prompt says the transcript is bad, gives two examples of how, and tells it what to do when two readings lead to different actions. And because the harness prints heard: "..." on every turn, so when one wrong word flips the question, you see it before you believe the answer.

The first thing that breaks: everything it says

Here is the answer from the opening, in full. This is Part 1's system prompt, unchanged, with the reply sent to the speaker:

4 of 91 tests failed, all in `PatchParserTests` (`tests/ClaudeReviewBot.Tests/PatchParserTests.cs`):

1. **`AddedLines_reports_new_file_numbers_across_hunks`** (line 29): expected `[15, 19, 20, 21]`, got `[15, 20, 21, 22]`.
2. **`ParseUnifiedDiff_splits_per_file_and_strips_the_b_prefix`** (line 109): expected first element `1`, got `2`.
3. **`AddedLines_removed_lines_do_not_advance_the_counter`** (line 43): expected first element `2`, got `3`.
4. **`AddedLines_ignores_no_newline_marker_and_crlf`** (line 62): expected first element `2`, got `3`.

The failures are all in line-number tracking, and the actual values are consistently one higher or shifted by one. That suggests an off-by-one in how the parser counts new-file line numbers, but I haven't read the parser code to confirm. I can look at the parser in `src/ClaudeReviewBot.Core` next if you want.

That is a good written answer. Piper reads it in 67.9 seconds. The diagnosis, off by one, starts after the fourth test name. Reading Part 1's raw dotnet_test output aloud instead, the 1,600 characters with stack frames, takes 109.4 seconds.

The fix has two halves, and the second is the one that matters.

Give the agent somewhere else to put things. A fourth tool, show_on_screen, does nothing but print. It turns "don't read out file paths" from a prohibition into an instruction with somewhere to go.

Rewrite the system prompt for an ear. Two sentences maximum. Never say a path, a frame, a hash or a full identifier. Lead with the answer. Here is the same question, same repository, same model, with the new prompt:

Four tests failed, all in PatchParserTests, and they all show line numbers off by one. Details are on screen.

The four test names, lines and arrays went to show_on_screen. I ran both prompts twice against two broken states of the repository:

Scenario	Part 1's prompt, spoken	Voice prompt, spoken
Four failing tests	88–105 words, 57.2–67.9 s	19–21 words, 6.5–7.2 s
One compile error	103–120 words, 46.7–53.2 s	20 words, 7.1–7.2 s

And the diagnosis moved from the last paragraph to the first sentence, because "lead with the answer" also means find the answer before speaking. It is not free. Each turn makes one more API call, for show_on_screen, and sends two to three thousand more input tokens, which on Haiku is under a tenth of a cent. It is also slower before it starts talking: the voice-prompt turns took 8.3–19.9 seconds against 6.1–12.2 for Part 1's prompt, tools included. You wait a few seconds longer and then listen for seven seconds instead of a minute.

The agent

Here is the whole agent. The loop is Part 1's, the three tools are Part 1's, and the new parts are the prompt, show_on_screen, the silence filter and the length guard at the bottom:

using System.ComponentModel;
using System.Text.Json;
using System.Text.RegularExpressions;
using Anthropic;
using Anthropic.Models.Messages;

/// <summary>
/// Part 1's tool-use loop with two output channels: the final text is spoken, and anything
/// that can't be listened to goes to the screen through the show_on_screen tool.
/// </summary>
sealed class VoiceAgent(AnthropicClient client, string repo)
{
    const string Model = "claude-haiku-5-5";

    // About ten seconds of listening at Piper's pace. Longer replies go to the screen.
    const int MaxSpokenWords = 30;

    const string SystemPrompt = """
        You are a development assistant for the ClaudeReviewBot repository, and the
        developer is TALKING to you. Their words arrive through speech-to-text, and your
        reply is read aloud by a text-to-speech voice.

        Three projects. src/ClaudeReviewBot.Core holds the logic and is the one that
        matters. src/ClaudeReviewBot is a thin CLI wrapper. tests/ is xUnit.
        TreatWarningsAsErrors is on. CS1591 is noise; nullable warnings are real defects.

        The transcript is often wrong. Speech-to-text mangles identifiers and jargon:
        "ChangedFile" may arrive as "changed file" or "unchanged file", "build red" as
        "view right". Read for intent. If you can tell what was meant, act on it. If two
        readings would lead to different actions, ask one short question instead of guessing.

        Your reply is heard, not read. So:
        - Speak at most two short sentences. No lists, no markdown, no code.
        - Never say a file path, stack frame, hash, or full identifier aloud. Put them on
          the screen with show_on_screen, then say what matters and "details on screen".
        - Lead with the answer: "Build's red, three errors, all from your rename."

        Check state before answering. If the question is about the build, build. If it is
        about what changed, call git_status. Do not speculate.
        """;

    static readonly List<ToolUnion> Tools =
    [
        new Tool
        {
            Name = "git_status",
            Description = "Branch, ahead/behind counts, and changed and untracked files in the working copy.",
            InputSchema = new() { Properties = new Dictionary<string, JsonElement>() },
        },
        new Tool
        {
            Name = "dotnet_build",
            Description = "Builds the solution, or one project, and returns deduplicated errors and warnings.",
            InputSchema = new()
            {
                Properties = new Dictionary<string, JsonElement>
                {
                    ["project"] = JsonSerializer.SerializeToElement(new
                    {
                        type = "string",
                        description = "Optional project path relative to the repository root.",
                    }),
                },
            },
        },
        new Tool
        {
            Name = "dotnet_test",
            Description = "Runs the test suite and returns pass/fail counts plus each failure's message and own-code frames.",
            InputSchema = new() { Properties = new Dictionary<string, JsonElement>() },
        },
        new Tool
        {
            Name = "show_on_screen",
            Description = "Shows text on the developer's screen without reading it aloud. Use for paths, " +
                          "diagnostics, stack frames, lists: anything too long or too precise to listen to.",
            InputSchema = new()
            {
                Properties = new Dictionary<string, JsonElement>
                {
                    ["text"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                },
                Required = ["text"],
            },
        },
    ];

    readonly List<MessageParam> messages = [];

    /// <summary>
    /// Whisper marks silence and noise with bracketed tags: [BLANK_AUDIO], [inaudible],
    /// (silence), [Music]. A transcript that is nothing but tags is not a request: an
    /// accidental push-to-talk press must not cost an API call or run a tool.
    /// </summary>
    public static bool IsBlank(string transcript) =>
        Regex.Replace(transcript, @"\[[^\]]*\]|\([^)]*\)", "").Trim().Trim('.', ' ', '>').Length == 0;

    /// <summary>One spoken request in, one spoken reply out. Screen output goes to <paramref name="screen"/>.</summary>
    public async Task<string> AskAsync(string transcript, Action<string> screen, CancellationToken ct)
    {
        if (IsBlank(transcript)) return "";

        int turnStart = messages.Count;
        messages.Add(new() { Role = Role.User, Content = transcript });

        try
        {
            string? reply = await RunTurnAsync(screen, ct);
            if (reply is not null) return reply;
        }
        catch
        {
            // A failed request can leave a tool_use with no tool_result at the end of the
            // history, and every later request would be rejected. Drop the whole turn.
            messages.RemoveRange(turnStart, messages.Count - turnStart);
            throw;
        }

        messages.RemoveRange(turnStart, messages.Count - turnStart);
        return "I went in circles on that one. Try asking differently.";
    }

    /// <summary>Returns the spoken reply, or null if the step limit ran out.</summary>
    async Task<string?> RunTurnAsync(Action<string> screen, CancellationToken ct)
    {
        for (int step = 0; step < 8; step++)
        {
            Message response = await client.Messages.Create(new MessageCreateParams
            {
                Model = Model,
                MaxTokens = 4096,
                System = new List<TextBlockParam> { new() { Text = SystemPrompt, CacheControl = new CacheControlEphemeral() } },
                Tools = Tools,
                OutputConfig = new OutputConfig { Effort = Effort.Low },
                Messages = messages,
            }, ct);

            if (response.StopReason == "refusal")
            {
                // Haiku 5.5 has no server-side fallback, so the request stays declined.
                throw new RefusalException();
            }

            // Echo every block back unchanged - thinking blocks included, even when their
            // text is empty - or the next request fails the history check.
            List<ContentBlockParam> echo = [];
            List<ContentBlockParam> results = [];
            string spoken = "";

            foreach (ContentBlock block in response.Content)
            {
                if (block.TryPickThinking(out ThinkingBlock? thinking))
                {
                    echo.Add(new ThinkingBlockParam { Thinking = thinking.Thinking, Signature = thinking.Signature });
                }
                else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted))
                {
                    echo.Add(new RedactedThinkingBlockParam { Data = redacted.Data });
                }
                else if (block.TryPickText(out TextBlock? text))
                {
                    echo.Add(new TextBlockParam { Text = text.Text });
                    spoken += text.Text;
                }
                else if (block.TryPickToolUse(out ToolUseBlock? use))
                {
                    echo.Add(new ToolUseBlockParam { ID = use.ID, Name = use.Name, Input = use.Input });
                    (string content, bool isError) = await RunToolAsync(use, screen, ct);
                    results.Add(new ToolResultBlockParam { ToolUseID = use.ID, Content = content, IsError = isError });
                }
            }

            messages.Add(new() { Role = Role.Assistant, Content = echo });

            if (results.Count == 0) return GuardSpoken(spoken.Trim(), screen);

            // All results for one turn go back in ONE user message.
            messages.Add(new() { Role = Role.User, Content = results });
        }

        return null;
    }

    async Task<(string Content, bool IsError)> RunToolAsync(ToolUseBlock use, Action<string> screen, CancellationToken ct)
    {
        try
        {
            switch (use.Name)
            {
                case "git_status":
                    return (await DevTools.GitStatusAsync(repo, ct), false);
                case "dotnet_build":
                    string? project = use.Input.TryGetValue("project", out JsonElement p) && p.ValueKind == JsonValueKind.String
                        ? p.GetString()
                        : null;
                    return (await DevTools.DotnetBuildAsync(repo, project, ct), false);
                case "dotnet_test":
                    return (await DevTools.DotnetTestAsync(repo, ct), false);
                case "show_on_screen":
                    screen(use.Input["text"].GetString() ?? "");
                    return ("Shown.", false);
                default:
                    return ($"Unknown tool {use.Name}.", true);
            }
        }
        // A tool that can't run is an answer for the model ("I couldn't build"), not a crash.
        // Win32Exception is what Process.Start throws for a missing executable or a bad
        // working directory.
        catch (Exception ex) when (ex is TimeoutException or InvalidOperationException or KeyNotFoundException
                                       or Win32Exception or IOException)
        {
            return (ex.Message, true);
        }
    }

    /// <summary>
    /// The prompt asks for short replies; this makes sure of it. A reply too long to listen
    /// to goes to the screen, and only its first sentence is spoken.
    /// </summary>
    static string GuardSpoken(string spoken, Action<string> screen)
    {
        string[] words = spoken.Split(' ', StringSplitOptions.RemoveEmptyEntries);
        if (words.Length <= MaxSpokenWords) return spoken;

        screen(spoken);
        // A sentence ends at . ? ! followed by a space or the end - not inside
        // "ChangedFile.cs" or "1.8 seconds".
        Match end = Regex.Match(spoken, @"[.?!](\s|$)");
        string first = end.Success ? spoken[..(end.Index + 1)] : spoken;
        string[] firstWords = first.Split(' ', StringSplitOptions.RemoveEmptyEntries);
        if (firstWords.Length > MaxSpokenWords) first = string.Join(' ', firstWords.Take(MaxSpokenWords)) + "...";
        return $"{first} The rest is on screen.";
    }
}

sealed class RefusalException() : Exception("The model declined this request.");

DevTools is Part 1's three tool functions and its RunAsync helper, wrapped in static partial class DevTools and made public, along with Part 1's BuildOutput regex class and its Diagnostic and ProcessResult records.

The prompt is a request; GuardSpoken is a guarantee. In the four scripted voice turns above, the prompt alone kept every reply under 30 words and the guard never fired. Then in the live session I asked an open question, "What do I need to do to fix it?", and the reply ran long. The guard moved it to the screen and spoke one sentence and "The rest is on screen." A rule that only lives in a prompt holds until the first question nobody tested.

Tool failures go back to the model. If dotnet cannot start, because of a missing SDK or a bad path, Process.Start throws a Win32Exception. My first version did not catch it, and the first time it happened, the whole agent died mid-sentence. Now the exception becomes a tool_result with IsError = true, and the agent says so. Pointed at a directory that does not exist, it answered: "I couldn't tell whether it's red. The build tool failed twice before compiling, because it's pointed at a working directory that doesn't exist. Details on screen."

A failed request must not poison the history. If a request fails after a tool step (a rate limit, an overloaded API, a dropped connection), messages ends with a tool_use that has no tool_result, and every later request is rejected. So AskAsync drops the whole turn on any exception, and also when it runs out of steps, and the loop below catches the error, says so, and keeps the session. With an invalid key, two turns in a row failed, were announced, and the session carried on.

The loop

using System.Diagnostics;
using Anthropic;
using Anthropic.Exceptions;
using PortAudioSharp;

// usage: dotnet run -- <repo path> [--text]
//   --text  type instead of talking (the reply is still spoken)
if (args.Length == 0)
{
    Console.Error.WriteLine("usage: dotnet run -- <repo path> [--text]");
    return 2;
}

string repo = args[0];
bool typed = args.Contains("--text");

// Whisper's initial prompt: spelling hints for the words it gets wrong most.
const string Vocabulary =
    "dotnet build, dotnet test, git status, xUnit, ClaudeReviewBot, ChangedFile, CS1061, nullable, origin main.";

// Fail before opening the microphone, not after the first recording.
if (string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")))
{
    Console.Error.WriteLine("ANTHROPIC_API_KEY is not set.");
    return 1;
}

using HttpClient whisperHttp = new() { BaseAddress = new Uri("http://localhost:8080"), Timeout = TimeSpan.FromMinutes(2) };
using HttpClient piperHttp = new() { BaseAddress = new Uri("http://localhost:5000"), Timeout = TimeSpan.FromMinutes(2) };
WhisperClient whisper = new(whisperHttp);
PiperClient piper = new(piperHttp);

try
{
    await piper.SynthesizeAsync("ready", CancellationToken.None);
    if (!typed)
        await whisper.TranscribeAsync(Wav.Encode(new short[Microphone.SampleRate / 2], Microphone.SampleRate), null, "en", CancellationToken.None);
}
catch (HttpRequestException ex)
{
    Console.Error.WriteLine($"Start the containers first (docker compose up -d): {ex.Message}");
    return 1;
}

PortAudio.Initialize();
try
{
    VoiceAgent agent = new(new AnthropicClient(), repo);
    Console.WriteLine(typed ? "Type a request, empty line to quit." : "Enter to talk, Enter again to stop. Ctrl+C to quit.");
    bool alreadyPressed = false;

    while (true)
    {
        string heard;
        if (typed)
        {
            Console.Write("\n> ");
            heard = Console.ReadLine() ?? "";
            if (heard.Length == 0) break;
        }
        else
        {
            if (!alreadyPressed)
            {
                Console.Write("\n[Enter to talk] ");
                Console.ReadLine();
            }
            alreadyPressed = false;
            Console.Write("listening... ");
            byte[] wav = await Microphone.RecordAsync(ct => Task.Run(() => Console.ReadLine(), ct), CancellationToken.None);

            Stopwatch stt = Stopwatch.StartNew();
            try
            {
                heard = await whisper.TranscribeAsync(wav, Vocabulary, "en", CancellationToken.None);
            }
            catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
            {
                Console.WriteLine($"\n  speech-to-text failed: {ex.Message}");
                continue;
            }
            // Always show what was heard: one wrong word can flip the question.
            Console.WriteLine($"\n  heard: \"{heard}\"  ({stt.ElapsedMilliseconds} ms)");
        }

        Stopwatch thinking = Stopwatch.StartNew();
        string reply;
        try
        {
            reply = await agent.AskAsync(heard, text => Console.WriteLine($"  ┌ screen\n  │ {text.Replace("\n", "\n  │ ")}\n  └"), CancellationToken.None);
        }
        catch (RefusalException)
        {
            reply = "I can't help with that one.";
        }
        catch (Exception ex) when (ex is AnthropicException or HttpRequestException or TaskCanceledException)
        {
            // Rate limits, overload, a dropped connection: say so and keep the session.
            Console.WriteLine($"  request failed: {ex.Message}");
            reply = "I couldn't reach the model. Try again in a moment.";
        }
        Console.WriteLine($"  ({thinking.ElapsedMilliseconds} ms)");
        if (reply.Length == 0) continue;

        Console.WriteLine($"  says: \"{reply}\"");
        byte[] speech;
        try
        {
            speech = await piper.SynthesizeAsync(reply, CancellationToken.None);
        }
        catch (Exception ex) when (ex is HttpRequestException or TaskCanceledException)
        {
            Console.WriteLine($"  text-to-speech failed: {ex.Message}");
            continue;
        }

        if (typed)
        {
            await Speaker.PlayAsync(speech, CancellationToken.None);
            continue;
        }

        // Enter while it speaks cuts it off (barge-in). Enter after it finishes starts the
        // next recording, so either way one key press moves the conversation on.
        using CancellationTokenSource stop = new();
        Task<string?> press = Task.Run(Console.ReadLine);
        Task playback = Speaker.PlayAsync(speech, stop.Token);
        if (await Task.WhenAny(press, playback) == press) stop.Cancel();
        await playback;
        if (!press.IsCompleted) Console.Write("  [Enter to talk] ");
        await press;
        alreadyPressed = true;
    }
}
finally
{
    PortAudio.Terminate();
}
return 0;

One key drives everything. Enter while it speaks cuts it off; Enter after it finishes starts the next recording. --text swaps the microphone for the keyboard and keeps the voice, which is useful in an open-plan office and for testing the loop without talking to it.

Why Haiku, not the model from Part 1

Part 1 used Claude Opus 5. This post uses Claude Haiku 5.5, and the reason is that the reply now sits behind two other slow things: speech-to-text before it, and synthesis after it.

I gave Claude Opus 5.5, the current Opus, the twelve transcripts where Haiku had asked, failed or changed its answer between runs. Opus ran once on each, against Haiku's three, so this is a small sample. Opus did recover more of them: all four "nullable coordinates" questions became builds. But it also acted where Haiku had asked. "What is the field print?" made Haiku ask three times out of three; Opus, on its one run, ran the build and the tests. For an agent you talk to, a question when the transcript is nonsense is the behavior you want.

On those same twelve transcripts, an Opus call cost about thirty times what a Haiku call did, with a median of 2.5 seconds against 1.8. A turn takes one to three calls, so that is up to two more seconds on a loop that already takes seven to twelve. The design above (show what was heard, ask when unsure) covers most of the accuracy gap. The cost and the seconds stay.

Haiku 5.5 brings three API differences that shape the code. It rejects any non-default temperature, so you cannot pin its output, and the same transcript can get a different tool on a different run: 8 of my 64 transcripts did. Its thinking is adaptive and on by default, so thinking blocks must be echoed back unchanged even when their text is empty. And effort is the latency lever: on the transcripts of the three easiest requests (build, tests, status), low and medium picked the same tool in 21 of 22, so the agent runs at low. I did not compare them on the hard cases.

A real session

Four turns, spoken, against a repository where I had renamed ChangedFile.Patch to Diff and forgotten one call site. Transcripts are as Whisper heard them, with tiny.en and the vocabulary prompt:

Heard	Tools	Said
"What is the build, great?"	`dotnet_build`, screen	"The build's red with one error: ReviewOrchestrator is calling a Patch property that ChangedFile doesn't have. Details on screen."
"Why did I change?"	`git_status`, screen	"I can't see your reasons, only the edits. Three files changed, and ChangedFile.cs is the likely cause of the Patch error. The list is on screen."
"Run the test."	`dotnet_test`	"The tests didn't run because the build is still failing, so there are no results yet. Fixing the Patch error in ReviewOrchestrator should unblock them."
"What I need to do to fix it."	none	"I can't read the code from here, so I can't say the exact fix yet. The rest is on screen."

The second row is the transcript problem in one line. I said what; Whisper heard why; the agent answered the question it was given, philosophically, before giving me the file list anyway. The fourth row is a missing tool, and Part 3's material.

The measured stages between releasing Enter and the first word of the reply added up to 7 to 12 seconds per turn: 2.6–3.6 s of speech-to-text, 2.1–7.4 s of agent (one to three API calls, plus the build itself), and 2.3–2.9 s for Piper to synthesize the whole reply before any of it plays. Decoding the WAV and the audio device's own latency come on top, and I did not time them. That last number is the cheapest to cut: synthesize the first sentence, start playing it, synthesize the rest behind it.

The bug Part 1 shipped

Halfway through this post, an update installed the .NET 11 RC SDK next to .NET 10. From then on, the agent reported every build as broken with MSB4216, a task-host error from deep inside MSBuild, even on code that compiled fine from a terminal.

dotnet run on a project exports MSBuildSDKsPath and MSBuildExtensionsPath, pointing at the SDK that built the agent. Every dotnet build the agent starts inherits them. The repository's global.json selects .NET 10, the inherited variables load .NET 11's targets, and the build dies before it reaches a line of code. Run against a build with one real CS1061, Part 1's original helper returned six MSB4216 and six MSB4027 errors and no CS1061 at all. Interestingly, dotnet run app.cs on a file-based app does not export those two variables, which is why the bug hides in some setups and not others.

The fix is three lines in RunAsync, which Part 1 now includes. It drops every MSBuild* variable, including any you set on purpose, such as MSBUILDDEBUGPATH; if you rely on one, remove MSBuildSDKsPath and MSBuildExtensionsPath by name instead.

foreach (string key in psi.Environment.Keys
             .Where(k => k.StartsWith("MSBuild", StringComparison.OrdinalIgnoreCase)).ToList())
    psi.Environment.Remove(key);

When not to give your agent a voice

If you are at your desk with your hands on the keyboard, typing is faster and more precise than talking. Every number above says so: 7 to 12 seconds per turn, and a transcript that gets more than half the words wrong.

Voice earns its place when your hands or eyes are busy elsewhere: walking a test run while you read a diff on the other monitor, or asking "is it green yet?" from across the room while a slow build finishes. It also suits short questions with short answers, which is most of what you ask a build agent.

It is the wrong tool for anything that writes, deletes or pushes. Part 1's tools are read-only on purpose, and that matters more now: a misheard request can at worst run a build. Before adding a tool with side effects to a voice agent, make it ask for confirmation in code, not in the prompt.

If you would rather not run models locally, hosted speech-to-text and text-to-speech services run on GPUs and skip the CPU latency above, at the price of sending your voice to someone else. I have not measured them here. Everything in the design still applies to them; only the latency table would change.

Key Takeaways

Your agent's answers are written to be read. Read aloud, the same answer took 57–68 seconds. A voice prompt with an on-screen channel brought it to 7, with the diagnosis first.
Design for the transcript you will get. On a laptop CPU, the two Whisper models fast enough to talk to got 59 to 76 percent of my words wrong. Tell the model the transcript is bad, have it ask when two readings diverge, and always show what was heard.
A prompt rule needs a code guarantee. The 30-word guard never fired in testing and fired on the first open question in real use. The same goes for silence: filter it before it costs a call.
Pick the model for the whole loop, not the reply. On my twelve hardest transcripts, Opus recovered more garbled requests, but cost about thirty times as much per call, added time to a loop that is already slow, and acted where Haiku asked. For this agent, Haiku plus good design was the better choice.
Measure in the configuration your reader runs. The SDK leak only appears under dotnet run on a project, and the Compose flags only fail silently. Both looked fine until measured the right way.

The complete code is on GitHub, ready to clone and run: Juxn89/dotnet-voice-dev-agent. It is the code from this post, with Part 1's tools and both of their fixes.

Next in the series: Building a .NET Dev Agent, Part 3: Make It Remember You, session memory, so the agent stops asking which project matters every morning, and so "what was I doing yesterday?" becomes a question it can answer.

RabbitMQ de los fundamentos a producción, Parte 2: construir un servicio escalable

Juan Gómez — Thu, 15 Oct 2026 14:00:00 +0000

RabbitMQ de los fundamentos a producción, Parte 2: construir un servicio escalable

Maté el broker a mitad de una ráfaga de 20.000 pedidos. El publisher de la Parte 1 había llamado a channel.publish 10.900 veces sin un solo error. Cuando RabbitMQ volvió, la cola tenía 10.433 pedidos. Faltaban 467, y el proceso no se enteró: ni una excepción, ni una línea de log, ni una promesa rechazada. Para el checkout, a todos esos clientes se les iba a cobrar con normalidad.

La Parte 1 explicaba cómo hacer llegar un mensaje a la cola correcta. Esta parte trata de lo que lo mantiene ahí cuando algo falla: publisher confirms, conexiones que se recuperan solas, consumidores que puedes escalar y apagar sin perder trabajo y, al final, un ensayo medido que mata el broker con carga y cuenta qué sobrevivió. La topología de Aurora Coffee Co. es la misma, y src/topology.ts es el mismo.

El hueco que dejó la Parte 1

La Parte 1 terminaba reconociendo un problema. Así resolvía los reintentos en su primera versión, en src/billing-consumer.ts:

// Lo aparca en la cola de espera con su routing key y sus cabeceras originales,
// para que el contador x-death siga acumulando entre intentos.
channel.publish(RETRY_EXCHANGE, message.fields.routingKey, message.content, {
  persistent: true,
  headers: message.properties.headers,
  messageId: message.properties.messageId,
});
channel.ack(message);

Son dos operaciones, no una transacción. Si la copia nunca llega a la cola de reintentos, el ack ya borró el original y el pedido desaparece. Además, que channel.publish devuelva true no significa lo que parece: solo indica que el mensaje cupo en un buffer de tu propio proceso. El broker todavía no lo ha visto, y puede que nunca lo vea.

El publisher del checkout tiene exactamente el mismo punto ciego, y de ahí salen los 467 pedidos perdidos del principio. Para cerrarlo hacen falta los publisher confirms.

Y dos cosas en las que la Parte 1 se equivocó

Antes de construir sobre la Parte 1, comprobé contra RabbitMQ 4.3 qué hacía su código cuando algo fallaba. Dos de sus afirmaciones no aguantaron, y la Parte 1 ya está corregida. Esto es lo que mostraron las pruebas.

El contador de reintentos nunca contaba. La Parte 1 leía el header x-death del broker para contar los reintentos. Este es su consumidor, sin cambios, con el servicio de pagos inalcanzable y un solo pedido que procesar:

$ docker run … -e PAYMENTS_URL=http://payments-is-down.invalid:4001 aurora-billing node part1/billing-consumer.ts
$ node src/checkout.ts 1
[checkout] no queue bound for order.us.refunded
[checkout] 1/1 orders confirmed by the broker
$ docker logs <consumer> | grep -E "^\[billing\] (retry|giving up)"
[billing] retry 1/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
name    messages
orders.billing  0
orders.billing.retry    1
orders.billing.dead 0

Reintento 2 de 3, cada 30 segundos, todo el tiempo que lo dejé correr. El pedido nunca llega a orders.billing.dead. Al leer el mensaje en la cola de reintentos se ve el motivo: después de varias vueltas, su x-death seguía diciendo count: 1. Cuando un consumidor republica un mensaje, RabbitMQ 4.x no conserva el x-death que manda el cliente; solo anota la expiración que acaba de ver. La solución es llevar la cuenta en un header propio del consumidor, retry-count, que es lo que lee ahora retriesSoFar. La misma prueba con el consumidor de este artículo:

$ docker run … -e PAYMENTS_URL=http://payments-is-down.invalid:4001 aurora-billing
$ node src/checkout.ts 1
[checkout] no queue bound for order.us.refunded
[checkout] 1/1 orders confirmed by the broker
$ docker logs <consumer> | grep -E "^\[billing\] (retry|giving up)"
[billing] retry 1/3 for ord-14f839be-4815-4639-88b2-d8deb9302923 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-14f839be-4815-4639-88b2-d8deb9302923 [TypeError: fetch failed] {
[billing] retry 3/3 for ord-14f839be-4815-4639-88b2-d8deb9302923 [TypeError: fetch failed] {
[billing] giving up on ord-14f839be-4815-4639-88b2-d8deb9302923 after 3 retries [TypeError: fetch failed] {
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
name    messages
orders.billing  0
orders.billing.retry    0
orders.billing.dead 1

x-delivery-limit no frena un bucle de requeue. La Parte 1 presentaba el límite de entregas como la primera defensa contra un mensaje que falla siempre. En RabbitMQ 4.3 cuenta los mensajes que vuelven a la cola porque se cerró su canal o su conexión: en mi prueba, 6 entregas y luego dead-letter. No cuenta un nack(message, false, true) explícito sobre un canal abierto: 50 requeues seguidos del mismo mensaje y ningún dead-letter. Es una red de seguridad para los consumidores que se caen, no un freno para el código que devuelve mensajes a la cola. Por eso cambia una línea del consumidor de este artículo, como verás más abajo.

Antes de nada, actualiza amqplib

Un paso de mantenimiento antes del código nuevo. La Parte 1 fijó amqplib@^0.10.5, y esa versión ya estaba atrasada cuando se publicó el artículo: amqplib 1.0 salió en marzo de 2026 y hoy la rama vigente es la 2.x. Para este artículo importan tres cambios:

Desde la 1.2 trae sus propios tipos, así que @types/amqplib sobra.
La 1.1 añadió recuperación de conexión opcional. Buena parte de este artículo trata de lo que hace y de lo que te deja a ti.
La 2.0 cambió un valor por defecto: heartbeat: 0 ahora desactiva los heartbeats, en lugar de significar "usa el valor del servidor". Si nunca lo configuraste, no te afecta.

Las dependencias del package.json de la Parte 1:

{
  "dependencies": { "amqplib": "^0.10.5" },
  "devDependencies": { "@types/amqplib": "^0.10.6", "typescript": "^5.9.0" }
}

El de la Parte 2, completo:

{
  "name": "aurora-orders-queue",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24" },
  "dependencies": { "amqplib": "^2.2.0" },
  "devDependencies": { "typescript": "^5.9.0", "@types/node": "^24.0.0" }
}

@types/node está para que tsc --noEmit reconozca process y Buffer. Compilé el topology.ts y el billing-consumer.ts de la Parte 1 contra los tipos que trae amqplib 2.2, y los dos pasan sin tocar nada.

Publisher confirms: la mitad del contrato que le toca al broker

El consumidor le confirma al broker que procesó un mensaje. Un publisher confirm es lo mismo en sentido contrario: el broker le confirma al publisher que recibió el mensaje. Se activa por canal (createConfirmChannel en amqplib), y a partir de ahí cada publicación recibe exactamente una respuesta:

basic.ack: el broker se hace responsable del mensaje. Si es persistente y va a una cola clásica durable, significa que ya está escrito en disco. En una cola quorum, que la mayoría de las réplicas lo tiene en su log de Raft, sea cual sea el modo de entrega, porque las colas quorum persisten todos los mensajes. Con un solo nodo, esa mayoría es el propio nodo, con el fsync hecho.
basic.nack: el broker no pudo aceptarlo, normalmente por un error interno o porque una cola llena rechaza publicaciones. Es raro, pero pasa.
Ninguna respuesta, porque la conexión se cayó antes. Este es el caso que importa, y no significa que el mensaje se perdiera. Significa que no lo sabes: puede que el broker lo escribiera y perdiera el socket antes de mandar el ack.

De ese tercer caso salen directamente dos consecuencias.

Un mensaje sin confirmar hay que enviarlo otra vez, así que los duplicados forman parte del diseño. Al reenviar tras reconectar, a veces llegará un pedido que el broker ya tenía. Por eso el consumidor de la Parte 1 manda el id del pedido como clave de idempotencia. El ensayo del final cuenta esos duplicados en lugar de fingir que no existen.

Que llegue el confirm no significa que el mensaje se enrutara. El otro problema de la Parte 1 era una routing key mal escrita que no coincidía con ningún binding. Con mandatory: true el broker devuelve el mensaje (basic.return), y después igual manda el basic.ack, porque para él ya terminó su trabajo con ese mensaje. El return siempre llega antes que el ack, así que un publisher que registra los returns puede distinguir "confirmado" de "confirmado y tirado a la basura".

Los confirms no son lentos. Esperarlos de uno en uno, sí.

La objeción habitual contra los confirms es el rendimiento. Medí tres maneras de publicar los mismos 20.000 pedidos persistentes en la cola quorum, dos corridas de cada una:

run 1
no confirms (fire-and-forget)              6859 msg/s
confirms, awaiting each one                  70 msg/s
confirms, 1,000 in flight (OrderPublisher)   5728 msg/s
run 2
no confirms (fire-and-forget)              7425 msg/s
confirms, awaiting each one                  78 msg/s
confirms, 1,000 in flight (OrderPublisher)   4784 msg/s

Esperar cada confirm antes de mandar el siguiente hunde el rendimiento en dos órdenes de magnitud, porque cada mensaje espera, él solo, a que el broker lo escriba en disco y responda. Mantener una ventana de mensajes en vuelo e ir emparejando los confirms a medida que llegan conserva la mayor parte del rendimiento: 4.784–5.728 msg/s frente a 6.859–7.425 sin confirms. Esa diferencia es lo que cuesta saberlo, y es poca al lado de la alternativa. Las cifras absolutas son de Docker Desktop en un portátil con Windows, donde un fsync a través de la máquina virtual es lento, así que las tuyas serán otras. Lo que importa es la proporción. Si te quedas con una sola frase de esta sección, que sea esta: nunca hagas await de un confirm dentro de un bucle que publica.

El publisher

Este es el lado del checkout, con confirms, una ventana limitada de mensajes en vuelo y reenvío tras reconectar. Sustituye al channel.publish a secas de la Parte 1 y a su manejo de drain.

// src/order-publisher.ts
import type { ChannelModel, ConfirmChannel, Options, RecoveringChannelModel } from 'amqplib';
import { connectWithRecovery } from './connection.ts';
import { assertTopology, ORDERS_EXCHANGE } from './topology.ts';

export type OrderPlaced = {
  orderId: string;
  sku: string;
  quantity: number;
  totalCents: number;
};

/** Acota la memoria y es la contrapresión: quien publica espera si hay tantos sin confirmar. */
const MAX_IN_FLIGHT = 1_000;

// amqplib rechaza el callback del confirm con este mensaje cuando el broker hace nack, y
// con "channel closed" cuando el canal muere antes. Solo vale la pena reenviar el segundo.
const BROKER_NACK = 'message nacked';

type Unconfirmed = {
  routingKey: string;
  content: Buffer;
  options: Options.Publish & { messageId: string };
  /** Se escribió en un socket al menos una vez, así que el broker puede tenerlo. */
  sent: boolean;
  resolve: () => void;
  reject: (error: Error) => void;
};

export class UnroutableError extends Error {
  override name = 'UnroutableError';
}

/** El plazo venció antes de que el pedido llegara a un socket. Nunca se publicó. */
export class NotPublishedError extends Error {
  override name = 'NotPublishedError';
}

/**
 * El plazo venció después de enviar el pedido pero antes del confirm. Sigue en cola y
 * se reenvía hasta que se confirme, así que no se debe informar como fallido.
 */
export class PublishPendingError extends Error {
  override name = 'PublishPendingError';
}

export class OrderPublisher {
  #connection: RecoveringChannelModel | null = null;
  #channel: ConfirmChannel | null = null;
  #closed = false;
  #nextKey = 0;
  readonly #unconfirmed = new Map<number, Unconfirmed>();
  readonly #returned = new Set<string>();
  readonly #waitingForCapacity: Array<() => void> = [];
  readonly #waitingForIdle: Array<() => void> = [];

  static async start(): Promise<OrderPublisher> {
    const publisher = new OrderPublisher();
    publisher.#connection = await connectWithRecovery('checkout-publisher', (model) =>
      publisher.#attach(model),
    );
    return publisher;
  }

  /**
   * Se resuelve cuando el broker confirma el pedido. Se rechaza si el broker lo rechaza,
   * si ninguna cola está enlazada a la routing key o si `signal` se aborta antes. Mientras
   * el broker no responde, espera: el pedido se reenvía en la siguiente conexión.
   */
  async publish(routingKey: string, order: OrderPlaced, { signal }: { signal?: AbortSignal } = {}): Promise<void> {
    while (this.#unconfirmed.size >= MAX_IN_FLIGHT && !this.#closed && !signal?.aborted) {
      await new Promise<void>((resolve) => {
        this.#waitingForCapacity.push(resolve);
        signal?.addEventListener('abort', () => resolve(), { once: true });
      });
    }
    if (this.#closed) throw new NotPublishedError('publisher is closed');
    if (signal?.aborted) throw new NotPublishedError(`no capacity before the deadline for ${order.orderId}`);

    const { promise, resolve, reject } = Promise.withResolvers<void>();
    const key = this.#nextKey++;
    const message: Unconfirmed = {
      routingKey,
      content: Buffer.from(JSON.stringify(order)),
      options: {
        persistent: true,
        mandatory: true,
        contentType: 'application/json',
        messageId: order.orderId,
      },
      sent: false,
      resolve,
      reject,
    };

    this.#unconfirmed.set(key, message);
    // Sin canal estamos entre dos conexiones. El pedido espera en #unconfirmed y
    // #attach lo envía en cuanto vuelva a haber canal.
    if (this.#channel) this.#send(this.#channel, key, message);

    signal?.addEventListener('abort', () => {
      if (!this.#unconfirmed.has(key)) return;
      if (!message.sent) {
        // Nunca salió de este proceso: se puede descartar y dar por fallido sin riesgo.
        this.#settle(key);
        reject(new NotPublishedError(`${order.orderId} was not published before the deadline`));
      } else {
        // El broker quizá ya lo tiene. Se sigue reenviando; quien llamó solo deja de esperar.
        reject(new PublishPendingError(`${order.orderId} is sent but not yet confirmed`));
      }
    }, { once: true });

    return promise;
  }

  /** Espera los confirms pendientes (con un plazo máximo) y luego cierra la conexión. */
  async close(timeoutMs = 10_000): Promise<void> {
    this.#closed = true;
    for (const wake of this.#waitingForCapacity.splice(0)) wake();
    if (this.#unconfirmed.size > 0) {
      const idle = new Promise<void>((resolve) => this.#waitingForIdle.push(resolve));
      await Promise.race([idle, new Promise((resolve) => setTimeout(resolve, timeoutMs))]);
    }
    await this.#connection?.close();
    for (const message of this.#unconfirmed.values()) {
      message.reject(new PublishPendingError(`publisher closed before ${message.options.messageId} was confirmed`));
    }
    this.#unconfirmed.clear();
  }

  /** Se ejecuta después de cada conexión y reconexión. */
  async #attach(model: ChannelModel): Promise<void> {
    const channel = await model.createConfirmChannel();
    await assertTopology(channel);

    // Los returns pertenecen al canal que los vio. Un return cuyo confirm murió con el canal
    // viejo no debe marcar el reenvío, que esta vez puede enrutarse sin problema.
    this.#returned.clear();

    // Con `mandatory`, un mensaje sin destino vuelve como basic.return *antes* de su
    // confirm, y ese confirm sigue siendo un ack. Anotamos el return para leer bien el ack.
    channel.on('return', (returned) => {
      const id: unknown = returned.properties.messageId;
      if (typeof id === 'string') this.#returned.add(id);
    });

    // Un error de canal deja la conexión viva, así que la recuperación nunca se activa y
    // todo lo no confirmado esperaría para siempre. Cerrar la conexión le pasa el problema
    // a la recuperación, que espera, reconecta y vuelve a ejecutar este método.
    channel.on('error', (error: Error) => {
      console.error(`[checkout-publisher] channel error, rebuilding: ${error.message}`);
      void model.close().catch(() => undefined);
    });
    channel.on('close', () => {
      if (this.#channel === channel) this.#channel = null;
    });

    this.#channel = channel;

    // Lo que la conexión anterior dejó sin confirmar sale otra vez. Parte puede estar ya
    // en disco y solo se perdió el confirm: eso es un duplicado, y la clave de
    // idempotencia del consumidor es lo que lo vuelve inofensivo.
    for (const [key, message] of this.#unconfirmed) this.#send(channel, key, message);
  }

  #send(channel: ConfirmChannel, key: number, message: Unconfirmed): void {
    try {
      channel.publish(ORDERS_EXCHANGE, message.routingKey, message.content, message.options, (error) => {
        if (error instanceof Error && error.message !== BROKER_NACK) return; // se reenvía al reconectar

        this.#settle(key);
        const wasReturned = this.#returned.delete(message.options.messageId);

        if (error) message.reject(new Error(`broker refused ${message.options.messageId}`));
        else if (wasReturned) message.reject(new UnroutableError(`no queue bound for ${message.routingKey}`));
        else message.resolve();
      });
      message.sent = true;
    } catch {
      // El canal se cerró mientras publicábamos. El mensaje sigue en #unconfirmed.
    }
  }

  #settle(key: number): void {
    this.#unconfirmed.delete(key);
    this.#waitingForCapacity.shift()?.();
    if (this.#unconfirmed.size === 0) {
      for (const wake of this.#waitingForIdle.splice(0)) wake();
    }
  }
}

Lo que conviene mirar, de más a menos importante:

#unconfirmed es todo el diseño. Un mensaje entra ahí antes de enviarse y solo sale cuando el broker responde. Lo que siga dentro cuando una conexión muere, #attach lo reenvía en la siguiente. Ese buffer en memoria no es una caché: es la lista de pedidos cuyo destino todavía no conoces.
La ventana también frena a quien publica. La Parte 1 esperaba el evento drain cuando se llenaba el buffer del socket. Aquí quien llama espera en cuanto hay 1.000 mensajes sin confirmar, y eso también pone techo al buffer del socket. Con el broker caído, publish() se queda esperando, y la petición del checkout con él. Es lo honesto: si una petición no se puede guardar de forma duradera, no debería responder que todo salió bien.
Distingue un nack de un canal muerto. amqplib avisa de las dos cosas por el mismo callback, con mensajes distintos. Un nack es el broker diciendo que no, así que quien llamó recibe un error. Un canal cerrado no dice nada sobre el mensaje, así que se queda en la cola para la siguiente conexión.
Ante un error de canal, cierra la conexión a propósito. Parece exagerado, y es deliberado. Lo explico en la siguiente sección.
Un plazo solo puede cancelar lo que nunca se envió. Si pasas { signal: AbortSignal.timeout(…) }, recibes uno de dos errores. NotPublishedError significa que el pedido nunca llegó a un socket: no existe para el broker, y quien llamó puede informar del fallo sin riesgo. PublishPendingError significa que se envió y que el broker quizá ya lo tiene, así que sigue en cola y se reenvía hasta que llegue el confirm. Si tratas ese segundo caso como un fallo, el cliente ve "el pago falló" y se le cobra igual.

Desde el checkout se usa como cualquier otra llamada asíncrona:

// src/checkout.ts
import { randomUUID } from 'node:crypto';
import { OrderPublisher, UnroutableError } from './order-publisher.ts';

const COUNT = Number(process.argv[2] ?? 10);
const publisher = await OrderPublisher.start();

const results = await Promise.allSettled(
  Array.from({ length: COUNT }, () =>
    publisher.publish('order.us.placed', {
      orderId: `ord-${randomUUID()}`,
      sku: 'BEAN-ETH-250',
      quantity: 1,
      totalCents: 1450,
    }),
  ),
);

// Una routing key sin ningún binding: el confirm llega, pero no es un éxito.
try {
  await publisher.publish('order.us.refunded', {
    orderId: `ord-${randomUUID()}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: -1450,
  });
} catch (error) {
  if (!(error instanceof UnroutableError)) throw error;
  console.warn(`[checkout] ${error.message}`);
}

const confirmed = results.filter((result) => result.status === 'fulfilled').length;
console.log(`[checkout] ${confirmed}/${COUNT} orders confirmed by the broker`);
await publisher.close();

$ node src/checkout.ts 100
[checkout] no queue bound for order.us.refunded
[checkout] 100/100 orders confirmed by the broker

La línea del reembolso es la routing key mal escrita de la Parte 1, que esta vez sí se detecta: el confirm llegó, y aun así el publisher sabía que no era un éxito.

Y los dos resultados posibles del plazo, con una prueba que publica una vez con el broker detenido y otra con el broker congelado (docker pause: el pedido llega al socket, pero el confirm nunca vuelve). Las líneas de reconexión están filtradas:

$ node src/deadline-probe.ts | grep -v '^[checkout-publisher]'
broker stopped     -> NotPublishedError: ord-deadline-unsent was not published before the deadline
broker frozen      -> PublishPendingError: ord-deadline-sent is sent but not yet confirmed
in orders.billing  -> ord-deadline-sent

El pedido que nunca salió del proceso no se publicó. El que estaba pendiente cuando venció su plazo llegó de todos modos, y por eso no se dio por fallido.

Conexiones, canales y qué arrastra a qué

Una conexión es un socket TCP con su negociación AMQP: abrirla es caro, y lo normal es que dure lo mismo que el proceso. Un canal es una sesión virtual ligera que viaja multiplexada dentro de esa conexión. Casi todo el protocolo ocurre en los canales, y por eso el canal es la unidad de fallo.

De ahí salen tres reglas. En una de ellas, Node matiza el consejo habitual.

1. Un error de canal cierra el canal, y solo el canal. Si redeclaras una cola con otros argumentos, publicas en un exchange que no existe o haces ack de un delivery tag que el canal no conoce, el broker cierra ese canal con un error. La conexión sigue viva. Todos los consumidores y todos los confirms pendientes de ese canal desaparecen, y nada se reconecta, porque desde el punto de vista de la conexión no pasó nada. Tu consumidor simplemente deja de recibir mensajes. Por eso tanto el publisher como el consumidor de este artículo reaccionan a channel.on('error') cerrando la conexión: convierten un fallo a medias, silencioso, en un fallo completo, y la recuperación sabe qué hacer con un fallo completo.

2. Conexiones separadas para publicar y para consumir. Cuando RabbitMQ se queda corto de memoria o de disco, levanta una alarma y bloquea las conexiones que publican hasta que la alarma se apaga. Si tus consumidores comparten esa conexión, sus acks también se quedan atascados detrás del bloqueo, y la cola que más necesita vaciarse deja de vaciarse. Una conexión por rol evita ese bloqueo mutuo. El connection_name del código de abajo hace que cada rol aparezca con su nombre en la pestaña Connections de la UI de administración.

3. Los delivery tags pertenecen a un canal. Un delivery tag es un contador local al canal que entregó el mensaje. Si haces ack en cualquier otro canal, incluido el canal nuevo después de reconectar, estás confirmando un mensaje ajeno. Lo normal es que el tag no exista ahí, y eso es un error de canal (regla 1).

El consejo que leerás en otros sitios, "nunca compartas un canal entre hilos", es literal en .NET y en Java, donde dos hilos que escriben frames en el mismo canal los mezclan. Node tiene un solo hilo, así que ese error concreto no puede pasar aquí. Las reglas 1 y 3 son la versión para Node de la misma lección: todo lo que comparte un canal corre la misma suerte. Pon cosas en el mismo canal solo si te parece bien que caigan juntas.

Reconexión: lo que hace amqplib y lo que te deja a ti

amqplib 1.1 añadió recuperación: le pasas opciones de recovery a connect, y cada vez que el socket se cae la conexión vuelve a intentarlo, con esperas que crecen de forma exponencial (backoff) y una variación aleatoria (jitter). Hasta ahí funciona como promete. Lo que no hace, y que solo descubrí leyendo lib/recovery.js, es esto:

No recupera los canales. Un canal pertenece a un socket concreto. Cuando ese socket muere, todos sus canales quedan cerrados para siempre, y los objetos que guardas ya no apuntan a nada.
No restaura consumidores ni topología. Viven en los canales.
No reenvía nada. Los mensajes sin confirmar son asunto tuyo, y por eso OrderPublisher los guarda.

A cambio te da setup: una función que se ejecuta después de cada conexión exitosa, incluida la primera. Todo lo que vive en un canal se reconstruye ahí. La Parte 1 hizo que assertTopology fuera idempotente justo por esto.

// src/connection.ts
import amqp from 'amqplib';
import type { ChannelModel, RecoveringChannelModel } from 'amqplib';

export const RABBIT_URL = process.env.RABBIT_URL ?? 'amqp://aurora:aurora-dev@localhost:5672';

// Un broker que se cae cierra el socket y se nota al instante. Uno detrás de una red rota
// no manda nada, y solo los heartbeats perdidos lo delatan. RabbitMQ sugiere 60 s; con
// 15 s, un broker congelado se detectó a los 45 s.
const HEARTBEAT_SECONDS = 15;

/**
 * Una conexión por proceso *y por rol*. El nombre aparece en la pestaña Connections de
 * la UI de administración, y así distingues tres réplicas de facturación de un publisher.
 *
 * `setup` se ejecuta después de cada conexión exitosa, incluida la primera. amqplib
 * reconecta el socket por su cuenta; canales, consumidores y topología los reconstruyes
 * tú, y este es el único lugar donde se reconstruyen.
 */
export async function connectWithRecovery(
  role: string,
  setup: (model: ChannelModel) => Promise<void>,
): Promise<RecoveringChannelModel> {
  const url = new URL(RABBIT_URL);
  url.searchParams.set('heartbeat', String(HEARTBEAT_SECONDS));

  const connection = await amqp.connect(url.toString(), {
    clientProperties: { connection_name: role },
    // Sin esto, un intento contra un host que nunca responde espera al timeout de TCP del
    // sistema, y la recuperación no programa el siguiente intento hasta que ese se rinda.
    timeout: 10_000,
    recovery: {
      initialDelay: 500,
      maxDelay: 15_000,
      // Un broker inalcanzable al arrancar es un error de configuración: que falle el despliegue.
      initialMaxRetries: 5,
      // Un broker que desaparece más tarde es un incidente: seguir intentando hasta que vuelva.
      maxRetries: Infinity,
      setup,
    },
  });

  // Sin este listener, la recuperación nunca llega a actuar: el error del socket se
  // reemite como 'error' en la conexión, y un 'error' sin manejar termina el proceso.
  connection.on('error', (error) => console.warn(`[${role}] connection error: ${error.message}`));
  connection.on('disconnect', (error) => console.warn(`[${role}] disconnected: ${error.message}`));
  connection.on('reconnect-scheduled', ({ attempt, delay }) =>
    console.warn(`[${role}] reconnect attempt ${attempt} in ${delay} ms`),
  );
  connection.on('connect', () => console.log(`[${role}] reconnected`));
  connection.on('blocked', (reason) => console.warn(`[${role}] blocked by broker: ${reason}`));
  connection.on('unblocked', () => console.log(`[${role}] unblocked`));
  connection.on('reconnect-failed', (error) => {
    console.error(`[${role}] giving up on the broker: ${error.message}`);
    process.exitCode = 1;
  });

  return connection;
}

Ese listener de error es la línea que estuve a punto de dejar fuera. El ejemplo de recuperación del README no lo incluye, y la primera vez que mi ensayo mató el broker con la recuperación activada, el proceso murió igual. Aquí está reproducido en un contenedor: un cliente que se conecta con opciones de recovery, solo registra un listener de disconnect y luego pierde el broker.

connected with recovery enabled
/app/node_modules/amqplib/lib/safe_emit.js:8
      throw e;
      ^

Error: read ECONNRESET
    at TCP.onStreamRead (node:internal/stream_base_commons:216:20)
Emitted 'error' event on RecoveringPromiseModel instance at:
    at RecoveringCore.<anonymous> (/app/node_modules/amqplib/lib/recovery.js:445:46)
    at RecoveringCore.emit (node:events:514:28)
    at ChannelModel.onConnectionError (/app/node_modules/amqplib/lib/recovery.js:269:45)
    at ChannelModel.emit (node:events:514:28)
    at Connection.emit (node:events:514:28)
    at safeEmit (/app/node_modules/amqplib/lib/safe_emit.js:3:13)
    at Connection.onSocketError (/app/node_modules/amqplib/lib/connection.js:300:7)
    at Socket.emit (node:events:526:24)
    at emitErrorNT (node:internal/streams/destroy:170:8)
    at emitErrorCloseNT (node:internal/streams/destroy:129:3) {
  errno: -104,
  code: 'ECONNRESET',
  syscall: 'read'
}

Node.js v24.21.0

La conexión con recuperación reemite el error del socket como 'error', y un EventEmitter sin listener de 'error' lanza una excepción. El listener de disconnect nunca llegó a ejecutarse. La recuperación estaba lista para reconectar, y el proceso ya no existía cuando le tocaba. Una conexión que se reconecta sola es una función muy convincente, hasta el momento en que se lleva el proceso por delante.

Hay cuatro ajustes más que vale la pena copiar:

initialMaxRetries aparte de maxRetries. Si no puedes llegar al broker al arrancar, casi siempre es una URL o una contraseña equivocada, y el despliegue debería fallar de forma visible. Si el broker desaparece más tarde, es un incidente, y el servicio debería esperar a que pase.
Un heartbeat lo bastante corto para notar el silencio. Un broker al que matan cierra el socket, y por eso el ensayo de más abajo detecta cada caída al instante. Un broker detrás de una red rota no manda nada, y solo los heartbeats perdidos lo delatan. En la prueba de abajo, con un heartbeat de 15 segundos, el publisher notó el broker congelado a los 45 segundos. RabbitMQ sugiere 60, y con eso el mismo silencio dura minutos, mientras los pedidos se acumulan en #unconfirmed.
Un timeout de conexión. Sin timeout, un intento contra un host que nunca responde espera al timeout de TCP del sistema operativo, y la recuperación no puede programar el siguiente hasta que ese se rinda. En la prueba, el intento 2 se programó diez segundos después del intento 1.
El jitter no es un adorno. Cuando el ensayo de más abajo reinicia el broker con tres réplicas consumiendo, los logs muestran a cada una reintentando a su propio ritmo (522 ms, 466 ms y 427 ms en el primer intento). Sin jitter, las tres se reconectan en el mismo milisegundo, y con cien réplicas el pico de carga también llega todo junto.

La prueba detrás de las cifras del heartbeat y del timeout: congela el broker con docker pause, lo más parecido en local a una red rota, y publica un pedido.

[+0.2 s] [probe] broker frozen with docker pause
[+45.0 s] [checkout-publisher] connection error: Heartbeat timeout
[+45.0 s] [checkout-publisher] disconnected: Heartbeat timeout
[+45.0 s] [checkout-publisher] reconnect attempt 1 in 587 ms
[+55.6 s] [checkout-publisher] reconnect attempt 2 in 904 ms
[+60.4 s] [probe] broker unfrozen
[checkout-publisher] reconnected
[+60.5 s] [probe] order confirmed

El consumidor

El consumidor recibe cuatro cambios. Lo que no cambia (parseOrder, retriesSoFar y chargeCard) pasa tal cual de la Parte 1 a src/billing.ts, con export añadido. Está en el apéndice del final, para que el consumidor de abajo se centre en lo nuevo.

// src/billing-consumer.ts
import type { ChannelModel, ConfirmChannel, ConsumeMessage, Options } from 'amqplib';
import { chargeCard, parseOrder, RETRY_COUNT_HEADER, retriesSoFar } from './billing.ts';
import { connectWithRecovery } from './connection.ts';
import { assertTopology, BILLING_QUEUE, RETRY_EXCHANGE } from './topology.ts';

const MAX_RETRIES = 3;
// En Node no solo reparte la carga: limita cuántos handlers corren a la vez.
const PREFETCH = Number(process.env.BILLING_PREFETCH ?? 20);

const inFlight = new Set<Promise<void>>();
// Ids de mensajes que el broker devolvió por no tener destino, por canal. Ver publishConfirmed.
const returnedOn = new WeakMap<ConfirmChannel, Set<string>>();
let active: { channel: ConfirmChannel; consumerTag: string } | null = null;
let shuttingDown = false;

/**
 * Solo se resuelve si el broker confirmó la copia *y* la enrutó a una cola. Un mensaje
 * sin destino también recibe ack del broker; sin `mandatory` y sin revisar el return,
 * un binding que falta haría que se confirmara el original y se perdiera el pedido.
 */
function publishConfirmed(
  channel: ConfirmChannel,
  exchange: string,
  routingKey: string,
  content: Buffer,
  options: Options.Publish & { messageId: string },
): Promise<void> {
  return new Promise((resolve, reject) => {
    channel.publish(exchange, routingKey, content, { ...options, mandatory: true }, (error) => {
      const returned = returnedOn.get(channel)?.delete(options.messageId) ?? false;
      if (error) reject(error);
      else if (returned) reject(new Error(`no queue bound for ${routingKey} on ${exchange}`));
      else resolve();
    });
  });
}

/**
 * Los delivery tags pertenecen al canal que entregó el mensaje. Si ese canal murió a
 * mitad del handler, el broker ya devolvió el mensaje a la cola y el ack no tiene nada
 * que confirmar. Nunca hagas ack en el canal *nuevo*: ahí un tag desconocido es un error.
 */
function settle(action: () => void): void {
  try {
    action();
  } catch {
    // Canal cerrado: el mensaje se volverá a entregar con `redelivered: true`.
  }
}

async function handle(channel: ConfirmChannel, message: ConsumeMessage): Promise<void> {
  let order;

  try {
    order = parseOrder(message);
  } catch (error) {
    console.error('[billing] unparseable message, dead-lettering', error);
    settle(() => channel.nack(message, false, false));
    return;
  }

  try {
    const chargeId = await chargeCard(order);
    console.log(`[billing] charged ${order.orderId} -> ${chargeId}`);
    settle(() => channel.ack(message));
    return;
  } catch (error) {
    const attempts = retriesSoFar(message);

    if (attempts >= MAX_RETRIES) {
      console.error(`[billing] giving up on ${order.orderId} after ${attempts} retries`, error);
      settle(() => channel.nack(message, false, false));
      return;
    }

    console.warn(`[billing] retry ${attempts + 1}/${MAX_RETRIES} for ${order.orderId}`, error);

    try {
      // La Parte 1 publicaba y hacía ack seguidos. Ahora el ack espera a que el broker
      // confirme que la copia está a salvo en la cola de reintentos.
      await publishConfirmed(channel, RETRY_EXCHANGE, message.fields.routingKey, message.content, {
        persistent: true,
        headers: { ...message.properties.headers, [RETRY_COUNT_HEADER]: attempts + 1 },
        messageId: order.orderId,
      });
      settle(() => channel.ack(message));
    } catch (publishError) {
      // La copia para reintento no está confirmada, así que el original no puede recibir
      // ack. Devolverlo a la cola sería un bucle: en RabbitMQ 4.x un requeue explícito no
      // cuenta para x-delivery-limit. Se manda a dead-letter, donde una persona lo verá.
      console.error(`[billing] could not park ${order.orderId} for retry, dead-lettering`, publishError);
      settle(() => channel.nack(message, false, false));
    }
  }
}

/** Se ejecuta tras cada (re)conexión: un canal nuevo, la topología y el consumidor. */
async function attach(model: ChannelModel): Promise<void> {
  if (shuttingDown) return;

  const channel = await model.createConfirmChannel();
  await assertTopology(channel);
  await channel.prefetch(PREFETCH);

  const returned = new Set<string>();
  returnedOn.set(channel, returned);
  channel.on('return', (message) => {
    const id: unknown = message.properties.messageId;
    if (typeof id === 'string') returned.add(id);
  });

  // La misma regla que en el publisher: un canal muerto en una conexión viva es un
  // consumidor que se detuvo en silencio. Lo escalamos para que la recuperación rehaga todo.
  channel.on('error', (error: Error) => {
    console.error(`[billing] channel error, rebuilding: ${error.message}`);
    void model.close().catch(() => undefined);
  });

  const { consumerTag } = await channel.consume(BILLING_QUEUE, (message) => {
    if (message === null) {
      // El broker canceló el consumidor (por ejemplo, borraron la cola). Al rehacer, se redeclara.
      void model.close().catch(() => undefined);
      return;
    }

    const task: Promise<void> = handle(channel, message)
      .catch((error: unknown) => console.error('[billing] handler crashed', error))
      .finally(() => inFlight.delete(task));
    inFlight.add(task);
  });

  active = { channel, consumerTag };
}

const connection = await connectWithRecovery('billing-consumer', attach);
console.log(`[billing] consuming ${BILLING_QUEUE} with prefetch ${PREFETCH}`);

async function shutdown(): Promise<void> {
  shuttingDown = true;

  console.log(`[billing] shutting down with ${inFlight.size} in flight`);
  // 1. Cortar las entregas nuevas, pero dejar el canal abierto para que lo que está en curso haga ack.
  if (active) await active.channel.cancel(active.consumerTag).catch(() => undefined);
  // 2. Dejar terminar lo que ya corre. chargeCard expira a los 5 s, así que esto tiene límite.
  await Promise.allSettled([...inFlight]);
  // 3. Cerrar primero el canal. Su cierre queda en cola detrás de los acks del mismo canal;
  //    cerrar la conexión directamente puede adelantarse al último ack y devolver un pedido ya cobrado.
  if (active) await active.channel.close().catch(() => undefined);
  await connection.close();
}

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => {
    void shutdown().then(() => process.exit(0));
  });
}

Los cuatro cambios respecto a la Parte 1:

La copia para reintento se confirma, y se enruta, antes de hacer ack del original. Esto cierra el hueco que reconocía la Parte 1: publishConfirmed espera al broker, y solo entonces ack borra el original. Además publica con mandatory y trata un return como un fallo, porque si faltara el binding de la cola de reintentos el broker confirmaría igual y el pedido se perdería. Si la copia no se puede aparcar, el original va a dead-letter en lugar de volver a la cola. Un requeue no cuenta para x-delivery-limit, así que se repetiría tan rápido como lo permita la red. Con el binding de reintentos borrado, el pedido llegó a orders.billing.dead tras un solo intento. Los reintentos se cuentan en retry-count, la corrección que explico al principio.
Todo lo que vive en un canal se reconstruye en attach: el canal, la topología, el prefetch y el consumidor. Es todo lo que la recuperación necesita de ti.
El ack va al canal que entregó el mensaje, y solo a ese. handle recibe su canal como argumento y nunca lee una variable de "canal actual". Si ese canal murió a mitad del handler, settle absorbe el ack fallido. El broker devolvió el mensaje a la cola en cuanto se cerró el canal, así que ya no quedaba nada que confirmar.
El apagado termina el trabajo antes de cerrar. Eso merece sección propia.

El apagado, y el ack que nunca llegó

Este era el apagado de la Parte 1:

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => {
    // Cerrar el canal devuelve a la cola todo lo que quedó sin confirmar, así que un
    // despliegue progresivo le pasa el trabajo en curso al siguiente pod en vez de
    // perderlo.
    void channel
      .close()
      .then(() => connection.close())
      .then(() => process.exit(0));
  });
}

El comentario es cierto, pero oculta un costo. Cerrar el canal con handlers todavía en marcha significa que cada pedido en curso que ya llamó al servicio de pagos, pero aún no hizo ack, vuelve a la cola y se cobra otra vez en la siguiente réplica. La clave de idempotencia convierte ese segundo cobro en una operación sin efecto, así que nadie paga dos veces. Aun así es trabajo desperdiciado, y además es apostar a que todos los servicios siguientes respetan las claves de idempotencia.

El shutdown nuevo lo hace en tres pasos: cancela el consumidor para que no lleguen mensajes nuevos, espera a los handlers en curso y luego cierra. Medí las dos versiones de la misma forma: una réplica, prefetch 20, 1.000 pedidos y docker stop a los 2,5 segundos, contando después cuántos cobros vio repetidos el stub de pagos. La tabla la armé con esas corridas:

Consumidor	Corrida 1	Corrida 2	Corrida 3
Parte 1 (cierra el canal de inmediato)	16	5	8
Parte 2, cerrando la conexión tras terminar lo pendiente	1	1	2
Parte 2, cerrando el canal y después la conexión	0	0	0

La fila del medio me costó casi una hora. Esperar a lo pendiente funcionaba: la primera vez que me pasó, el log decía que había 15 handlers en curso, y los 15 cobraron y llamaron a ack. Aun así, uno o dos pedidos se volvían a entregar en cada corrida. El origen estaba en cómo escribe amqplib los frames: cada canal tiene su propio buffer de escritura, y un multiplexor los va intercalando en el socket. El ack espera en el buffer del canal 1, mientras que connection.close() sale por el buffer del canal 0. El cierre puede adelantarse al último ack. El broker ve que la conexión se cierra y devuelve a la cola un mensaje que ya estaba terminado.

Cerrar primero el canal lo resuelve, porque channel.close() queda en cola detrás de los acks de ese mismo canal. Es una línea, y solo apareció porque el stub cuenta las repeticiones.

Escalar: consumidores en competencia y prefetch

Si varios consumidores leen la misma cola, RabbitMQ les reparte los mensajes por turnos. Es el patrón de consumidores en competencia (competing consumers), y es todo lo que hace falta para escalar una cola horizontalmente: no hay particiones que planificar ni coordinador. Arrancas otra réplica y empieza a recibir mensajes.

El archivo de compose suma los servicios nuevos. El de RabbitMQ es el de la Parte 1 con una línea más, que explico en la sección sobre reinicios:

# docker-compose.yml
services:
  rabbitmq:
    image: rabbitmq:4-management
    container_name: aurora-rabbitmq
    # El nodo se llama rabbit@<hostname>, y su directorio de datos lleva el nombre del nodo.
    # Sin un hostname fijo, un contenedor recreado es un nodo nuevo y sin colas.
    hostname: aurora-rabbitmq
    ports:
      - "5672:5672"    # AMQP — aquí se conecta tu app
      - "15672:15672"  # UI de administración — aquí te conectas tú
    environment:
      RABBITMQ_DEFAULT_USER: aurora
      RABBITMQ_DEFAULT_PASS: aurora-dev
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "-q", "check_running"]
      interval: 10s
      timeout: 5s
      retries: 5

  payments:
    build: .
    command: ["node", "src/payments-stub.ts"]
    environment:
      PAYMENTS_LATENCY_MS: "50"
    ports:
      - "4001:4001"

  billing:
    build: .
    environment:
      RABBIT_URL: amqp://aurora:aurora-dev@rabbitmq:5672
      PAYMENTS_URL: http://payments:4001
      BILLING_PREFETCH: ${BILLING_PREFETCH:-20}
    depends_on:
      rabbitmq:
        condition: service_healthy
      payments:
        condition: service_started
    # Margen para que shutdown() termine lo que está en curso antes de que Docker mande SIGKILL.
    stop_grace_period: 30s

volumes:
  rabbitmq-data:

FROM node:24-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY src ./src
USER node
CMD ["node", "src/billing-consumer.ts"]

Node 24 ejecuta los .ts directamente, así que la imagen no necesita paso de compilación, igual que no lo necesita tu máquina. El stub de pagos, un servidor HTTP de unas 50 líneas que tarda 50 ms por cobro, respeta las claves de idempotencia incluso con peticiones simultáneas con la misma clave y cuenta las repeticiones, está en el apéndice.

El prefetch es tu límite de concurrencia

En la Parte 1, el prefetch servía para repartir la carga: sin él, el primer consumidor que se conecta se queda con toda la cola. En Node es algo más. Fíjate en el callback del consumidor: lanza handle() y retorna enseguida, sin esperar a nada. Por eso el prefetch pone techo al número de handlers que corren a la vez en un proceso: el broker no manda más mensajes sin ack que ese número. Tres réplicas con prefetch 20 suponen hasta 60 llamadas simultáneas al servicio de pagos.

Los mismos 3.000 pedidos, tres réplicas y el stub tardando 50 ms por cobro:

$ BILLING_PREFETCH=1 docker compose up -d --wait --scale billing=3 billing
$ BILLING_PREFETCH=1 node src/measure-drain.ts 3000
prefetch 1: 3000 orders charged in 66.3 s (45 orders/s)
$ BILLING_PREFETCH=20 docker compose up -d --wait --scale billing=3 billing
$ BILLING_PREFETCH=20 node src/measure-drain.ts 3000
prefetch 20: 3000 orders charged in 5.8 s (516 orders/s)
$ BILLING_PREFETCH=100 docker compose up -d --wait --scale billing=3 billing
$ BILLING_PREFETCH=100 node src/measure-drain.ts 3000
prefetch 100: 3000 orders charged in 3.7 s (821 orders/s)

Con prefetch 1, tres réplicas se comportan como tres trabajadores de un solo hilo: en teoría 3 × (1 / 50 ms) da 60 pedidos por segundo, y medí 45. Con prefetch 20 va once veces más rápido. Con prefetch 100 va más rápido todavía, pero mucho menos de cinco veces, porque 300 handlers simultáneos podrían cobrar en teoría 6.000 pedidos por segundo, y algo que no son los consumidores se agota antes. Aun así, significa 300 peticiones simultáneas contra el proveedor de pagos. Con un proveedor real que te limita las peticiones, así es como llegan los 429 y una tormenta de reintentos. Calcula el prefetch a partir de lo que acepta el servicio más lento, dividido entre el número de réplicas, no a partir de lo que la cola puede entregar. La cola siempre va a entregar más rápido de lo que el proveedor puede cobrar.

Lo que pierdes: el orden

Ya lo decía la Parte 1: el orden dentro de una cola solo se mantiene mientras la lee un único consumidor. Los consumidores en competencia procesan pedidos en paralelo, así que el pedido 41 puede terminar antes que el 40. Para facturación no importa. Si tu consumidor sí necesita orden (por ejemplo, para aplicar cambios de saldo de una cuenta), declara la cola con x-single-active-consumer: true. Todas las réplicas siguen conectadas, pero solo una recibe mensajes, y otra toma el relevo cuando esa se va. Obtienes conmutación por error, no paralelismo. Y como es un argumento de la cola, se aplica el otro aviso de la Parte 1: decídelo antes de que la cola exista, porque después no se puede añadir.

Cuando el broker se reinicia

El reinicio que conserva tus datos y el que no

El compose de la Parte 1 declaraba un volumen con nombre para /var/lib/rabbitmq, lo que da a entender que los datos persisten. Persisten mientras el contenedor siga existiendo. Esto es lo que pasa cuando no:

$ docker compose up -d --wait && node src/checkout.ts 100
[checkout] no queue bound for order.us.refunded
[checkout] 100/100 orders confirmed by the broker
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
name    messages
orders.billing  100
orders.billing.retry    0
orders.billing.dead 0
$ docker compose down && docker compose up -d --wait
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
$ docker exec aurora-rabbitmq ls /var/lib/rabbitmq/mnesia
rabbit@8dfd00d4dcd6
rabbit@8dfd00d4dcd6-feature_flags
rabbit@8dfd00d4dcd6-plugins-expand
rabbit@ffe1f6cff9d8
rabbit@ffe1f6cff9d8-feature_flags
rabbit@ffe1f6cff9d8-plugins-expand
rabbit@ffe1f6cff9d8.pid

Cien pedidos confirmados, y después ninguna cola, con el volumen todavía guardando los datos viejos. Un nodo de RabbitMQ se llama rabbit@<hostname>, su directorio de datos lleva el nombre del nodo, y el hostname por defecto de un contenedor es su id aleatorio. docker compose down seguido de up crea un contenedor nuevo: arranca un nodo nuevo, no encuentra ningún directorio con su nombre y empieza vacío. Los datos del nodo anterior siguen ahí al lado, intactos e ignorados. docker restart conserva el contenedor y su hostname, y por eso el problema no aparece en las pruebas del día a día y salta con la primera actualización de imagen, que sí recrea el contenedor.

La solución es la línea que añade el compose nuevo:

    container_name: aurora-rabbitmq
    hostname: aurora-rabbitmq

La misma prueba con esa línea: 100 mensajes antes del down, 100 después y un único directorio de datos. Los StatefulSets de Kubernetes dan a los pods hostnames estables por la misma razón.

Lo que un solo nodo puede prometer y lo que no

Una cola quorum en un solo nodo te da durabilidad: un mensaje confirmado ya pasó por el fsync antes de que salga el ack. Lo que no te da es disponibilidad: mientras ese nodo está caído, no se publica ni se consume nada. La razón de ser de las colas quorum es la replicación: en un clúster de tres nodos, una cola sobrevive a la caída de uno y sigue atendiendo. Eso cambia lo que pasa durante la caída, no el código del cliente. El cliente sí necesita un cambio. amqp.connect recibe una sola URL y la recuperación sigue llamando a esa misma dirección, así que si ese nodo es el que cayó, el cliente espera a que vuelva en lugar de pasarse a otro. Pon delante de los nodos un balanceador TCP como HAProxy, o un nombre DNS que solo resuelva a nodos sanos, y conéctate a eso. Todo lo demás de este artículo funciona igual contra un clúster. Montar uno en local da para un compose propio.

El ensayo: matar el broker a mitad del lote y contar

La preparación es esta. Nadie consume la cola durante la corrida. El script publica 20.000 pedidos a unos 10.000 por segundo. Tras el pedido 10.000 ejecuta docker kill aurora-rabbitmq (SIGKILL, sin apagado ordenado) y luego docker start, sin dejar de publicar en ningún momento, como haría el tráfico real del checkout. Cuando el broker vuelve, vacía orders.billing y cuenta los ids de pedido distintos. El script completo está en el apéndice.

Conviene tener claro qué prueba esto y qué no. docker kill termina el proceso del broker, pero la caché de páginas del host sobrevive, así que lo que el broker escribió sin hacer fsync sigue ahí después. El ensayo mide lo que se pierde en tránsito: en el buffer del cliente y en la memoria del broker. No puede demostrar que un mensaje confirmado pasó por el fsync, porque estas corridas darían el mismo resultado aunque no hubiera pasado. Para probar eso hay que perder la máquina entera, por ejemplo apagando una VM de golpe. Hay tres escenarios.

A: el publisher de la Parte 1. Un canal normal. Que publish() retorne sin error es la única señal que recibe. Una concesión a la medición: el publisher de la Parte 1 no registraba ningún listener de error, así que el real se habría caído en el momento del kill. El ensayo añade los listeners para poder seguir contando. Los pedidos que faltan ya se habían aceptado de todos modos.

scenario: fire-and-forget
orders published: 20000, broker killed after #10000
broker down for 9.6 s, run took 16.2 s
  publish() returned normally          10900
  publish() threw                      9100
  messages in orders.billing           10433
  distinct orders in orders.billing    10433
  orders lost                          9567
  duplicates                           0

Los 9.100 que lanzaron excepción no son el problema: el checkout vio un error y pudo avisar al cliente. El problema es la diferencia entre 10.900 y 10.433. Se aceptaron 467 pedidos sin ningún error y nunca llegaron. Estaban en el buffer del cliente, o en la memoria del broker, cuando mataron el proceso.

B: confirms, pero sin reenvío.

scenario: confirms
orders published: 20000, broker killed after #10000
broker down for 11.0 s, run took 17.3 s
  confirmed by the broker              10665
  confirm failed (channel closed)      1335
  publish() threw                      8000
  messages in orders.billing           10793
  distinct orders in orders.billing    10793
  orders lost                          9207
  duplicates                           0

Los 10.665 pedidos confirmados están todos en la cola. Los 1.335 cuyo confirm nunca llegó son el caso de "no lo sabes", y el conteo lo demuestra: 128 llegaron de todos modos (10.793 − 10.665) y 1.207 no. Los confirms no evitan la pérdida, pero la hacen visible, y sin verla no hay forma de corregirla.

C: OrderPublisher. Confirms, recuperación y reenvío de todo lo no confirmado.

[checkout-publisher] connection error: Unexpected close
[checkout-publisher] disconnected: Unexpected close
[checkout-publisher] reconnect attempt 1 in 530 ms
[checkout-publisher] reconnect attempt 2 in 1007 ms
[checkout-publisher] reconnect attempt 3 in 1760 ms
[checkout-publisher] reconnect attempt 4 in 3332 ms
[checkout-publisher] reconnect attempt 5 in 9301 ms
[checkout-publisher] reconnected

scenario: recovery
orders published: 20000, broker killed after #10000
broker down for 9.9 s, run took 24.8 s
  confirmed by the broker              20000
  rejected                             0
  seconds from kill to last confirm    18.4
  messages in orders.billing           20128
  distinct orders in orders.billing    20000
  orders lost                          0
  duplicates                           128

Están los 20.000 pedidos, más 128 duplicados: pedidos que el broker ya había escrito, cuyo confirm murió con el socket y que se enviaron otra vez. Esta corrida enseña también lo que cuesta el backoff. El broker volvió a los 9,9 segundos, pero el intento 5 ya estaba programado para dentro de 9,3, así que el publisher se quedó varios segundos parado frente a un broker sano. maxDelay es un equilibrio entre no saturar a un broker que todavía está arrancando y no tardar de más cuando ya se recuperó. Quince segundos es mi término medio. Elige el tuyo pensando en un incidente real.

Corrí cada escenario tres veces. La tabla la armé con las nueve capturas:

Escenario	Aceptados sin error que nunca llegaron	Confirmados que nunca llegaron	Perdidos en total	Duplicados
A: sin confirmación	467 / 1.406 / 1.125	n/a	9.567 / 9.606 / 9.125	0 / 0 / 0
B: solo confirms	n/a	0 / 0 / 0	9.207 / 10.934 / 9.400	0 / 0 / 0
C: `OrderPublisher`	n/a	0 / 0 / 0	0 / 0 / 0	128 / 64 / 322

A pierde en silencio una cantidad distinta en cada corrida, según lo que hubiera en vuelo justo cuando cae el broker. B nunca pierde un mensaje confirmado y nunca reenvía uno sin confirmar. C cambia pérdidas por duplicados, que es el único cambio que permite la entrega al menos una vez.

El mismo ensayo, del lado del consumidor

La misma caída, esta vez con tres réplicas de facturación consumiendo 6.000 pedidos con prefetch 20:

$ curl -s localhost:4001/stats
{"charges":9000,"replays":0}
$ (sleep 4; docker kill aurora-rabbitmq; docker start aurora-rabbitmq) & BILLING_PREFETCH=20 node src/measure-drain.ts 6000
prefetch 20: 6000 orders charged in 28.9 s (208 orders/s)
$ curl -s localhost:4001/stats
{"charges":15000,"replays":53}
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
name    messages
orders.billing  0
orders.billing.retry    0
orders.billing.dead 0
$ docker compose logs billing --since 1m --no-log-prefix | grep -v charged
[billing] consuming orders.billing with prefetch 20
[billing] consuming orders.billing with prefetch 20
[billing] consuming orders.billing with prefetch 20
[billing-consumer] connection error: read ECONNRESET
[billing-consumer] disconnected: read ECONNRESET
[billing-consumer] reconnect attempt 1 in 522 ms
[billing-consumer] reconnect attempt 2 in 938 ms
[billing-consumer] reconnect attempt 3 in 2182 ms
[billing-consumer] reconnect attempt 4 in 4550 ms
[billing-consumer] reconnect attempt 5 in 8630 ms
[billing-consumer] reconnected
[billing-consumer] connection error: read ECONNRESET
[billing-consumer] disconnected: read ECONNRESET
[billing-consumer] reconnect attempt 1 in 466 ms
[billing-consumer] reconnect attempt 2 in 1148 ms
[billing-consumer] reconnect attempt 3 in 1829 ms
[billing-consumer] reconnect attempt 4 in 4379 ms
[billing-consumer] reconnect attempt 5 in 8235 ms
[billing-consumer] reconnected
[billing-consumer] connection error: read ECONNRESET
[billing-consumer] disconnected: read ECONNRESET
[billing-consumer] reconnect attempt 1 in 427 ms
[billing-consumer] reconnect attempt 2 in 997 ms
[billing-consumer] reconnect attempt 3 in 1823 ms
[billing-consumer] reconnect attempt 4 in 3324 ms
[billing-consumer] reconnect attempt 5 in 8230 ms
[billing-consumer] reconnected

Exactamente 6.000 cobros nuevos y distintos, las tres colas vacías y 53 repeticiones. Son pedidos que una réplica ya había cobrado cuando el socket murió, antes de que su ack llegara al broker. El broker los volvió a entregar, otra réplica llamó al stub de pagos con la misma clave de idempotencia, y el stub devolvió el cobro original. A nadie se le cobró dos veces, y eso quedó decidido en la Parte 1, con un header HTTP. Todos los mecanismos de fiabilidad de este artículo generan duplicados en algún punto. La clave de idempotencia es lo que hace que no cuesten nada.

Qué usar en cada caso

Usa confirms con un buffer de reenvío cuando:

Un mensaje perdido es una venta perdida, un cobro que no se hace o un pedido que nunca sale. Es decir, cualquier publisher cuyos mensajes alguien vaya a reclamar.
Puedes hacer que los consumidores sean idempotentes. Si no puedes, arregla eso primero: reenviar sin idempotencia convierte los mensajes perdidos en cobros dobles.

Quédate con algo más simple cuando:

El mensaje es telemetría, como una visita a una página o una muestra de una métrica. Perder 467 de 20.000 durante una caída del broker es aceptable, y publicar sin confirmación cuesta varias veces menos, tanto en operación como en complejidad.
La publicación y una escritura en base de datos tienen que ser atómicas. OrderPublisher guarda en memoria los pedidos sin confirmar. Si el que se cae es el propio proceso del checkout, esos pedidos desaparecen con él, igual que el pedido que ya estaba guardado en Postgres. La solución es una bandeja de salida transaccional (transactional outbox): escribes el evento en una tabla de salida dentro de la misma transacción que el pedido, y un proceso aparte lo publica desde esa tabla con confirms. Es el siguiente nivel de fiabilidad, y es otra arquitectura, no un ajuste de esta.

Sobre construirlo o usar una librería:

La recuperación de amqplib más tu propio setup es lo que usa este artículo: poco código, y se ve todo.
amqp-connection-manager envuelve los canales para que sobrevivan a las reconexiones, vuelve a ejecutar tu configuración y encola las publicaciones mientras no hay conexión. Es anterior a la recuperación de amqplib y hace más trabajo por ti. Merece la pena si prefieres no mantener tu propio #unconfirmed. Antes de confiarle una caída larga, revisa cómo limita esa cola.
Los brokers gestionados (Amazon MQ for RabbitMQ, CloudAMQP) te quitan de encima el clúster, las actualizaciones y el problema del hostname. No te quitan nada del trabajo del lado del cliente: todo lo anterior sigue valiendo, porque la conexión se puede seguir cayendo.

Y sobre los clústeres: un solo nodo basta hasta que el costo de "no se publica nada durante ocho segundos" supere el de mantener tres nodos. En un checkout, ese momento suele llegar pronto.

Puntos clave

Que publish() devuelva true significa que lo aceptó tu buffer, no el broker. En el ensayo, 467 pedidos se perdieron así sin un solo error. Los confirms son la única señal de que un mensaje ya es problema del broker y no tuyo, y en paralelo cuestan una parte del rendimiento (4.784–5.728 msg/s frente a 6.859–7.425). Esperados uno a uno, fueron 70–78.
La recuperación de amqplib reconecta el socket y nada más. Reconstruye canales, topología y consumidores en setup, reenvía lo que quedó sin confirmar y añade un listener de 'error', o el proceso muere antes de que la recuperación pueda hacer nada.
En Node, el prefetch limita tu concurrencia. Réplicas × prefetch es el máximo de peticiones que mandas a la vez a los servicios siguientes. Ajústalo según la dependencia más lenta, no según la cola.
Todos los mecanismos de fiabilidad de este artículo producen duplicados. 128 por reenvío y 53 por reentrega, todos absorbidos por una clave de idempotencia. Haz idempotentes los consumidores primero, y lo demás se puede añadir sin riesgo.
Provoca de verdad cada fallo que tu código dice manejar, en tu versión del broker, antes de confiar en él. El contador de reintentos de la Parte 1 leía x-death, y su protección contra bucles se apoyaba en x-delivery-limit. En RabbitMQ 4.3 no se sostuvo ninguna de las dos cosas, y solo una prueba con el servicio de pagos caído lo mostró.

Apéndice: el resto del código

Todo lo que sigue hace falta para ejecutar los ejemplos y el ensayo, pero nada de esto es el patrón en sí.

src/billing.ts — las funciones de la Parte 1, sin cambios salvo el export

// src/billing.ts
import type { ConsumeMessage } from 'amqplib';
import type { OrderPlaced } from './order-publisher.ts';

const PAYMENTS_URL = process.env.PAYMENTS_URL ?? 'http://localhost:4001';
export const RETRY_COUNT_HEADER = 'retry-count';

/**
 * Cuántas veces se ha aparcado ya este mensaje en la cola de reintentos. Lo cuenta el
 * propio consumidor: RabbitMQ 4.x ignora el x-death que manda un cliente al republicar,
 * así que x-death nunca pasa de 1 y un pedido que falla se reintentaría para siempre.
 */
export function retriesSoFar(message: ConsumeMessage): number {
  const count: unknown = message.properties.headers?.[RETRY_COUNT_HEADER];
  return typeof count === 'number' ? count : 0;
}

export function parseOrder(message: ConsumeMessage): OrderPlaced {
  const parsed: unknown = JSON.parse(message.content.toString('utf8'));

  if (
    typeof parsed !== 'object' || parsed === null ||
    typeof (parsed as OrderPlaced).orderId !== 'string' ||
    typeof (parsed as OrderPlaced).totalCents !== 'number'
  ) {
    throw new SyntaxError('order payload is missing orderId or totalCents');
  }

  return parsed as OrderPlaced;
}

export async function chargeCard(order: OrderPlaced): Promise<string> {
  const response = await fetch(`${PAYMENTS_URL}/charges`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      // La entrega es al menos una vez, así que el mismo pedido puede llegar dos
      // veces. Usar el id del pedido como clave de idempotencia hace que el segundo
      // intento devuelva el primer cargo en vez de cobrarle otra vez al cliente.
      'idempotency-key': order.orderId,
    },
    body: JSON.stringify({ amountCents: order.totalCents, reference: order.orderId }),
    signal: AbortSignal.timeout(5_000),
  });

  if (!response.ok) {
    throw new Error(`payments service returned ${response.status} for ${order.orderId}`);
  }

  const { chargeId } = (await response.json()) as { chargeId: string };
  return chargeId;
}

src/payments-stub.ts — el sustituto del servicio de pagos

// src/payments-stub.ts
// Un sustituto del proveedor de pagos, para que el consumidor tenga a quién llamar.
// Respeta las claves de idempotencia como lo haría uno real, y cuenta las repeticiones.
import { randomUUID } from 'node:crypto';
import { createServer } from 'node:http';
import { setTimeout as sleep } from 'node:timers/promises';

const PORT = Number(process.env.PORT ?? 4001);
const LATENCY_MS = Number(process.env.PAYMENTS_LATENCY_MS ?? 50);

// El cobro pendiente se guarda antes de la espera, así que dos peticiones simultáneas con
// la misma clave comparten un cobro en lugar de no encontrarse en el mapa y crear dos.
const chargesByKey = new Map<string, Promise<string>>();
let replays = 0;

const server = createServer(async (request, response) => {
  const reply = (status: number, body: unknown): void => {
    response.writeHead(status, { 'content-type': 'application/json' });
    response.end(JSON.stringify(body));
  };

  if (request.method === 'GET' && request.url === '/stats') {
    reply(200, { charges: chargesByKey.size, replays });
    return;
  }

  if (request.method !== 'POST' || request.url !== '/charges') {
    reply(404, { error: 'not found' });
    return;
  }

  for await (const _chunk of request); // el cuerpo no se usa, solo se consume
  const key = request.headers['idempotency-key'];
  if (typeof key !== 'string' || key.length === 0) {
    reply(400, { error: 'idempotency-key header is required' });
    return;
  }

  const existing = chargesByKey.get(key);
  if (existing) {
    replays++;
    console.log(`[payments] replayed ${key}`);
    reply(200, { chargeId: await existing });
    return;
  }

  const charge = sleep(LATENCY_MS).then(() => `ch_${randomUUID()}`);
  chargesByKey.set(key, charge);
  reply(201, { chargeId: await charge });
});

server.listen(PORT, () => console.log(`[payments] listening on ${PORT}, ${LATENCY_MS} ms per charge`));

src/drill.ts — el ensayo que mata el broker

// src/drill.ts
// Publica TOTAL pedidos, mata el broker después de KILL_AFTER, lo reinicia y cuenta lo
// que queda en orders.billing. Nadie consume la cola durante la corrida.
//
//   node src/drill.ts <fire-and-forget|confirms|recovery> [total] [killAfter]
import amqp from 'amqplib';
import { execFile } from 'node:child_process';
import { once } from 'node:events';
import { setTimeout as sleep } from 'node:timers/promises';
import { promisify } from 'node:util';
import { RABBIT_URL } from './connection.ts';
import { OrderPublisher } from './order-publisher.ts';
import type { OrderPlaced } from './order-publisher.ts';
import {
  assertTopology, BILLING_DEAD_QUEUE, BILLING_QUEUE, BILLING_RETRY_QUEUE, ORDERS_EXCHANGE,
} from './topology.ts';

const SCENARIOS = ['fire-and-forget', 'confirms', 'recovery'] as const;
type Scenario = (typeof SCENARIOS)[number];

const scenario = process.argv[2] as Scenario;
if (!SCENARIOS.includes(scenario)) {
  console.error(`usage: node src/drill.ts <${SCENARIOS.join('|')}> [total] [killAfter]`);
  process.exit(2);
}
const TOTAL = Number(process.argv[3] ?? 20_000);
const KILL_AFTER = Number(process.argv[4] ?? TOTAL / 2);
const CONTAINER = 'aurora-rabbitmq';
const ROUTING_KEY = 'order.us.placed';
const SENTINEL = 'drill-sentinel';
// Unos 10.000 pedidos por segundo: un checkout con mucho tráfico, no un bucle de benchmark.
const BATCH = 100;
const BATCH_PAUSE_MS = 10;

const docker = promisify(execFile);

function orderNumber(i: number): OrderPlaced {
  return { orderId: `ord-${String(i).padStart(6, '0')}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 };
}

async function waitForBroker(): Promise<void> {
  for (;;) {
    try {
      const probe = await amqp.connect(RABBIT_URL);
      await probe.close();
      return;
    } catch {
      await sleep(250);
    }
  }
}

let killedAt = 0;
let backAt = 0;
async function killAndRestartBroker(): Promise<void> {
  killedAt = performance.now();
  await docker('docker', ['kill', CONTAINER]);
  await docker('docker', ['start', CONTAINER]);
  await waitForBroker();
  backAt = performance.now();
}

async function resetQueues(): Promise<void> {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createChannel();
  await assertTopology(channel);
  for (const queue of [BILLING_QUEUE, BILLING_RETRY_QUEUE, BILLING_DEAD_QUEUE]) await channel.purgeQueue(queue);
  await connection.close();
}

/** Vacía orders.billing e informa cuántos mensajes, y cuántos pedidos distintos, contenía. */
async function countQueue(): Promise<{ total: number; unique: number }> {
  // Una cola quorum recién reiniciada elige líder y reproduce su log antes de informar su
  // profundidad real, y contar antes de tiempo da 0. Un write confirmado prueba que ya hay
  // líder, así que primero publicamos un centinela y luego esperamos una profundidad estable.
  const connection = await amqp.connect(RABBIT_URL);
  const confirms = await connection.createConfirmChannel();
  confirms.sendToQueue(BILLING_QUEUE, Buffer.from('{}'), { persistent: true, messageId: SENTINEL });
  await confirms.waitForConfirms();
  await confirms.close();

  const channel = await connection.createChannel();
  let depth = -1;
  for (;;) {
    await sleep(1_000);
    const { messageCount } = await channel.checkQueue(BILLING_QUEUE);
    if (messageCount === depth) break;
    depth = messageCount;
  }

  const seen = new Set<string>();
  let total = 0;
  let lastMessageAt = performance.now();
  await channel.consume(BILLING_QUEUE, (message) => {
    if (message === null) return;
    lastMessageAt = performance.now();
    if (message.properties.messageId === SENTINEL) return;
    total++;
    seen.add(String(message.properties.messageId));
  }, { noAck: true });

  // Terminamos cuando no llega nada en dos segundos y el broker confirma que la cola está vacía.
  for (;;) {
    await sleep(500);
    if (performance.now() - lastMessageAt < 2_000) continue;
    const { messageCount } = await channel.checkQueue(BILLING_QUEUE);
    if (messageCount === 0) break;
  }

  await connection.close();
  return { total, unique: seen.size };
}

const pace = async (i: number): Promise<void> => {
  if (i % BATCH === BATCH - 1) await sleep(BATCH_PAUSE_MS);
};

/** El publisher de la Parte 1: que publish() devuelva true es la única señal que recibe. */
async function fireAndForget(): Promise<Record<string, number>> {
  const connection = await amqp.connect(RABBIT_URL);
  connection.on('error', () => undefined); // mantiene vivo el ensayo para contar; el código de la Parte 1 se cae aquí
  const channel = await connection.createChannel();
  channel.on('error', () => undefined);

  let accepted = 0;
  let threw = 0;
  let restart: Promise<void> | undefined;

  for (let i = 0; i < TOTAL; i++) {
    if (i === KILL_AFTER) restart = killAndRestartBroker();
    const order = orderNumber(i);
    try {
      const writable = channel.publish(ORDERS_EXCHANGE, ROUTING_KEY, Buffer.from(JSON.stringify(order)), {
        persistent: true, contentType: 'application/json', messageId: order.orderId,
      });
      accepted++;
      if (!writable) await Promise.race([once(channel, 'drain'), once(channel, 'close')]);
    } catch {
      threw++;
    }
    await pace(i);
  }

  await restart;
  return { 'publish() returned normally': accepted, 'publish() threw': threw };
}

/** Un confirm channel, pero nada reenvía lo que quedó sin confirmar. */
async function confirmsOnly(): Promise<Record<string, number>> {
  const connection = await amqp.connect(RABBIT_URL);
  connection.on('error', () => undefined);
  const channel = await connection.createConfirmChannel();
  channel.on('error', () => undefined);

  let confirmed = 0;
  let failed = 0;
  let threw = 0;
  let restart: Promise<void> | undefined;

  for (let i = 0; i < TOTAL; i++) {
    if (i === KILL_AFTER) restart = killAndRestartBroker();
    const order = orderNumber(i);
    try {
      channel.publish(
        ORDERS_EXCHANGE, ROUTING_KEY, Buffer.from(JSON.stringify(order)),
        { persistent: true, contentType: 'application/json', messageId: order.orderId },
        (error) => (error ? failed++ : confirmed++),
      );
    } catch {
      threw++;
    }
    await pace(i);
  }

  await restart;
  return { 'confirmed by the broker': confirmed, 'confirm failed (channel closed)': failed, 'publish() threw': threw };
}

/** OrderPublisher: confirms, recuperación de la conexión y reenvío de todo lo no confirmado. */
async function withRecovery(): Promise<Record<string, number>> {
  const publisher = await OrderPublisher.start();
  const results: Array<Promise<boolean>> = [];
  let restart: Promise<void> | undefined;

  for (let i = 0; i < TOTAL; i++) {
    if (i === KILL_AFTER) restart = killAndRestartBroker();
    results.push(publisher.publish(ROUTING_KEY, orderNumber(i)).then(() => true, () => false));
    await pace(i);
  }

  const outcomes = await Promise.all(results);
  const allConfirmedAt = performance.now();
  await restart;
  await publisher.close();
  return {
    'confirmed by the broker': outcomes.filter(Boolean).length,
    'rejected': outcomes.filter((ok) => !ok).length,
    'seconds from kill to last confirm': Math.round((allConfirmedAt - killedAt) / 100) / 10,
  };
}

await resetQueues();
const started = performance.now();
const counters =
  scenario === 'fire-and-forget' ? await fireAndForget()
  : scenario === 'confirms' ? await confirmsOnly()
  : await withRecovery();
const { total, unique } = await countQueue();

console.log(`\nscenario: ${scenario}`);
console.log(`orders published: ${TOTAL}, broker killed after #${KILL_AFTER}`);
console.log(`broker down for ${((backAt - killedAt) / 1000).toFixed(1)} s, run took ${((performance.now() - started) / 1000).toFixed(1)} s`);
for (const [label, value] of Object.entries(counters)) console.log(`  ${label.padEnd(36)} ${value}`);
console.log(`  ${'messages in orders.billing'.padEnd(36)} ${total}`);
console.log(`  ${'distinct orders in orders.billing'.padEnd(36)} ${unique}`);
console.log(`  ${'orders lost'.padEnd(36)} ${TOTAL - unique}`);
console.log(`  ${'duplicates'.padEnd(36)} ${total - unique}`);

src/pause-probe.ts y src/deadline-probe.ts — las dos pruebas

// src/pause-probe.ts — congela el broker (sin RST, como una red rota) y mide cuánto tarda
// el publisher en notarlo y en entregar un pedido cuando el broker vuelve.
import { execFile } from 'node:child_process';
import { setTimeout as sleep } from 'node:timers/promises';
import { promisify } from 'node:util';
import { OrderPublisher } from './order-publisher.ts';

const docker = promisify(execFile);
const publisher = await OrderPublisher.start();
const started = performance.now();
const elapsed = (): string => `${((performance.now() - started) / 1000).toFixed(1)} s`;
const log = console.warn;
console.warn = (...args: unknown[]) => log(`[+${elapsed()}]`, ...args);

await docker('docker', ['pause', 'aurora-rabbitmq']);
console.warn('[probe] broker frozen with docker pause');
const confirmed = publisher.publish('order.us.placed', {
  orderId: `ord-probe-${Date.now()}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450,
});

await sleep(60_000);
await docker('docker', ['unpause', 'aurora-rabbitmq']);
console.warn('[probe] broker unfrozen');
await confirmed;
console.warn('[probe] order confirmed');
await publisher.close();

// src/deadline-probe.ts — qué significa para un pedido el plazo de quien llama, en los dos casos.
import amqp from 'amqplib';
import { execFile } from 'node:child_process';
import { setTimeout as sleep } from 'node:timers/promises';
import { promisify } from 'node:util';
import { RABBIT_URL } from './connection.ts';
import { OrderPublisher } from './order-publisher.ts';
import { BILLING_QUEUE } from './topology.ts';

const docker = promisify(execFile);
const order = (id: string) => ({ orderId: id, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 });
const outcome = (promise: Promise<void>): Promise<string> =>
  promise.then(() => 'confirmed', (error: Error) => `${error.name}: ${error.message}`);

async function idsInQueue(): Promise<string[]> {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createChannel();
  const ids: string[] = [];
  for (;;) {
    const message = await channel.get(BILLING_QUEUE, { noAck: true });
    if (message === false) break;
    ids.push(String(message.properties.messageId));
  }
  await connection.close();
  return ids;
}

const publisher = await OrderPublisher.start();

// 1. Broker detenido, sin canal: el pedido nunca sale del proceso.
await docker('docker', ['stop', 'aurora-rabbitmq']);
await sleep(1_000);
console.log('broker stopped     ->', await outcome(publisher.publish('order.us.placed', order('ord-deadline-unsent'), { signal: AbortSignal.timeout(2_000) })));
await docker('docker', ['start', 'aurora-rabbitmq']);

// 2. Broker congelado, canal vivo: el pedido se escribe en el socket y el confirm nunca llega.
await sleep(20_000);
await docker('docker', ['pause', 'aurora-rabbitmq']);
console.log('broker frozen      ->', await outcome(publisher.publish('order.us.placed', order('ord-deadline-sent'), { signal: AbortSignal.timeout(2_000) })));
await docker('docker', ['unpause', 'aurora-rabbitmq']);

await publisher.close();
await sleep(2_000);
console.log('in orders.billing  ->', (await idsInQueue()).join(', ') || '(empty)');

src/bench-confirms.ts y src/measure-drain.ts — las dos mediciones

// src/bench-confirms.ts — lo que cuestan los confirms en rendimiento, de tres formas. Nadie consume la cola.
import amqp from 'amqplib';
import { once } from 'node:events';
import { RABBIT_URL } from './connection.ts';
import { OrderPublisher } from './order-publisher.ts';
import { assertTopology, BILLING_QUEUE, ORDERS_EXCHANGE } from './topology.ts';

const COUNT = Number(process.argv[2] ?? 20_000);
const KEY = 'order.us.placed';
const body = (i: number): Buffer =>
  Buffer.from(JSON.stringify({ orderId: `ord-${i}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 }));

async function purge(): Promise<void> {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createChannel();
  await assertTopology(channel);
  await channel.purgeQueue(BILLING_QUEUE);
  await connection.close();
}

async function timed(label: string, run: () => Promise<void>): Promise<void> {
  await purge();
  const started = performance.now();
  await run();
  const seconds = (performance.now() - started) / 1000;
  console.log(`${label.padEnd(40)} ${String(Math.round(COUNT / seconds)).padStart(6)} msg/s`);
}

await timed('no confirms (fire-and-forget)', async () => {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createChannel();
  for (let i = 0; i < COUNT; i++) {
    if (!channel.publish(ORDERS_EXCHANGE, KEY, body(i), { persistent: true })) await once(channel, 'drain');
  }
  await connection.close();
});

await timed('confirms, awaiting each one', async () => {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createConfirmChannel();
  for (let i = 0; i < COUNT; i++) {
    await new Promise<void>((resolve, reject) =>
      channel.publish(ORDERS_EXCHANGE, KEY, body(i), { persistent: true }, (error) => (error ? reject(error) : resolve())));
  }
  await connection.close();
});

await timed('confirms, 1,000 in flight (OrderPublisher)', async () => {
  const publisher = await OrderPublisher.start();
  await Promise.all(Array.from({ length: COUNT }, (_, i) =>
    publisher.publish(KEY, { orderId: `ord-${i}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 })));
  await publisher.close();
});

await purge();

// src/measure-drain.ts — publica N pedidos y mide cuánto tarda facturación en cobrarlos todos.
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';
import { OrderPublisher } from './order-publisher.ts';

const COUNT = Number(process.argv[2] ?? 3_000);
const stats = async (): Promise<{ charges: number; replays: number }> =>
  (await fetch('http://localhost:4001/stats')).json() as Promise<{ charges: number; replays: number }>;

const before = await stats();
const publisher = await OrderPublisher.start();
const started = performance.now();
await Promise.all(Array.from({ length: COUNT }, () =>
  publisher.publish('order.us.placed', { orderId: `ord-${randomUUID()}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 })));
await publisher.close();

let now = await stats();
while (now.charges - before.charges < COUNT) { await sleep(100); now = await stats(); }
const seconds = (performance.now() - started) / 1000;
console.log(`prefetch ${process.env.BILLING_PREFETCH}: ${COUNT} orders charged in ${seconds.toFixed(1)} s (${Math.round(COUNT / seconds)} orders/s)`);

Con esto se cierra la serie. La Parte 1 llevaba un mensaje a la cola correcta, y esta lo mantuvo ahí durante la caída del broker, una reconexión, un escalado y un despliegue gradual, con cifras para cada caso. Si te llevas un solo hábito de las dos partes, que sea el ensayo: tumba el sistema a propósito y cuenta lo que vuelve. Casi siempre, la sorpresa está en ese conteo.

RabbitMQ from Fundamentals to Production, Part 2: Building a Scalable Service

Juan Gómez — Tue, 13 Oct 2026 14:00:00 +0000

RabbitMQ from Fundamentals to Production, Part 2: Building a Scalable Service

I killed the broker halfway through a burst of 20,000 orders. The publisher from Part 1 had called channel.publish 10,900 times without a single error. When RabbitMQ came back, the queue held 10,433 orders. Four hundred and sixty-seven orders had vanished, and nothing in the process knew. No exception, no log line, no failed promise. As far as checkout could tell, every one of those customers was about to be charged.

Part 1 was about getting a message to the right queue. This part is about what keeps it there when things go wrong: publisher confirms, connections that come back on their own, consumers you can scale and shut down without losing work, and a measured drill at the end that kills the broker under load and counts what survived. The same Aurora Coffee Co. topology, the same src/topology.ts.

Where Part 1 left the gap

Part 1 ended with an admission. This is its retry path as first published, from src/billing-consumer.ts:

// Park it in the delay queue with its original routing key and headers, so the
// x-death counter keeps accumulating across attempts.
channel.publish(RETRY_EXCHANGE, message.fields.routingKey, message.content, {
  persistent: true,
  headers: message.properties.headers,
  messageId: message.properties.messageId,
});
channel.ack(message);

Two operations, not one transaction. If the copy never reaches the retry queue, the ack has already deleted the original, and the order is gone. And channel.publish returning true does not mean what it looks like. It means the message fit in a buffer in your own process. The broker has not seen it yet. It may never see it.

The checkout publisher has exactly the same blind spot, and that is what the 467 missing orders above came from. Closing it takes publisher confirms.

And two things Part 1 got wrong

Before building on Part 1, I tested its failure paths against RabbitMQ 4.3. Two of its claims did not survive, and Part 1 has since been corrected. Here is what the tests showed.

The retry counter never counted. Part 1 read the broker's x-death header to count retries. This is its consumer, unchanged, with the payments service unreachable and one order to process:

$ docker run … -e PAYMENTS_URL=http://payments-is-down.invalid:4001 aurora-billing node part1/billing-consumer.ts
$ node src/checkout.ts 1
[checkout] no queue bound for order.us.refunded
[checkout] 1/1 orders confirmed by the broker
$ docker logs <consumer> | grep -E "^\[billing\] (retry|giving up)"
[billing] retry 1/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-be50d472-fee9-4c2d-a88c-a92bcfd568d7 [TypeError: fetch failed] {
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
name    messages
orders.billing  0
orders.billing.retry    1
orders.billing.dead 0

Retry 2 of 3, every 30 seconds, for as long as I let it run. The order never reaches orders.billing.dead. Reading the message in the retry queue showed why: after several trips, its x-death still said count: 1. When a consumer republishes a message, RabbitMQ 4.x does not carry over the x-death the client sends. It records only the death it has just seen. The fix is to count in a header the consumer owns, retry-count, which is what retriesSoFar reads now. The same test with this article's consumer:

$ docker run … -e PAYMENTS_URL=http://payments-is-down.invalid:4001 aurora-billing
$ node src/checkout.ts 1
[checkout] no queue bound for order.us.refunded
[checkout] 1/1 orders confirmed by the broker
$ docker logs <consumer> | grep -E "^\[billing\] (retry|giving up)"
[billing] retry 1/3 for ord-14f839be-4815-4639-88b2-d8deb9302923 [TypeError: fetch failed] {
[billing] retry 2/3 for ord-14f839be-4815-4639-88b2-d8deb9302923 [TypeError: fetch failed] {
[billing] retry 3/3 for ord-14f839be-4815-4639-88b2-d8deb9302923 [TypeError: fetch failed] {
[billing] giving up on ord-14f839be-4815-4639-88b2-d8deb9302923 after 3 retries [TypeError: fetch failed] {
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
name    messages
orders.billing  0
orders.billing.retry    0
orders.billing.dead 1

x-delivery-limit does not stop a requeue loop. Part 1 presented the delivery limit as the first layer of defence against a message that fails forever. On RabbitMQ 4.3, it counts a message that comes back because its channel or connection closed: in my test, 6 deliveries and then dead-lettered. It does not count an explicit nack(message, false, true) on a live channel: 50 back-to-back requeues of one message, and no dead-lettering at all. It is a safety net for consumers that crash, not a brake on code that requeues. That changes one line of this article's consumer, as you will see below.

First, upgrade amqplib

One housekeeping step before any new code. Part 1 pinned amqplib@^0.10.5, and that was already behind when the article went out. amqplib 1.0 shipped in March 2026, and the 2.x line is current. Three changes matter here:

Types are bundled since 1.2, so @types/amqplib goes away.
1.1 added opt-in connection recovery. Most of this article is about what it does, and what it leaves to you.
2.0 changed one default: heartbeat: 0 now disables heartbeats instead of meaning "use the server's value". If you never set it, nothing changes.

The dependency lines of Part 1's package.json:

{
  "dependencies": { "amqplib": "^0.10.5" },
  "devDependencies": { "@types/amqplib": "^0.10.6", "typescript": "^5.9.0" }
}

Part 2's, in full:

{
  "name": "aurora-orders-queue",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24" },
  "dependencies": { "amqplib": "^2.2.0" },
  "devDependencies": { "typescript": "^5.9.0", "@types/node": "^24.0.0" }
}

@types/node is there for tsc --noEmit, so process and Buffer typecheck. I ran Part 1's topology.ts and billing-consumer.ts through the compiler against amqplib 2.2's bundled types, and both compile without a single change.

Publisher confirms: the broker's half of the contract

The consumer acknowledges messages to the broker. A publisher confirm is the same thing pointed the other way: the broker acknowledges messages to the publisher. You turn it on per channel (createConfirmChannel in amqplib), and every publish then gets exactly one answer:

basic.ack: the broker took responsibility. For a persistent message routed to a durable classic queue, that means written to disk. For a quorum queue, it means a majority of replicas have it in their Raft log, whatever the delivery mode, since quorum queues persist every message. On a single node, a majority is that one node, fsynced.
basic.nack: the broker could not take it, usually because of an internal error or a queue refusing publishes when it is full. Rare, but real.
No answer, because the connection died first. This one is the important case, and it does not mean the message was lost. It means you do not know. The broker may have written it and lost the socket before the ack went out.

Two consequences fall straight out of that third case.

An unconfirmed message has to be sent again, so duplicates are part of the design. Republishing on reconnect will sometimes deliver an order the broker already had. That is why Part 1's consumer sends the order id as an idempotency key. The drill below counts these duplicates rather than pretending they do not happen.

A confirm does not mean the message was routed. Part 1's other gotcha was a typo'd routing key matching no binding. With mandatory: true, the broker returns the message (basic.return), and then it still sends basic.ack, because from its point of view it has finished with the message. The return always arrives before the ack, so a publisher that tracks returns can tell "confirmed" apart from "confirmed, and dropped on the floor".

Confirms are not slow. Waiting for them one at a time is.

The usual objection to confirms is throughput. I measured three ways of publishing the same 20,000 persistent orders into the quorum queue, two runs each:

run 1
no confirms (fire-and-forget)              6859 msg/s
confirms, awaiting each one                  70 msg/s
confirms, 1,000 in flight (OrderPublisher)   5728 msg/s
run 2
no confirms (fire-and-forget)              7425 msg/s
confirms, awaiting each one                  78 msg/s
confirms, 1,000 in flight (OrderPublisher)   4784 msg/s

Awaiting each confirm before sending the next one drops throughput by two orders of magnitude, because every message pays a full fsync round trip on its own. Keeping a window of messages in flight and matching confirms as they come back keeps most of the throughput: 4,784–5,728 msg/s against 6,859–7,425 with no confirms at all. That gap is the real price of knowing, and it is small next to the alternative. The absolute numbers come from Docker Desktop on a Windows laptop, where an fsync through the VM is slow, so expect yours to be different. The ratio is the point. If you remember one sentence from this section: never await a confirm inside a publishing loop.

The publisher

Here is the checkout side, with confirms, a bounded in-flight window, and resending after reconnect. It replaces Part 1's bare channel.publish plus drain handling.

// src/order-publisher.ts
import type { ChannelModel, ConfirmChannel, Options, RecoveringChannelModel } from 'amqplib';
import { connectWithRecovery } from './connection.ts';
import { assertTopology, ORDERS_EXCHANGE } from './topology.ts';

export type OrderPlaced = {
  orderId: string;
  sku: string;
  quantity: number;
  totalCents: number;
};

/** Caps memory, and is the backpressure: callers wait once this many are unconfirmed. */
const MAX_IN_FLIGHT = 1_000;

// amqplib rejects a confirm callback with this message when the broker nacks, and with
// "channel closed" when the channel dies first. Only the second one is worth resending.
const BROKER_NACK = 'message nacked';

type Unconfirmed = {
  routingKey: string;
  content: Buffer;
  options: Options.Publish & { messageId: string };
  /** Written to a socket at least once, so the broker may have it. */
  sent: boolean;
  resolve: () => void;
  reject: (error: Error) => void;
};

export class UnroutableError extends Error {
  override name = 'UnroutableError';
}

/** The deadline passed before the order reached any socket. It was never published. */
export class NotPublishedError extends Error {
  override name = 'NotPublishedError';
}

/**
 * The deadline passed after the order was sent but before the broker confirmed it.
 * It stays queued and is resent until confirmed, so it must not be reported as failed.
 */
export class PublishPendingError extends Error {
  override name = 'PublishPendingError';
}

export class OrderPublisher {
  #connection: RecoveringChannelModel | null = null;
  #channel: ConfirmChannel | null = null;
  #closed = false;
  #nextKey = 0;
  readonly #unconfirmed = new Map<number, Unconfirmed>();
  readonly #returned = new Set<string>();
  readonly #waitingForCapacity: Array<() => void> = [];
  readonly #waitingForIdle: Array<() => void> = [];

  static async start(): Promise<OrderPublisher> {
    const publisher = new OrderPublisher();
    publisher.#connection = await connectWithRecovery('checkout-publisher', (model) =>
      publisher.#attach(model),
    );
    return publisher;
  }

  /**
   * Resolves once the broker has confirmed the order. Rejects if the broker refuses it,
   * if no queue is bound for the routing key, or when `signal` aborts first. While the
   * broker is unreachable it waits: the order is resent on the next connection.
   */
  async publish(routingKey: string, order: OrderPlaced, { signal }: { signal?: AbortSignal } = {}): Promise<void> {
    while (this.#unconfirmed.size >= MAX_IN_FLIGHT && !this.#closed && !signal?.aborted) {
      await new Promise<void>((resolve) => {
        this.#waitingForCapacity.push(resolve);
        signal?.addEventListener('abort', () => resolve(), { once: true });
      });
    }
    if (this.#closed) throw new NotPublishedError('publisher is closed');
    if (signal?.aborted) throw new NotPublishedError(`no capacity before the deadline for ${order.orderId}`);

    const { promise, resolve, reject } = Promise.withResolvers<void>();
    const key = this.#nextKey++;
    const message: Unconfirmed = {
      routingKey,
      content: Buffer.from(JSON.stringify(order)),
      options: {
        persistent: true,
        mandatory: true,
        contentType: 'application/json',
        messageId: order.orderId,
      },
      sent: false,
      resolve,
      reject,
    };

    this.#unconfirmed.set(key, message);
    // No channel means we are between connections. The order waits in #unconfirmed
    // and #attach sends it as soon as there is a channel again.
    if (this.#channel) this.#send(this.#channel, key, message);

    signal?.addEventListener('abort', () => {
      if (!this.#unconfirmed.has(key)) return;
      if (!message.sent) {
        // Never left this process, so it is safe to drop and safe to report as failed.
        this.#settle(key);
        reject(new NotPublishedError(`${order.orderId} was not published before the deadline`));
      } else {
        // The broker may already have it. Keep resending; the caller only stops waiting.
        reject(new PublishPendingError(`${order.orderId} is sent but not yet confirmed`));
      }
    }, { once: true });

    return promise;
  }

  /** Waits for outstanding confirms (up to a deadline), then closes the connection. */
  async close(timeoutMs = 10_000): Promise<void> {
    this.#closed = true;
    for (const wake of this.#waitingForCapacity.splice(0)) wake();
    if (this.#unconfirmed.size > 0) {
      const idle = new Promise<void>((resolve) => this.#waitingForIdle.push(resolve));
      await Promise.race([idle, new Promise((resolve) => setTimeout(resolve, timeoutMs))]);
    }
    await this.#connection?.close();
    for (const message of this.#unconfirmed.values()) {
      message.reject(new PublishPendingError(`publisher closed before ${message.options.messageId} was confirmed`));
    }
    this.#unconfirmed.clear();
  }

  /** Runs after every (re)connect. */
  async #attach(model: ChannelModel): Promise<void> {
    const channel = await model.createConfirmChannel();
    await assertTopology(channel);

    // Returns belong to the channel that saw them. A return whose confirm died with the
    // old channel must not mark the resend, which may well be routed this time.
    this.#returned.clear();

    // With `mandatory`, an unroutable message comes back as basic.return *before* its
    // confirm, and that confirm is still an ack. Note the return so the ack is read right.
    channel.on('return', (returned) => {
      const id: unknown = returned.properties.messageId;
      if (typeof id === 'string') this.#returned.add(id);
    });

    // A channel error leaves the connection up, so recovery never fires and everything
    // unconfirmed would wait forever. Closing the connection hands the problem to
    // recovery, which backs off, reconnects, and runs this method again.
    channel.on('error', (error: Error) => {
      console.error(`[checkout-publisher] channel error, rebuilding: ${error.message}`);
      void model.close().catch(() => undefined);
    });
    channel.on('close', () => {
      if (this.#channel === channel) this.#channel = null;
    });

    this.#channel = channel;

    // Whatever the previous connection left unconfirmed goes out again. Some of it may
    // already be on disk with only the confirm lost: that is a duplicate, and the
    // consumer's idempotency key is what makes a duplicate harmless.
    for (const [key, message] of this.#unconfirmed) this.#send(channel, key, message);
  }

  #send(channel: ConfirmChannel, key: number, message: Unconfirmed): void {
    try {
      channel.publish(ORDERS_EXCHANGE, message.routingKey, message.content, message.options, (error) => {
        if (error instanceof Error && error.message !== BROKER_NACK) return; // resent on reconnect

        this.#settle(key);
        const wasReturned = this.#returned.delete(message.options.messageId);

        if (error) message.reject(new Error(`broker refused ${message.options.messageId}`));
        else if (wasReturned) message.reject(new UnroutableError(`no queue bound for ${message.routingKey}`));
        else message.resolve();
      });
      message.sent = true;
    } catch {
      // The channel closed under us. The message stays in #unconfirmed for the next one.
    }
  }

  #settle(key: number): void {
    this.#unconfirmed.delete(key);
    this.#waitingForCapacity.shift()?.();
    if (this.#unconfirmed.size === 0) {
      for (const wake of this.#waitingForIdle.splice(0)) wake();
    }
  }
}

What to notice, in order of how much it matters:

#unconfirmed is the whole design. A message enters it before it is sent and leaves only when the broker answers. Anything still in it when a connection dies is resent by #attach on the next one. The in-memory buffer is not a cache. It is the list of orders whose fate is unknown.
The window is also the backpressure. Part 1 waited for drain when the socket buffer filled. Here, a caller waits once 1,000 messages are unconfirmed, which caps the socket buffer as well. While the broker is down, that means publish() blocks, and the checkout request blocks with it. That is the honest behaviour: a request that cannot be made durable should not return success.
It distinguishes a nack from a dead channel. amqplib reports both through the same callback, with different messages. A nack is the broker saying no, so the caller gets an error. A closed channel says nothing about the message, so it stays queued for the next connection.
A channel error closes the connection on purpose. That looks heavy-handed, and it is deliberate. See the next section.
A deadline can only cancel what was never sent. Pass { signal: AbortSignal.timeout(…) } and you get one of two errors. NotPublishedError means the order never reached a socket, so it is gone, and the caller can safely report a failure. PublishPendingError means it was sent, and the broker may already have it, so it stays queued and is resent until confirmed. Reporting that second case as a failure is how a customer sees "payment failed" and gets charged anyway.

Using it from checkout looks like any other async call:

// src/checkout.ts
import { randomUUID } from 'node:crypto';
import { OrderPublisher, UnroutableError } from './order-publisher.ts';

const COUNT = Number(process.argv[2] ?? 10);
const publisher = await OrderPublisher.start();

const results = await Promise.allSettled(
  Array.from({ length: COUNT }, () =>
    publisher.publish('order.us.placed', {
      orderId: `ord-${randomUUID()}`,
      sku: 'BEAN-ETH-250',
      quantity: 1,
      totalCents: 1450,
    }),
  ),
);

// A routing key nothing is bound to: the confirm arrives, but it is not a success.
try {
  await publisher.publish('order.us.refunded', {
    orderId: `ord-${randomUUID()}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: -1450,
  });
} catch (error) {
  if (!(error instanceof UnroutableError)) throw error;
  console.warn(`[checkout] ${error.message}`);
}

const confirmed = results.filter((result) => result.status === 'fulfilled').length;
console.log(`[checkout] ${confirmed}/${COUNT} orders confirmed by the broker`);
await publisher.close();

$ node src/checkout.ts 100
[checkout] no queue bound for order.us.refunded
[checkout] 100/100 orders confirmed by the broker

The refund line is the routing-key typo from Part 1, caught this time. The confirm arrived, and the publisher still knew it was not a success.

And the two deadline outcomes, from a probe that publishes once with the broker stopped and once with it frozen (docker pause, so the order reaches the socket but no confirm ever comes back). Reconnect log lines are filtered out:

$ node src/deadline-probe.ts | grep -v '^[checkout-publisher]'
broker stopped     -> NotPublishedError: ord-deadline-unsent was not published before the deadline
broker frozen      -> PublishPendingError: ord-deadline-sent is sent but not yet confirmed
in orders.billing  -> ord-deadline-sent

The order that never left the process was never published. The one that was pending when its deadline passed arrived anyway, which is exactly why it was not reported as failed.

Connections, channels, and what kills which

A connection is a TCP socket with an AMQP handshake: expensive to open, and meant to live as long as the process. A channel is a lightweight virtual session multiplexed inside it. Most of the protocol happens on channels, which makes channels the unit of failure.

Three rules follow, and Node bends the usual advice on one of them.

1. A channel error closes the channel, and only the channel. Redeclare a queue with different arguments, publish to an exchange that does not exist, ack a delivery tag the channel does not know, and the broker closes that channel with an error. The connection stays up. Every consumer and every pending confirm on that channel is gone, and nothing reconnects, because from the connection's point of view nothing happened. Your consumer just goes quiet. That is why both the publisher and the consumer here react to channel.on('error') by closing the connection. It turns a silent half-failure into a full one, and recovery knows how to deal with a full one.

2. Separate connections for publishing and consuming. When RabbitMQ runs low on memory or disk, it raises an alarm and blocks connections that publish, until the alarm clears. If your consumers share that connection, their acks are stuck behind the block too, and the queue that needs draining stops draining. One connection per role avoids the deadlock. The connection_name in the code below makes each role show up by name on the management UI's Connections tab.

3. Delivery tags belong to a channel. A delivery tag is a counter, scoped to the channel that delivered the message. Ack it on any other channel, including the new one after a reconnect, and you are acking a stranger. Usually that is an unknown tag, which is a channel error (rule 1).

The advice you will read elsewhere, "never share a channel between threads", is literal in .NET and Java, where two threads writing frames to one channel interleave them. Node has one thread, so that particular bug cannot happen here. Rules 1 and 3 are the Node version of the same lesson: a channel is a unit of shared fate. Put things on the same channel only if you are happy for them to die together.

Reconnection: what amqplib does, and what it leaves to you

amqplib 1.1 added recovery: pass recovery options to connect, and the connection reconnects with exponential backoff and jitter whenever the socket drops. That much works as advertised. Here is what it does not do, which I only learned by reading lib/recovery.js:

It does not recover channels. A channel belongs to one underlying socket. When the socket dies, every channel on it is closed for good, and the objects you hold point at nothing.
It does not restore consumers or topology. Those live on channels.
It does not resend anything. Unconfirmed messages are your problem, which is why OrderPublisher keeps them.

What it gives you instead is setup: a function that runs after every successful connection, the first one included. Everything that lives on a channel gets rebuilt there. Part 1 made assertTopology idempotent for exactly this reason.

// src/connection.ts
import amqp from 'amqplib';
import type { ChannelModel, RecoveringChannelModel } from 'amqplib';

export const RABBIT_URL = process.env.RABBIT_URL ?? 'amqp://aurora:aurora-dev@localhost:5672';

// A crashed broker resets the socket and is noticed at once. A broker behind a dead
// network path sends nothing at all, and only missed heartbeats reveal it. RabbitMQ
// suggests 60 s; at 15 s, a frozen broker was noticed after 45 s.
const HEARTBEAT_SECONDS = 15;

/**
 * One connection per process *and role*. The name shows up in the management UI's
 * Connections tab, which is how you tell three billing replicas from a publisher.
 *
 * `setup` runs after every successful connect, including the first. amqplib reconnects
 * the socket on its own; channels, consumers and topology are yours to rebuild, and
 * this is the only place they get rebuilt.
 */
export async function connectWithRecovery(
  role: string,
  setup: (model: ChannelModel) => Promise<void>,
): Promise<RecoveringChannelModel> {
  const url = new URL(RABBIT_URL);
  url.searchParams.set('heartbeat', String(HEARTBEAT_SECONDS));

  const connection = await amqp.connect(url.toString(), {
    clientProperties: { connection_name: role },
    // Without it, a connect attempt to a host that never answers waits for the OS TCP
    // timeout, and recovery cannot schedule the next attempt until that one gives up.
    timeout: 10_000,
    recovery: {
      initialDelay: 500,
      maxDelay: 15_000,
      // A broker that is unreachable at boot is a misconfiguration: fail the deploy.
      initialMaxRetries: 5,
      // A broker that disappears later is an incident: keep trying until it is back.
      maxRetries: Infinity,
      setup,
    },
  });

  // Without this listener, recovery never gets the chance: the socket error is re-emitted
  // as 'error' on the recovering connection, and an unhandled 'error' kills the process.
  connection.on('error', (error) => console.warn(`[${role}] connection error: ${error.message}`));
  connection.on('disconnect', (error) => console.warn(`[${role}] disconnected: ${error.message}`));
  connection.on('reconnect-scheduled', ({ attempt, delay }) =>
    console.warn(`[${role}] reconnect attempt ${attempt} in ${delay} ms`),
  );
  connection.on('connect', () => console.log(`[${role}] reconnected`));
  connection.on('blocked', (reason) => console.warn(`[${role}] blocked by broker: ${reason}`));
  connection.on('unblocked', () => console.log(`[${role}] unblocked`));
  connection.on('reconnect-failed', (error) => {
    console.error(`[${role}] giving up on the broker: ${error.message}`);
    process.exitCode = 1;
  });

  return connection;
}

That error listener is the line I almost shipped without. The README's recovery example does not include one, and the first time my drill killed the broker with recovery switched on, the process died anyway. Here it is reproduced in a container: a client that connects with recovery options, registers only a disconnect listener, and then loses the broker.

connected with recovery enabled
/app/node_modules/amqplib/lib/safe_emit.js:8
      throw e;
      ^

Error: read ECONNRESET
    at TCP.onStreamRead (node:internal/stream_base_commons:216:20)
Emitted 'error' event on RecoveringPromiseModel instance at:
    at RecoveringCore.<anonymous> (/app/node_modules/amqplib/lib/recovery.js:445:46)
    at RecoveringCore.emit (node:events:514:28)
    at ChannelModel.onConnectionError (/app/node_modules/amqplib/lib/recovery.js:269:45)
    at ChannelModel.emit (node:events:514:28)
    at Connection.emit (node:events:514:28)
    at safeEmit (/app/node_modules/amqplib/lib/safe_emit.js:3:13)
    at Connection.onSocketError (/app/node_modules/amqplib/lib/connection.js:300:7)
    at Socket.emit (node:events:526:24)
    at emitErrorNT (node:internal/streams/destroy:170:8)
    at emitErrorCloseNT (node:internal/streams/destroy:129:3) {
  errno: -104,
  code: 'ECONNRESET',
  syscall: 'read'
}

Node.js v24.21.0

The recovering connection re-emits the socket error as 'error', and an EventEmitter with no 'error' listener throws. The disconnect listener never ran. Recovery was ready to reconnect, and the process was gone before it got the chance. A connection that reconnects automatically is a very convincing feature right up to the moment it takes the process down with it.

Four more settings are worth stealing:

initialMaxRetries separate from maxRetries. A broker you cannot reach at boot is almost always a wrong URL or a wrong password, and the deploy should fail loudly. A broker that disappears later is an incident, and the service should wait it out.
A heartbeat short enough to notice silence. A killed broker resets the socket, so the drill below sees every disconnect at once. A broker behind a dead network path sends nothing at all, and only missed heartbeats reveal it. In the probe below, a 15-second heartbeat noticed a frozen broker after 45 seconds. RabbitMQ suggests 60, which stretches the same silence to minutes, with every order piling up in #unconfirmed in the meantime.
A connect timeout. Without timeout, an attempt against a host that never answers waits for the operating system's TCP timeout, and recovery cannot schedule the next one until it gives up. In the probe, attempt 2 was scheduled ten seconds after attempt 1.
Jitter is not decoration. When the drill below restarts the broker under three consumer replicas, the logs show each one retrying on its own schedule (522 ms, 466 ms and 427 ms for the first attempt). Without jitter, all three reconnect in the same millisecond, and with a hundred replicas, so does the load spike.

The probe behind the heartbeat and timeout numbers: it freezes the broker with docker pause, the closest local stand-in for a dead network path, and publishes one order.

[+0.2 s] [probe] broker frozen with docker pause
[+45.0 s] [checkout-publisher] connection error: Heartbeat timeout
[+45.0 s] [checkout-publisher] disconnected: Heartbeat timeout
[+45.0 s] [checkout-publisher] reconnect attempt 1 in 587 ms
[+55.6 s] [checkout-publisher] reconnect attempt 2 in 904 ms
[+60.4 s] [probe] broker unfrozen
[checkout-publisher] reconnected
[+60.5 s] [probe] order confirmed

The consumer

The consumer gets four changes. Everything that does not change, which is parseOrder, retriesSoFar and chargeCard, moves verbatim from Part 1 into src/billing.ts, with export added. It is in the appendix at the end, so the consumer below can stay about what is new.

// src/billing-consumer.ts
import type { ChannelModel, ConfirmChannel, ConsumeMessage, Options } from 'amqplib';
import { chargeCard, parseOrder, RETRY_COUNT_HEADER, retriesSoFar } from './billing.ts';
import { connectWithRecovery } from './connection.ts';
import { assertTopology, BILLING_QUEUE, RETRY_EXCHANGE } from './topology.ts';

const MAX_RETRIES = 3;
// In Node this is not just a fairness knob: it caps how many handlers run at once.
const PREFETCH = Number(process.env.BILLING_PREFETCH ?? 20);

const inFlight = new Set<Promise<void>>();
// Message ids the broker returned as unroutable, per channel. See publishConfirmed.
const returnedOn = new WeakMap<ConfirmChannel, Set<string>>();
let active: { channel: ConfirmChannel; consumerTag: string } | null = null;
let shuttingDown = false;

/**
 * Resolves only when the broker confirmed the copy *and* routed it to a queue. An
 * unroutable message is still acked by the broker; without `mandatory` and the return
 * check, a missing binding would let the caller ack the original and lose the order.
 */
function publishConfirmed(
  channel: ConfirmChannel,
  exchange: string,
  routingKey: string,
  content: Buffer,
  options: Options.Publish & { messageId: string },
): Promise<void> {
  return new Promise((resolve, reject) => {
    channel.publish(exchange, routingKey, content, { ...options, mandatory: true }, (error) => {
      const returned = returnedOn.get(channel)?.delete(options.messageId) ?? false;
      if (error) reject(error);
      else if (returned) reject(new Error(`no queue bound for ${routingKey} on ${exchange}`));
      else resolve();
    });
  });
}

/**
 * Delivery tags belong to the channel that delivered the message. If that channel died
 * mid-handler, the broker has already requeued the message, and the ack has nothing to
 * acknowledge. Never ack on the *new* channel: an unknown tag is a channel error there.
 */
function settle(action: () => void): void {
  try {
    action();
  } catch {
    // Channel closed: the message will be redelivered with `redelivered: true`.
  }
}

async function handle(channel: ConfirmChannel, message: ConsumeMessage): Promise<void> {
  let order;

  try {
    order = parseOrder(message);
  } catch (error) {
    console.error('[billing] unparseable message, dead-lettering', error);
    settle(() => channel.nack(message, false, false));
    return;
  }

  try {
    const chargeId = await chargeCard(order);
    console.log(`[billing] charged ${order.orderId} -> ${chargeId}`);
    settle(() => channel.ack(message));
    return;
  } catch (error) {
    const attempts = retriesSoFar(message);

    if (attempts >= MAX_RETRIES) {
      console.error(`[billing] giving up on ${order.orderId} after ${attempts} retries`, error);
      settle(() => channel.nack(message, false, false));
      return;
    }

    console.warn(`[billing] retry ${attempts + 1}/${MAX_RETRIES} for ${order.orderId}`, error);

    try {
      // Part 1 published and acked back to back. Now the ack waits for the broker to
      // confirm the copy is safe in the retry queue.
      await publishConfirmed(channel, RETRY_EXCHANGE, message.fields.routingKey, message.content, {
        persistent: true,
        headers: { ...message.properties.headers, [RETRY_COUNT_HEADER]: attempts + 1 },
        messageId: order.orderId,
      });
      settle(() => channel.ack(message));
    } catch (publishError) {
      // The retry copy is not confirmed, so the original must not be acked. Requeueing
      // would loop: on RabbitMQ 4.x an explicit requeue does not count towards
      // x-delivery-limit. Dead-letter it instead, where a human will see it.
      console.error(`[billing] could not park ${order.orderId} for retry, dead-lettering`, publishError);
      settle(() => channel.nack(message, false, false));
    }
  }
}

/** Runs after every (re)connect: a fresh channel, the topology, and the consumer. */
async function attach(model: ChannelModel): Promise<void> {
  if (shuttingDown) return;

  const channel = await model.createConfirmChannel();
  await assertTopology(channel);
  await channel.prefetch(PREFETCH);

  const returned = new Set<string>();
  returnedOn.set(channel, returned);
  channel.on('return', (message) => {
    const id: unknown = message.properties.messageId;
    if (typeof id === 'string') returned.add(id);
  });

  // Same rule as the publisher: a dead channel on a live connection is a consumer that
  // silently stopped. Escalate it so recovery rebuilds everything.
  channel.on('error', (error: Error) => {
    console.error(`[billing] channel error, rebuilding: ${error.message}`);
    void model.close().catch(() => undefined);
  });

  const { consumerTag } = await channel.consume(BILLING_QUEUE, (message) => {
    if (message === null) {
      // Cancelled by the broker, e.g. the queue was deleted. Rebuild, which re-declares it.
      void model.close().catch(() => undefined);
      return;
    }

    const task: Promise<void> = handle(channel, message)
      .catch((error: unknown) => console.error('[billing] handler crashed', error))
      .finally(() => inFlight.delete(task));
    inFlight.add(task);
  });

  active = { channel, consumerTag };
}

const connection = await connectWithRecovery('billing-consumer', attach);
console.log(`[billing] consuming ${BILLING_QUEUE} with prefetch ${PREFETCH}`);

async function shutdown(): Promise<void> {
  shuttingDown = true;

  console.log(`[billing] shutting down with ${inFlight.size} in flight`);
  // 1. Stop new deliveries, but keep the channel open so in-flight work can still ack.
  if (active) await active.channel.cancel(active.consumerTag).catch(() => undefined);
  // 2. Let what is already running finish. chargeCard times out at 5 s, so this is bounded.
  await Promise.allSettled([...inFlight]);
  // 3. Close the channel first. Its close is queued behind the acks on the same channel;
  //    closing the connection directly can overtake the last ack and requeue a finished order.
  if (active) await active.channel.close().catch(() => undefined);
  await connection.close();
}

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => {
    void shutdown().then(() => process.exit(0));
  });
}

The four changes, against Part 1:

The retry copy is confirmed, and routed, before the original is acked. This closes the gap Part 1 admitted: publishConfirmed waits for the broker, and only then does ack delete the original. It also publishes with mandatory and treats a return as a failure, because a missing retry binding would otherwise be confirmed, and the order lost. If the copy cannot be parked, the original is dead-lettered, not requeued. A requeue does not count towards x-delivery-limit, so it would loop as fast as the network allows. With the retry binding deleted, the order went straight to orders.billing.dead after a single attempt. Retries are counted in retry-count, the fix described at the top.
Everything that lives on a channel is rebuilt in attach. The channel, the topology, the prefetch and the consumer. That is the whole of what recovery needs from you.
Acks go to the channel that delivered the message, and only to that one. handle receives its channel as an argument and never reads a "current channel" variable. If that channel died mid-handler, settle swallows the failed ack. The broker requeued the message the moment the channel closed, so there was nothing left to acknowledge.
Shutdown drains before it closes. That needs its own section.

Shutdown, and the ack that never arrived

This is Part 1's shutdown:

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => {
    // Closing the channel requeues anything still unacknowledged, so a rolling deploy
    // hands in-flight work to the next pod instead of losing it.
    void channel
      .close()
      .then(() => connection.close())
      .then(() => process.exit(0));
  });
}

The comment is true, and it hides a cost. Closing the channel while handlers are still running means every in-flight order that has already called the payments service but has not yet acked is requeued, and charged again on the next replica. The idempotency key turns the second charge into a no-op, so no customer pays twice. It is still wasted work, and it is a bet that every downstream service honours idempotency keys.

The new shutdown does it in three steps: cancel the consumer so no new messages arrive, wait for in-flight handlers, then close. I measured both versions the same way: one replica, prefetch 20, 1,000 orders, docker stop after 2.5 seconds, then counting how many charges the payments stub saw twice. The table is assembled from those runs:

Consumer	Run 1	Run 2	Run 3
Part 1 (close the channel immediately)	16	5	8
Part 2, closing the connection after draining	1	1	2
Part 2, closing the channel and then the connection	0	0	0

That middle row cost me most of an hour. The drain worked: when I first hit it, the log said it waited for 15 in-flight handlers, and all 15 charged and acked. One or two orders were redelivered anyway, on every run. I traced it to how amqplib writes frames. Each channel has its own write buffer, and a multiplexer interleaves them onto the socket. The ack sits in channel 1's buffer, while connection.close() goes out through channel 0's. The close can overtake the last ack. The broker sees "connection closing" and requeues a message that was already finished.

Closing the channel first fixes it, because channel.close() is queued behind the acks on that same channel. It is one line, and it only showed up because the stub counts replays.

Scaling out: competing consumers and prefetch

Run more than one consumer on the same queue and RabbitMQ round-robins messages between them. This is the competing consumers pattern, and it is the whole of horizontal scaling for a queue. No partitions to plan, no coordinator. Start another replica and it starts taking messages.

The compose file gains the services. The RabbitMQ service is Part 1's, plus one line, which the restart section below explains:

# docker-compose.yml
services:
  rabbitmq:
    image: rabbitmq:4-management
    container_name: aurora-rabbitmq
    # The node name is rabbit@<hostname>, and the data directory is named after the node.
    # Without a fixed hostname, a recreated container is a new node with no queues.
    hostname: aurora-rabbitmq
    ports:
      - "5672:5672"    # AMQP — what your app connects to
      - "15672:15672"  # management UI — what you connect to
    environment:
      RABBITMQ_DEFAULT_USER: aurora
      RABBITMQ_DEFAULT_PASS: aurora-dev
    volumes:
      - rabbitmq-data:/var/lib/rabbitmq
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "-q", "check_running"]
      interval: 10s
      timeout: 5s
      retries: 5

  payments:
    build: .
    command: ["node", "src/payments-stub.ts"]
    environment:
      PAYMENTS_LATENCY_MS: "50"
    ports:
      - "4001:4001"

  billing:
    build: .
    environment:
      RABBIT_URL: amqp://aurora:aurora-dev@rabbitmq:5672
      PAYMENTS_URL: http://payments:4001
      BILLING_PREFETCH: ${BILLING_PREFETCH:-20}
    depends_on:
      rabbitmq:
        condition: service_healthy
      payments:
        condition: service_started
    # Long enough for shutdown() to drain in-flight handlers before Docker sends SIGKILL.
    stop_grace_period: 30s

volumes:
  rabbitmq-data:

FROM node:24-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY src ./src
USER node
CMD ["node", "src/billing-consumer.ts"]

Node 24 runs the .ts files directly, so the image needs no build step, the same way the laptop needs none. The payments stub, an HTTP server of about 50 lines that sleeps 50 ms per charge, honours idempotency keys even for concurrent requests with the same key, and counts replays, is in the appendix.

Prefetch is your concurrency limit

In Part 1, prefetch was a fairness knob: without it, the first consumer to connect gets the whole queue. In Node, it is also something else. Look at the consumer callback: it starts handle() and returns immediately. Nothing waits. So the prefetch count caps how many handlers run at once in a process, because the broker will not send more unacked messages than that. Three replicas with prefetch 20 means up to 60 concurrent calls to the payments service.

Same 3,000 orders, three replicas, the stub taking 50 ms per charge:

$ BILLING_PREFETCH=1 docker compose up -d --wait --scale billing=3 billing
$ BILLING_PREFETCH=1 node src/measure-drain.ts 3000
prefetch 1: 3000 orders charged in 66.3 s (45 orders/s)
$ BILLING_PREFETCH=20 docker compose up -d --wait --scale billing=3 billing
$ BILLING_PREFETCH=20 node src/measure-drain.ts 3000
prefetch 20: 3000 orders charged in 5.8 s (516 orders/s)
$ BILLING_PREFETCH=100 docker compose up -d --wait --scale billing=3 billing
$ BILLING_PREFETCH=100 node src/measure-drain.ts 3000
prefetch 100: 3000 orders charged in 3.7 s (821 orders/s)

With prefetch 1, three replicas behave like three single-threaded workers: 3 × (1 / 50 ms) is 60 orders a second in theory, and 45 measured. Prefetch 20 is eleven times faster. Prefetch 100 is faster again, but by much less than five times, because 300 concurrent handlers could in theory charge 6,000 orders a second, and something other than the consumers runs out first. It still means 300 concurrent requests landing on the payments provider. With a real provider that rate-limits you, that is how you get 429s and a retry storm. Size prefetch against what the slowest downstream accepts, divided by the number of replicas, not against what the queue can deliver. The queue will always deliver faster than the provider can charge.

What you give up: ordering

Part 1 already said it: order is preserved within a queue only while one consumer reads it. Competing consumers process orders side by side, so order 41 can finish before order 40. For billing, that is fine. If your consumer genuinely needs order (applying account balance changes, say), declare the queue with x-single-active-consumer: true. Every replica stays connected, but only one receives messages, and another takes over when it goes away. You get failover without parallelism. And because it is a queue argument, Part 1's other gotcha applies: decide it before the queue exists, because you cannot add it later.

When the broker restarts

The restart that keeps your data, and the one that does not

Part 1's compose file declared a named volume for /var/lib/rabbitmq, which reads like persistence. It is, as long as the container survives. Here is what happens when it does not:

$ docker compose up -d --wait && node src/checkout.ts 100
[checkout] no queue bound for order.us.refunded
[checkout] 100/100 orders confirmed by the broker
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
name    messages
orders.billing  100
orders.billing.retry    0
orders.billing.dead 0
$ docker compose down && docker compose up -d --wait
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
$ docker exec aurora-rabbitmq ls /var/lib/rabbitmq/mnesia
rabbit@8dfd00d4dcd6
rabbit@8dfd00d4dcd6-feature_flags
rabbit@8dfd00d4dcd6-plugins-expand
rabbit@ffe1f6cff9d8
rabbit@ffe1f6cff9d8-feature_flags
rabbit@ffe1f6cff9d8-plugins-expand
rabbit@ffe1f6cff9d8.pid

A hundred confirmed orders, then no queues at all, and the volume still holding the old data. A RabbitMQ node is named rabbit@<hostname>, its data directory is named after the node, and a container's default hostname is its random container id. docker compose down and up create a new container, so a new node boots, finds no directory under its own name, and starts empty. The old node's data sits next to it, intact and ignored. docker restart keeps the container and its hostname, which is why this survives casual testing and then bites on the first image upgrade, because upgrading recreates the container.

The fix is the line the new compose file adds:

    container_name: aurora-rabbitmq
    hostname: aurora-rabbitmq

Same test with it: 100 messages before down, 100 messages after, one data directory. Kubernetes StatefulSets give pods stable hostnames for the same reason.

What one node can and cannot promise

A quorum queue on a single node gives you durability: a confirmed message has been fsynced before the ack goes out. It does not give you availability. While that node is down, nothing publishes and nothing consumes. Replication is what quorum queues are actually for: on a three-node cluster a queue survives one node failing and keeps serving. That changes what happens during the outage, not the client code. The client does need one change, though. amqp.connect takes a single URL, and recovery keeps dialling that same address, so if that node is the one that died, the client waits for it to come back instead of failing over. Put a TCP load balancer such as HAProxy in front of the nodes, or a DNS name that only resolves to healthy ones, and connect to that. Everything else in this article works the same against a cluster. Running one locally is a compose file of its own.

The drill: kill the broker mid-batch and count

Here is the setup. Nothing consumes the queue during a run. The harness publishes 20,000 orders at about 10,000 a second. After order #10,000, it runs docker kill aurora-rabbitmq (SIGKILL, no graceful shutdown), then docker start, keeps publishing the whole time the way checkout traffic would, and when the broker is back it drains orders.billing and counts distinct order ids. The full script is in the appendix.

Be clear about what this does and does not test. docker kill ends the broker process, but the host's page cache survives, so writes the broker made and never fsynced are still there afterwards. The drill measures what is lost in flight, in the client's buffer and the broker's memory. It cannot prove that a confirmed message was fsynced, because these runs would show the same result even if it was not. Testing that takes losing the machine itself, a VM power-off for instance. Three scenarios.

A: Part 1's publisher. A plain channel. publish() returning normally is the only signal it gets. One concession to the measurement: Part 1's publisher registered no error listener, so the real one would have crashed at the kill. The drill adds listeners to keep counting. The orders that went missing had already been accepted either way.

scenario: fire-and-forget
orders published: 20000, broker killed after #10000
broker down for 9.6 s, run took 16.2 s
  publish() returned normally          10900
  publish() threw                      9100
  messages in orders.billing           10433
  distinct orders in orders.billing    10433
  orders lost                          9567
  duplicates                           0

The 9,100 that threw are not the problem: checkout saw an error and could tell the customer. The problem is the gap between 10,900 and 10,433. 467 orders were accepted without an error and never arrived. They were in the client's buffer, or in the broker's memory, when the process was killed.

B: confirms, but nothing resends.

scenario: confirms
orders published: 20000, broker killed after #10000
broker down for 11.0 s, run took 17.3 s
  confirmed by the broker              10665
  confirm failed (channel closed)      1335
  publish() threw                      8000
  messages in orders.billing           10793
  distinct orders in orders.billing    10793
  orders lost                          9207
  duplicates                           0

Every one of the 10,665 confirmed orders is in the queue. The 1,335 whose confirm never came are the "you do not know" case, and the count proves it: 128 of them made it anyway (10,793 − 10,665), and 1,207 did not. Confirms do not prevent the loss. They make it visible, which is the precondition for fixing it.

C: OrderPublisher. Confirms, recovery, and resending everything unconfirmed.

[checkout-publisher] connection error: Unexpected close
[checkout-publisher] disconnected: Unexpected close
[checkout-publisher] reconnect attempt 1 in 530 ms
[checkout-publisher] reconnect attempt 2 in 1007 ms
[checkout-publisher] reconnect attempt 3 in 1760 ms
[checkout-publisher] reconnect attempt 4 in 3332 ms
[checkout-publisher] reconnect attempt 5 in 9301 ms
[checkout-publisher] reconnected

scenario: recovery
orders published: 20000, broker killed after #10000
broker down for 9.9 s, run took 24.8 s
  confirmed by the broker              20000
  rejected                             0
  seconds from kill to last confirm    18.4
  messages in orders.billing           20128
  distinct orders in orders.billing    20000
  orders lost                          0
  duplicates                           128

All 20,000 orders, plus 128 duplicates: orders the broker had written whose confirm died with the socket, sent again. Note also the cost of backoff in this run. The broker was back after 9.9 seconds, but attempt 5 was already scheduled 9.3 seconds out, so the publisher sat idle against a healthy broker for several seconds. maxDelay is a trade between hammering a broker that is still booting and lingering after it recovers. Fifteen seconds is my compromise. Pick yours with an incident in mind.

I ran each scenario three times. The table is assembled from the nine captures:

Scenario	Accepted with no error, never arrived	Confirmed, never arrived	Lost overall	Duplicates
A: fire-and-forget	467 / 1,406 / 1,125	n/a	9,567 / 9,606 / 9,125	0 / 0 / 0
B: confirms only	n/a	0 / 0 / 0	9,207 / 10,934 / 9,400	0 / 0 / 0
C: `OrderPublisher`	n/a	0 / 0 / 0	0 / 0 / 0	128 / 64 / 322

A loses a different amount of silent data every run, depending on what was in flight at the moment of the kill. B never loses a confirmed message and never resends an unconfirmed one. C trades loss for duplicates, which is the only trade at-least-once delivery offers.

The consumer side of the same drill

Same kill, this time with three billing replicas consuming 6,000 orders at prefetch 20:

$ curl -s localhost:4001/stats
{"charges":9000,"replays":0}
$ (sleep 4; docker kill aurora-rabbitmq; docker start aurora-rabbitmq) & BILLING_PREFETCH=20 node src/measure-drain.ts 6000
prefetch 20: 6000 orders charged in 28.9 s (208 orders/s)
$ curl -s localhost:4001/stats
{"charges":15000,"replays":53}
$ docker exec aurora-rabbitmq rabbitmqctl -q list_queues name messages
name    messages
orders.billing  0
orders.billing.retry    0
orders.billing.dead 0
$ docker compose logs billing --since 1m --no-log-prefix | grep -v charged
[billing] consuming orders.billing with prefetch 20
[billing] consuming orders.billing with prefetch 20
[billing] consuming orders.billing with prefetch 20
[billing-consumer] connection error: read ECONNRESET
[billing-consumer] disconnected: read ECONNRESET
[billing-consumer] reconnect attempt 1 in 522 ms
[billing-consumer] reconnect attempt 2 in 938 ms
[billing-consumer] reconnect attempt 3 in 2182 ms
[billing-consumer] reconnect attempt 4 in 4550 ms
[billing-consumer] reconnect attempt 5 in 8630 ms
[billing-consumer] reconnected
[billing-consumer] connection error: read ECONNRESET
[billing-consumer] disconnected: read ECONNRESET
[billing-consumer] reconnect attempt 1 in 466 ms
[billing-consumer] reconnect attempt 2 in 1148 ms
[billing-consumer] reconnect attempt 3 in 1829 ms
[billing-consumer] reconnect attempt 4 in 4379 ms
[billing-consumer] reconnect attempt 5 in 8235 ms
[billing-consumer] reconnected
[billing-consumer] connection error: read ECONNRESET
[billing-consumer] disconnected: read ECONNRESET
[billing-consumer] reconnect attempt 1 in 427 ms
[billing-consumer] reconnect attempt 2 in 997 ms
[billing-consumer] reconnect attempt 3 in 1823 ms
[billing-consumer] reconnect attempt 4 in 3324 ms
[billing-consumer] reconnect attempt 5 in 8230 ms
[billing-consumer] reconnected

Exactly 6,000 new distinct charges, all three queues empty, and 53 replays. Those are orders a replica had charged when the socket died, before its ack reached the broker. The broker redelivered them, another replica called the payments stub again with the same idempotency key, and the stub returned the original charge. Nobody was billed twice, and that was decided in Part 1, by one HTTP header. Every reliability mechanism in this article produces duplicates somewhere. The idempotency key is what makes them free.

When to use what

Reach for confirms with a resend buffer when:

A lost message is a lost sale, a missed charge, or an order that never ships. That is any publisher whose messages someone will come looking for.
You can make consumers idempotent. If you cannot, fix that first: resending without idempotency turns lost messages into double charges.

Keep it simpler when:

The message is telemetry, such as a page view or a metric sample. Losing 467 of 20,000 during a broker crash is acceptable, and fire-and-forget is several times cheaper to run and reason about.
The publish and a database write have to be atomic. OrderPublisher keeps unconfirmed orders in memory. If the checkout process itself crashes, they die with it, and so does the order that was already saved in Postgres. The fix is the transactional outbox: write the event to an outbox table in the same transaction as the order, and have a relay publish from that table with confirms. It is the next step up in reliability, and it is a different architecture, not a tweak to this one.

On the build-versus-buy question:

amqplib's built-in recovery plus your own setup is what this article uses. It is a small amount of code, and every part of it is visible.
amqp-connection-manager wraps channels so they survive reconnects, re-runs your setup, and queues publishes while disconnected. It predates amqplib's recovery and does more of the work for you. It is worth a look if you would rather not own #unconfirmed. Read how it bounds that queue before trusting it with a long outage.
Managed brokers (Amazon MQ for RabbitMQ, CloudAMQP) take the cluster, the upgrades, and the hostname problem off your hands. They do not take any of the client-side work off your hands. Everything above still applies, because the connection can still drop.

And on clusters: a single node is fine until the cost of "nothing publishes for eight seconds" exceeds the cost of running three nodes. For a checkout, that line usually arrives early.

Key Takeaways

publish() returning true means your buffer accepted the message, not the broker. In the drill, 467 orders went that way with no error anywhere. Confirms are the only signal that a message is the broker's problem and not yours, and pipelined they cost a fraction of the throughput (4,784–5,728 msg/s against 6,859–7,425). Awaited one by one, they ran at 70–78.
amqplib's recovery reconnects the socket and nothing else. Rebuild channels, topology and consumers in setup, resend what was unconfirmed, and add an 'error' listener, or the process dies before recovery gets a chance.
In Node, prefetch caps your concurrency. Replicas × prefetch is the most requests you send downstream at once. Size it against the slowest dependency, not the queue.
Every reliability mechanism here produces duplicates. 128 from resending, 53 from redelivery, all absorbed by one idempotency key. Make consumers idempotent first, and the rest becomes safe to add.
Trigger every failure path on your broker version before trusting it. Part 1's retry counter read x-death, and its loop protection leaned on x-delivery-limit. On RabbitMQ 4.3 neither held, and only a test with a dead payments service showed it.

Appendix: the rest of the code

Everything below is needed to run the examples and the drill, but none of it is the pattern itself.

src/billing.ts — Part 1's helpers, unchanged except for export

// src/billing.ts
import type { ConsumeMessage } from 'amqplib';
import type { OrderPlaced } from './order-publisher.ts';

const PAYMENTS_URL = process.env.PAYMENTS_URL ?? 'http://localhost:4001';
export const RETRY_COUNT_HEADER = 'retry-count';

/**
 * How many times this message has already been parked in the retry queue. The consumer
 * counts it itself: RabbitMQ 4.x ignores the x-death a client sends when it republishes,
 * so x-death never gets past 1 and a failing order would be retried forever.
 */
export function retriesSoFar(message: ConsumeMessage): number {
  const count: unknown = message.properties.headers?.[RETRY_COUNT_HEADER];
  return typeof count === 'number' ? count : 0;
}

export function parseOrder(message: ConsumeMessage): OrderPlaced {
  const parsed: unknown = JSON.parse(message.content.toString('utf8'));

  if (
    typeof parsed !== 'object' || parsed === null ||
    typeof (parsed as OrderPlaced).orderId !== 'string' ||
    typeof (parsed as OrderPlaced).totalCents !== 'number'
  ) {
    throw new SyntaxError('order payload is missing orderId or totalCents');
  }

  return parsed as OrderPlaced;
}

export async function chargeCard(order: OrderPlaced): Promise<string> {
  const response = await fetch(`${PAYMENTS_URL}/charges`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      // Delivery is at-least-once, so the same order can arrive twice. The order id
      // as idempotency key means the second attempt returns the first charge instead
      // of billing the customer again.
      'idempotency-key': order.orderId,
    },
    body: JSON.stringify({ amountCents: order.totalCents, reference: order.orderId }),
    signal: AbortSignal.timeout(5_000),
  });

  if (!response.ok) {
    throw new Error(`payments service returned ${response.status} for ${order.orderId}`);
  }

  const { chargeId } = (await response.json()) as { chargeId: string };
  return chargeId;
}

src/payments-stub.ts — the stand-in payments service

// src/payments-stub.ts
// A stand-in for the payments provider, so the consumer has something to call.
// It honours idempotency keys the way a real provider does, and counts replays.
import { randomUUID } from 'node:crypto';
import { createServer } from 'node:http';
import { setTimeout as sleep } from 'node:timers/promises';

const PORT = Number(process.env.PORT ?? 4001);
const LATENCY_MS = Number(process.env.PAYMENTS_LATENCY_MS ?? 50);

// The pending charge is stored before the delay, so two concurrent requests with the
// same key share one charge instead of both missing the map and creating two.
const chargesByKey = new Map<string, Promise<string>>();
let replays = 0;

const server = createServer(async (request, response) => {
  const reply = (status: number, body: unknown): void => {
    response.writeHead(status, { 'content-type': 'application/json' });
    response.end(JSON.stringify(body));
  };

  if (request.method === 'GET' && request.url === '/stats') {
    reply(200, { charges: chargesByKey.size, replays });
    return;
  }

  if (request.method !== 'POST' || request.url !== '/charges') {
    reply(404, { error: 'not found' });
    return;
  }

  for await (const _chunk of request); // the body is not needed, only consumed
  const key = request.headers['idempotency-key'];
  if (typeof key !== 'string' || key.length === 0) {
    reply(400, { error: 'idempotency-key header is required' });
    return;
  }

  const existing = chargesByKey.get(key);
  if (existing) {
    replays++;
    console.log(`[payments] replayed ${key}`);
    reply(200, { chargeId: await existing });
    return;
  }

  const charge = sleep(LATENCY_MS).then(() => `ch_${randomUUID()}`);
  chargesByKey.set(key, charge);
  reply(201, { chargeId: await charge });
});

server.listen(PORT, () => console.log(`[payments] listening on ${PORT}, ${LATENCY_MS} ms per charge`));

src/drill.ts — the broker-kill drill

// src/drill.ts
// Publishes TOTAL orders, kills the broker after KILL_AFTER of them, restarts it, and
// counts what is in orders.billing afterwards. Nothing consumes the queue during the run.
//
//   node src/drill.ts <fire-and-forget|confirms|recovery> [total] [killAfter]
import amqp from 'amqplib';
import { execFile } from 'node:child_process';
import { once } from 'node:events';
import { setTimeout as sleep } from 'node:timers/promises';
import { promisify } from 'node:util';
import { RABBIT_URL } from './connection.ts';
import { OrderPublisher } from './order-publisher.ts';
import type { OrderPlaced } from './order-publisher.ts';
import {
  assertTopology, BILLING_DEAD_QUEUE, BILLING_QUEUE, BILLING_RETRY_QUEUE, ORDERS_EXCHANGE,
} from './topology.ts';

const SCENARIOS = ['fire-and-forget', 'confirms', 'recovery'] as const;
type Scenario = (typeof SCENARIOS)[number];

const scenario = process.argv[2] as Scenario;
if (!SCENARIOS.includes(scenario)) {
  console.error(`usage: node src/drill.ts <${SCENARIOS.join('|')}> [total] [killAfter]`);
  process.exit(2);
}
const TOTAL = Number(process.argv[3] ?? 20_000);
const KILL_AFTER = Number(process.argv[4] ?? TOTAL / 2);
const CONTAINER = 'aurora-rabbitmq';
const ROUTING_KEY = 'order.us.placed';
const SENTINEL = 'drill-sentinel';
// Roughly 10,000 orders a second: a busy checkout, not a benchmark loop.
const BATCH = 100;
const BATCH_PAUSE_MS = 10;

const docker = promisify(execFile);

function orderNumber(i: number): OrderPlaced {
  return { orderId: `ord-${String(i).padStart(6, '0')}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 };
}

async function waitForBroker(): Promise<void> {
  for (;;) {
    try {
      const probe = await amqp.connect(RABBIT_URL);
      await probe.close();
      return;
    } catch {
      await sleep(250);
    }
  }
}

let killedAt = 0;
let backAt = 0;
async function killAndRestartBroker(): Promise<void> {
  killedAt = performance.now();
  await docker('docker', ['kill', CONTAINER]);
  await docker('docker', ['start', CONTAINER]);
  await waitForBroker();
  backAt = performance.now();
}

async function resetQueues(): Promise<void> {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createChannel();
  await assertTopology(channel);
  for (const queue of [BILLING_QUEUE, BILLING_RETRY_QUEUE, BILLING_DEAD_QUEUE]) await channel.purgeQueue(queue);
  await connection.close();
}

/** Drains orders.billing and reports how many messages, and how many distinct orders, it held. */
async function countQueue(): Promise<{ total: number; unique: number }> {
  // A quorum queue that just restarted elects a leader and replays its log before it
  // reports its real depth, and counting too early reads 0. A confirmed write proves
  // there is a leader again, so publish a sentinel first, then wait for a stable depth.
  const connection = await amqp.connect(RABBIT_URL);
  const confirms = await connection.createConfirmChannel();
  confirms.sendToQueue(BILLING_QUEUE, Buffer.from('{}'), { persistent: true, messageId: SENTINEL });
  await confirms.waitForConfirms();
  await confirms.close();

  const channel = await connection.createChannel();
  let depth = -1;
  for (;;) {
    await sleep(1_000);
    const { messageCount } = await channel.checkQueue(BILLING_QUEUE);
    if (messageCount === depth) break;
    depth = messageCount;
  }

  const seen = new Set<string>();
  let total = 0;
  let lastMessageAt = performance.now();
  await channel.consume(BILLING_QUEUE, (message) => {
    if (message === null) return;
    lastMessageAt = performance.now();
    if (message.properties.messageId === SENTINEL) return;
    total++;
    seen.add(String(message.properties.messageId));
  }, { noAck: true });

  // Done when nothing has arrived for two seconds and the broker agrees the queue is empty.
  for (;;) {
    await sleep(500);
    if (performance.now() - lastMessageAt < 2_000) continue;
    const { messageCount } = await channel.checkQueue(BILLING_QUEUE);
    if (messageCount === 0) break;
  }

  await connection.close();
  return { total, unique: seen.size };
}

const pace = async (i: number): Promise<void> => {
  if (i % BATCH === BATCH - 1) await sleep(BATCH_PAUSE_MS);
};

/** Part 1's publisher: publish() returning true is the only signal it gets. */
async function fireAndForget(): Promise<Record<string, number>> {
  const connection = await amqp.connect(RABBIT_URL);
  connection.on('error', () => undefined); // keep the drill alive to count; Part 1's code crashes here
  const channel = await connection.createChannel();
  channel.on('error', () => undefined);

  let accepted = 0;
  let threw = 0;
  let restart: Promise<void> | undefined;

  for (let i = 0; i < TOTAL; i++) {
    if (i === KILL_AFTER) restart = killAndRestartBroker();
    const order = orderNumber(i);
    try {
      const writable = channel.publish(ORDERS_EXCHANGE, ROUTING_KEY, Buffer.from(JSON.stringify(order)), {
        persistent: true, contentType: 'application/json', messageId: order.orderId,
      });
      accepted++;
      if (!writable) await Promise.race([once(channel, 'drain'), once(channel, 'close')]);
    } catch {
      threw++;
    }
    await pace(i);
  }

  await restart;
  return { 'publish() returned normally': accepted, 'publish() threw': threw };
}

/** A confirm channel, but nothing resends what was left unconfirmed. */
async function confirmsOnly(): Promise<Record<string, number>> {
  const connection = await amqp.connect(RABBIT_URL);
  connection.on('error', () => undefined);
  const channel = await connection.createConfirmChannel();
  channel.on('error', () => undefined);

  let confirmed = 0;
  let failed = 0;
  let threw = 0;
  let restart: Promise<void> | undefined;

  for (let i = 0; i < TOTAL; i++) {
    if (i === KILL_AFTER) restart = killAndRestartBroker();
    const order = orderNumber(i);
    try {
      channel.publish(
        ORDERS_EXCHANGE, ROUTING_KEY, Buffer.from(JSON.stringify(order)),
        { persistent: true, contentType: 'application/json', messageId: order.orderId },
        (error) => (error ? failed++ : confirmed++),
      );
    } catch {
      threw++;
    }
    await pace(i);
  }

  await restart;
  return { 'confirmed by the broker': confirmed, 'confirm failed (channel closed)': failed, 'publish() threw': threw };
}

/** OrderPublisher: confirms, connection recovery, and a resend of everything unconfirmed. */
async function withRecovery(): Promise<Record<string, number>> {
  const publisher = await OrderPublisher.start();
  const results: Array<Promise<boolean>> = [];
  let restart: Promise<void> | undefined;

  for (let i = 0; i < TOTAL; i++) {
    if (i === KILL_AFTER) restart = killAndRestartBroker();
    results.push(publisher.publish(ROUTING_KEY, orderNumber(i)).then(() => true, () => false));
    await pace(i);
  }

  const outcomes = await Promise.all(results);
  const allConfirmedAt = performance.now();
  await restart;
  await publisher.close();
  return {
    'confirmed by the broker': outcomes.filter(Boolean).length,
    'rejected': outcomes.filter((ok) => !ok).length,
    'seconds from kill to last confirm': Math.round((allConfirmedAt - killedAt) / 100) / 10,
  };
}

await resetQueues();
const started = performance.now();
const counters =
  scenario === 'fire-and-forget' ? await fireAndForget()
  : scenario === 'confirms' ? await confirmsOnly()
  : await withRecovery();
const { total, unique } = await countQueue();

console.log(`\nscenario: ${scenario}`);
console.log(`orders published: ${TOTAL}, broker killed after #${KILL_AFTER}`);
console.log(`broker down for ${((backAt - killedAt) / 1000).toFixed(1)} s, run took ${((performance.now() - started) / 1000).toFixed(1)} s`);
for (const [label, value] of Object.entries(counters)) console.log(`  ${label.padEnd(36)} ${value}`);
console.log(`  ${'messages in orders.billing'.padEnd(36)} ${total}`);
console.log(`  ${'distinct orders in orders.billing'.padEnd(36)} ${unique}`);
console.log(`  ${'orders lost'.padEnd(36)} ${TOTAL - unique}`);
console.log(`  ${'duplicates'.padEnd(36)} ${total - unique}`);

src/pause-probe.ts and src/deadline-probe.ts — the two probes

// src/pause-probe.ts — freezes the broker (no RST, like a dead network path) and times
// how long the publisher takes to notice and to deliver one order once it is back.
import { execFile } from 'node:child_process';
import { setTimeout as sleep } from 'node:timers/promises';
import { promisify } from 'node:util';
import { OrderPublisher } from './order-publisher.ts';

const docker = promisify(execFile);
const publisher = await OrderPublisher.start();
const started = performance.now();
const elapsed = (): string => `${((performance.now() - started) / 1000).toFixed(1)} s`;
const log = console.warn;
console.warn = (...args: unknown[]) => log(`[+${elapsed()}]`, ...args);

await docker('docker', ['pause', 'aurora-rabbitmq']);
console.warn('[probe] broker frozen with docker pause');
const confirmed = publisher.publish('order.us.placed', {
  orderId: `ord-probe-${Date.now()}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450,
});

await sleep(60_000);
await docker('docker', ['unpause', 'aurora-rabbitmq']);
console.warn('[probe] broker unfrozen');
await confirmed;
console.warn('[probe] order confirmed');
await publisher.close();

// src/deadline-probe.ts — what a caller's deadline means for an order, in both cases.
import amqp from 'amqplib';
import { execFile } from 'node:child_process';
import { setTimeout as sleep } from 'node:timers/promises';
import { promisify } from 'node:util';
import { RABBIT_URL } from './connection.ts';
import { OrderPublisher } from './order-publisher.ts';
import { BILLING_QUEUE } from './topology.ts';

const docker = promisify(execFile);
const order = (id: string) => ({ orderId: id, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 });
const outcome = (promise: Promise<void>): Promise<string> =>
  promise.then(() => 'confirmed', (error: Error) => `${error.name}: ${error.message}`);

async function idsInQueue(): Promise<string[]> {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createChannel();
  const ids: string[] = [];
  for (;;) {
    const message = await channel.get(BILLING_QUEUE, { noAck: true });
    if (message === false) break;
    ids.push(String(message.properties.messageId));
  }
  await connection.close();
  return ids;
}

const publisher = await OrderPublisher.start();

// 1. Broker down, no channel: the order never leaves the process.
await docker('docker', ['stop', 'aurora-rabbitmq']);
await sleep(1_000);
console.log('broker stopped     ->', await outcome(publisher.publish('order.us.placed', order('ord-deadline-unsent'), { signal: AbortSignal.timeout(2_000) })));
await docker('docker', ['start', 'aurora-rabbitmq']);

// 2. Broker frozen, channel alive: the order is written to the socket, the confirm never comes.
await sleep(20_000);
await docker('docker', ['pause', 'aurora-rabbitmq']);
console.log('broker frozen      ->', await outcome(publisher.publish('order.us.placed', order('ord-deadline-sent'), { signal: AbortSignal.timeout(2_000) })));
await docker('docker', ['unpause', 'aurora-rabbitmq']);

await publisher.close();
await sleep(2_000);
console.log('in orders.billing  ->', (await idsInQueue()).join(', ') || '(empty)');

src/bench-confirms.ts and src/measure-drain.ts — the two benchmarks

// src/bench-confirms.ts — what confirms cost in throughput, three ways. Nothing consumes the queue.
import amqp from 'amqplib';
import { once } from 'node:events';
import { RABBIT_URL } from './connection.ts';
import { OrderPublisher } from './order-publisher.ts';
import { assertTopology, BILLING_QUEUE, ORDERS_EXCHANGE } from './topology.ts';

const COUNT = Number(process.argv[2] ?? 20_000);
const KEY = 'order.us.placed';
const body = (i: number): Buffer =>
  Buffer.from(JSON.stringify({ orderId: `ord-${i}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 }));

async function purge(): Promise<void> {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createChannel();
  await assertTopology(channel);
  await channel.purgeQueue(BILLING_QUEUE);
  await connection.close();
}

async function timed(label: string, run: () => Promise<void>): Promise<void> {
  await purge();
  const started = performance.now();
  await run();
  const seconds = (performance.now() - started) / 1000;
  console.log(`${label.padEnd(40)} ${String(Math.round(COUNT / seconds)).padStart(6)} msg/s`);
}

await timed('no confirms (fire-and-forget)', async () => {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createChannel();
  for (let i = 0; i < COUNT; i++) {
    if (!channel.publish(ORDERS_EXCHANGE, KEY, body(i), { persistent: true })) await once(channel, 'drain');
  }
  await connection.close();
});

await timed('confirms, awaiting each one', async () => {
  const connection = await amqp.connect(RABBIT_URL);
  const channel = await connection.createConfirmChannel();
  for (let i = 0; i < COUNT; i++) {
    await new Promise<void>((resolve, reject) =>
      channel.publish(ORDERS_EXCHANGE, KEY, body(i), { persistent: true }, (error) => (error ? reject(error) : resolve())));
  }
  await connection.close();
});

await timed('confirms, 1,000 in flight (OrderPublisher)', async () => {
  const publisher = await OrderPublisher.start();
  await Promise.all(Array.from({ length: COUNT }, (_, i) =>
    publisher.publish(KEY, { orderId: `ord-${i}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 })));
  await publisher.close();
});

await purge();

// src/measure-drain.ts — publishes N orders and times how long billing takes to charge them all.
import { randomUUID } from 'node:crypto';
import { setTimeout as sleep } from 'node:timers/promises';
import { OrderPublisher } from './order-publisher.ts';

const COUNT = Number(process.argv[2] ?? 3_000);
const stats = async (): Promise<{ charges: number; replays: number }> =>
  (await fetch('http://localhost:4001/stats')).json() as Promise<{ charges: number; replays: number }>;

const before = await stats();
const publisher = await OrderPublisher.start();
const started = performance.now();
await Promise.all(Array.from({ length: COUNT }, () =>
  publisher.publish('order.us.placed', { orderId: `ord-${randomUUID()}`, sku: 'BEAN-ETH-250', quantity: 1, totalCents: 1450 })));
await publisher.close();

let now = await stats();
while (now.charges - before.charges < COUNT) { await sleep(100); now = await stats(); }
const seconds = (performance.now() - started) / 1000;
console.log(`prefetch ${process.env.BILLING_PREFETCH}: ${COUNT} orders charged in ${seconds.toFixed(1)} s (${Math.round(COUNT / seconds)} orders/s)`);

That closes the series. Part 1 got a message to the right queue, and this part kept it there through a broker crash, a reconnect, a scale-out and a rolling deploy, with numbers for each. If you take a single habit from both parts, make it the drill: kill the thing on purpose and count what came back. The count is usually where the surprise is.

Pino y Serilog, medidos: el sink asíncrono es rápido porque descarta líneas

Juan Gómez — Thu, 08 Oct 2026 14:00:00 +0000

Pino y Serilog, medidos: el sink asíncrono es rápido porque descarta líneas

El checkout de Aurora Coffee Co. escribe una línea de log estructurada por cada orden. Quería saber cuánto cuesta eso, así que registré el mismo evento 200.000 veces por cada configuración de destino que se me ocurrió, en Node 24 y en .NET 10. Dos líneas de la corrida de Serilog:

serilog -> compact JSON, sync           164 k/s  mean   6081 ns  p50  4500  p99  28400  max 46985500
serilog -> compact JSON, async          331 k/s  mean   3017 ns  p50  1000  p99   4000  max 19268600

Envolver el destino en WriteTo.Async duplicó el rendimiento y dividió el p99 entre siete. Ese es el resultado que todo el mundo cita, y la razón por la que ese envoltorio aparece en casi todas las configuraciones de Serilog que he leído.

Después conté las líneas que llegaron al archivo:

file                   lines        bytes   bytes/line   expected lines
serilog-async.log       80256   21,047,885          262           202000   <-- MISMATCH
serilog-json.log       202000   53,009,780          262           202000

121.744 líneas de log no existían. Sin excepción, sin advertencia, sin ningún contador en la aplicación. El sink asíncrono era el doble de rápido porque estaba haciendo algo más de un tercio del trabajo.

Este artículo es lo que encontró el resto de ese banco de pruebas: cuánto cuesta la estructura (menos de lo que crees), cuánto cuesta el destino (más de lo que crees), y cuál de los dos valores por defecto que tienes delante pierde datos en silencio.

El montaje, para que los números signifiquen algo

Cada número de aquí sale de un arnés por runtime que registra el mismo evento —una orden con cinco campos— 200.000 veces, después de 2.000 iteraciones de calentamiento. Cada llamada se cronometra por separado con process.hrtime.bigint() en Node y Stopwatch.GetTimestamp() en .NET, así que la cola es real y no una resta del total.

Dos detalles importan más de lo que parecen.

El bucle cede el control. Mi primera corrida en Node daba el destino con búfer más lento que el síncrono, lo cual es imposible. La causa era el banco de pruebas, no el destino: un bucle síncrono cerrado nunca vuelve al event loop, así que un destino con búfer no puede vaciarse y simplemente acumula — 40 MB de acumulación. Ceder el control cada 1.000 iteraciones lo arregló. Si tu medición de logging muestra que el búfer empeora las cosas, es por esto.

Los conteos de líneas se verifican. Cada arnés termina contando las líneas de cada archivo y comparándolas con lo que registró. Esa comprobación es la única razón por la que existe este artículo; sin ella, el resultado asíncrono de Serilog se lee como una victoria limpia.

// bench.ts — la forma de cada medición
const N = Number(process.argv[2] ?? 200_000);
const WARMUP = 2_000;
const YIELD_EVERY = 1_000;

const tick = () => new Promise<void>((resolve) => setImmediate(resolve));

async function measure(name: string, run: (i: number) => void, flush?: () => void): Promise<void> {
  for (let i = 0; i < WARMUP; i += 1) run(i);
  await tick();

  const samples = new Float64Array(N);
  let busy = 0;
  for (let i = 0; i < N; i += 1) {
    const t0 = process.hrtime.bigint();
    run(i);
    const dt = Number(process.hrtime.bigint() - t0);
    samples[i] = dt;
    busy += dt;
    // Sin esto el event loop nunca corre y un destino con búfer no puede vaciarse.
    if (i % YIELD_EVERY === YIELD_EVERY - 1) await tick();
  }
  flush?.();

  const sorted = Float64Array.from(samples).sort();
  const at = (q: number) => sorted[Math.min(sorted.length - 1, Math.ceil(q * sorted.length) - 1)];
  const mean = samples.reduce((a, b) => a + b, 0) / samples.length;

  console.log(
    `${name.padEnd(36)} ${(N / (busy / 1e9) / 1000).toFixed(0).padStart(6)} k/s  ` +
      `mean ${mean.toFixed(0).padStart(6)} ns  p50 ${at(0.5).toFixed(0).padStart(5)}  ` +
      `p99 ${at(0.99).toFixed(0).padStart(6)}  max ${at(1).toFixed(0).padStart(8)}`,
  );
}

El hardware es un portátil, no un servidor, así que fíjate en las proporciones y no en las cifras absolutas.

Cuánto cuesta de verdad la estructura

El miedo es que serializar JSON sea caro comparado con escribir una cadena. Esta es la corrida de Node, las seis configuraciones, tal cual:

node v24.16.0   pino 10.3.1   N=200000 (+2000 warm-up)

string concat, writeSync                211 k/s  mean   4733 ns  p50  3700  p99  16400  max  1070300
pino, sync destination                  193 k/s  mean   5181 ns  p50  4400  p99  19400  max  1035400
pino, buffered destination              176 k/s  mean   5694 ns  p50  5100  p99  18700  max   931400
debug at level=info, plain payload    12068 k/s  mean     83 ns  p50   100  p99    300  max   263800
debug at level=info, costly payload     100 k/s  mean  10047 ns  p50  7900  p99  26400  max  1240800
debug guarded by isLevelEnabled       10295 k/s  mean     97 ns  p50   100  p99    300  max    56300

file                   lines        bytes   bytes/line   expected lines
pino-buffered.log      202000   41,091,780          203           202000
pino-quiet.log              0            0            0                0
pino-sync.log          202000   41,091,780          203           202000
text-sync.log          202000   22,709,780          112           202000

all files complete

El logging estructurado cuesta un 9%. 5.181 ns contra 4.733 ns de construir a mano la cadena equivalente y escribirla al mismo descriptor de archivo. Esa es toda la penalización de serializar, y a cambio obtienes una línea que una máquina puede filtrar en lugar de una que una expresión regular tiene que adivinar.

El lado de .NET es menos halagador y más interesante:

string interpolation, AutoFlush         302 k/s  mean   3313 ns  p50  2600  p99  13200  max   695200
serilog template -> text file           127 k/s  mean   7888 ns  p50  5700  p99  31000  max  3345300
serilog -> compact JSON, sync           164 k/s  mean   6081 ns  p50  4500  p99  28400  max 46985500

El sink de texto de Serilog es más lento que el de JSON: 7.888 ns contra 6.081 ns. Convertir una plantilla de mensaje en una frase legible cuesta más que emitir el documento estructurado, porque convertir significa formatear cada propiedad dentro de una cadena, mientras que el formateador JSON escribe los valores donde ya están. El formato legible es el caro. Si conservas un sink de texto porque el JSON "tiene que pesar más", es al revés.

Lo que no sale gratis son los bytes:

	bytes por línea	relativo
texto, Node	112	1,0×
JSON, Node (pino)	203	1,8×
texto, .NET	117	1,0×
plantilla renderizada, .NET	176	1,5×
JSON compacto, .NET (Serilog)	262	2,2×

Esa es la factura de verdad, y no es de CPU. A mil líneas por segundo, los 91 bytes extra por línea de pino son 7,9 GB al día de almacenamiento e ingesta que antes no tenías: 86,4 millones de líneas por 91 bytes. Todos los productos de logs cobran exactamente por ese número.

El destino, que es donde está el dinero

Un logger hace dos cosas: convertir un evento en bytes y llevar esos bytes a algún sitio. Lo primero es lo que miden los bancos de pruebas. Lo segundo es lo que te despierta de madrugada.

Síncrono

La escritura ocurre en el hilo que llama. Tu petición espera al disco. Con un SSD local y la caché del sistema delante, eso suele estar bien. Y a veces no:

serilog -> compact JSON, sync           164 k/s  mean   6081 ns  p50  4500  p99  28400  max 46985500

La media son 6 µs. El máximo son 47 milisegundos, para una sola llamada de log. Es una petición, en algún punto de esas 200.000, que pasó una veinteava parte de segundo dentro de Log.Information. Nada del código es lento; el sistema operativo decidió vaciar a disco y el llamador lo pagó. Los sinks síncronos ponen la cola del almacenamiento sobre la cola de tus peticiones, y una media no te lo va a enseñar nunca.

Con búfer, estilo Node

El destino con búfer de pino entrega los bytes a un búfer interno y regresa. Lo apunté a un destino que tarda 2 ms por vaciado —un recolector de logs saturado, un volumen de red, un disco bajo presión— y registré 20.000 líneas:

sink: 2ms per flush, 20000 lines logged
  caller p50           1900 ns
  caller p99          14500 ns
  caller max        1071900 ns
  flushes done             21
  RSS at start         57.5 MB
  RSS peak             73.7 MB
  RSS growth           16.2 MB

El llamador nunca esperó: un p50 de 1,9 µs frente a un destino que tarda dos milisegundos por vaciado. Se completaron veintiún vaciados en el tiempo que costó registrar veinte mil líneas, y la memoria residente creció 16,2 MB. El atasco no desapareció: está en el heap, esperando a un destino que no da abasto.

Ese es el intercambio, dicho sin rodeos: un destino con búfer no abarata la escritura, la convierte en problema de otro para más tarde, y ese "más tarde" se guarda en la memoria de tu proceso. Si el destino sigue lento, no recibes una alerta de latencia. Recibes un proceso eliminado por falta de memoria, que es una forma bastante peor de enterarte.

Y cuando el proceso se muere

La razón por la que registras logs suele ser que algo salió mal. Así que registré 50.000 líneas en un destino con búfer de pino y maté el proceso como se mueren los procesos de verdad: sin vaciado y sin manejador de cierre.

lines logged       50000
lines on disk          1
lost               49999  (100.0%)

Una línea. El búfer está en la memoria de un proceso muerto, y el archivo tiene lo que se hubiera vaciado antes de morir. Un process.on('exit') que llame a flushSync() cierra casi todo este agujero, y un SIGKILL o una caída dura lo vuelven a abrir entero.

Asíncrono, estilo .NET

WriteTo.Async pone una cola acotada y un hilo de fondo entre tu código y el sink. La cola por defecto son 10.000 eventos, y el comportamiento por defecto cuando se llena es descartar. Estas son las tres configuraciones de Serilog de la misma corrida:

serilog -> compact JSON, sync           164 k/s  mean   6081 ns  p50  4500  p99  28400  max 46985500
serilog -> compact JSON, async          331 k/s  mean   3017 ns  p50  1000  p99   4000  max 19268600
serilog -> JSON, async blockWhenFull    122 k/s  mean   8220 ns  p50  3700  p99  38700  max 23037300

Y los conteos de líneas de esos tres archivos:

serilog-async-block.log   202000   53,009,780          262           202000
serilog-async.log          80256   21,047,885          262           202000   <-- MISMATCH
serilog-json.log          202000   53,009,780          262           202000

Lee los dos bloques juntos y el panorama se invierte:

configuración	rendimiento	líneas conservadas
síncrono	164 k/s	202.000
asíncrono, por defecto	331 k/s	80.256
asíncrono, `blockWhenFull: true`	122 k/s	202.000

El sink asíncrono que conserva tus datos es más lento que no poner ningún sink asíncrono. 122 k/s contra 164 k/s: la cola, el traspaso y el cambio de contexto cuestan más de lo que ahorran en cuanto dejas de permitirle descartar lo que sobra. La configuración que todo el mundo copia es la fila de en medio, y la fila de en medio perdió el 60% de los eventos.

Conviene advertir algo sobre ese número: este banco de pruebas machaca el logger en un bucle cerrado, mucho más fuerte de lo que lo hará un servicio real, así que en producción la cola se vacía entre peticiones y casi nunca descarta nada. La conclusión no es "te falta el 60% de los logs". La conclusión es que el descarte es silencioso y nadie lo mide, así que la única vez que importa —un incidente, una tormenta de reintentos, el pico que más querías ver registrado— no vas a saber que ocurrió. Si usas WriteTo.Async, pon blockWhenFull: true y acepta la latencia, o conecta su callback monitor para que la profundidad de la cola sea una métrica que puedas ver.

Niveles: la llamada que creías gratis

Una llamada de log desactivada igual evalúa sus argumentos. El objeto se construye, la cadena se interpola, la pila se captura, y solo entonces el logger decide tirarlo todo.

Cuánto cuesta eso depende por completo del payload, y los dos casos están separados por cuatro órdenes de magnitud:

debug at level=info, plain payload    12068 k/s  mean     83 ns   (pino)
debug at level=info, costly payload     100 k/s  mean  10047 ns   (pino)
debug guarded by isLevelEnabled       10295 k/s  mean     97 ns   (pino)

debug at Information, plain payload   37351 k/s  mean     27 ns   (serilog)
debug at Information, costly payload     77 k/s  mean  12981 ns   (serilog)
debug guarded by IsEnabled            55574 k/s  mean     18 ns   (serilog)

Con un objeto plano, una llamada de debug descartada cuesta 83 ns en pino y 27 ns en Serilog: gratis, para cualquier propósito. Protegerla con isLevelEnabled no cambia nada; pino sale a 97 ns protegida frente a 83 ns sin proteger, que es ruido en la dirección equivocada.

Con un payload que cuesta construir —aquí una traza de pila capturada— esa misma llamada descartada cuesta 10.047 ns en pino y 12.981 ns en Serilog. Eso es el doble que una línea de log activa que sí se escribe. Protegida, baja a 97 ns y 18 ns.

Así que el consejo de "protege siempre tus llamadas de debug" y el de "no te molestes, el logger es rápido" están los dos equivocados, y la regla es mecánica:

Protege una llamada de nivel desactivado cuando, y solo cuando, construir sus argumentos haga trabajo real. Un objeto serializado, un JSON.stringify, una traza de pila, una consulta a base de datos para obtener un nombre legible, un string.Join sobre una colección. Si el payload son campos que ya tienes a mano, la protección es estorbo.

Los números de .NET traen una nota extra: las plantillas de mensaje de Serilog difieren el formateo automáticamente, y por eso su caso de payload plano es tres veces más barato que el de pino. Lo que no se difiere es la expresión del argumento. Log.Debug("{Trace}", new StackTrace().ToString()) construye la traza de pila quiera alguien verla o no.

Enmascarar datos, que es a donde fue a parar la PII

Todo el valor del logging estructurado es que registras el objeto en lugar de una frase sobre el objeto. Lo que significa que tarde o temprano registras al cliente:

{"customer":{"id":"cus-5521","email":"ana.morales@example.com","phone":"+505-5555-0188","address":{"line1":"Reparto San Juan 120","city":"Managua","country":"NI"}},"payment":{"brand":"visa","last4":"4242","token":"tok_live_9f2b61ac"}}

La opción redact de pino toma rutas y las censura o las elimina. Medí cuatro configuraciones contra el mismo payload anidado:

no redaction                          119 k/s  mean  8406 ns  p99  24900
redact: 4 paths, censored             137 k/s  mean  7284 ns  p99  19800
redact: 4 paths, removed              100 k/s  mean 10032 ns  p99  31000
redact: wildcard on two objects       110 k/s  mean  9120 ns  p99  26700

Censurar es más rápido que no enmascarar nada: 7.284 ns contra 8.406 ns, porque [redacted] es más corto que una dirección y queda menos JSON que escribir. Enmascarar no es un costo que estés pesando contra la seguridad. Es gratis, y en el caso habitual sale a favor.

remove: true es la opción lenta, 10.032 ns, porque borrar claves cuesta más que sobrescribir valores. Prefiere censurar, salvo que una clave ausente rompa a quien lee después.

Y luego la trampa, que es la razón de imprimir la salida de cada configuración en vez de fiarse:

redact-paths.log
  customer: {"id":"cus-5521","email":"[redacted]","phone":"[redacted]","address":"[redacted]"}
  payment : {"brand":"visa","last4":"4242","token":"[redacted]"}
redact-wildcard.log
  customer: {"id":"[redacted]","email":"[redacted]","phone":"[redacted]","address":"[redacted]"}
  payment : {"brand":"[redacted]","last4":"[redacted]","token":"[redacted]"}

La versión con comodín —customer.* y payment.*, la configuración que escribes con prisa queriendo ir sobre seguro— también censuró customer.id y payment.last4. Esos no son datos personales: son los dos campos que hacían útil la línea. Alguien de soporte puede encontrar una orden con cus-5521. No puede encontrar nada con [redacted].

Nombra las rutas. En .NET el equivalente es una política Destructure.ByTransforming<T>() en la configuración del logger, y tiene la misma propiedad: sé específico o borrarás tus propias claves de correlación.

Los campos que conviene acordar

Nada de esto sirve si dos servicios llaman distinto a lo mismo. Consultar entre servicios es el objetivo entero, y lo que lo rompe es el vocabulario, no el volumen. La lista corta que se gana su sitio:

service y version — qué desplegable y qué compilación. El segundo responde "¿esto empezó con la release?" sin tener que adivinar.
trace_id y span_id — la unión con tus trazas. Los dos loggers los añaden solos bajo OpenTelemetry; el artículo anterior de esta línea cubre el cableado y el hook del cargador que, si falta, lo impide en silencio.
Un identificador de dominio por evento — order_id, no id. Un campo llamado id en cuatro servicios son cuatro cosas distintas en un mismo índice.
error.type y error.stack como campos separados, nunca una cadena ya formateada. El tipo es por lo que agrupas; la pila es lo que lees después.
Un level normalizado — los dos loggers no se ponen de acuerdo por partida doble, que es la siguiente sección.

El campo de nivel es peor que un desacuerdo de nombres

Registrando un info y un warning con cada librería, y leyendo lo que quedó. El base de pino está puesto al desplegable en vez de dejarlo por defecto, que es la primera recomendación de abajo y además mantiene el nombre de la máquina fuera de cada línea:

{"level":30,"time":1790954578827,"service":"checkout","version":"2.4.1","orderId":"ord-1","msg":"info line"}
{"level":40,"time":1790954578828,"service":"checkout","version":"2.4.1","orderId":"ord-1","msg":"warn line"}

{"@t":"2026-10-02T15:16:23.5838758Z","@mt":"info line {OrderId}","OrderId":"ord-1"}
{"@t":"2026-10-02T15:16:23.6023060Z","@mt":"warn line {OrderId}","@l":"Warning","OrderId":"ord-1"}

Pino escribe un número. Serilog escribe un nombre. Hasta ahí es una tabla de equivalencias en el recolector.

Lo que pilla a la gente es la primera línea de Serilog: no hay @l por ningún lado. El JSON compacto omite el nivel cuando es Information, porque es el valor implícito. Así que un panel que filtre level = "Information" no devuelve nada de tus servicios .NET —no pocos resultados, ninguno— mientras que level >= 40 no devuelve nada de los de Node. Normaliza los dos en el recolector, y trata el campo ausente como Information en vez de como algo que no se pudo interpretar.

Acuerda esos seis y podrás hacerle una pregunta a toda la flota. Sáltatelo y tendrás una forma muy rápida de producir JSON que nadie puede consultar.

Cuándo usar qué

Registra estructurado desde la primera línea de un servicio nuevo. Cuesta un 9% en Node y en .NET es más barato que el texto renderizado. No hay un umbral a partir del cual empiece a valer la pena; solo está la migración que te tocará hacer después.

Deja el destino en síncrono hasta que midas que duele. Es la única configuración que no puede perder datos en silencio, y sobre un disco local su media está en microsegundos de un dígito. Renuncia a eso a propósito, no por copiar un fragmento de configuración.

Si te vas a asíncrono, haz visible la pérdida. blockWhenFull: true en Serilog, un vaciado al salir en Node, y la profundidad de la cola como métrica. Un sink asíncrono sin contador de eventos descartados es un sistema que te miente justo bajo la carga que te importa.

No registres en debug en producción confiando en que el nivel te salve: solo te salva de la escritura, no de construir el payload. Protege las llamadas caras.

Regla práctica: el costo del logging estructurado son bytes, no CPU. Presupuesta almacenamiento, mide el destino, y que un búfer no sea nunca la única copia de algo que ibas a necesitar.

Puntos clave

La estructura cuesta alrededor de un 9% de CPU y 1,8× los bytes. En .NET, el sink JSON de Serilog es más rápido que el de texto renderizado —6.081 ns contra 7.888 ns— así que el formato legible para humanos es el caro.
WriteTo.Async duplicó el rendimiento descartando 121.744 de 202.000 líneas. Su valor por defecto es descartar cuando la cola se llena, en silencio. Con blockWhenFull: true lo conserva todo y va más lento que no poner el envoltorio.
Un destino con búfer traslada el costo a tu heap. Contra un destino de 2 ms, el llamador se quedó en 1,9 µs mientras la memoria residente crecía 16,2 MB — y un cierre abrupto dejó 1 de 50.000 líneas en disco.
Una llamada de debug descartada es gratis con un payload plano (83 ns) y cuesta más que un log real con uno caro (10.047 ns). Protege las del segundo tipo; la protección en las del primero es ruido.
Censurar al enmascarar es más rápido que no enmascarar — pero un comodín borra customer.id y payment.last4 junto con los datos personales, que son los dos campos que hacían valiosa la línea. Nombra las rutas.

Lo que sigue en esta línea: trazado distribuido con OpenTelemetry — instrumentar a través de los límites de proceso, y la pregunta sobre muestreo de cola que planteó un lector en el artículo anterior, que el muestreo de cabecera no puede responder.

Pino and Serilog, Measured: The Async Sink Is Fast Because It Drops Lines

Juan Gómez — Tue, 06 Oct 2026 14:00:00 +0000

Pino and Serilog, Measured: The Async Sink Is Fast Because It Drops Lines

Aurora Coffee Co.'s checkout writes a structured log line for every order. I wanted to know what that costs, so I logged the same event 200,000 times through every sink configuration I could think of, on Node 24 and on .NET 10. Two lines of the Serilog run:

serilog -> compact JSON, sync           164 k/s  mean   6081 ns  p50  4500  p99  28400  max 46985500
serilog -> compact JSON, async          331 k/s  mean   3017 ns  p50  1000  p99   4000  max 19268600

Wrapping the sink in WriteTo.Async doubled throughput and cut the p99 by a factor of seven. That is the result everyone quotes, and it is the reason the async wrapper is in nearly every Serilog configuration I have ever read.

Then I counted the lines that reached the file:

file                   lines        bytes   bytes/line   expected lines
serilog-async.log       80256   21,047,885          262           202000   <-- MISMATCH
serilog-json.log       202000   53,009,780          262           202000

121,744 log lines did not exist. No exception, no warning, no counter anywhere in the application. The async sink was twice as fast because it was doing a little over a third of the work.

This post is what the rest of that benchmark found: what structure actually costs (less than you think), what the sink costs (more than you think), and which of the two defaults in front of you is quietly lossy.

The setup, so the numbers mean something

Every number below comes from one harness per runtime, logging the same event — an order with five fields — 200,000 times after a 2,000-iteration warm-up. Each call is timed individually with process.hrtime.bigint() on Node and Stopwatch.GetTimestamp() on .NET, so the tail is real rather than derived from a total.

Two details matter more than they look.

The loop yields. My first Node run had the buffered sink coming out slower than the synchronous one, which is impossible. The cause was the benchmark, not the sink: a tight synchronous loop never returns to the event loop, so a buffered destination can never drain and simply accumulates — 40MB of it. Yielding every 1,000 iterations fixed it. If your logging benchmark shows buffering making things worse, this is why.

The line counts are verified. Every harness finishes by counting the lines in each file and comparing against what it logged. That check is the only reason this post exists; without it, the Serilog async result reads as a clean win.

// bench.ts — the shape of each measurement
const N = Number(process.argv[2] ?? 200_000);
const WARMUP = 2_000;
const YIELD_EVERY = 1_000;

const tick = () => new Promise<void>((resolve) => setImmediate(resolve));

async function measure(name: string, run: (i: number) => void, flush?: () => void): Promise<void> {
  for (let i = 0; i < WARMUP; i += 1) run(i);
  await tick();

  const samples = new Float64Array(N);
  let busy = 0;
  for (let i = 0; i < N; i += 1) {
    const t0 = process.hrtime.bigint();
    run(i);
    const dt = Number(process.hrtime.bigint() - t0);
    samples[i] = dt;
    busy += dt;
    // Without this the event loop never runs and a buffered sink cannot drain.
    if (i % YIELD_EVERY === YIELD_EVERY - 1) await tick();
  }
  flush?.();

  const sorted = Float64Array.from(samples).sort();
  const at = (q: number) => sorted[Math.min(sorted.length - 1, Math.ceil(q * sorted.length) - 1)];
  const mean = samples.reduce((a, b) => a + b, 0) / samples.length;

  console.log(
    `${name.padEnd(36)} ${(N / (busy / 1e9) / 1000).toFixed(0).padStart(6)} k/s  ` +
      `mean ${mean.toFixed(0).padStart(6)} ns  p50 ${at(0.5).toFixed(0).padStart(5)}  ` +
      `p99 ${at(0.99).toFixed(0).padStart(6)}  max ${at(1).toFixed(0).padStart(8)}`,
  );
}

Hardware is a laptop, not a server, so read the ratios rather than the absolute rates.

What structure actually costs

The fear is that JSON serialization is expensive compared to writing a string. Here is the Node run, all six configurations, verbatim:

node v24.16.0   pino 10.3.1   N=200000 (+2000 warm-up)

string concat, writeSync                211 k/s  mean   4733 ns  p50  3700  p99  16400  max  1070300
pino, sync destination                  193 k/s  mean   5181 ns  p50  4400  p99  19400  max  1035400
pino, buffered destination              176 k/s  mean   5694 ns  p50  5100  p99  18700  max   931400
debug at level=info, plain payload    12068 k/s  mean     83 ns  p50   100  p99    300  max   263800
debug at level=info, costly payload     100 k/s  mean  10047 ns  p50  7900  p99  26400  max  1240800
debug guarded by isLevelEnabled       10295 k/s  mean     97 ns  p50   100  p99    300  max    56300

file                   lines        bytes   bytes/line   expected lines
pino-buffered.log      202000   41,091,780          203           202000
pino-quiet.log              0            0            0                0
pino-sync.log          202000   41,091,780          203           202000
text-sync.log          202000   22,709,780          112           202000

all files complete

Structured logging costs 9%. 5,181ns against 4,733ns for building the equivalent string by hand and writing it to the same file descriptor. That is the entire serialization penalty, and it buys you a line a machine can filter instead of one a regex has to guess at.

The .NET side is less flattering and more interesting:

string interpolation, AutoFlush         302 k/s  mean   3313 ns  p50  2600  p99  13200  max   695200
serilog template -> text file           127 k/s  mean   7888 ns  p50  5700  p99  31000  max  3345300
serilog -> compact JSON, sync           164 k/s  mean   6081 ns  p50  4500  p99  28400  max 46985500

Serilog's text sink is slower than its JSON sink — 7,888ns against 6,081ns. Rendering a message template into a human sentence costs more than emitting the structured document, because rendering means formatting every property into the middle of a string, while the JSON formatter writes the values where they already are. The readable format is the expensive one. If you have been keeping a text sink because JSON "must be heavier", that is backwards.

What is not free is the bytes:

	bytes per line	relative
text, Node	112	1.0×
JSON, Node (pino)	203	1.8×
text, .NET	117	1.0×
rendered template, .NET	176	1.5×
compact JSON, .NET (Serilog)	262	2.2×

That is the real bill, and it is not CPU. At a thousand lines a second, pino's extra 91 bytes per line is 7.9GB a day of storage and ingest you did not have before — 86.4 million lines times 91 bytes. Every hosted log product prices on exactly that number.

The sink, where the actual money is

A logger does two things: turn an event into bytes, and get those bytes somewhere. The first is what benchmarks measure. The second is what wakes you up.

Synchronous

The write happens on the calling thread. Your request waits for the disk. On a local SSD with the page cache in front of it that is usually fine — and sometimes it is not:

serilog -> compact JSON, sync           164 k/s  mean   6081 ns  p50  4500  p99  28400  max 46985500

The mean is 6µs. The maximum is 47 milliseconds, for a single log call. That is one request, somewhere in those 200,000, that spent a twentieth of a second inside Log.Information. Nothing in the code is slow; the operating system decided to flush, and the caller paid for it. Synchronous sinks put the storage tail onto your request tail, and a mean will never show it to you.

Buffered, Node style

Pino's buffered destination hands the bytes to an internal buffer and returns. I pointed it at a sink that takes 2ms per flush — a loaded log shipper, a network volume, a disk under pressure — and logged 20,000 lines:

sink: 2ms per flush, 20000 lines logged
  caller p50           1900 ns
  caller p99          14500 ns
  caller max        1071900 ns
  flushes done             21
  RSS at start         57.5 MB
  RSS peak             73.7 MB
  RSS growth           16.2 MB

The caller never waited — a p50 of 1.9µs against a sink taking two milliseconds per flush. Twenty-one flushes completed in the time it took to log twenty thousand lines, and resident memory grew 16.2MB. The backlog did not disappear; it is sitting in the heap waiting for a sink that is not keeping up.

This is the trade, stated plainly: a buffered sink does not make the write cheaper, it makes the write someone else's problem later, and "later" is held in your process memory. If the sink stays slow, you do not get a latency alert. You get an out-of-memory kill, which is a much worse way to find out.

And when the process dies

The reason you are logging at all is usually that something went wrong. So I logged 50,000 lines to a buffered pino destination and killed the process the way processes actually die — no flush, no shutdown handler:

lines logged       50000
lines on disk          1
lost               49999  (100.0%)

One line. The buffer is in the dead process's memory, and the file has what happened to be flushed before it died. A process.on('exit') handler calling flushSync() closes most of this, and SIGKILL and a hard crash close it right back open.

Asynchronous, .NET style

WriteTo.Async puts a bounded queue and a background thread between your code and the sink. The default queue is 10,000 events, and the default behaviour when that queue is full is to drop. Here are all three Serilog sink configurations side by side, from the same run:

serilog -> compact JSON, sync           164 k/s  mean   6081 ns  p50  4500  p99  28400  max 46985500
serilog -> compact JSON, async          331 k/s  mean   3017 ns  p50  1000  p99   4000  max 19268600
serilog -> JSON, async blockWhenFull    122 k/s  mean   8220 ns  p50  3700  p99  38700  max 23037300

And the line counts for those three files:

serilog-async-block.log   202000   53,009,780          262           202000
serilog-async.log          80256   21,047,885          262           202000   <-- MISMATCH
serilog-json.log          202000   53,009,780          262           202000

Read those two blocks together and the picture inverts:

configuration	throughput	lines kept
sync	164 k/s	202,000
async, default	331 k/s	80,256
async, `blockWhenFull: true`	122 k/s	202,000

The async sink that keeps your data is slower than having no async sink at all. 122 k/s against 164 k/s — the queue, the hand-off and the context switch cost more than they save once you stop letting it discard the overflow. The configuration everybody copies is the middle row, and the middle row lost 60% of the events.

One honest caveat on that number: this benchmark hammers the logger in a tight loop, far harder than a real service ever will, so a production queue drains between requests and drops nothing most of the time. The point is not "60% of your logs are missing". The point is that the drop is silent and unmeasured, so the one time it matters — an incident, a retry storm, the burst you most want logged — you will not know it happened. If you run WriteTo.Async, set blockWhenFull: true and accept the latency, or wire up its monitor callback so the queue depth is a metric you can see.

Levels: the call you thought was free

A disabled log call still evaluates its arguments. The object is built, the string is interpolated, the stack is captured — and only then does the logger decide to throw it away.

How much that costs depends entirely on the payload, and the two cases are four orders of magnitude apart:

debug at level=info, plain payload    12068 k/s  mean     83 ns   (pino)
debug at level=info, costly payload     100 k/s  mean  10047 ns   (pino)
debug guarded by isLevelEnabled       10295 k/s  mean     97 ns   (pino)

debug at Information, plain payload   37351 k/s  mean     27 ns   (serilog)
debug at Information, costly payload     77 k/s  mean  12981 ns   (serilog)
debug guarded by IsEnabled            55574 k/s  mean     18 ns   (serilog)

With a plain object, a discarded debug call costs 83ns on pino and 27ns on Serilog — free, for any purpose. Guarding it with isLevelEnabled changes nothing; pino comes out at 97ns guarded versus 83ns unguarded, which is noise in the wrong direction.

With a payload that costs something to build — here a captured stack trace — the same discarded call costs 10,047ns on pino and 12,981ns on Serilog. That is twice the price of an enabled log line that actually gets written. Guarded, it drops to 97ns and 18ns.

So the advice "always guard your debug calls" and the advice "never bother, the logger is fast" are both wrong, and the rule is mechanical:

Guard a disabled-level call when, and only when, building its arguments does real work. A serialized object, a JSON.stringify, a stack trace, a database lookup for a friendly name, a string.Join over a collection. If the payload is fields you already have, the guard is clutter.

The .NET numbers come with an extra note: Serilog's message templates mean the formatting is deferred automatically, which is why its plain-payload case is three times cheaper than pino's. What is not deferred is the argument expression itself. Log.Debug("{Trace}", new StackTrace().ToString()) builds the stack trace whether or not anybody wants it.

Redaction, which is where the PII went

The entire value of structured logging is that you log the object instead of a sentence about it. Which means that sooner or later you log the customer:

{"customer":{"id":"cus-5521","email":"ana.morales@example.com","phone":"+505-5555-0188","address":{"line1":"Reparto San Juan 120","city":"Managua","country":"NI"}},"payment":{"brand":"visa","last4":"4242","token":"tok_live_9f2b61ac"}}

Pino's redact option takes paths and either censors or removes them. I measured four configurations against the same nested payload:

no redaction                          119 k/s  mean  8406 ns  p99  24900
redact: 4 paths, censored             137 k/s  mean  7284 ns  p99  19800
redact: 4 paths, removed              100 k/s  mean 10032 ns  p99  31000
redact: wildcard on two objects       110 k/s  mean  9120 ns  p99  26700

Censoring is faster than not redacting at all — 7,284ns against 8,406ns — because [redacted] is shorter than an address, so there is less JSON to write. Redaction is not a cost you are weighing against safety. It is free, and in the common case it is negative.

remove: true is the slower option at 10,032ns, because deleting keys costs more than overwriting values. Prefer censoring unless an empty key would break a downstream parser.

And then the trap, which is why the output of each configuration is worth printing rather than trusting:

redact-paths.log
  customer: {"id":"cus-5521","email":"[redacted]","phone":"[redacted]","address":"[redacted]"}
  payment : {"brand":"visa","last4":"4242","token":"[redacted]"}
redact-wildcard.log
  customer: {"id":"[redacted]","email":"[redacted]","phone":"[redacted]","address":"[redacted]"}
  payment : {"brand":"[redacted]","last4":"[redacted]","token":"[redacted]"}

The wildcard version — customer.* and payment.*, the configuration you write when you are in a hurry and want to be safe — redacted customer.id and payment.last4 as well. Those are not PII; they are the two fields that make the log line useful. A support engineer can find an order with cus-5521. They cannot find anything with [redacted].

Name the paths. On the .NET side the equivalent is a Destructure.ByTransforming<T>() policy on the logger configuration, which has the same property: be specific, or you will erase your own correlation keys.

The fields worth agreeing on

None of this matters if two services call the same thing by different names. Queries across services are the whole point, and they break on vocabulary, not on volume. The short list that earns its place:

service and version — which deployable, and which build. The second one answers "did this start with the release?" without a guess.
trace_id and span_id — the join to your traces. Both loggers attach them automatically under OpenTelemetry; the previous post in this thread covers the wiring and the loader hook that silently prevents it.
A normalized level — the two loggers disagree about it twice over, which is the next section.
One domain identifier per event — order_id, not id. A field called id in four services is four different things in one index.
error.type and error.stack as separate fields, never a formatted string. The type is what you group by; the stack is what you read afterwards.

The level field is worse than a naming disagreement

Logging an info and a warning through each library, and reading back what landed. Pino's base is set to the deployable rather than left at its default, which is the first fix below and also keeps the machine's hostname out of every line:

{"level":30,"time":1790954578827,"service":"checkout","version":"2.4.1","orderId":"ord-1","msg":"info line"}
{"level":40,"time":1790954578828,"service":"checkout","version":"2.4.1","orderId":"ord-1","msg":"warn line"}

{"@t":"2026-10-02T15:16:23.5838758Z","@mt":"info line {OrderId}","OrderId":"ord-1"}
{"@t":"2026-10-02T15:16:23.6023060Z","@mt":"warn line {OrderId}","@l":"Warning","OrderId":"ord-1"}

Pino writes a number. Serilog writes a name. That much is a mapping table at the collector.

The part that catches people is the first Serilog line: there is no @l at all. Compact JSON omits the level when it is Information, because that is the implicit default. So a dashboard filtering level = "Information" returns nothing from your .NET services — not few results, none — while level >= 40 returns nothing from the Node ones. Normalize both at the collector, and treat a missing level field as Information rather than as unparseable.

Agree on those six and you can ask a question across the whole fleet. Skip it and you have a very fast way to produce JSON nobody can query.

When to reach for what

Log structured from the first line of a new service. It costs 9% on Node and is actually cheaper than rendered text on .NET. There is no threshold at which it starts being worth it; there is only the migration you will have to do later.

Keep the sink synchronous until you have measured that it hurts. It is the only configuration that cannot silently lose data, and on a local disk its mean is single-digit microseconds. Trade that away deliberately, not by copying a configuration snippet.

If you go async, make the loss visible. blockWhenFull: true in Serilog, a flush on exit in Node, and the queue depth as a metric. An async sink without a dropped-events counter is a system that lies to you under exactly the load you care about.

Do not log at debug in production and rely on the level to save you — it only saves you from the write, not from building the payload. Guard the expensive ones.

Rule of thumb: the cost of structured logging is bytes, not CPU. Budget storage, measure the sink, and never let a buffer be the only copy of something you needed.

Key Takeaways

Structure costs about 9% of CPU and 1.8× the bytes. On .NET, Serilog's JSON sink is faster than its rendered-text sink — 6,081ns against 7,888ns — so the human-readable format is the expensive one.
WriteTo.Async doubled throughput by dropping 121,744 of 202,000 lines. Its default is to discard on a full queue, silently. With blockWhenFull: true it keeps everything and runs slower than no async wrapper at all.
A buffered sink moves the cost into your heap. Against a 2ms sink, the caller stayed at 1.9µs while RSS grew 16.2MB — and a hard exit left 1 of 50,000 lines on disk.
A disabled debug call is free with a plain payload (83ns) and costs more than a real log line with an expensive one (10,047ns). Guard the second kind; the guard on the first kind is noise.
Redaction by censoring is faster than not redacting — but a wildcard erases customer.id and payment.last4 along with the PII, which are the two fields that made the line worth keeping. Name the paths.

Coming next in this thread: distributed tracing with OpenTelemetry — instrumenting across service boundaries, and the tail-sampling question a reader raised on the last post, which head-based sampling cannot answer.

Logs, métricas y trazas no son tres pilares. Son una sola petición.

Juan Gómez — Thu, 01 Oct 2026 14:00:00 +0000

Logs, métricas y trazas no son tres pilares. Son una sola petición.

Aurora Coffee Co. tiene un checkout que llama a un servicio de precios y a uno de inventario. Le apunté un generador de carga — 1.000 órdenes, nada del otro mundo — y medí lo que de verdad esperó quien llamaba:

{
  "requests": 1000,
  "mean_ms": 23.9,
  "p50_ms": 4.2,
  "p95_ms": 8.7,
  "p99_ms": 856.4,
  "max_ms": 1758.7
}

La orden mediana tardó 4,2 milisegundos. Una tardó 1,76 segundos, cuatrocientas veces más, y el promedio de 23,9 ms no describe ninguna de las dos. No es la petición típica ni la mala. Es un número que no le corresponde a nada de lo que ocurrió.

Durante toda esa corrida los tres servicios escribieron sus logs con toda normalidad. Nada falló, nada reintentó, ninguna alerta se disparó. La única persona que sabía que algo andaba mal era el cliente viendo girar un spinner, y esa persona no abre un ticket: se va.

Este artículo trata de los tres tipos de telemetría que responden la pregunta que nadie podía responder en esa corrida — cuáles órdenes estuvieron lentas y por qué — y de por qué "los tres pilares de la observabilidad" es una mala forma de pensarlos. No son tres sistemas puestos uno al lado del otro. Son tres proyecciones de los mismos eventos, y lo que los vuelve útiles no es tenerlos los tres: es el identificador que te permite saltar de uno a otro.

El monitoreo responde preguntas que ya escribiste

La distinción que importa no es "logs contra métricas". Es esta:

El monitoreo responde preguntas que pensaste de antemano. ¿La CPU pasó del 80%? ¿La tasa de errores pasó del 1%? ¿Se está llenando el disco? Cada una de esas preguntas alguien la escribió, la convirtió en un chequeo y le colgó una alerta. Eso funciona y deberías tenerlo.

La observabilidad es poder responder preguntas que no pensaste de antemano, sin desplegar código nuevo para averiguarlo. "¿Por qué exactamente veinte peticiones estuvieron lentas esta tarde y qué tenían en común?" no es una pregunta para la que alguien haya escrito un chequeo. Si responderla exige agregar una línea de log y volver a desplegar, el sistema no es observable: es depurable, en algún momento, con permiso.

Esa es toda la medida. No "¿tenemos un dashboard?", sino "cuando pase algo raro, ¿podemos averiguar qué fue con datos que ya recolectamos?".

El sistema de prueba

Tres servicios pequeños en Node 24, para que cada número de este artículo sea reproducible y no un recuerdo. Checkout llama a precios y después a inventario:

{
  "name": "aurora-observability",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24" },
  "dependencies": {
    "@opentelemetry/api": "^1.9.1",
    "@opentelemetry/auto-instrumentations-node": "^0.80.0",
    "@opentelemetry/exporter-prometheus": "^0.222.0",
    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
    "@opentelemetry/sdk-node": "^0.222.0",
    "pino": "^10.3.1"
  }
}

Detrás hay tres contenedores de código abierto. Sin cuenta, sin API key y sin capa gratuita que se venza:

# docker-compose.yml
services:
  jaeger:
    image: jaegertracing/jaeger:2.21.0
    container_name: aurora-jaeger
    ports:
      - "16686:16686"   # la interfaz de trazas que vas a abrir
      - "4318:4318"     # OTLP sobre HTTP — a donde los servicios envían los spans

  prometheus:
    image: prom/prometheus:v3.15.0
    container_name: aurora-prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    extra_hosts:
      # Prometheus consulta. Los servicios corren en el host, no en esta red.
      - "host.docker.internal:host-gateway"

  grafana:
    image: grafana/grafana:13.2.2
    container_name: aurora-grafana
    ports:
      - "3030:3000"
    environment:
      GF_AUTH_ANONYMOUS_ENABLED: "true"
      GF_AUTH_ANONYMOUS_ORG_ROLE: Admin
    depends_on:
      - prometheus
      - jaeger

# prometheus.yml
global:
  scrape_interval: 5s

scrape_configs:
  - job_name: aurora
    static_configs:
      - targets:
          - host.docker.internal:9464   # checkout
          - host.docker.internal:9465   # precios
          - host.docker.internal:9466   # inventario

docker compose up -d

Un solo archivo arma toda la telemetría, y se carga con --import para que corra antes que cualquier código de la aplicación:

// telemetry.ts
import { register } from 'node:module';

// La instrumentación automática reescribe los módulos mientras se importan, y en ESM
// eso necesita un hook del cargador. Sin esta línea el SDK arranca igual y exporta
// igual: simplemente nunca ve node:http y nada queda correlacionado. Vuelvo a esto
// más abajo.
register('@opentelemetry/instrumentation/hook.mjs', import.meta.url);

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';

const sdk = new NodeSDK({
  serviceName: process.env.OTEL_SERVICE_NAME ?? 'unnamed-service',
  // Las trazas se envían a Jaeger por OTLP.
  traceExporter: new OTLPTraceExporter({
    url: `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? 'http://localhost:4318'}/v1/traces`,
  }),
  // Las métricas se consultan: esto abre /metrics para que Prometheus lo lea.
  metricReader: new PrometheusExporter({ port: Number(process.env.METRICS_PORT ?? 9464) }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => {
    // Vacía lo que quedó en el lote pendiente. Si no, los últimos spans antes de un
    // despliegue — que suelen ser los interesantes — nunca salen del proceso.
    void sdk.shutdown().finally(() => process.exit(0));
  });
}

OTEL_SERVICE_NAME=pricing   METRICS_PORT=9465 node --import ./telemetry.ts pricing.ts
OTEL_SERVICE_NAME=inventory METRICS_PORT=9466 node --import ./telemetry.ts inventory.ts
OTEL_SERVICE_NAME=checkout  METRICS_PORT=9464 node --import ./telemetry.ts checkout.ts

Node 24 ejecuta esos archivos TypeScript directamente, y por eso aquí no hay paso de compilación ni tsx. Fíjate en el .ts explícito de --import ./telemetry.ts: Node resuelve el archivo real, no reescribe el especificador por ti.

La parte interesante del servicio de precios es que las promociones se evalúan por SKU y se guardan en caché, y los SKU de temporada tienen doscientas veces más reglas de promoción que las mezclas de la casa:

// pricing.ts (la parte que importa)
const cache = new Map<string, number>();

function ruleCountFor(sku: string): number {
  return sku.startsWith('seasonal-') ? 2400 : 12;
}

tracer.startActiveSpan('pricing.quote', (span) => {
  span.setAttribute('aurora.sku', sku);

  const cached = cache.get(sku);
  if (cached !== undefined) {
    span.setAttribute('aurora.cache_hit', true);
    span.end();
    respond(cached);
    return;
  }

  span.setAttribute('aurora.cache_hit', false);

  const priced = tracer.startActiveSpan('pricing.evaluate_rules', (inner) => {
    inner.setAttribute('aurora.rule_count', ruleCountFor(sku));
    const value = evaluateRules(sku);
    inner.end();
    return value;
  });

  cache.set(sku, priced);
  log.warn({ sku, rule_count: ruleCountFor(sku) }, 'priced on a cold cache');
  span.end();
  respond(priced);
});

Nadie escribió un bug. Hay una caché, funciona, y 977 de las 1.000 peticiones dieron con ella. Ese es justamente el punto: en producción las fallas interesantes casi nunca son errores de código, son distribuciones.

Logs: qué pasó, contado por un solo proceso

Un log es un evento con marca de tiempo, emitido por un proceso, que describe algo que hizo. Es la señal más antigua y sigue siendo la más detallada: es el único lugar donde vive el motivo.

La primera mejora no tiene nada que ver con herramientas de observabilidad y además es gratis. Deja de redactar oraciones y empieza a emitir objetos:

// Antes: la información está, pero solo una persona puede extraerla
console.log(`precio de ${sku} con caché fría y ${rules} reglas`);

// Después: el mismo evento, ahora consultable
log.warn({ sku, rule_count: rules }, 'priced on a cold cache');

{"level":40,"time":1790347139632,"service":"pricing","sku":"seasonal-19","rule_count":2400,"msg":"priced on a cold cache"}

La diferencia no es estética. A la primera versión solo puedes hacerle grep, así que "muéstrame los precios calculados con caché fría donde el número de reglas pasó de mil, agrupados por SKU" significa escribir una expresión regular contra una frase que cualquier compañero puede reescribir mañana. La segunda es un filtro sobre dos campos. Pino escribe esa forma por defecto; Serilog hace lo mismo en .NET.

Ahora, lo que los logs no pueden hacer, que es la razón de que existan las otras dos señales. Bajo carga, esos tres servicios producen líneas como estas, todas a la vez:

{"time":1790347137929,"service":"checkout","sku":"house-blend-1kg","ms":3,"msg":"checkout complete"}
{"time":1790347137934,"service":"checkout","sku":"decaf-250g","ms":4,"msg":"checkout complete"}
{"time":1790347137938,"service":"checkout","sku":"espresso-500g","ms":3,"msg":"checkout complete"}
{"time":1790347139632,"service":"pricing","sku":"seasonal-19","rule_count":2400,"msg":"priced on a cold cache"}
{"time":1790347139695,"service":"checkout","sku":"seasonal-19","ms":1755,"msg":"checkout complete"}

Cada línea es cierta. Cada línea está estructurada. Y no hay forma confiable de afirmar que la línea de precios y la de checkout que sigue pertenecen a la misma orden. Parecen relacionadas porque el SKU coincide y las marcas de tiempo están a 63 ms — pero eso es una suposición, y con concurrencia real es una suposición equivocada. Diez clientes pidiendo la misma mezcla de temporada en el mismo segundo producen diez pares indistinguibles. Los logs describen eventos de un proceso a la vez; una petición que cruza tres procesos no tiene dueño en ese modelo.

Ahí está el hueco. No es falta de detalle — de eso los logs tienen de sobra. Es falta de identidad.

Trazas: una petición, en todos los procesos que tocó

Una traza (trace) es el recorrido de una petición. Está hecha de spans, y un span es una operación con nombre, duración y padre. El árbol que sale de ahí es lo que una traza es: no una lista de marcas de tiempo, sino una estructura causal — esta llamada ocurrió a causa de aquella, y dentro de su tiempo de vida.

Dos cosas hacen que eso funcione al cruzar la red. Cada span lleva el identificador de la traza, y el cliente HTTP inyecta ese identificador en una cabecera traceparent de salida, que el siguiente servicio vuelve a leer. Ese es todo el mecanismo del trazado distribuido, y por eso el identificador es lo que vale la pena cuidar.

Esta es la petición más lenta de la corrida de 1.000 órdenes, dibujada como árbol. Cada fila es el nombre, la duración y el servicio de un span; la columna de atributos está recortada a las dos URL de salida, que es de donde salen:

trace 4eef76aeccdbd0f961d78dc7e4241092  (8 spans)

GET                            1756.1 ms  [checkout]
  checkout                     1755.6 ms  [checkout]
    GET                        1752.2 ms  [checkout]   -> localhost:3001/price
      GET                      1692.3 ms  [pricing]
        pricing.quote          1691.4 ms  [pricing]
          pricing.evaluate_rules  1690.7 ms  [pricing]
    GET                           1.6 ms  [checkout]   -> localhost:3002/reserve
      GET                         0.4 ms  [inventory]

Lee los números de arriba abajo. De 1.756 milisegundos, 1.690,7 se fueron dentro de pricing.evaluate_rules: el 96% de la petición en un solo span, cuatro niveles adentro, en un proceso distinto de aquel con el que hablaba el cliente. Inventario, que es el servicio del que todos sospechan primero porque toca una base de datos, respondió en cuatro décimas de milisegundo.

Nada de ese árbol está inferido. Cada span anidado está dentro de su padre porque llevaba encima el identificador del padre, no porque las marcas de tiempo se traslapen.

Y ahora la unión que los logs no podían hacer solos, porque el SDK agrega el identificador de la traza activa en cada línea escrita dentro de un span:

{"level":40,"time":1790347139632,"service":"pricing","trace_id":"4eef76aeccdbd0f961d78dc7e4241092","span_id":"b56f30e5561dd16d","trace_flags":"01","sku":"seasonal-19","rule_count":2400,"msg":"priced on a cold cache"}
{"level":30,"time":1790347139695,"service":"checkout","trace_id":"4eef76aeccdbd0f961d78dc7e4241092","span_id":"2dafc950aac40ac6","trace_flags":"01","sku":"seasonal-19","ms":1755,"msg":"checkout complete"}

Son las mismas dos líneas de antes. Tres campos más, y "parecen relacionadas" se convierte en "son la misma petición". Deja ahí trace_flags: el 01 significa que esta traza se conservó y de verdad está en Jaeger. Una línea con 00 lleva un identificador que no conduce a ninguna parte, y la sección de muestreo del final es donde eso empieza a importar. Pega ese identificador en tu buscador de logs y obtienes todas las líneas que cualquier servicio escribió sobre esa orden; pégalo en Jaeger y obtienes el árbol de arriba. Ese es el puente, y es la razón para que te importe el trazado aunque nunca abras una interfaz de cascada.

Ese campo no lo escribes tú. @opentelemetry/instrumentation-pino, que getNodeAutoInstrumentations() activa por ti, agrega trace_id, span_id y trace_flags a toda línea de Pino emitida dentro de un span activo. El logger se queda en tres líneas:

// logger.ts
import pino from 'pino';

export const log = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  base: { service: process.env.OTEL_SERVICE_NAME ?? 'unnamed-service' },
});

Métricas: con qué frecuencia y qué tan grave

Una traza describe una petición. Esa es su fuerza y también todo su límite: no puedes mirar 1.000 trazas y formarte una opinión, y en producción ni siquiera vas a tenerlas todas.

Una métrica es un número agregado en el tiempo y agrupado por un conjunto pequeño de etiquetas. Checkout registra una:

const duration = meter.createHistogram('checkout.duration', {
  description: 'End-to-end checkout latency',
  unit: 'ms',
});

duration.record(elapsed, {
  route: '/checkout',
  outcome: reservation.reserved ? 'ok' : 'rejected',
});

Un histograma no guarda tus mediciones. Guarda cuántas cayeron en cada bucket, y por eso es lo bastante barato como para conservarlo para siempre. Esta es la lectura real después de la corrida, recortada: cada línea lleva además otel_scope_name="aurora.checkout", y faltan los buckets le="0", 50, 75, 250, 5000, 7500, 10000 y +Inf:

checkout_duration_count{route="/checkout",outcome="ok"} 1001
checkout_duration_sum{route="/checkout",outcome="ok"} 22441.000499999976
checkout_duration_bucket{route="/checkout",outcome="ok",le="5"} 910
checkout_duration_bucket{route="/checkout",outcome="ok",le="10"} 972
checkout_duration_bucket{route="/checkout",outcome="ok",le="25"} 976
checkout_duration_bucket{route="/checkout",outcome="ok",le="100"} 979
checkout_duration_bucket{route="/checkout",outcome="ok",le="500"} 981
checkout_duration_bucket{route="/checkout",outcome="ok",le="750"} 988
checkout_duration_bucket{route="/checkout",outcome="ok",le="1000"} 995
checkout_duration_bucket{route="/checkout",outcome="ok",le="2500"} 1001

Los buckets son acumulativos, así que léelos como una escalera. 910 de 1.001 peticiones terminaron en 5 ms o menos. 981 terminaron en menos de medio segundo, lo que significa que 20 peticiones, el 2% del tráfico, tardaron más que eso, y 6 de ellas pasaron del segundo. (El conteo es 1.001 y no 1.000 porque checkout también midió la petición de calentamiento; esta es la visión que el servidor tiene de su propia latencia, no la del generador de carga.)

Ese dato es justo lo que ninguna traza te puede dar. Una traza demuestra que una petición estuvo lenta; el histograma dice cuánto de tu tráfico vive allá afuera, que es la diferencia entre "se quejó un cliente" y "una orden de cada cincuenta es inservible".

También deja ver por qué sum / count — 22.441 entre 1.001, o sea 22,4 ms — es el número menos útil de la página. Es el promedio de 910 peticiones de 5 ms y 20 peticiones de un segundo, y no describe a ninguno de los dos grupos. Alerta sobre el promedio y te vas a enterar de una caída más o menos cuando tus clientes dejen de tener el problema.

También funciona al revés. Pregúntale al histograma cuáles peticiones estuvieron lentas y no tiene nada: ahí no hay SKU, ni identificador de orden, ni cliente. Eso es a propósito, y la siguiente sección trata de lo que pasa cuando intentas arreglarlo.

Las tres juntas: ese 2% que importa

Este es el ciclo, y el orden no es decorativo.

Las métricas te dicen que hay un problema y qué tan grande es. El 2% de los checkouts por encima de 500 ms. Ese número salió de datos recolectados antes de que alguien estuviera mirando, y es lo bastante barato como para guardarlo un año, así que también puedes ver que empezó el martes.

Las trazas te dicen a dónde se fue el tiempo. Abre una lenta y el 96% está dentro de pricing.evaluate_rules. Ya sabes el servicio, la función, y que la red y el inventario son inocentes, sin haber leído una línea de código.

Los logs te dicen por qué. La línea marcada con ese mismo identificador de traza dice rule_count: 2400 y priced on a cold cache. Esa es la causa, en el vocabulario de la propia aplicación: este SKU tiene 2.400 reglas de promoción y su entrada en caché no estaba.

Métricas sin trazas te deja un número sobre el que no puedes actuar. Trazas sin métricas te deja una anécdota. Cualquiera de las dos sin logs te deja una ubicación sin explicación. Y las tres sin un identificador compartido te dejan tres dashboards y una reunión.

Los atributos del span cierran el caso. pricing.quote lleva aurora.cache_hit, así que "¿esto solo pasa con la caché fría?" es un filtro sobre spans y no una hipótesis. En toda la corrida, incluida la petición de calentamiento: 24 fallos de caché contra 977 aciertos, y todas las peticiones lentas fueron fallos.

Tres tropiezos que me costaron una tarde cada uno

1. En ESM el SDK arranca bien y no correlaciona nada

Borra la línea register(...) de telemetry.ts y todo sigue arrancando. Sin error, sin advertencia, y los spans siguen llegando a Jaeger. Misma carga, mismo código, esto es lo que sale:

con el hook del cargador           sin él
------------------------------------------------------------------
checkout   1 identificador         checkout   su propio identificador
pricing    el mismo                pricing    uno distinto
inventory  el mismo                inventory  ningún span
8 spans en un solo árbol           dos fragmentos sin relación
trace_id en cada línea de log      ninguna línea con trace_id

La instrumentación automática funciona reescribiendo módulos cuando se cargan. En CommonJS engancha require; en ESM necesita un hook del cargador registrado antes del primer import de cualquier cosa instrumentada. Sin eso node:http nunca queda parcheado, el lado servidor nunca lee la cabecera traceparent entrante, cada servicio empieza su propia traza y la instrumentación de Pino tampoco se engancha. Es exactamente el estado de "tres flujos de logs desconectados" del inicio de este artículo, solo que ahora además estás pagando por guardar spans.

Los spans manuales siguen funcionando, y eso es lo que lo vuelve tan silencioso. Solo lo vas a notar si miras dos servicios y encuentras dos identificadores de traza distintos para una misma petición.

2. Un campo es gratis en un span y carísimo en una métrica

aurora.sku como atributo de span no cuesta nada: un span es un evento, lleva sus propios campos, y las dos docenas de SKU de la corrida fueron dos docenas de valores repartidos en sus propios spans.

Pon ese mismo campo en el histograma y deja de ser un campo. Cada combinación distinta de etiquetas es una serie temporal aparte, y un histograma expone dieciocho líneas por serie. Medido sobre el exportador real:

etiquetas                                    series esperadas   series reales
------------------------------------------------------------------------------
route + outcome                                          6        6  (108 líneas)
route + outcome + customer_id (1.000 ids)            6.000    2.000  (36.000 líneas)

La lectura pasó de un par de kilobytes a 4,4 MB. Pero mira la columna de la derecha, porque el daño real es lo que nadie espera: el SDK limita cada métrica a 2.000 conjuntos de atributos y mete en silencio todo lo que pase de ahí en una sola serie.

checkout_duration_risky_count{otel_metric_overflow="true"} 4001

4.001 de 6.000 registros cayeron ahí. La métrica no se volvió cara: se volvió incorrecta, y la única señal es una etiqueta que la mayoría nunca ha visto.

La regla que te mantiene fuera de problemas: una etiqueta de métrica debe tener un conjunto pequeño y acotado de valores que podrías escribir hoy en una hoja. Ruta, estado, región, resultado. Nunca un identificador de usuario, ni uno de orden, ni un SKU de un catálogo abierto, ni una URL con un id adentro. El contexto de alta cardinalidad va en los spans y en las líneas de log, que es precisamente para lo que sirven.

3. Las trazas son la señal cara, y el muestreo no es opcional

Esas 1.000 peticiones produjeron siete spans cuando la caché acertó y ocho cuando falló: 7.032 en total. Sumando lo que recibió cada endpoint:

endpoint	envíos	bytes
`/v1/traces`	19	6.252.907
`/v1/logs`	28	166.783

No hay fila de /v1/metrics porque nunca se le envió nada. Prometheus consulta, así que las métricas no viajan por este camino — que es la línea más barata de cualquier presupuesto de telemetría.

Seis megabytes y cuarto de spans por mil checkouts. Son 889 bytes por span, unos 6,2 KB por petición, y treinta y siete veces el volumen de logs del mismo tráfico. Multiplica eso por el tráfico de producción y trazar cada petición deja de ser un valor por defecto y pasa a ser una línea del presupuesto.

La respuesta es el muestreo, y la versión que conviene saber ahora es: muestrea trazas completas, nunca spans sueltos, o vas a terminar con árboles incompletos. El SDK por defecto se queda con todo, y dos variables de entorno cambian eso sin tocar código:

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

Al abrir 2.000 spans con la configuración por defecto se conservaron 2.000; con esas dos variables se conservaron 201. El prefijo parentbased_ es lo que hace que funcione: la decisión se toma una sola vez en el primer servicio que recibe la petición, viaja en traceparent, y todos los servicios siguientes la respetan. Así obtienes el 10% de las trazas enteras, y no el 10% de los spans repartidos entre todas.

Las métricas se quedan al 100%, que es la otra mitad de por qué las quieres: tu p99 sigue siendo exacto aunque hayas perdido el 90% de las trazas.

Y aquí es donde esto se pone incómodo, porque el muestreo de cabecera choca con el ciclo que defendí en todo el artículo. La decisión se toma cuando entra la petición, antes de que nadie sepa si va a ser lenta. De los 20 checkouts por encima de 500 ms de esta corrida, un muestreo al 10% conserva unos 2 — y si la cola fuera más rara, digamos una petición de cada mil, el histograma te seguiría diciendo que el problema existe mientras en Jaeger no hay ninguna traza que abrir. Las métricas dicen con qué frecuencia, las trazas dicen dónde, y el muestreo echa los dados justo sobre las peticiones que fuiste a buscar.

Peor todavía: el identificador de traza existe se haya conservado la traza o no, así que una línea de log puede llevar un identificador que no conduce a nada. Para eso está trace_flags, y por eso se queda en el ejemplo de arriba: 01 se conservó, 00 no, y diez minutos buscando un árbol que nunca se envió son un error fácil de evitar.

La solución de verdad es decidir después de que la traza esté completa, no antes de que empiece: muestreo de cola, que implica un OpenTelemetry Collector entre tus servicios y Jaeger, conservando el 100% de las trazas que pasan de cierta latencia y el 100% de las que tienen error, más un porcentaje del resto. No sale gratis: el Collector tiene que guardar cada traza en memoria hasta decidir, y todos los spans de una misma traza tienen que llegar a la misma instancia, que es un problema de enrutamiento aparte. Eso da para un artículo propio y llega en esta serie. Mientras tanto, ten claro que un porcentaje fijo en la cabecera es un control de costo, no una respuesta a "encuéntrame la lenta".

Cuándo necesitas las tres y cuándo no

Empieza con logs estructurados y un histograma de latencia por punto de entrada. Un servicio solo con una base de datos ya obtiene con eso casi todo el valor. Una traza de una petición que nunca sale del proceso es un flame graph con pasos de más, y para eso un profiler funciona mejor.

Agrega trazado en cuanto una petición cruce un límite de proceso. Dos servicios y una cola ya bastan. Ese es el punto donde "cuál de los dos está lento" deja de poder responderse desde los logs, y no hay disciplina de logging que lo arregle: lo que falta es el identificador, no el detalle.

Agrega métricas antes de creer que las necesitas, porque son la única señal lo bastante barata como para conservarla un año con toda su fidelidad. No puedes volver atrás a preguntar cuál era el p99 del trimestre pasado si nadie estaba contando.

Déjalo en paz cuando el sistema es un cron, una CLI, o cualquier cosa donde la ejecución es la unidad de trabajo y la salida estándar ya cuenta la historia completa. Déjalo en paz también cuando no hay nadie de guardia: telemetría que nadie lee es un gasto con dashboard. Instrumentar es la mitad fácil; la difícil es que alguien tenga como trabajo mirarla.

Regla práctica: necesitas una traza cuando la respuesta a "¿a dónde se fue el tiempo?" vive en un proceso distinto del que atiende la petición.

Puntos clave

El monitoreo responde preguntas que escribiste de antemano; la observabilidad responde las que no. Si averiguarlo implica agregar una línea de log y volver a desplegar, tienes logging, no observabilidad.
Las tres señales son una misma petición vista de tres formas. Las métricas dicen con qué frecuencia y qué tan grave, las trazas dicen dónde, los logs dicen por qué. El identificador de traza es lo que las vuelve un solo sistema en vez de tres pestañas, y en ESM basta con perder una línea register(...) para quedarte sin él en silencio.
El promedio es el número menos informativo que vas a calcular. Una corrida con una mediana de 4,2 ms y un p99 de 856 ms promedia 23,9 ms, que no describe ninguna petición que haya ocurrido de verdad.
La cardinalidad es gratis en los spans y ruinosa en las métricas. El SDK de OpenTelemetry limita cada métrica a 2.000 conjuntos de atributos y agrupa todo lo demás dentro de otel_metric_overflow, así que una etiqueta customer_id no solo cuesta dinero: deja la métrica incorrecta.
Las trazas son la señal cara. Aquí 6,2 KB por petición, treinta y siete veces los logs. Muestrea trazas completas y deja las métricas al 100%: tus percentiles siguen exactos y tu factura no.

Lo que sigue en esta línea: logging estructurado en la práctica — cuánto cuestan de verdad Pino y Serilog bajo carga, y por qué "loguea todo como JSON y ya" se queda corto antes de lo que te gustaría.

Logs, Metrics and Traces Are Not Three Pillars. They're One Request.

Juan Gómez — Tue, 29 Sep 2026 14:00:00 +0000

Logs, Metrics and Traces Are Not Three Pillars. They're One Request.

Aurora Coffee Co. runs a checkout that calls a pricing service and an inventory service. I pointed a load generator at it — 1,000 orders, nothing exotic — and measured what the caller actually waited:

{
  "requests": 1000,
  "mean_ms": 23.9,
  "p50_ms": 4.2,
  "p95_ms": 8.7,
  "p99_ms": 856.4,
  "max_ms": 1758.7
}

The median order took 4.2 milliseconds. One of them took 1.76 seconds — four hundred times longer — and the mean, sitting at 23.9ms, reports neither. It is not the typical request and it is not the bad one. It is a number that describes nothing that happened.

Every service in that run logged happily throughout. Nothing errored, nothing retried, no alert fired. The only person who knew something was wrong was the customer staring at a spinner, and they did not file a ticket, they left.

This post is about the three kinds of telemetry that answer the question nobody in that run could answer — which orders were slow, and why — and about why "the three pillars of observability" is a bad way to think about them. They are not three systems standing side by side. They are three projections of the same events, and what makes them useful is not that you have all three — it is the ID that lets you jump between them.

Monitoring asks a question you already wrote down

The distinction that actually matters is not "logs vs metrics". It is this:

Monitoring answers questions you thought of in advance. Is the CPU above 80%? Is the error rate above 1%? Is the disk filling? Every one of those is a question somebody wrote down, turned into a check, and hung an alert on. That works, and you should have it.

Observability is the ability to answer questions you did not think of in advance — without shipping new code to find out. "Why were exactly twenty requests slow this afternoon, and what did they have in common?" is not a question anyone wrote a check for. If answering it requires adding a log line and redeploying, the system is not observable; it is debuggable, eventually, with permission.

That is the whole bar. Not "do we have a dashboard", but "when something weird happens, can we find out what, from data we already collected?"

The system under test

Three small Node 24 services, so every number in this post is reproducible rather than remembered. Checkout calls pricing, then inventory:

{
  "name": "aurora-observability",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24" },
  "dependencies": {
    "@opentelemetry/api": "^1.9.1",
    "@opentelemetry/auto-instrumentations-node": "^0.80.0",
    "@opentelemetry/exporter-prometheus": "^0.222.0",
    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
    "@opentelemetry/sdk-node": "^0.222.0",
    "pino": "^10.3.1"
  }
}

The backing stack is three open-source containers — no account, no API key, no free tier to age out:

# docker-compose.yml
services:
  jaeger:
    image: jaegertracing/jaeger:2.21.0
    container_name: aurora-jaeger
    ports:
      - "16686:16686"   # the trace UI you actually open
      - "4318:4318"     # OTLP over HTTP — where the services send spans

  prometheus:
    image: prom/prometheus:v3.15.0
    container_name: aurora-prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
    extra_hosts:
      # Prometheus pulls. The services run on the host, not inside this network.
      - "host.docker.internal:host-gateway"

  grafana:
    image: grafana/grafana:13.2.2
    container_name: aurora-grafana
    ports:
      - "3030:3000"
    environment:
      GF_AUTH_ANONYMOUS_ENABLED: "true"
      GF_AUTH_ANONYMOUS_ORG_ROLE: Admin
    depends_on:
      - prometheus
      - jaeger

# prometheus.yml
global:
  scrape_interval: 5s

scrape_configs:
  - job_name: aurora
    static_configs:
      - targets:
          - host.docker.internal:9464   # checkout
          - host.docker.internal:9465   # pricing
          - host.docker.internal:9466   # inventory

docker compose up -d

One file does all the telemetry wiring, and it is loaded with --import so that it runs before any application code:

// telemetry.ts
import { register } from 'node:module';

// Auto-instrumentation rewrites modules as they are imported, and under ESM that
// needs a loader hook. Without this line the SDK still starts and still exports —
// it just never sees node:http, so nothing correlates. More on that below.
register('@opentelemetry/instrumentation/hook.mjs', import.meta.url);

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';

const sdk = new NodeSDK({
  serviceName: process.env.OTEL_SERVICE_NAME ?? 'unnamed-service',
  // Traces are pushed to Jaeger over OTLP.
  traceExporter: new OTLPTraceExporter({
    url: `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? 'http://localhost:4318'}/v1/traces`,
  }),
  // Metrics are pulled: this opens /metrics for Prometheus to scrape.
  metricReader: new PrometheusExporter({ port: Number(process.env.METRICS_PORT ?? 9464) }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, () => {
    // Flush whatever is still batched, otherwise the last spans before a deploy —
    // often the interesting ones — never leave the process.
    void sdk.shutdown().finally(() => process.exit(0));
  });
}

OTEL_SERVICE_NAME=pricing   METRICS_PORT=9465 node --import ./telemetry.ts pricing.ts
OTEL_SERVICE_NAME=inventory METRICS_PORT=9466 node --import ./telemetry.ts inventory.ts
OTEL_SERVICE_NAME=checkout  METRICS_PORT=9464 node --import ./telemetry.ts checkout.ts

Node 24 runs those TypeScript files directly, which is why there is no build step and no tsx anywhere. Note the explicit .ts in --import ./telemetry.ts: Node resolves the real file rather than rewriting the specifier for you.

The interesting part of pricing is that promotions are evaluated per SKU and cached, and the seasonal SKUs carry two hundred times more promotion rules than the house blends:

// pricing.ts (the part that matters)
const cache = new Map<string, number>();

function ruleCountFor(sku: string): number {
  return sku.startsWith('seasonal-') ? 2400 : 12;
}

tracer.startActiveSpan('pricing.quote', (span) => {
  span.setAttribute('aurora.sku', sku);

  const cached = cache.get(sku);
  if (cached !== undefined) {
    span.setAttribute('aurora.cache_hit', true);
    span.end();
    respond(cached);
    return;
  }

  span.setAttribute('aurora.cache_hit', false);

  const priced = tracer.startActiveSpan('pricing.evaluate_rules', (inner) => {
    inner.setAttribute('aurora.rule_count', ruleCountFor(sku));
    const value = evaluateRules(sku);
    inner.end();
    return value;
  });

  cache.set(sku, priced);
  log.warn({ sku, rule_count: ruleCountFor(sku) }, 'priced on a cold cache');
  span.end();
  respond(priced);
});

Nobody wrote a bug. There is a cache, it works, and 977 of the 1,000 requests hit it. That is the point: the interesting failures in production are usually not bugs, they are distributions.

Logs: what happened, in the words of one process

A log is an event with a timestamp, emitted by one process, describing something it did. It is the oldest signal and still the most detailed one — it is the only place where the reason lives.

The first upgrade has nothing to do with observability tooling, and it is free. Stop formatting sentences and start emitting objects:

// Before: the information exists, but only a human can extract it
console.log(`priced ${sku} on a cold cache with ${rules} rules`);

// After: the same event, queryable
log.warn({ sku, rule_count: rules }, 'priced on a cold cache');

{"level":40,"time":1790347139632,"service":"pricing","sku":"seasonal-19","rule_count":2400,"msg":"priced on a cold cache"}

The difference is not aesthetic. The first version can only be grepped, so "show me cold-cache pricings where the rule count was over a thousand, grouped by SKU" means writing a regex against prose that a teammate is free to reword at any time. The second is a filter over two fields. Pino writes that shape by default; Serilog does the same for .NET.

Now here is what logs cannot do, and it is the reason the other two signals exist. Those three services are producing lines like these, all at once, under load:

{"time":1790347137929,"service":"checkout","sku":"house-blend-1kg","ms":3,"msg":"checkout complete"}
{"time":1790347137934,"service":"checkout","sku":"decaf-250g","ms":4,"msg":"checkout complete"}
{"time":1790347137938,"service":"checkout","sku":"espresso-500g","ms":3,"msg":"checkout complete"}
{"time":1790347139632,"service":"pricing","sku":"seasonal-19","rule_count":2400,"msg":"priced on a cold cache"}
{"time":1790347139695,"service":"checkout","sku":"seasonal-19","ms":1755,"msg":"checkout complete"}

Every line is true. Every line is structured. And there is no reliable way to say that the pricing line and the checkout line below it belong to the same order. They look related because the SKU matches and the timestamps are 63ms apart — but that is a guess, and with real concurrency it is a wrong one. Ten customers ordering the same seasonal blend in the same second produce ten indistinguishable pairs. Logs describe events one process at a time; a request that crosses three processes has no owner in that model.

That is the gap. Not detail — logs have plenty. Identity.

Traces: one request, across every process it touched

A trace is one request's journey. It is made of spans, and a span is a named, timed operation with a parent. The tree that comes out of that is what a trace is: not a list of timestamps, but a causal structure — this call happened because of that one, and inside its lifetime.

Two things make it work across a network boundary. Every span carries the trace's ID, and the HTTP client injects that ID into an outgoing traceparent header, which the next service reads back out. That is the entire mechanism of distributed tracing, and it is why the id is the thing worth caring about.

Here is the slowest request from the 1,000-order run, rendered as a tree. Each row is a span's name, duration and service; the attribute column is trimmed down to the two outbound URLs, which is where they come from:

trace 4eef76aeccdbd0f961d78dc7e4241092  (8 spans)

GET                            1756.1 ms  [checkout]
  checkout                     1755.6 ms  [checkout]
    GET                        1752.2 ms  [checkout]   -> localhost:3001/price
      GET                      1692.3 ms  [pricing]
        pricing.quote          1691.4 ms  [pricing]
          pricing.evaluate_rules  1690.7 ms  [pricing]
    GET                           1.6 ms  [checkout]   -> localhost:3002/reserve
      GET                         0.4 ms  [inventory]

Read the numbers down the left. Of 1,756 milliseconds, 1,690.7 were spent inside pricing.evaluate_rules — 96% of the request in a single span, four levels down, in a different process from the one the customer was talking to. Inventory, which is the service everyone suspects first because it touches a database, answered in four tenths of a millisecond.

Nothing in that tree is inferred. Each nested span is inside its parent because the parent's ID was on it, not because the timestamps happen to overlap.

And now the join that the logs could not make on their own, because the SDK stamps the active trace ID onto every line written inside a span:

{"level":40,"time":1790347139632,"service":"pricing","trace_id":"4eef76aeccdbd0f961d78dc7e4241092","span_id":"b56f30e5561dd16d","trace_flags":"01","sku":"seasonal-19","rule_count":2400,"msg":"priced on a cold cache"}
{"level":30,"time":1790347139695,"service":"checkout","trace_id":"4eef76aeccdbd0f961d78dc7e4241092","span_id":"2dafc950aac40ac6","trace_flags":"01","sku":"seasonal-19","ms":1755,"msg":"checkout complete"}

Same two lines as before. Three extra fields, and "these look related" becomes "these are the same request". Keep trace_flags in there — 01 means this trace was sampled and really is in Jaeger. A line carrying 00 has a trace id that leads nowhere, and the sampling section at the end of this post is where that starts to matter. Paste the trace ID into your log search and you get every line any service wrote about that one order; paste it into Jaeger and you get the tree above. That is the bridge, and it is the reason to care about tracing even if you never open a waterfall UI.

You do not write that field. @opentelemetry/instrumentation-pino, which getNodeAutoInstrumentations() turns on for you, adds trace_id, span_id and trace_flags to every Pino line emitted inside an active span. The logger stays three lines long:

// logger.ts
import pino from 'pino';

export const log = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  base: { service: process.env.OTEL_SERVICE_NAME ?? 'unnamed-service' },
});

Metrics: how often, and how bad

A trace describes one request. That is its strength and its entire limitation: you cannot look at 1,000 traces and form an opinion, and in production you will not even have them all.

A metric is a number aggregated over time and grouped by a small set of labels. Checkout records one:

const duration = meter.createHistogram('checkout.duration', {
  description: 'End-to-end checkout latency',
  unit: 'ms',
});

duration.record(elapsed, {
  route: '/checkout',
  outcome: reservation.reserved ? 'ok' : 'rejected',
});

A histogram does not store your measurements. It stores counts per bucket, which is what makes it cheap enough to keep forever. Here is the real scrape after the run, shortened — every line also carries otel_scope_name="aurora.checkout", and the le="0", 50, 75, 250, 5000, 7500, 10000 and +Inf buckets are left out:

checkout_duration_count{route="/checkout",outcome="ok"} 1001
checkout_duration_sum{route="/checkout",outcome="ok"} 22441.000499999976
checkout_duration_bucket{route="/checkout",outcome="ok",le="5"} 910
checkout_duration_bucket{route="/checkout",outcome="ok",le="10"} 972
checkout_duration_bucket{route="/checkout",outcome="ok",le="25"} 976
checkout_duration_bucket{route="/checkout",outcome="ok",le="100"} 979
checkout_duration_bucket{route="/checkout",outcome="ok",le="500"} 981
checkout_duration_bucket{route="/checkout",outcome="ok",le="750"} 988
checkout_duration_bucket{route="/checkout",outcome="ok",le="1000"} 995
checkout_duration_bucket{route="/checkout",outcome="ok",le="2500"} 1001

Buckets are cumulative, so read them as a staircase. 910 of 1,001 requests finished in 5ms or less. 981 finished within half a second — which means 20 requests, 2% of the traffic, took longer than that, and 6 of them took more than a second. (The count is 1,001 rather than 1,000 because checkout also measured the warm-up request; this is the server's own view of its latency, not the load generator's.)

That single fact is what no trace can give you. A trace proves one request was slow; the histogram says how much of your traffic lives out there, which is the difference between "a customer complained" and "one order in fifty is unusable".

It also shows why sum / count — 22,441 / 1,001, or 22.4ms — is the least useful number on the page. It is the average of 910 requests at 5ms and 20 requests at a second, and it describes neither group. Alert on the mean and you will find out about an outage roughly when your customers stop having the problem.

The trade-off runs the other way too. Ask the histogram which requests were slow and it has nothing: there is no SKU in it, no order ID, no customer. That is deliberate, and the next section is about what happens when you try to fix it.

Putting the three together: the 2% that matters

This is the loop, and the order is not decorative.

Metrics tell you there is a problem, and how big it is. 2% of checkouts over 500ms. That number came from data collected before anyone was looking, and it is cheap enough to keep for a year, so you can also see that it started on Tuesday.

Traces tell you where the time went. Pull a slow one and 96% of it is inside pricing.evaluate_rules. You now know the service, the function, and that the network and inventory are innocent — without reading any code.

Logs tell you why. The log line stamped with that same trace ID says rule_count: 2400 and priced on a cold cache. That is the cause, in the application's own vocabulary: this SKU has 2,400 promotion rules and its cache entry was not there.

Metrics without traces gives you a number you cannot act on. Traces without metrics gives you an anecdote. Either without logs gives you a location with no explanation. And all three without a shared ID gives you three dashboards and a meeting.

The span attributes close it out. pricing.quote carries aurora.cache_hit, so "is this only ever happening on cold caches?" is a filter over spans, not a hypothesis. Across the whole run, warm-up included: 24 cold misses against 977 hits, and every single slow request was a miss.

Three gotchas that cost me an afternoon each

1. Under ESM, the SDK starts fine and correlates nothing

Delete the register(...) line from telemetry.ts and everything still boots. No error, no warning, spans still arrive at Jaeger. Same load, same code, this is what comes out:

with the loader hook          without it
-----------------------------------------------------------
checkout   1 trace id         checkout   its own trace id
pricing    same trace id      pricing    a different trace id
inventory  same trace id      inventory  no spans at all
8 spans in one tree           two unrelated fragments
trace_id on every log line    no trace_id on any log line

Auto-instrumentation works by rewriting modules as they load. Under CommonJS it hooks require; under ESM it needs a loader hook registered before the first import of anything instrumented. Without it, node:http is never patched, so the server side never reads the incoming traceparent header, every service starts its own trace, and the Pino instrumentation never attaches either — which is exactly the "three disconnected log streams" state from the top of this article, except now you are also paying to store spans.

The manual spans keep working, which is what makes this so quiet. You will only notice by looking at two services and finding two different trace IDs for one request.

2. A field is free on a span and expensive on a metric

aurora.sku as a span attribute costs nothing: a span is one event, it carries its own fields, and the two dozen SKUs in the run were two dozen values sitting on their own spans.

Put the same field on the histogram and it stops being a field. Every distinct combination of labels is a separate time series, and a histogram exposes eighteen lines per series. Measured on the real exporter:

labels                                       series expected    actually exposed
--------------------------------------------------------------------------------
route + outcome                                          6         6  (108 lines)
route + outcome + customer_id (1,000 ids)            6,000     2,000  (36,000 lines)

The scrape went from a couple of kilobytes to 4.4MB. But look at the right-hand column, because the real damage is the part nobody expects: the SDK caps a metric at 2,000 attribute sets and silently folds everything past that into a single series.

checkout_duration_risky_count{otel_metric_overflow="true"} 4001

4,001 of 6,000 recordings landed there. The metric did not get expensive — it got wrong, and the only sign is a label most people have never seen.

The rule that keeps you out of trouble: a metric label must have a small, bounded set of values you could write down today. Route, status, region, outcome. Never a user ID, an order ID, a SKU from an open-ended catalogue, or a URL with an ID in it. High-cardinality context belongs on spans and log lines, which is exactly what they are good at.

3. Traces are the expensive signal, and sampling is not optional

Those 1,000 requests produced seven spans on a cache hit and eight on a miss — 7,032 in total. Totalling what each endpoint received:

endpoint	posts	bytes
`/v1/traces`	19	6,252,907
`/v1/logs`	28	166,783

There is no /v1/metrics row because nothing was ever sent to it. Prometheus pulls, so metrics never travel this path at all — which is the cheapest line in any telemetry budget.

Six and a quarter megabytes of span data for a thousand checkouts. That is 889 bytes per span, about 6.2KB per request, and thirty-seven times the log volume for the same traffic. Multiply by production traffic and tracing every request is a budget line, not a default.

The answer is sampling, and the version worth knowing now is: sample whole traces, never individual spans, or you get trees with holes in them. The SDK defaults to keeping everything, and two environment variables change that without touching code:

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

Starting 2,000 spans with the default kept 2,000; with those two variables set it kept 201. The parentbased_ prefix is the load-bearing part: the decision is made once at the front door, travels in traceparent, and every downstream service honours it, so you get 10% of traces whole rather than 10% of spans scattered across all of them.

Metrics stay at 100%, which is the other half of why you want them: your p99 remains exact even when 90% of traces are gone.

And that is also where this gets uncomfortable, because head sampling fights the loop this whole post just argued for. The decision is made when the request arrives, before anyone knows whether it will be slow. So of the 20 checkouts over 500ms in this run, a 10% sampler keeps about 2 — and if the tail were rarer, say one request in a thousand, the histogram would still tell you the problem exists while Jaeger has nothing to open. Metrics say how often, traces say where, and the sampler throws dice at exactly the requests you went looking for.

Worse, the trace id exists whether or not the trace was kept, so a log line can carry an id that leads nowhere. That is what trace_flags is for, and it is why it stays in the log sample above: 01 was sampled, 00 was not, and ten minutes hunting for a trace that was never sent is a cheap mistake to avoid.

The real fix is to decide after the trace is complete rather than before it starts — tail sampling, which means an OpenTelemetry Collector between your services and Jaeger, keeping 100% of traces over a latency threshold and 100% of those with errors, plus a percentage of the rest. It is not free: the Collector has to buffer every trace in memory until it decides, and every span of a given trace has to reach the same Collector instance, which is its own routing problem. That is a post of its own, and it is coming in this series. Until then, know that a head-based ratio is a cost control, not an answer to "find me the slow one".

When you need all three, and when you don't

Start with structured logs and one latency histogram per entry point. A single service with one database gets most of the value there. A trace of a request that never leaves the process is a flame graph with extra steps, and a profiler does that better.

Add tracing the moment a request crosses a process boundary. Two services and a queue is enough. That is the point where "which one is slow" stops being answerable from logs, and no amount of log discipline fixes it — the missing thing is the ID, not the detail.

Add metrics before you think you need them, because they are the only signal that is cheap to keep at full fidelity for a year. You cannot go back and ask what the p99 was last quarter if nobody was counting.

Leave it alone when the system is a cron job, a CLI, or anything where the run is the unit of work and stdout already tells the whole story. Also leave it alone when nobody is on call: telemetry nobody reads is a cost centre with a dashboard. Instrumenting is the easy half; the hard half is having someone whose job it is to look.

Rule of thumb: you need a trace when the answer to "where did the time go?" lives in a different process than the one holding the request.

Key Takeaways

Monitoring answers questions you wrote down in advance; observability answers the ones you didn't. If finding out means adding a log line and redeploying, you have logging, not observability.
The three signals are one request seen three ways. Metrics say how often and how bad, traces say where, logs say why. The trace ID is what makes them one system instead of three tabs — and under ESM it takes exactly one register(...) line to lose it silently.
The mean is the least informative number you will compute. A run with a 4.2ms median and an 856ms p99 averages out to 23.9ms, which describes no request that actually happened.
Cardinality is free on spans and ruinous on metrics. The OpenTelemetry SDK caps a metric at 2,000 attribute sets and quietly folds the overflow into otel_metric_overflow, so a customer_id label doesn't just cost money — it makes the metric wrong.
Traces are the expensive signal. 6.2KB per request here, thirty-seven times the logs. Sample whole traces, keep metrics at 100%, and your percentiles stay exact while your bill doesn't.

Coming next in this thread: structured logging in practice — what Pino and Serilog actually cost under load, and why "just log everything as JSON" runs out of road faster than you would like.

Node 24 ejecuta TypeScript sin compilar: lo que funciona y lo que no

Juan Gómez — Thu, 24 Sep 2026 14:00:00 +0000

Node 24 ejecuta TypeScript sin compilar: lo que funciona y lo que no

node server.ts funciona. Sin opciones extra, sin loaders, sin tsx, sin carpeta dist/. Node 24 lee el TypeScript, descarta los tipos y ejecuta lo que queda.

La opción que todavía aparece en todos los tutoriales, --experimental-strip-types, dejó de ser necesaria en Node 23.6. En la 24 puedes pasarla u omitirla y la salida es idéntica byte por byte. Yo la escribí una semana entera por pura inercia, como la contraseña de una cuenta que ya cerré.

Eso de "descarta los tipos" es literal, y Node te lo muestra la primera vez que algo revienta. Este es un archivo completo: tres líneas de código, y una de ellas lleva dos anotaciones de tipo largas.

interface Invoice { id: string }

const describe = (invoice: Invoice, options: Readonly<Record<string, string>>): string => invoice.id.toUpperCase() + options.locale.trim();

console.log(describe({ id: "inv-1" }, {}));

Y esto es lo que imprimió Node al ejecutarlo:

file:///C:/code/scratch/cols.ts:3
const describe = (invoice         , options                                  )         => invoice.id.toUpperCase() + options.locale.trim();
                                                                                                                                    ^

TypeError: Cannot read properties of undefined (reading 'trim')
    at describe (file:///C:/code/scratch/cols.ts:3:133)

Compara la línea 3 en los dos bloques. : Invoice son nueve caracteres, y en la copia de Node hay nueve espacios justo donde estaba. : Readonly<Record<string, string>> son treinta y cuatro, y el hueco que lo reemplazó también. Las dos versiones de esa línea miden exactamente 139 caracteres.

Ahí está el mecanismo completo: las anotaciones se sobrescriben en su lugar con la misma cantidad de espacios, nunca se eliminan. Por eso la columna 133 del archivo que Node ejecutó es la columna 133 del archivo que yo escribí, la flecha señala el carácter correcto, y no hizo falta ningún source map para ponerla ahí.

Esto es lo que aprendí al tomarme la idea en serio: primero en un servicio de cuatro módulos, después en los dos scripts que publican este blog. Funciona. También se niega a hacer cinco cosas concretas, y una de ellas falla de una forma que te va a costar una tarde si nadie te avisa antes.

Qué está pasando en realidad

Node incluye Amaro, una capa delgada sobre el componente de swc que borra los tipos, compilado a WebAssembly. Cuando carga un archivo .ts, .mts o .cts, lo parsea, borra todo lo que existe solo para el verificador de tipos y le entrega el resultado a V8. Ese borrado de tipos (type stripping) es todo el mecanismo.

De esa única frase salen tres consecuencias, y cada problema de este artículo es una de ellas:

No lee tu tsconfig.json. Ni paths, ni experimentalDecorators, ni target. Node ni siquiera busca el archivo.
No verifica tipos. No valida nada. Ni resuelve nada.
No puede generar código. Sobrescribir caracteres con espacios es el mecanismo completo, así que cualquier función de TypeScript que necesite emitir JavaScript queda fuera por diseño.

Puedes preguntarle al proceso en qué modo está corriendo:

process.features.typescript
// "strip"      -> el valor por omisión en Node 24
// "transform"  -> con --experimental-transform-types
// false        -> con --no-strip-types

El último caso vale la pena conocerlo: --no-strip-types devuelve a .ts la condición de extensión desconocida, y es la forma de comprobar que un despliegue está ejecutando código ya compilado en lugar de borrar tipos en cada arranque.

El ciclo sin compilación, en algo de verdad

Esta es la estructura que uso ahora para servicios pequeños: cuatro archivos, sin herramientas de build y sin nada instalado en tiempo de ejecución.

El package.json hace dos cosas interesantes: declara ESM y mapea #src/* para que los imports no se conviertan en cadenas de ../../...

{
  "name": "invoice-api",
  "private": true,
  "type": "module",
  "imports": { "#src/*": "./src/*" },
  "scripts": {
    "dev": "node --watch server.ts",
    "test": "node --test",
    "check": "tsc --noEmit"
  }
}

src/money.ts es el módulo aburrido que existe para que el dinero nunca sea un número con decimales:

export type Cents = number;

/** Solo acepta una cantidad entera y no negativa de centavos: ni decimales, ni strings. */
export function parseCents(raw: unknown): Cents | null {
  return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : null;
}

export function formatCents(cents: Cents): string {
  return (cents / 100).toFixed(2);
}

src/invoices.ts tiene el dominio. Fíjate en el especificador del import: #src/money.ts, con la extensión del archivo que existe realmente en disco. Guarda ese detalle, porque más adelante vuelve convertido en un mensaje de error.

import { type Cents, parseCents } from "#src/money.ts";

export type InvoiceState = "draft" | "sent" | "paid";

export interface Invoice {
  readonly id: string;
  readonly customer: string;
  readonly amountCents: Cents;
  readonly state: InvoiceState;
}

export interface NewInvoice {
  readonly customer: string;
  readonly amountCents: Cents;
}

export function parseNewInvoice(body: unknown): NewInvoice | null {
  if (typeof body !== "object" || body === null) return null;

  const { customer, amountCents } = body as Record<string, unknown>;
  const cents = parseCents(amountCents);

  if (typeof customer !== "string" || customer.trim().length === 0) return null;
  if (cents === null) return null;

  return { customer: customer.trim(), amountCents: cents };
}

export class InvoiceStore {
  readonly #byId = new Map<string, Invoice>();
  #sequence = 0;

  add(draft: NewInvoice): Invoice {
    const invoice: Invoice = {
      id: `INV-${(++this.#sequence).toString().padStart(4, "0")}`,
      customer: draft.customer,
      amountCents: draft.amountCents,
      state: "draft",
    };

    this.#byId.set(invoice.id, invoice);
    return invoice;
  }

  find(id: string): Invoice | undefined {
    return this.#byId.get(id);
  }

  all(): readonly Invoice[] {
    return [...this.#byId.values()];
  }
}

server.ts usa node:http, sin framework, con las dos cosas que un ejemplo suele omitir y que en producción no se perdonan: un límite estricto al tamaño del cuerpo de la petición y un cierre que deja terminar las peticiones en curso.

import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
import { InvoiceStore, parseNewInvoice, type Invoice } from "#src/invoices.ts";
import { formatCents } from "#src/money.ts";

const MAX_BODY_BYTES = 16 * 1024;
const store = new InvoiceStore();

function send(response: ServerResponse, status: number, payload: unknown): void {
  const body = JSON.stringify(payload);
  response.writeHead(status, {
    "content-type": "application/json; charset=utf-8",
    "content-length": Buffer.byteLength(body),
  });
  response.end(body);
}

/** Lee el cuerpo con un límite fijo, para que un solo cliente no haga crecer el proceso sin control. */
async function readJson(request: IncomingMessage): Promise<unknown> {
  const chunks: Buffer[] = [];
  let size = 0;

  for await (const chunk of request) {
    size += chunk.length;
    if (size > MAX_BODY_BYTES) throw new RangeError("cuerpo demasiado grande");
    chunks.push(chunk as Buffer);
  }

  return JSON.parse(Buffer.concat(chunks).toString("utf-8"));
}

function toResponseBody(invoice: Invoice): Record<string, unknown> {
  return { ...invoice, amount: formatCents(invoice.amountCents) };
}

const server = createServer(async (request, response) => {
  const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);

  if (request.method === "GET" && url.pathname === "/invoices") {
    send(response, 200, store.all().map(toResponseBody));
    return;
  }

  if (request.method === "POST" && url.pathname === "/invoices") {
    let body: unknown;
    try {
      body = await readJson(request);
    } catch (error) {
      const status = error instanceof RangeError ? 413 : 400;
      send(response, status, { error: "cuerpo ilegible" });
      return;
    }

    const draft = parseNewInvoice(body);
    if (draft === null) {
      send(response, 422, { error: "customer debe ser un string no vacío y amountCents un número entero" });
      return;
    }

    send(response, 201, toResponseBody(store.add(draft)));
    return;
  }

  send(response, 404, { error: "esa ruta no existe" });
});

server.listen(Number(process.env["PORT"] ?? 3000), () => {
  console.log(`invoice-api escuchando en ${JSON.stringify(server.address())}`);
});

// Deja de aceptar conexiones y permite que terminen las peticiones en curso antes de salir.
for (const signal of ["SIGINT", "SIGTERM"] as const) {
  process.once(signal, () => {
    server.close(() => process.exit(0));
    server.closeIdleConnections();
  });
}

Con node --watch server.ts tienes el ciclo de recarga. Y la parte que más me gustó descubrir: el runner de pruebas integrado no necesita configuración de ningún tipo para ejecutar pruebas en TypeScript.

import { test } from "node:test";
import assert from "node:assert/strict";
import { InvoiceStore, parseNewInvoice, type Invoice } from "#src/invoices.ts";

test("rechaza un monto que no sean centavos enteros", () => {
  assert.equal(parseNewInvoice({ customer: "Cafe Luna", amountCents: 1299.5 }), null);
});

test("rechaza un cliente vacío", () => {
  assert.equal(parseNewInvoice({ customer: "   ", amountCents: 1299 }), null);
});

test("numera las facturas desde uno y las crea como borrador", () => {
  const store = new InvoiceStore();
  const draft = parseNewInvoice({ customer: "Cafe Luna", amountCents: 129900 });
  assert.ok(draft);

  const invoice: Invoice = store.add(draft);
  assert.equal(invoice.id, "INV-0001");
  assert.equal(invoice.state, "draft");
});

node --test encuentra los *.test.ts, les borra los tipos y los ejecuta. Tres pruebas en 259 ms, arranque del proceso incluido. Sin configuración de Jest, sin ts-jest, sin ese bloque transform que nadie en el equipo entiende del todo.

No verifica tipos. En absoluto.

Este archivo se ejecuta sin queja alguna:

const amountCents: number = "129900";
console.log(amountCents.toFixed(2));

TypeError: amountCents.toFixed is not a function

Un TypeError en ejecución por un error que el compilador habría marcado mientras yo lo estaba escribiendo. El borrado de tipos no es una implementación de TypeScript: es una manera eficiente de ignorarlo. La verificación sigue siendo tu responsabilidad, solo que deja de estar en el camino crítico entre guardar y ejecutar:

npx tsc --noEmit    # 838 ms en este proyecto, con el compilador nativo de TypeScript 7

Esa separación es la verdadera ganancia, y es más grande de lo que parece. La verificación ocurre en tu editor mientras escribes, y una vez más en CI. La ejecución ocurre cientos de veces al día, y ahora no espera a ningún compilador.

Dos opciones del tsconfig.json hacen que el verificador exija lo que Node realmente puede ejecutar:

{
  "compilerOptions": {
    "module": "nodenext",
    "target": "es2024",
    "strict": true,
    "noEmit": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,
    "types": ["node"]
  },
  "include": ["server.ts", "src/**/*.ts"]
}

erasableSyntaxOnly rechaza, en tiempo de verificación, cada construcción que Node va a rechazar en tiempo de ejecución: te da un error TS1294 en lugar de una caída. verbatimModuleSyntax evita el único fallo de este artículo en el que de verdad perdí tiempo. Activa las dos antes de migrar algo, no después.

Las cinco cosas que se rompen

1. Enums, namespaces y propiedades de constructor

No son anotaciones. Se compilan a código que existe en ejecución, y sobrescribir caracteres con espacios no puede producir código. Las tres fallan igual:

SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode
SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript namespace declaration is not supported in strip-only mode
SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript parameter property is not supported in strip-only mode

Ese mensaje está bien hecho: nombra la construcción y el modo. Las propiedades declaradas en el constructor (parameter properties) son las que más duelen, porque constructor(private readonly baseUrl: string) {} es el estilo sobre el que está construida media comunidad de NestJS.

--experimental-transform-types hace que las tres funcionen, con un costo: sigue siendo experimental, imprime una advertencia en cada ejecución y ya no conserva las posiciones, porque ahora Node genera código en lugar de borrar caracteres. Mi comprobación fue accidental: un archivo con un decorador en la línea 6 reportó el error de sintaxis en la línea 6 en el modo de solo borrado, y en la línea 5 con la transformación activada. Los stack traces sí salen correctos, porque en ese modo Node activa los source maps; un error de sintaxis ocurre antes de que exista un mapa.

La otra opción es dejar de escribir esas tres construcciones. Un tipo unión reemplaza casi cualquier enum y además el estrechamiento de tipos funciona mejor:

export type InvoiceState = "draft" | "sent" | "paid";

2. Decoradores, sin ninguna explicación

Los decoradores son la excepción a la regla del mensaje útil, y la razón es precisa: no son sintaxis exclusiva de TypeScript. Son una propuesta de JavaScript. El borrado de tipos los deja intactos, se los pasa a V8, y V8 todavía no los implementa:

@logged
^

SyntaxError: Invalid or unexpected token

Ni ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX, ni una mención de TypeScript, ni una pista. Si vienes de NestJS o TypeORM, aquí se termina por ahora la idea de trabajar sin compilar, y --experimental-transform-types tampoco rescata los decoradores estándar. Usa tsx o un paso de compilación, y vuelve a revisarlo en un año.

3. El import que TypeScript jura que está bien

Este es el que me costó tiempo real:

import { Invoice, invoiceTotal } from "./types.ts";

import { Invoice, invoiceTotal } from "./types.ts";
         ^^^^^^^
SyntaxError: The requested module './types.ts' does not provide an export named 'Invoice'

Invoice es una interface. tsc lo sabe y la elimina del import que emite, y por eso esta línea compila sin problemas y ha funcionado en todos los proyectos con paso de compilación que has escrito. Node no tiene ese conocimiento. Ve un import nombrado, V8 le pide ese nombre al módulo, el módulo no lo tiene, y recibes un error de módulos apuntando a una línea que tu verificador aprobó.

La solución es una palabra, y cuando ya la sabes la escribes en automático:

import { type Invoice, invoiceTotal } from "./types.ts";

verbatimModuleSyntax: true convierte esto de sorpresa en ejecución a error de verificación, que es donde corresponde. Estaba en mi tsconfig.json antes de que terminara de depurarlo. Te lo cuento porque el mensaje habla de módulos y de exports, así que pasé veinte minutos revisando mi mapa de imports en lugar de mirar la palabra type que faltaba.

4. Los imports nombran el archivo en disco, no el que planeas emitir

import { toDisplay } from "./money.js";   // money.js no existe

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../esm/money.js'

Node resuelve los especificadores como siempre lo ha hecho, sin reescribir extensiones. Cada import tiene que terminar en .ts, que es exactamente lo contrario de como se ve un proyecto basado en tsc: ahí terminan en .js precisamente porque eso es lo que va a existir después de compilar.

Ese es el obstáculo mecánico más grande para migrar un proyecto existente, y TypeScript 5.7 agregó las opciones que lo resuelven: allowImportingTsExtensions te deja escribir .ts en el código fuente, y rewriteRelativeImportExtensions reescribe esos especificadores a .js al emitir. Puedes tener imports nativos de Node y seguir publicando código compilado; probé las dos rutas sobre el mismo proyecto para estar seguro.

5. Los alias de rutas no existen, y `node_modules` está fuera de alcance

Node nunca lee tsconfig.json, así que paths no hace nada:

TypeError [ERR_PACKAGE_IMPORT_NOT_DEFINED]: Package import specifier "#billing/types.ts" is not defined

El reemplazo es el campo imports del package.json: los subpath imports propios de Node, que TypeScript también entiende. Por eso el ejemplo de arriba mapea #src/*. Un solo mecanismo de alias, respetado por el runtime y por el verificador, sin plugins en medio.

El otro límite es más firme. El borrado de tipos está deshabilitado dentro de node_modules:

Error [ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING]: Stripping types is currently unsupported
for files under node_modules, for ".../node_modules/@acme/billing/index.ts"

O sea: no publiques un paquete cuyo punto de entrada sea un archivo .ts. Las librerías se siguen compilando.

El matiz que importa en un monorepo es el opuesto de lo que sugiere el error. Un paquete de workspace sí funciona, porque npm install lo enlaza con un symlink y Node resuelve por la ruta real, fuera de node_modules. Armé un workspace de npm con dos paquetes y "exports": "./src/index.ts", lo importé de un paquete al otro, y se ejecutó. La restricción es para copias instaladas, no para tus paquetes internos.

Los números

Mejor tiempo de 25 ejecuciones, en una laptop con i7-1165G7, Windows 11 y Node 24.16. Medir solo el arranque en una laptop es ruidoso, así que la columna honesta es el mínimo; dejo la mediana al lado para que veas la dispersión.

Qué se ejecuta	Mínimo	Mediana
archivo `.js` de 20 bytes	66 ms	94 ms
el mismo archivo como `.ts`	90 ms	114 ms
109 KB de `.js` ya emitido	69 ms	75 ms
los 229 KB de `.ts` de donde salió	153 ms	191 ms
servicio de cuatro módulos, compilado	100 ms	118 ms
servicio de cuatro módulos, con borrado de tipos	130 ms	176 ms
servicio de cuatro módulos, con `tsx`	486 ms	590 ms

De esa tabla salen dos conclusiones.

El costo fijo es de unos 25 ms, que es instanciar en WebAssembly el componente que borra los tipos, algo que antes no cargabas. El costo variable ronda los 0.26 ms por kilobyte de TypeScript: 229 KB en un solo archivo cuestan 84 ms y un archivo de 20 bytes cuesta 24 ms. El costo sigue el tamaño del código fuente, no el del proyecto, así que un servicio de cuatro módulos pequeños paga casi nada.

tsx arranca unas 3.7 veces más lento aquí, y sigue siendo la herramienta correcta para varios proyectos. Esa diferencia te compra decoradores, enums, alias de rutas e interoperabilidad con CommonJS. Es un intercambio razonable; solo que ahora conviene hacerlo a propósito y no por costumbre.

Lo que yo intenté hacer de verdad

Este blog son dos scripts de TypeScript independientes — uno publica en la API de dev.to, el otro postea en LinkedIn y X — y los dos corren con tsx. No importan nada más que módulos node:. Candidatos perfectos para eliminar una dependencia.

Los dos funcionaron con node pelado en el primer intento. Después busqué con grep cualquier otra mención de la herramienta y encontré esto, dentro del script de publicación:

spawnSync("tsx", [socialScript, "--url", result.url, "--file", filePath], {
  stdio: "inherit",
  shell: true,
});

El nombre del binario escrito a mano, en una rama del código que solo se ejecuta cuando pasas --social. Editar el package.json habría "eliminado" tsx un martes y roto la publicación el viernes siguiente, en un camino que ni el verificador de tipos ni una ejecución normal tocan nunca. La solución es lanzar el intérprete que ya está corriendo:

spawnSync(process.execPath, [socialScript, "--url", result.url, "--file", filePath], {
  stdio: "inherit",
});

process.execPath además vuelve innecesario el shell: true, que no es poco para un cambio de una línea. Y la lección sirve más allá de este repositorio: la dependencia que intentas eliminar casi nunca está solo en el package.json. Busca el nombre del binario antes de celebrar.

Cuándo usar cada cosa

node pelado: scripts, herramientas de línea de comandos, pruebas, servicios pequeños, cualquier cosa que escribas desde cero sobre Node 24. Sin dependencias y con una pieza menos entre tu editor y el proceso.

tsx: decoradores, enums o propiedades de constructor que no vas a reescribir; alias de rutas que no puedes convertir; dependencias en CommonJS con interoperabilidad incómoda; un proyecto donde todos los imports terminan en .js y la migración no entra en este trimestre.

Un paso de compilación de verdad: publicar una librería en npm, donde la restricción de node_modules es absoluta; empaquetar o minificar para un destino de despliegue; apuntar a un Node anterior al 22; o un presupuesto de arranque en frío tan ajustado que no puedas gastar 25 ms de borrado de tipos más un milisegundo por cada cuatro kilobytes de código.

Y en los tres casos, conserva tsc --noEmit. El borrado de tipos no eliminó la necesidad de verificar tipos: sacó al compilador del camino entre guardar un archivo y verlo correr, que era la parte que te hacía esperar.

Puntos clave

La opción ya no hace falta. node server.ts corre en Node 24 sin opciones extra, --experimental-strip-types ya no hace nada, y process.features.typescript reporta "strip", "transform" o false.
Los tipos se sobrescriben con espacios, no se eliminan. Las posiciones en bytes se conservan, así que las líneas y columnas de un stack trace son exactas sin ningún source map: los espacios se ven en la línea que Node imprime.
Nada se verifica, así que tsc --noEmit se queda. Agrega erasableSyntaxOnly y verbatimModuleSyntax para que el verificador rechace lo que Node va a rechazar, empezando por el import { AlgunaInterface } al que le falta la palabra type.
Se rompen cinco cosas: enums, namespaces y propiedades de constructor (con un error claro), decoradores (con un SyntaxError: Invalid or unexpected token a secas), imports que nombran archivos .js inexistentes, los alias de rutas del tsconfig, y cualquier archivo .ts instalado dentro de node_modules.
Presupuesta unos 25 ms más 0.26 ms por KB de código — cerca de 3.7 veces más rápido de arrancar que tsx sobre los mismos archivos, razón suficiente para usar node pelado por omisión y tsx a propósito.

Node 24 Runs TypeScript With No Build Step. Here's What It Won't Do.

Juan Gómez — Tue, 22 Sep 2026 12:40:28 +0000

Node 24 Runs TypeScript With No Build Step. Here's What It Won't Do.

node server.ts works. No flag, no loader, no tsx, no dist/ folder. Node 24 reads the TypeScript, throws the types away, and runs what is left.

The flag everybody still types — --experimental-strip-types — has been unnecessary since Node 23.6, and on 24 you can pass it or leave it off and get byte-identical output. I typed it for a week out of muscle memory, like a password for an account that no longer exists.

"Throws the types away" is not a metaphor, and Node shows you exactly what it means the first time something blows up. Here is a whole file — three lines of code, one of them carrying two long type annotations:

interface Invoice { id: string }

const describe = (invoice: Invoice, options: Readonly<Record<string, string>>): string => invoice.id.toUpperCase() + options.locale.trim();

console.log(describe({ id: "inv-1" }, {}));

And here is what Node printed when I ran it:

file:///C:/code/scratch/cols.ts:3
const describe = (invoice         , options                                  )         => invoice.id.toUpperCase() + options.locale.trim();
                                                                                                                                    ^

TypeError: Cannot read properties of undefined (reading 'trim')
    at describe (file:///C:/code/scratch/cols.ts:3:133)

Compare line 3 in the two blocks. : Invoice is nine characters, and Node's copy has nine spaces where it was. : Readonly<Record<string, string>> is thirty-four, and so is the gap that replaced it. Both versions of that line are exactly 139 characters long.

That is the entire mechanism: annotations are overwritten in place with the same number of blanks, never removed. So column 133 in the file Node executed is column 133 in the file I wrote, the caret lands under the right character, and no source map was needed to put it there.

This post is what I learned taking that seriously — first on a four-module service, then on the two scripts that publish this blog. It works. It also refuses five specific things, and one of them fails in a way that will cost you an afternoon if nobody tells you first.

What is actually happening

Node bundles Amaro, a thin wrapper around swc's TypeScript stripper compiled to WebAssembly. When it loads a .ts, .mts or .cts file, it parses the source, blanks out everything that exists only for the type checker, and hands the result to V8.

Three consequences follow from that one sentence, and every gotcha in this article is one of them:

It does not read your tsconfig.json. Not paths, not experimentalDecorators, not target. Node never looks for the file.
It does not type check. Nothing is validated. Nothing is even resolved.
It cannot generate code. Blanking out characters is the entire mechanism, so any TypeScript feature that has to emit JavaScript is out of scope by construction.

You can ask the running process which mode it is in:

process.features.typescript
// "strip"      -> the Node 24 default
// "transform"  -> with --experimental-transform-types
// false        -> with --no-strip-types

That last one is worth knowing: --no-strip-types turns .ts back into an unknown extension, which is how you prove a deployment is running compiled output instead of stripping on the fly.

The zero-build loop, on something real

Here is the shape I now use for small services: four files, no build tooling, nothing installed at runtime.

The package.json does two interesting things — it declares ESM, and it maps #src/* so imports do not turn into ../../.. chains:

{
  "name": "invoice-api",
  "private": true,
  "type": "module",
  "imports": { "#src/*": "./src/*" },
  "scripts": {
    "dev": "node --watch server.ts",
    "test": "node --test",
    "check": "tsc --noEmit"
  }
}

src/money.ts is the boring module that exists so money is never a float:

export type Cents = number;

/** Accepts only a non-negative integer number of cents — no floats, no strings. */
export function parseCents(raw: unknown): Cents | null {
  return typeof raw === "number" && Number.isInteger(raw) && raw >= 0 ? raw : null;
}

export function formatCents(cents: Cents): string {
  return (cents / 100).toFixed(2);
}

src/invoices.ts holds the domain. Note the import specifier — #src/money.ts, with the extension of the file that is actually on disk. Hold that thought; it comes back later as an error message.

import { type Cents, parseCents } from "#src/money.ts";

export type InvoiceState = "draft" | "sent" | "paid";

export interface Invoice {
  readonly id: string;
  readonly customer: string;
  readonly amountCents: Cents;
  readonly state: InvoiceState;
}

export interface NewInvoice {
  readonly customer: string;
  readonly amountCents: Cents;
}

export function parseNewInvoice(body: unknown): NewInvoice | null {
  if (typeof body !== "object" || body === null) return null;

  const { customer, amountCents } = body as Record<string, unknown>;
  const cents = parseCents(amountCents);

  if (typeof customer !== "string" || customer.trim().length === 0) return null;
  if (cents === null) return null;

  return { customer: customer.trim(), amountCents: cents };
}

export class InvoiceStore {
  readonly #byId = new Map<string, Invoice>();
  #sequence = 0;

  add(draft: NewInvoice): Invoice {
    const invoice: Invoice = {
      id: `INV-${(++this.#sequence).toString().padStart(4, "0")}`,
      customer: draft.customer,
      amountCents: draft.amountCents,
      state: "draft",
    };

    this.#byId.set(invoice.id, invoice);
    return invoice;
  }

  find(id: string): Invoice | undefined {
    return this.#byId.get(id);
  }

  all(): readonly Invoice[] {
    return [...this.#byId.values()];
  }
}

server.ts uses node:http and no framework, with the two things a demo usually skips and production never forgives: a hard cap on the request body, and a shutdown that lets in-flight requests finish.

import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
import { InvoiceStore, parseNewInvoice, type Invoice } from "#src/invoices.ts";
import { formatCents } from "#src/money.ts";

const MAX_BODY_BYTES = 16 * 1024;
const store = new InvoiceStore();

function send(response: ServerResponse, status: number, payload: unknown): void {
  const body = JSON.stringify(payload);
  response.writeHead(status, {
    "content-type": "application/json; charset=utf-8",
    "content-length": Buffer.byteLength(body),
  });
  response.end(body);
}

/** Reads the body with a hard cap, so one client cannot make the process grow forever. */
async function readJson(request: IncomingMessage): Promise<unknown> {
  const chunks: Buffer[] = [];
  let size = 0;

  for await (const chunk of request) {
    size += chunk.length;
    if (size > MAX_BODY_BYTES) throw new RangeError("body too large");
    chunks.push(chunk as Buffer);
  }

  return JSON.parse(Buffer.concat(chunks).toString("utf-8"));
}

function toResponseBody(invoice: Invoice): Record<string, unknown> {
  return { ...invoice, amount: formatCents(invoice.amountCents) };
}

const server = createServer(async (request, response) => {
  const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);

  if (request.method === "GET" && url.pathname === "/invoices") {
    send(response, 200, store.all().map(toResponseBody));
    return;
  }

  if (request.method === "POST" && url.pathname === "/invoices") {
    let body: unknown;
    try {
      body = await readJson(request);
    } catch (error) {
      const status = error instanceof RangeError ? 413 : 400;
      send(response, status, { error: "unreadable body" });
      return;
    }

    const draft = parseNewInvoice(body);
    if (draft === null) {
      send(response, 422, { error: "customer must be a non-empty string, amountCents a whole number" });
      return;
    }

    send(response, 201, toResponseBody(store.add(draft)));
    return;
  }

  send(response, 404, { error: "no such route" });
});

server.listen(Number(process.env["PORT"] ?? 3000), () => {
  console.log(`invoice-api listening on ${JSON.stringify(server.address())}`);
});

// Stop accepting connections and let in-flight requests finish before exiting.
for (const signal of ["SIGINT", "SIGTERM"] as const) {
  process.once(signal, () => {
    server.close(() => process.exit(0));
    server.closeIdleConnections();
  });
}

node --watch server.ts gives you the reload loop. And the part that surprised me most pleasantly: the built-in test runner needs no configuration at all to run TypeScript tests.

import { test } from "node:test";
import assert from "node:assert/strict";
import { InvoiceStore, parseNewInvoice, type Invoice } from "#src/invoices.ts";

test("rejects an amount that is not whole cents", () => {
  assert.equal(parseNewInvoice({ customer: "Cafe Luna", amountCents: 1299.5 }), null);
});

test("rejects a blank customer", () => {
  assert.equal(parseNewInvoice({ customer: "   ", amountCents: 1299 }), null);
});

test("numbers invoices from one and starts them as drafts", () => {
  const store = new InvoiceStore();
  const draft = parseNewInvoice({ customer: "Cafe Luna", amountCents: 129900 });
  assert.ok(draft);

  const invoice: Invoice = store.add(draft);
  assert.equal(invoice.id, "INV-0001");
  assert.equal(invoice.state, "draft");
});

node --test finds *.test.ts, strips it, runs it. Three tests in 259 ms including process startup — no Jest config, no ts-jest, no transform block that nobody on the team understands.

It does not type check. At all.

This file runs:

const amountCents: number = "129900";
console.log(amountCents.toFixed(2));

TypeError: amountCents.toFixed is not a function

A runtime TypeError for a mistake the compiler would have caught while I was still typing it. Type stripping is not a TypeScript implementation; it is a way to ignore TypeScript efficiently. Checking is still your job — it just stops being on the critical path of running the code:

npx tsc --noEmit    # 838 ms on this project, with TypeScript 7's native compiler

That split is the real win, and it is bigger than it looks. Checking happens in your editor as you type, and once more in CI. Running happens hundreds of times a day, and now it does not wait for a compiler.

Two tsconfig.json options make the checker enforce what Node can actually execute:

{
  "compilerOptions": {
    "module": "nodenext",
    "target": "es2024",
    "strict": true,
    "noEmit": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,
    "types": ["node"]
  },
  "include": ["server.ts", "src/**/*.ts"]
}

erasableSyntaxOnly rejects, at check time, every construct Node will refuse at run time — error TS1294 instead of a crash. verbatimModuleSyntax prevents the one failure in this article I genuinely lost time to. Turn both on before you migrate anything, not after.

The five things that break

1. Enums, namespaces and parameter properties

These are not annotations. They compile to runtime code, and blanking out characters cannot produce runtime code. All three fail the same way:

SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode
SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript namespace declaration is not supported in strip-only mode
SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript parameter property is not supported in strip-only mode

That is a good error message: it names the construct and the mode. Parameter properties are the one that stings, because constructor(private readonly baseUrl: string) {} is the idiom half the NestJS ecosystem is built on.

--experimental-transform-types makes all three work, at a price: it is still experimental, it prints a warning on every run, and it no longer preserves positions, because now Node is generating code rather than blanking characters. My proof of that was accidental — a file with a decorator on line 6 reported the syntax error on line 6 in strip mode and on line 5 with transform enabled. Stack traces still come out right, since Node enables source maps for that mode; a syntax error happens before any map exists.

The alternative is to stop writing the three constructs. A union type replaces most enums and gives you better narrowing anyway:

export type InvoiceState = "draft" | "sent" | "paid";

2. Decorators, with no explanation whatsoever

Decorators are the exception to the helpful-error rule, for a precise reason: they are not TypeScript-only syntax. They are a JavaScript proposal. The stripper leaves them alone, hands them to V8, and V8 does not implement them yet:

@logged
^

SyntaxError: Invalid or unexpected token

No ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX, no mention of TypeScript, no hint. If you are coming from NestJS or TypeORM, this is where the zero-build idea ends for now — and --experimental-transform-types does not rescue standard decorators either. Use tsx or a build step, and revisit in a year.

3. The import that TypeScript swears is fine

This is the one that cost me real time:

import { Invoice, invoiceTotal } from "./types.ts";

import { Invoice, invoiceTotal } from "./types.ts";
         ^^^^^^^
SyntaxError: The requested module './types.ts' does not provide an export named 'Invoice'

Invoice is an interface. tsc knows that and elides it from the emitted import, which is exactly why this line compiles cleanly and has worked in every build-step project you have ever written. Node has no such knowledge. It sees a named import, V8 asks the module for that name, the module does not have one, and you get a module error pointing at a line your type checker approved.

The fix is one keyword, and once you know it you write it automatically:

import { type Invoice, invoiceTotal } from "./types.ts";

verbatimModuleSyntax: true turns this from a runtime surprise into a compile-time error, which is where it belongs. It was in my tsconfig.json before I finished debugging it. The reason I am telling you at all is that the message talks about modules and exports, so I spent twenty minutes staring at my imports map instead of at the missing word type.

4. Import specifiers name the file on disk, not the one you plan to emit

import { toDisplay } from "./money.js";   // there is no money.js

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../esm/money.js'

Node resolves specifiers the way it always has, with no extension rewriting. Every import has to end in .ts, which is the opposite of what a tsc-based codebase looks like — there, imports end in .js precisely because that is what will exist after the build.

That makes it the biggest mechanical obstacle to migrating an existing project, and TypeScript 5.7 added the switch for it: allowImportingTsExtensions lets you write .ts in source, and rewriteRelativeImportExtensions rewrites those specifiers to .js on emit. You can have Node-native imports and still ship compiled output — I ran both paths over the same tree to be sure.

5. Path aliases do not exist, and `node_modules` is off limits

Node never reads tsconfig.json, so paths does nothing:

TypeError [ERR_PACKAGE_IMPORT_NOT_DEFINED]: Package import specifier "#billing/types.ts" is not defined

The replacement is the imports field in package.json — Node's own subpath imports, which TypeScript understands too. That is why the example above maps #src/*: one alias mechanism, honored by the runtime and the checker, no plugin in between.

The other limit is firmer. Type stripping is disabled under node_modules:

Error [ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING]: Stripping types is currently unsupported
for files under node_modules, for ".../node_modules/@acme/billing/index.ts"

Which means: do not publish a package whose entry point is a .ts file. Libraries still compile.

The nuance that matters for monorepos is the opposite of what the error suggests. A workspace package does work, because npm install symlinks it and Node resolves through the real path outside node_modules. I set up a two-package npm workspace with "exports": "./src/index.ts" and imported it across packages — it ran. The restriction is about installed copies, not about your internal packages.

The numbers

Best of 25 runs each, on an i7-1165G7 laptop with Windows 11 and Node 24.16. Startup-only workloads on a laptop are noisy, so the honest column is the minimum; the median sits next to it so you can see the spread.

What is running	Min	Median
20-byte `.js` file	66 ms	94 ms
the same file as `.ts`	90 ms	114 ms
109 KB of emitted `.js`	69 ms	75 ms
the 229 KB `.ts` it came from	153 ms	191 ms
four-module service, compiled	100 ms	118 ms
four-module service, stripped	130 ms	176 ms
four-module service, `tsx`	486 ms	590 ms

Two things fall out of that table.

The fixed cost is about 25 ms, which is instantiating a WebAssembly stripper you were not loading before. The marginal cost is roughly 0.26 ms per kilobyte of TypeScript: 229 KB in a single file costs 84 ms, a 20-byte file costs 24 ms. Strip cost tracks source size, not project size, so a service made of four small modules pays almost nothing.

tsx starts about 3.7x slower here, and it is still the right tool for some projects. That gap buys decorators, enums, path aliases and CommonJS interop. It is a fair trade — just one to make deliberately now, rather than by default.

The thing I actually tried to do

This blog is two standalone TypeScript scripts — one that publishes to the dev.to API, one that posts to LinkedIn and X — both run through tsx. They import nothing but node: builtins. Perfect candidates for deleting a dependency.

Both ran under bare node on the first attempt. Then I grepped for anything else mentioning the tool and found this, inside the publish script:

spawnSync("tsx", [socialScript, "--url", result.url, "--file", filePath], {
  stdio: "inherit",
  shell: true,
});

A hardcoded binary name, in a code path that only executes when you pass --social. Editing package.json would have "removed" tsx on a Tuesday and broken publishing the following Friday, in a branch of the code no type checker and no ordinary run ever touches. The fix is to spawn the interpreter that is already running:

spawnSync(process.execPath, [socialScript, "--url", result.url, "--file", filePath], {
  stdio: "inherit",
});

process.execPath also makes shell: true unnecessary, which is a good return on a one-line change. The lesson generalizes past this repo: the dependency you are trying to drop is rarely only in package.json. Grep for the binary name before you celebrate.

When to use which

Bare node — scripts, CLIs, tests, small services, anything you write from scratch on Node 24. No dependencies, and one fewer moving part between your editor and the process.

tsx — decorators, enums or parameter properties you are not going to rewrite; path aliases you cannot convert; CommonJS dependencies with awkward interop; a codebase whose imports all end in .js and a migration you cannot schedule this quarter.

A real build step — publishing a library to npm, where the node_modules restriction is absolute; bundling or minifying for a deployment target; targeting a Node older than 22; or a cold-start budget where 25 ms of stripper plus a millisecond per four kilobytes of source is more than you can spend.

And keep tsc --noEmit in all three. Type stripping did not remove the need for a type checker. It removed the compiler from the path between saving a file and watching it run, which was the part that was slowing you down.

Key Takeaways

The flag is gone. node server.ts runs on Node 24 with no flags, --experimental-strip-types is a silent no-op, and process.features.typescript reports "strip", "transform" or false.
Types are overwritten with spaces, not deleted. Byte positions survive, so line and column numbers in a stack trace are exact with no source map — you can see the blanks in the echoed source line.
Nothing is type checked, so tsc --noEmit stays. Add erasableSyntaxOnly and verbatimModuleSyntax so the checker rejects what Node will refuse, starting with import { SomeInterface } missing its type keyword.
Five things break: enums, namespaces and parameter properties (with a clear error), decorators (with a bare SyntaxError: Invalid or unexpected token), imports naming .js files that do not exist, tsconfig path aliases, and any .ts file installed under node_modules.
Budget about 25 ms plus 0.26 ms per KB of source — roughly 3.7x faster to start than tsx on the same files, which is reason enough to reach for bare node by default and for tsx on purpose.

Construye un agente de desarrollo .NET, Parte 1: enséñale tu flujo de trabajo real

Juan Gómez — Mon, 14 Sep 2026 00:00:00 +0000

Construye un agente de desarrollo .NET, Parte 1: enséñale tu flujo de trabajo real

El agente funcionó a la primera, y eso debió ponerme en alerta.

Le había conectado a Claude los tres comandos que uso todo el día — git status, dotnet build, dotnet test —, le pasé la salida y le pregunté por qué mi build estaba en rojo. Respondió bien. Después, por costumbre, conté lo que le había mandado en realidad. El build reportaba 70 warnings. La solución solo tiene 35. Le estaba enviando a Claude una segunda copia literal de cada diagnóstico, y Claude las leía las dos.

MSBuild imprime cada diagnóstico dos veces: una cuando el compilador lo encuentra, y otra más en el bloque de resumen que va después de Build FAILED.. El ojo humano se salta esa segunda copia con tal eficacia que yo llevaba años leyendo salidas de build sin notarla. Un modelo de lenguaje no se salta nada. Lee el duplicado, te cobra el duplicado, y razona sobre un problema que ahora parece el doble de grande.

Este post trata de la mitad menos vistosa de un agente de desarrollo: no el bucle que llama al modelo, sino lo que le pones delante. El bucle son unas veinte líneas y ya lo escribí antes. Averiguar qué significa de verdad la salida de tus herramientas — y descartar la buena parte que no significa nada — es lo que separa a un agente que ayuda de uno que solo te factura.

Lo que este post da por sabido

El bucle de tool_use en sí — declarar las herramientas, recibir un bloque tool_use, ejecutarlo, devolver un tool_result y repetir hasta que el modelo deje de pedir — lo construí paso a paso en Crea un agente con tool use de Claude en C#. Aquí no lo vuelvo a construir. Si nunca escribiste uno, empieza por ahí; todo lo que viene se conecta con eso.

Todos los ejemplos asumen .NET 10 y el SDK oficial:

dotnet add package Anthropic

Tres herramientas, y por qué ninguna es bash

Lo obvio sería darle al modelo una sola herramienta bash y dejar que ejecute lo que quiera. A veces esa es la decisión correcta — es lo que hace Claude Code, y ahí la amplitud es justamente el objetivo. Aquí es la decisión equivocada, por dos razones.

La primera: una herramienta bash le entrega a tu harness una cadena opaca. Todas las acciones se ven iguales desde fuera, así que no hay nada que inspeccionar, autorizar ni contar. Una herramienta dotnet_build tipada te da un punto de enganche con argumentos reales: puedes decidir que compilar es seguro sin supervisión y que cualquier cosa que toque la red no lo es.

La segunda es el alcance. git status, dotnet build y dotnet test son de solo lectura. Eso es lo que hace razonable apuntar esto a tu propia copia de trabajo un viernes por la tarde. En cuanto agregas bash, el radio de daño pasa a ser todo lo que pueda hacer tu usuario del sistema, y quedas a una sugerencia bien redactada de arruinarte la tarde.

Empieza con bash cuando quieras alcance. Pasa a herramientas tipadas cuando quieras control. Para un agente de uso diario en tu máquina, gana el control.

Pide la salida pensada para programas, no la bonita

Las dos herramientas que importan aquí tienen un segundo formato de salida diseñado para programas, y en ambos casos lo que se imprime por defecto para humanos es lo que no conviene parsear. Esta es la decisión con más impacto de todo el post, y aparece dos veces.

git status imprime algo amable e inestable. git status --porcelain=v2 imprime un formato documentado, con una promesa explícita de compatibilidad. dotnet test imprime un resumen legible; dotnet test --logger trx escribe XML estructurado.

Lo contraintuitivo: el formato para programas suele ser más grande. El archivo TRX de mi suite de 91 tests pesa 149,020 bytes, contra 2,291 bytes de salida en consola. Da igual, porque nunca vas a enviarlo. Lo consultas y emites un resumen. Parsear un contrato estable y tirar el 99% es mejor que aplicarle expresiones regulares a un formato bonito que cambia entre versiones del SDK.

Herramienta uno: git_status

Porcelain v2 entrega una línea por entrada. Los archivos modificados empiezan con 1 (normal) o 2 (renombrado), los no rastreados con ?, y la bandera --branch agrega cabeceras # branch.* con los contadores de adelanto y atraso.

static async Task<string> GitStatusAsync(string repo, CancellationToken ct)
{
    ProcessResult git = await RunAsync("git", ["status", "--porcelain=v2", "--branch"], repo, ct);
    if (git.ExitCode != 0) return $"git status falló (código de salida {git.ExitCode}): {git.Output.Trim()}";
    string output = git.Output;

    string branch = "(detached)";
    int ahead = 0, behind = 0;
    List<string> changed = [], untracked = [];

    foreach (string raw in output.Split('\n', StringSplitOptions.RemoveEmptyEntries))
    {
        string line = raw.TrimEnd('\r');

        if (line.StartsWith("# branch.head "))
        {
            branch = line["# branch.head ".Length..];
        }
        else if (line.StartsWith("# branch.ab "))
        {
            string[] ab = line["# branch.ab ".Length..].Split(' ');
            ahead = int.Parse(ab[0]);    // "+2"
            behind = int.Parse(ab[1]);   // "-0"
        }
        else if (line.StartsWith("1 "))
        {
            // 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <ruta>
            string[] f = line.Split(' ', 9);
            changed.Add($"{f[1]} {f[8]}");
        }
        else if (line.StartsWith("2 "))
        {
            // los renombrados traen un campo extra de puntaje, y la ruta viene
            // como "nueva<tab>anterior"
            string[] f = line.Split(' ', 10);
            string[] paths = f[9].Split('\t');
            changed.Add($"{f[1]} {paths[0]} (antes {paths[1]})");
        }
        else if (line.StartsWith("? "))
        {
            untracked.Add(line[2..]);
        }
    }

    StringBuilder summary = new();
    summary.AppendLine($"rama {branch}, {ahead} adelante, {behind} atrás");
    summary.AppendLine($"{changed.Count} modificados, {untracked.Count} sin rastrear");
    foreach (string entry in changed.Take(40)) summary.AppendLine($"  {entry}");
    foreach (string entry in untracked.Take(20)) summary.AppendLine($"  ?? {entry}");
    return summary.ToString();
}

El código XY de dos caracteres sobrevive al resumen porque es la diferencia entre lo que está en el índice y lo que no, y el modelo lo usa. El resto de la línea — los tres modos de archivo y los dos hashes — sirve para herramientas que necesitan calcular diferencias, no para responder qué estoy haciendo ahora.

Herramienta dos: dotnet_build, donde vive la duplicación

Así se ve un build fallido en una solución de tres proyectos, medido y no supuesto:

87 líneas, 20,681 bytes
70 warnings impresos
35 warnings que existen

Cada diagnóstico aparece exactamente dos veces. Encima, cada línea impresa carga la ruta absoluta dos veces — una como ubicación del archivo y otra en el marcador final [...csproj] —, así que un mensaje de 90 caracteres llega dentro de una línea de 500.

La solución es una expresión regular y un diccionario. Elimina duplicados por la tupla que de verdad identifica un diagnóstico — archivo, línea, columna, código — y deja las rutas relativas a la raíz del repositorio:

// Expresión regular generada en tiempo de compilación, no al arrancar. Va dentro
// de una clase porque en una aplicación de archivo único no hay lugar para un
// campo: lo que se declara junto a las instrucciones de nivel superior tiene que
// ser una variable local, y ahí `static readonly` da un CS0106.
static partial class BuildOutput
{
    [GeneratedRegex(@"^(?<file>.+?)\((?<line>\d+),(?<col>\d+)\): (?<severity>error|warning) (?<code>[A-Za-z]+\d+): (?<message>.+?)(?: \[[^\]]+\])?$")]
    public static partial Regex DiagnosticLine();
}

static async Task<string> DotnetBuildAsync(string repo, string? project, CancellationToken ct)
{
    string[] args = project is null
        ? ["build", "--nologo"]
        : ["build", "--nologo", project];

    ProcessResult build = await RunAsync("dotnet", args, repo, ct);
    string output = build.Output;

    // MSBuild emite cada diagnóstico en línea y otra vez en el bloque de resumen.
    Dictionary<(string, int, int, string), Diagnostic> unique = [];

    foreach (string raw in output.Split('\n'))
    {
        Match match = BuildOutput.DiagnosticLine().Match(raw.TrimEnd('\r'));
        if (!match.Success) continue;

        string file = match.Groups["file"].Value.Trim();

        // Los diagnósticos anclados en los .targets del propio SDK son fallos de
        // infraestructura, no de tu código. Consérvalos, pero no los presentes
        // como si vivieran en el repositorio.
        string display = file.StartsWith(repo, StringComparison.OrdinalIgnoreCase)
            ? Path.GetRelativePath(repo, file).Replace('\\', '/')
            : file;

        Diagnostic diagnostic = new(
            display,
            int.Parse(match.Groups["line"].Value),
            int.Parse(match.Groups["col"].Value),
            match.Groups["severity"].Value,
            match.Groups["code"].Value,
            match.Groups["message"].Value.Trim());

        unique.TryAdd((diagnostic.File, diagnostic.Line, diagnostic.Column, diagnostic.Code), diagnostic);
    }

    List<Diagnostic> errors = [.. unique.Values.Where(d => d.Severity == "error")];
    List<Diagnostic> warnings = [.. unique.Values.Where(d => d.Severity == "warning")];

    // El código de salida es el veredicto; las líneas parseadas solo lo explican. Un fallo
    // sin archivo ni línea (un proyecto que no existe, un argumento malo) tiene que leerse
    // igual como fallo.
    if (build.ExitCode != 0 && errors.Count == 0)
        return $"El build falló (código de salida {build.ExitCode}) sin diagnósticos con ubicación. Últimas líneas:\n" +
               string.Join('\n', output.Split('\n', StringSplitOptions.RemoveEmptyEntries).TakeLast(10));

    if (errors.Count == 0 && warnings.Count == 0) return "El build terminó sin diagnósticos.";

    StringBuilder summary = new();
    summary.AppendLine($"{errors.Count} error(es), {warnings.Count} warning(s).");

    // Primero los errores: rara vez un warning es la razón de que el build falle.
    foreach (Diagnostic d in errors.Concat(warnings).Take(50))
        summary.AppendLine($"{d.File}({d.Line},{d.Column}): {d.Severity} {d.Code}: {d.Message}");

    int total = errors.Count + warnings.Count;
    if (total > 50) summary.AppendLine($"... {total - 50} más omitidos.");

    return summary.ToString();
}

Diagnostic es record Diagnostic(string File, int Line, int Column, string Severity, string Code, string Message); y RunAsync devuelve record ProcessResult(string Output, int ExitCode);, los dos declarados después de la última instrucción de nivel superior junto con BuildOutput — en una aplicación de archivo único todos los tipos van al final del archivo o te sale un CS8803.

Eso lleva el mismo build de 20,681 bytes a 4,849 — una cuarta parte del original, sin perder nada de valor. El límite también cuenta: una solución donde una interfaz rota genera 900 diagnósticos no necesita los 900 en la ventana de contexto para diagnosticarse. Los primeros cincuenta dicen lo mismo.

El error que cometí primero

Antes de todo lo anterior, mi instinto fue que al agente le faltaba más contexto, no menos. Así que subí la verbosidad:

dotnet build -v n

Ese build pesa 187,412 bytes — nueve veces la salida por defecto, con los mismos tres proyectos y los mismos errores. La línea más larga tiene 25,635 caracteres: la invocación completa de csc, cada referencia, cada analizador, entera. Nada de eso explica un error de compilación, y todo eso desplaza a las tres líneas que sí lo hacen.

Las banderas de verbosidad están pensadas para una persona que baja por la pantalla buscando una cosa. Un agente lo lee todo, en cada turno. Subirla fue lo más caro que le hice a este proyecto, y empeoró las respuestas — lo cual al menos volvió fácil detectar el problema.

Herramienta tres: dotnet_test, vía TRX

El dotnet test moderno ya es contenido en consola: 89 tests que pasan no imprimen nada. Pero los fallos repiten el mismo patrón: cada uno se anuncia dos veces, una como línea [xUnit.net] y otra en el bloque de detalle.

El problema mayor son los stack traces. Entre mis dos tests fallidos había seis marcos, y solo dos apuntaban a mi código. Los otros cuatro se ven así:

at System.Reflection.MethodBaseInvoker.InterpretedInvoke_Method(Object obj, IntPtr* args)
at System.Reflection.MethodBaseInvoker.InvokeWithNoArgs(Object obj, BindingFlags invokeAttr)

Ese es el runner de tests entrando por reflexión a tu método. Es idéntico para cada fallo de cada suite que se haya escrito, y no le dice nada al modelo. Dos tercios del stack trace son relleno.

TRX te da todo esto como XML con un esquema estable, así que puedes tomar los tres campos que importan y dejar el resto en disco:

static async Task<string> DotnetTestAsync(string repo, CancellationToken ct)
{
    string resultsDir = Path.Combine(Path.GetTempPath(), $"agent-trx-{Guid.NewGuid():N}");
    try
    {
        ProcessResult run = await RunAsync("dotnet",
            ["test", "--nologo", "--logger", "trx;LogFileName=run.trx", "--results-directory", resultsDir],
            repo, ct);

        string trx = Path.Combine(resultsDir, "run.trx");
        if (!File.Exists(trx)) return $"No se generó TRX (código de salida {run.ExitCode}): seguramente el proyecto de tests no compiló.";

        XNamespace ns = "http://microsoft.com/schemas/VisualStudio/TeamTest/2010";
        XDocument doc = XDocument.Load(trx);

        XElement? counters = doc.Descendants(ns + "Counters").FirstOrDefault();
        StringBuilder summary = new();
        summary.AppendLine(
            $"{counters?.Attribute("passed")?.Value ?? "?"}/{counters?.Attribute("total")?.Value ?? "?"} pasaron, " +
            $"{counters?.Attribute("failed")?.Value ?? "?"} fallaron.");

        foreach (XElement result in doc.Descendants(ns + "UnitTestResult")
                                       .Where(r => (string?)r.Attribute("outcome") == "Failed")
                                       .Take(15))
        {
            string name = ((string?)result.Attribute("testName") ?? "(desconocido)").Split('.')[^1];
            string message = result.Descendants(ns + "Message").FirstOrDefault()?.Value.Trim() ?? "";

            // Conserva solo los marcos que están en el código del proyecto.
            IEnumerable<string> frames = (result.Descendants(ns + "StackTrace").FirstOrDefault()?.Value ?? "")
                .Split('\n')
                .Select(f => f.Trim())
                .Where(f => f.Length > 0 && !f.StartsWith("at System."))
                .Take(3);

            summary.AppendLine();
            summary.AppendLine($"FALLÓ {name}");
            foreach (string line in message.Split('\n')) summary.AppendLine($"  {line.TrimEnd('\r')}");
            foreach (string frame in frames) summary.AppendLine($"  {frame}");
        }

        return summary.ToString();
    }
    finally
    {
        if (Directory.Exists(resultsDir)) Directory.Delete(resultsDir, recursive: true);
    }
}

Filtrar por at System. es una regla tosca que ocultaría un fallo genuino dentro de la biblioteca base. En tres meses de uso diario eso no ha pasado ni una vez, y si pasa, el mensaje de la aserción igual nombra qué salió mal. Aquí lo tosco y barato le gana a lo ingenioso y frágil.

Los números, de punta a punta

Medido sobre una solución .NET 10 de tres proyectos con 91 tests de xUnit. Cualquier fila se reproduce con wc -c:

Fuente	Crudo	Filtrado	Proporción
Build fallido, 35 diagnósticos	20,681 B / 87 líneas	4,849 B / 37 líneas	4.3x
Tests fallidos, 2 de 91	2,291 B / 31 líneas	878 B / 17 líneas	2.6x
Archivo TRX de esa misma corrida	149,020 B	878 B	170x
Build con verbosidad normal	187,412 B	—	mejor no

Cuatro veces más pequeño no es el titular. El titular es que más o menos la mitad de lo que estaba enviando era un duplicado byte por byte, y no pude verlo hasta que lo conté.

Ejecutar el proceso sin abrir agujeros

Las tres herramientas pasan por un solo método auxiliar. Cuatro detalles suyos no son opcionales.

static async Task<ProcessResult> RunAsync(string file, string[] args, string cwd, CancellationToken ct)
{
    ProcessStartInfo psi = new()
    {
        FileName = file,
        WorkingDirectory = cwd,
        RedirectStandardOutput = true,
        RedirectStandardError = true,
        UseShellExecute = false,
    };

    // ArgumentList escapa cada valor por separado. Nunca armes la línea de
    // comando concatenando texto que viene del modelo.
    foreach (string arg in args) psi.ArgumentList.Add(arg);

    // `dotnet run` sobre un proyecto exporta MSBuildSDKsPath y MSBuildExtensionsPath del
    // SDK que compiló el AGENTE. Un `dotnet build` hijo las heredaría y cargaría los
    // targets de ese SDK aunque el global.json del repo elija otro.
    foreach (string key in psi.Environment.Keys
                 .Where(k => k.StartsWith("MSBuild", StringComparison.OrdinalIgnoreCase)).ToList())
        psi.Environment.Remove(key);

    using Process process = Process.Start(psi)
        ?? throw new InvalidOperationException($"No se pudo iniciar {file}.");

    using CancellationTokenSource timeout = CancellationTokenSource.CreateLinkedTokenSource(ct);
    timeout.CancelAfter(TimeSpan.FromMinutes(5));

    Task<string> stdout = process.StandardOutput.ReadToEndAsync(timeout.Token);
    Task<string> stderr = process.StandardError.ReadToEndAsync(timeout.Token);

    try
    {
        await process.WaitForExitAsync(timeout.Token);
    }
    catch (OperationCanceledException)
    {
        process.Kill(entireProcessTree: true);
        throw new TimeoutException($"{file} no terminó en cinco minutos.");
    }

    return new(await stdout + await stderr, process.ExitCode);
}

Usar ArgumentList en vez de una cadena unida significa que una ruta de proyecto inventada por el modelo no puede colar un segundo comando. Un dotnet test colgado tiene que morirse por su propio temporizador, o tu agente espera para siempre mientras el modelo te cobra la paciencia.

Y el proceso hijo arranca con un entorno limpio. dotnet run sobre un proyecto exporta MSBuildSDKsPath y MSBuildExtensionsPath, la ubicación del SDK que compiló tu agente, y cada dotnet build que el agente lanza las hereda. Con un solo SDK instalado nadie lo nota. El día que se instala otro (por ejemplo, una RC que llega con una actualización de Visual Studio), el global.json del repo elige un SDK y las variables heredadas cargan los targets del otro. Lanzado así contra un build con un único CS1061 real, el método original devolvió seis errores MSB4216 y seis MSB4027, y ni una palabra del CS1061: el agente informaba de una cadena de herramientas rota en lugar de tu código roto.

Y devuelve el código de salida junto con la salida. El código de salida es el veredicto, y las líneas parseadas solo lo explican: un build que falla sin archivo ni línea, como un proyecto que no existe, no le deja nada a la expresión regular, y sin el código de salida se lee como un build limpio.

Corregido en octubre de 2026. Un lector señaló que la versión original de este método descartaba el código de salida, así que dotnet_build en una carpeta sin proyecto respondía "El build terminó sin diagnósticos." mientras dotnet terminaba con código 1 y MSB1003. Tampoco limpiaba esas variables. Funcionó hasta que una máquina tuvo dos SDKs instalados, y así fue como lo descubrió la Parte 2 de esta serie. Si copiaste el código antes, toma el nuevo RunAsync y las comprobaciones del código de salida en las tres herramientas.

El system prompt es donde vive tu flujo de trabajo

Las herramientas son genéricas. Lo que vuelve tuyo al agente es el párrafo que describe el repositorio — y es la parte que todo el mundo se salta.

List<TextBlockParam> system =
[
    new()
    {
        Text = """
            Eres un asistente de desarrollo para el repositorio ClaudeReviewBot.

            Tres proyectos. src/ClaudeReviewBot.Core tiene la lógica y es el que
            importa. src/ClaudeReviewBot es un envoltorio de CLI delgado.
            tests/ es xUnit.

            TreatWarningsAsErrors está activo, así que cualquier warning rompe el
            build. CS1591 (falta comentario XML) es ruido que nunca nos ha
            importado. Los warnings de nulabilidad no son ruido: trátalos como
            defectos reales.

            Revisa el estado antes de responder. Si la pregunta es sobre el build,
            compila. Si es sobre qué cambió, llama a git_status. No especules.
            """,
        CacheControl = new CacheControlEphemeral(),
    },
];

Ese bloque es idéntico byte por byte en cada turno, y eso lo vuelve el punto de corte ideal para la caché. CacheControlEphemeral significa que lo escribes una vez y lo lees a una fracción del precio durante el resto de la sesión. Como además va delante de la conversación en el prefijo, todo el historial que viene detrás también se mantiene en caché.

Fíjate en lo que hace ese texto. Que CS1591 sea ruido y los warnings de nulabilidad no, no es un dato técnico sobre C#; es un criterio de tu equipo, y el modelo no tiene otra forma de aprenderlo. Esa frase es toda la premisa de la serie en una línea.

MessageCreateParams parameters = new()
{
    Model = "claude-opus-5",
    MaxTokens = 8000,
    System = system,
    Tools = [.. tools],
    Messages = messages,
};

La primera cosa útil que hizo

Nada de demos. Renombré una propiedad de un record usado en tres proyectos, olvidé un uso y pregunté:

por qué está en rojo el build

El agente llamó a dotnet_build, obtuvo tres errores CS1061 sin duplicar, todos nombrando ChangedFile.Patch, y después llamó a git_status por su cuenta y vio que ChangedFile.cs era el único archivo en el índice. Conectó las dos cosas: el renombrado se aplicó en la declaración y en dos de los tres lugares que la usan.

Esa segunda llamada es lo interesante. Nada en mi prompt decía que correlacionara errores de compilación con el árbol de trabajo. Tenía una herramienta capaz de decirle qué había cambiado, una pregunta que daba a entender que algo se rompió hace poco, y suficiente espacio en el contexto para pensar — porque el contexto no estaba lleno de warnings duplicados y líneas de comando de csc.

Cuándo no usar esto

Si puedes leer el error del compilador tú mismo, léelo tú mismo. Es más rápido y es gratis. Un CS1061 suelto en un archivo que acabas de tocar no necesita una ida y vuelta a un modelo de lenguaje.

Esto se gana su lugar cuando la pregunta cruza varias fuentes: un test que falla por razones que el build apenas insinúa, un cambio cuyo alcance no es evidente, el clásico lunes por la mañana de qué estaba haciendo yo. Y conviene recordar la lección de el bot de revisión de PR: a veces el número correcto de herramientas es menor del que crees, y de vez en cuando es cero.

Puntos clave

MSBuild imprime cada diagnóstico dos veces, una en línea y otra en el resumen. 70 impresos, 35 reales. Elimina duplicados por archivo, línea, columna y código antes de que nada llegue al modelo.
Pide el formato pensado para programas. git status --porcelain=v2 y dotnet test --logger trx son contratos de estabilidad; la salida de consola es una interfaz de usuario, y las interfaces cambian entre versiones del SDK.
Más grande en disco puede significar más pequeño en contexto. El archivo TRX pesa 149,020 bytes y el resumen que vale la pena enviar pesa 878. Lo consultas; nunca lo reenvías.
Subir la verbosidad empeora al agente, no lo mejora. La verbosidad normal fue nueve veces la carga para el mismo build, con líneas sueltas de 25,635 caracteres, y las respuestas se degradaron.
Las reglas de filtrado son tu flujo de trabajo. Qué warnings importan, qué proyectos importan, qué significa terminado: ese criterio no vive en otro lado que tu código de herramientas y tu system prompt.

Siguiente en la serie: Construye un agente de desarrollo .NET, Parte 2: dale voz — dictado y síntesis de voz para hablarle en vez de escribirle, por qué una respuesta hablada necesita un system prompt distinto al de una escrita, y qué le pasa al diseño de herramientas cuando la respuesta tiene que ser lo bastante corta como para escucharla.

Publicado el día 256 del año: 2^8, todo lo que cabe en un byte. Me pareció el día indicado para un post que se pasa entero contándolos.

01000110 01100101 01101100 01101001 01100011 01101001 01100100 01100001 01100100 01100101 01110011 00100000 01100100 01100101 01110110 01110011 00100001

Building a .NET Dev Agent, Part 1: Teach It Your Actual Workflow

Juan Gómez — Sun, 13 Sep 2026 12:00:00 +0000

Building a .NET Dev Agent, Part 1: Teach It Your Actual Workflow

The agent worked on the first try, which should have been my first warning.

I had wired Claude to the three commands I run all day — git status, dotnet build, dotnet test — handed it the output, and asked why my build was red. It answered correctly. Then, out of habit, I counted what I had actually sent. The build reported 70 warnings. The solution only has 35. I had been shipping Claude a verbatim second copy of every diagnostic, and Claude had been dutifully reading both.

MSBuild prints every diagnostic twice: once inline as the compiler reaches it, and once more in the summary block after Build FAILED.. Human eyes skip that second copy so completely that I had never noticed it in years of reading build output. A language model skips nothing. It reads the duplicate, you pay for the duplicate, and the model reasons about a problem that now looks twice its real size.

This post is about the unglamorous half of a dev agent: not the loop that calls the model, but what you put in front of it. The loop is about twenty lines and I have written it before. Working out what your toolchain's output actually means — and dropping the large fraction of it that means nothing — is what separates an agent that helps from one that merely bills you.

What this post assumes

The tool_use loop itself — declare tools, get a tool_use block back, execute it, return a tool_result, repeat until the model stops asking — was built step by step in Build a Claude Tool-Use Agent in C#. I am not rebuilding it here. If you have never written one, start there; everything below plugs into it.

All the examples assume .NET 10 and the official SDK:

dotnet add package Anthropic

Three tools, and why none of them is bash

The obvious move is to hand the model a single bash tool and let it run whatever it likes. That is genuinely the right call sometimes — it is what Claude Code does, and breadth is the whole point there. It is the wrong call here, for two reasons.

The first is that a bash tool hands your harness an opaque string. Every action looks identical from the outside, so there is nothing to inspect, gate, or count. A typed dotnet_build tool gives you a hook with real arguments: you can decide that a build is safe to run unattended and that anything touching the network is not.

The second is scope. git status, dotnet build and dotnet test are all read-only. That is what makes it reasonable to point this thing at your own working copy on a Friday afternoon. The moment you add bash, the blast radius becomes "anything my user account can do," and you are one confidently-worded suggestion away from a bad afternoon.

Start with bash when you want reach. Promote to typed tools when you want control. For a daily-driver agent on your own machine, control wins.

Ask for the machine-readable output, not the pretty one

Both of the tools that matter here have a second output format designed for programs, and in both cases the human-facing default is the wrong thing to parse. This is the single highest-leverage decision in the whole post, and it shows up twice.

git status prints something friendly and unstable. git status --porcelain=v2 prints a documented format with an explicit compatibility promise. dotnet test prints a readable summary; dotnet test --logger trx writes structured XML.

The counterintuitive part: the machine-readable format is usually bigger. The TRX file for my 91-test suite is 149,020 bytes, against 2,291 bytes of console output. That is fine, because you are never going to send it. You query it and emit a summary. Parsing a stable contract and discarding 99% of it beats regexing a pretty format that changes between SDK releases.

Tool one: git_status

Porcelain v2 gives one line per entry. Changed files start with 1 (ordinary) or 2 (renamed), untracked files with ?, and the --branch flag adds # branch.* headers with the ahead/behind counts.

static async Task<string> GitStatusAsync(string repo, CancellationToken ct)
{
    ProcessResult git = await RunAsync("git", ["status", "--porcelain=v2", "--branch"], repo, ct);
    if (git.ExitCode != 0) return $"git status failed (exit code {git.ExitCode}): {git.Output.Trim()}";
    string output = git.Output;

    string branch = "(detached)";
    int ahead = 0, behind = 0;
    List<string> changed = [], untracked = [];

    foreach (string raw in output.Split('\n', StringSplitOptions.RemoveEmptyEntries))
    {
        string line = raw.TrimEnd('\r');

        if (line.StartsWith("# branch.head "))
        {
            branch = line["# branch.head ".Length..];
        }
        else if (line.StartsWith("# branch.ab "))
        {
            string[] ab = line["# branch.ab ".Length..].Split(' ');
            ahead = int.Parse(ab[0]);    // "+2"
            behind = int.Parse(ab[1]);   // "-0"
        }
        else if (line.StartsWith("1 "))
        {
            // 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
            string[] f = line.Split(' ', 9);
            changed.Add($"{f[1]} {f[8]}");
        }
        else if (line.StartsWith("2 "))
        {
            // renames carry an extra score field, and the path field is "new<tab>old"
            string[] f = line.Split(' ', 10);
            string[] paths = f[9].Split('\t');
            changed.Add($"{f[1]} {paths[0]} (was {paths[1]})");
        }
        else if (line.StartsWith("? "))
        {
            untracked.Add(line[2..]);
        }
    }

    StringBuilder summary = new();
    summary.AppendLine($"branch {branch}, {ahead} ahead, {behind} behind");
    summary.AppendLine($"{changed.Count} changed, {untracked.Count} untracked");
    foreach (string entry in changed.Take(40)) summary.AppendLine($"  {entry}");
    foreach (string entry in untracked.Take(20)) summary.AppendLine($"  ?? {entry}");
    return summary.ToString();
}

The two-character XY code survives into the summary because it is the difference between "staged" and "not staged," and the model uses it. Everything else on the line — the three file modes and two object hashes — is for tooling that needs to diff, not for answering "what am I working on."

Tool two: dotnet_build, where the duplication lives

Here is what a failing build actually looks like on a three-project solution, measured rather than guessed:

87 lines, 20,681 bytes
70 warnings printed
35 warnings that exist

Every diagnostic appears exactly twice. On top of that, each printed line carries the absolute path twice — once as the file location and once again in the trailing [...csproj] marker — so a 90-character message arrives inside a 500-character line.

The fix is a regex and a dictionary. Deduplicate on the tuple that actually identifies a diagnostic — file, line, column, code — and make paths relative to the repository root:

// A source-generated regex, so the pattern is compiled at build time rather than
// at startup. It lives in a class because a file-based app has no room for a
// field: anything declared alongside top-level statements has to be a local, and
// `static readonly` there is a CS0106.
static partial class BuildOutput
{
    [GeneratedRegex(@"^(?<file>.+?)\((?<line>\d+),(?<col>\d+)\): (?<severity>error|warning) (?<code>[A-Za-z]+\d+): (?<message>.+?)(?: \[[^\]]+\])?$")]
    public static partial Regex DiagnosticLine();
}

static async Task<string> DotnetBuildAsync(string repo, string? project, CancellationToken ct)
{
    string[] args = project is null
        ? ["build", "--nologo"]
        : ["build", "--nologo", project];

    ProcessResult build = await RunAsync("dotnet", args, repo, ct);
    string output = build.Output;

    // MSBuild emits each diagnostic inline and then again in the summary block.
    Dictionary<(string, int, int, string), Diagnostic> unique = [];

    foreach (string raw in output.Split('\n'))
    {
        Match match = BuildOutput.DiagnosticLine().Match(raw.TrimEnd('\r'));
        if (!match.Success) continue;

        string file = match.Groups["file"].Value.Trim();

        // Diagnostics anchored in the SDK's own .targets files are infrastructure
        // failures, not code failures. Keep them, but don't pretend they're yours.
        string display = file.StartsWith(repo, StringComparison.OrdinalIgnoreCase)
            ? Path.GetRelativePath(repo, file).Replace('\\', '/')
            : file;

        Diagnostic diagnostic = new(
            display,
            int.Parse(match.Groups["line"].Value),
            int.Parse(match.Groups["col"].Value),
            match.Groups["severity"].Value,
            match.Groups["code"].Value,
            match.Groups["message"].Value.Trim());

        unique.TryAdd((diagnostic.File, diagnostic.Line, diagnostic.Column, diagnostic.Code), diagnostic);
    }

    List<Diagnostic> errors = [.. unique.Values.Where(d => d.Severity == "error")];
    List<Diagnostic> warnings = [.. unique.Values.Where(d => d.Severity == "warning")];

    // The exit code is the verdict; the parsed lines are only the explanation. A failure
    // with no file and line (a missing project, a bad argument) still has to read as one.
    if (build.ExitCode != 0 && errors.Count == 0)
        return $"Build failed (exit code {build.ExitCode}) with no file-located diagnostics. Last lines:\n" +
               string.Join('\n', output.Split('\n', StringSplitOptions.RemoveEmptyEntries).TakeLast(10));

    if (errors.Count == 0 && warnings.Count == 0) return "Build succeeded with no diagnostics.";

    StringBuilder summary = new();
    summary.AppendLine($"{errors.Count} error(s), {warnings.Count} warning(s).");

    // Errors first: a warning is rarely why the build is red.
    foreach (Diagnostic d in errors.Concat(warnings).Take(50))
        summary.AppendLine($"{d.File}({d.Line},{d.Column}): {d.Severity} {d.Code}: {d.Message}");

    int total = errors.Count + warnings.Count;
    if (total > 50) summary.AppendLine($"... {total - 50} more suppressed.");

    return summary.ToString();
}

Diagnostic is record Diagnostic(string File, int Line, int Column, string Severity, string Code, string Message); and RunAsync returns record ProcessResult(string Output, int ExitCode);, both declared after the last top-level statement along with BuildOutput — in a file-based app every type goes at the end of the file or you get a CS8803.

That takes the same build from 20,681 bytes to 4,849 — about a quarter of the original, with nothing of value lost. The cap matters too: a solution where one broken interface produces 900 diagnostics does not need all 900 in the context window to be diagnosed. The first fifty say the same thing.

The mistake I made first

Before any of the above, my instinct was that the agent needed more context, not less. So I raised the verbosity:

dotnet build -v n

That build is 187,412 bytes — nine times the default output, for the same three projects and the same errors. The longest single line is 25,635 characters: the complete csc invocation, every reference, every analyzer, in full. None of it explains a compile error, and all of it crowds out the three lines that do.

Verbosity flags are written for a human scrolling to find one thing. An agent reads all of it, every turn. Turning it up was the most expensive thing I did to this project, and it made the answers worse — which at least made the problem easy to spot.

Tool three: dotnet_test, via TRX

Modern dotnet test is already restrained on the console — 89 passing tests produce no output at all. But the failures repeat the same pattern: each one is announced twice, once as an [xUnit.net] line and once in the detail block.

The bigger problem is stack traces. Across my two failing tests there were six frames, and only two pointed at my code. The other four look like this:

at System.Reflection.MethodBaseInvoker.InterpretedInvoke_Method(Object obj, IntPtr* args)
at System.Reflection.MethodBaseInvoker.InvokeWithNoArgs(Object obj, BindingFlags invokeAttr)

That is the test runner reflecting its way into your test method. It is identical for every failure in every suite ever written, and it tells the model precisely nothing. Two-thirds of the stack trace is boilerplate.

TRX gives you all of this as XML with a stable schema, so you can take the three fields that matter and leave the rest on disk:

static async Task<string> DotnetTestAsync(string repo, CancellationToken ct)
{
    string resultsDir = Path.Combine(Path.GetTempPath(), $"agent-trx-{Guid.NewGuid():N}");
    try
    {
        ProcessResult run = await RunAsync("dotnet",
            ["test", "--nologo", "--logger", "trx;LogFileName=run.trx", "--results-directory", resultsDir],
            repo, ct);

        string trx = Path.Combine(resultsDir, "run.trx");
        if (!File.Exists(trx)) return $"No TRX produced (exit code {run.ExitCode}) — the test project probably failed to build.";

        XNamespace ns = "http://microsoft.com/schemas/VisualStudio/TeamTest/2010";
        XDocument doc = XDocument.Load(trx);

        XElement? counters = doc.Descendants(ns + "Counters").FirstOrDefault();
        StringBuilder summary = new();
        summary.AppendLine(
            $"{counters?.Attribute("passed")?.Value ?? "?"}/{counters?.Attribute("total")?.Value ?? "?"} passed, " +
            $"{counters?.Attribute("failed")?.Value ?? "?"} failed.");

        foreach (XElement result in doc.Descendants(ns + "UnitTestResult")
                                       .Where(r => (string?)r.Attribute("outcome") == "Failed")
                                       .Take(15))
        {
            string name = ((string?)result.Attribute("testName") ?? "(unknown)").Split('.')[^1];
            string message = result.Descendants(ns + "Message").FirstOrDefault()?.Value.Trim() ?? "";

            // Keep only frames in the project's own code.
            IEnumerable<string> frames = (result.Descendants(ns + "StackTrace").FirstOrDefault()?.Value ?? "")
                .Split('\n')
                .Select(f => f.Trim())
                .Where(f => f.Length > 0 && !f.StartsWith("at System."))
                .Take(3);

            summary.AppendLine();
            summary.AppendLine($"FAILED {name}");
            foreach (string line in message.Split('\n')) summary.AppendLine($"  {line.TrimEnd('\r')}");
            foreach (string frame in frames) summary.AppendLine($"  {frame}");
        }

        return summary.ToString();
    }
    finally
    {
        if (Directory.Exists(resultsDir)) Directory.Delete(resultsDir, recursive: true);
    }
}

Filtering at System. is a blunt rule that would hide a genuine failure inside the BCL. In three months of daily use that has not happened once, and if it does, the assertion message still names what went wrong. Blunt and cheap beats clever and fragile here.

The numbers, end to end

Measured on a three-project .NET 10 solution with 91 xUnit tests. Reproduce any row with wc -c:

Source	Raw	Filtered	Ratio
Failing build, 35 diagnostics	20,681 B / 87 lines	4,849 B / 37 lines	4.3x
Failing tests, 2 of 91	2,291 B / 31 lines	878 B / 17 lines	2.6x
TRX file for the same run	149,020 B	878 B	170x
Build at `-v n`	187,412 B	—	don't

Four times smaller is not the headline. The headline is that roughly half of what I was sending was a byte-for-byte duplicate, and I could not see it until I counted.

Running the process safely

All three tools go through one helper. Four details in it are not optional.

static async Task<ProcessResult> RunAsync(string file, string[] args, string cwd, CancellationToken ct)
{
    ProcessStartInfo psi = new()
    {
        FileName = file,
        WorkingDirectory = cwd,
        RedirectStandardOutput = true,
        RedirectStandardError = true,
        UseShellExecute = false,
    };

    // ArgumentList escapes each value individually. Never concatenate a command
    // string from model-supplied input.
    foreach (string arg in args) psi.ArgumentList.Add(arg);

    // `dotnet run` on a project exports MSBuildSDKsPath and MSBuildExtensionsPath for the
    // SDK that built the AGENT. A child `dotnet build` would inherit them and load that
    // SDK's targets even when the repo's global.json picks another one.
    foreach (string key in psi.Environment.Keys
                 .Where(k => k.StartsWith("MSBuild", StringComparison.OrdinalIgnoreCase)).ToList())
        psi.Environment.Remove(key);

    using Process process = Process.Start(psi)
        ?? throw new InvalidOperationException($"Could not start {file}.");

    using CancellationTokenSource timeout = CancellationTokenSource.CreateLinkedTokenSource(ct);
    timeout.CancelAfter(TimeSpan.FromMinutes(5));

    Task<string> stdout = process.StandardOutput.ReadToEndAsync(timeout.Token);
    Task<string> stderr = process.StandardError.ReadToEndAsync(timeout.Token);

    try
    {
        await process.WaitForExitAsync(timeout.Token);
    }
    catch (OperationCanceledException)
    {
        process.Kill(entireProcessTree: true);
        throw new TimeoutException($"{file} did not finish within five minutes.");
    }

    return new(await stdout + await stderr, process.ExitCode);
}

ArgumentList rather than a joined string means a project path the model invented cannot smuggle in a second command. A hung dotnet test has to die on its own timer, or your agent waits forever while the model sits there billing you for patience.

And the child gets a clean environment. dotnet run on a project exports MSBuildSDKsPath and MSBuildExtensionsPath, the location of the SDK that built your agent, and every dotnet build the agent launches inherits them. While one SDK is installed, nobody notices. The day a second one lands, say an RC that arrives with a Visual Studio update, the repo's global.json picks one SDK and the inherited variables load the other's targets. Run that way against a build with one real CS1061, the original helper returned six MSB4216 and six MSB4027 errors and not a word about CS1061, and the agent reported a broken toolchain instead of your broken code.

And it returns the exit code with the output. The exit code is the verdict and the parsed lines are only the explanation: a build that fails without a file and line, such as a missing project, has nothing for the regex to match, and without the exit code it reads as a clean build.

Corrected in October 2026. A reader pointed out that the original version of this helper dropped the exit code, so dotnet_build on a folder with no project answered "Build succeeded with no diagnostics." while dotnet itself exited with code 1 and MSB1003. It also did not clear those variables. It worked until a machine had two SDKs installed, which is how Part 2 of this series found it. If you copied the code before then, take the new RunAsync and the exit-code checks in the three tools.

The system prompt is where your workflow actually lives

The tools are generic. What makes the agent yours is the paragraph describing the repository — and it is the part everyone skips.

List<TextBlockParam> system =
[
    new()
    {
        Text = """
            You are a development assistant for the ClaudeReviewBot repository.

            Three projects. src/ClaudeReviewBot.Core holds the logic and is the one
            that matters. src/ClaudeReviewBot is a thin CLI wrapper. tests/ is xUnit.

            TreatWarningsAsErrors is on, so any warning fails the build. CS1591
            (missing XML comment) is noise we have never cared about. Nullable
            warnings are not noise -- treat those as real defects.

            Check state before answering. If the question is about the build, build.
            If it is about what changed, call git_status. Do not speculate.
            """,
        CacheControl = new CacheControlEphemeral(),
    },
];

That block is byte-identical on every turn, which makes it the ideal cache breakpoint. CacheControlEphemeral means you write it once and read it at a fraction of the price for the rest of the session — and since it sits ahead of the conversation in the prefix, the whole history behind it stays cached too.

Note what the text is doing. "CS1591 is noise, nullable warnings are not" is not a technical fact about C#; it is a judgement call from your team, and there is nowhere else for the model to learn it. That sentence is the entire premise of the series in one line.

MessageCreateParams parameters = new()
{
    Model = "claude-opus-5",
    MaxTokens = 8000,
    System = system,
    Tools = [.. tools],
    Messages = messages,
};

The first useful thing it did

Not a toy. I renamed a property on a record used across three projects, forgot a usage, and asked:

why is the build red

The agent called dotnet_build, got three deduplicated CS1061 errors all naming ChangedFile.Patch, then called git_status unprompted and saw that ChangedFile.cs was the only staged file. It connected the two: the rename was applied at the declaration and at two of the three call sites.

That second tool call is the interesting part. Nothing in my prompt said "correlate build errors with the working tree." It had a tool that could tell it what changed, a question that implied something recently broke, and enough room in the context to think — because the context was not full of duplicated warnings and csc command lines.

When not to reach for this

If you can read the compiler error yourself, read the compiler error yourself. It is faster and free. A single CS1061 on a file you just touched does not need a round trip to a language model.

This earns its place when the question spans sources — a test failing for reasons the build output only hints at, a change whose blast radius is not obvious, the Monday-morning "what was I even doing." And it is worth remembering the lesson from the PR review bot: sometimes the right number of tools is fewer than you think, and occasionally it is zero.

Key Takeaways

MSBuild prints every diagnostic twice — once inline, once in the summary. 70 printed, 35 real. Deduplicate on file, line, column and code before anything reaches the model.
Ask for the machine-readable format. git status --porcelain=v2 and dotnet test --logger trx are stability contracts; console output is a UI, and UIs change between SDK releases.
Bigger on disk can mean smaller in context. The TRX file is 149,020 bytes and the summary worth sending is 878. You query it; you never forward it.
Raising verbosity makes an agent worse, not better. Normal verbosity was nine times the payload for the same build, with single lines of 25,635 characters, and the answers degraded.
The filtering rules are your workflow. Which warnings matter, which projects matter, what "done" means — that judgement has no home other than your tool code and your system prompt.

Next in the series: Building a .NET Dev Agent, Part 2: Give It a Voice — speech-to-text and text-to-speech so you talk to it instead of typing, why a spoken answer needs a different system prompt than a written one, and what happens to tool design when the reply has to be short enough to listen to.

Published on the 256th day of the year: 2^8, everything a single byte can hold. Seemed like the right day for a post that spends its whole length counting them.

01001000 01100001 01110000 01110000 01111001 00100000 01100100 01100101 01110110 01110011 00100001