DEV Community: Juan Torchia

Show HN: Needle distilled Gemini tool calling into 26M parameters — technical read, zero hype

Juan Torchia — Sun, 17 May 2026 12:30:43 +0000

Show HN: Needle distilled Gemini tool calling into 26M parameters — technical read, zero hype

I was in the middle of reviewing my Ollama pipeline when the HN post appeared: Needle, a 26M parameter model distilled from Gemini specifically for tool calling. My first reaction was skeptical. 26M sounds like a toy. Then I read more carefully and understood that the interesting point isn't the size — it's the problem they're actually attacking.

Here's my technical read. No euphoria, no easy dismissal.

The real problem behind Needle and Gemini tool calling distillation

My thesis is this: the bottleneck in systems with external tools isn't the LLM's general reasoning — it's the parsability of the output. If the model produces malformed JSON, calls functions with wrong arguments, or hallucinates tool names that don't exist, the whole system breaks — doesn't matter how "intelligent" the model is at other tasks.

I ran into this directly while building agent loops with Claude Code. The most fragile part was never the reasoning; it was the reliability of the data contract. It reminded me of when I resisted TypeScript for years thinking types were bureaucracy. Then I understood that most avoidable failures start as poorly expressed data contracts. Tool calling is exactly the same: a model can be brilliant in prose and terrible at respecting a strict JSON schema under latency pressure.

Needle attacks that specific point: it takes Gemini's tool calling behavior — which is consistent and well-structured — and distills it into a small, specialized model. The hypothesis is that for this specific task, 26M parameters trained on the right behavior can outperform giant generalist models that were never fine-tuned to respect function schemas with precision.

Is it true? In their own benchmarks, according to the project repo, yes. In my own real production, I don't know yet — and that difference matters.

What knowledge distillation is and why it matters here

Knowledge distillation is a technique where a large model — the teacher — generates outputs that are then used to train a smaller model — the student. The student doesn't learn from raw data: it learns to imitate the teacher's behavior on the distributions that matter most.

# Simplified concept of the distillation pipeline for tool calling:
# 1. Teacher (Gemini) generates thousands of correct tool calling examples
# 2. Student (Needle, 26M) trains on those examples
# 3. The student learns the teacher's output distribution, not hand-written rules

For tool calling, this makes particular sense. You don't need the model to know universal history. You need it to, when you hand it this schema:

// Tool definition — the model has to respect this 100%
const tools = [
  {
    name: "search_product",
    description: "Searches for a product by ID in the catalog",
    parameters: {
      type: "object",
      properties: {
        product_id: { type: "string" },
        include_stock: { type: "boolean" }
      },
      required: ["product_id"]
    }
  }
]

Produce exactly:

{
  "name": "search_product",
  "arguments": {
    "product_id": "SKU-4821",
    "include_stock": true
  }
}

Not some creative variation with renamed keys, wrong types, or invented fields. Small generalist models fail at this constantly. If Needle solves it reliably, the use case exists.

How to test it in Ollama: a reproducible checklist

If you want to validate whether a model like Needle has a place in your stack, the criterion shouldn't be someone else's benchmark. It should be your own set of tools under your system's real conditions.

# Step 1: Install Ollama if you haven't
curl -fsSL https://ollama.com/install.sh | sh

# Step 2: When the model is available in the Ollama registry, pull directly
# (check availability at https://ollama.com/search)
ollama pull needle  # tentative name — verify the official registry

# Step 3: Prepare your own tool calling test suite
# Don't use the model README's examples; use YOUR real tools

// tool-calling-test.ts
// Validation criteria I'd use to evaluate any small model

interface TestResult {
  case: string;
  expected: object;
  received: string;
  validJson: boolean;
  schemaRespected: boolean;
  latencyMs: number;
}

async function evaluateToolCallingModel(
  model: string,
  cases: Array<{ prompt: string; expectedSchema: object }>
): Promise<TestResult[]> {
  const results: TestResult[] = [];

  for (const testCase of cases) {
    const start = Date.now();

    // Call the model via Ollama API
    const response = await fetch("http://localhost:11434/api/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        model: model,
        messages: [{ role: "user", content: testCase.prompt }],
        // Pass tools as part of the request
        tools: [testCase.expectedSchema],
        stream: false,
      }),
    });

    const data = await response.json();
    const latency = Date.now() - start;

    // Validate if the JSON is parseable and if it respects the schema
    let validJson = false;
    let schemaRespected = false;
    let received = "";

    try {
      // The tool_call should be in message.tool_calls[0]
      const toolCall = data.message?.tool_calls?.[0];
      received = JSON.stringify(toolCall ?? data.message?.content ?? "");
      validJson = !!toolCall;
      // Basic schema validation: required keys must be present
      if (toolCall?.function?.arguments) {
        const args = toolCall.function.arguments;
        const requiredKeys = Object.keys(testCase.expectedSchema);
        schemaRespected = requiredKeys.every((k) => k in args);
      }
    } catch {
      received = "parse error";
    }

    results.push({
      case: testCase.prompt.slice(0, 50),
      expected: testCase.expectedSchema,
      received,
      validJson,
      schemaRespected,
      latencyMs: latency,
    });
  }

  return results;
}

My minimum acceptance criteria for any tool calling model in a real system:

Metric	Minimum acceptable	Why
Valid JSON	99%+	A parse error in production breaks the entire flow
Schema respected	95%+	Wrong arguments are silently dangerous
p95 latency	< 500ms local	If it's slower than an external API, you've lost the point
Tool name hallucination	0%	An invented name is a non-recoverable error

The limits that the hype doesn't mention

There are three limitations that don't show up in the headlines and that I consider essential before betting on a distilled model in a real system.

First, the teacher's distribution defines the ceiling. If Gemini has biases in how it generates tool calls — certain argument patterns, certain naming conventions — the student inherits them unfiltered. This matters if your API has conventions that drift from Gemini's style.

Second, generalization to unseen schemas is an open question. A distilled model can be excellent on the patterns it learned and brittle against complex schemas with anyOf, nested $refs, or conditional validations. You have to test it explicitly against your own schemas — don't assume the general benchmark applies.

Third, 26M parameters implies limited context capacity. In systems where the prompt includes many tools simultaneously — common in backends with dozens of endpoints exposed as tools — degradation can be significant. That's a hypothesis to validate, not assume.

None of this invalidates the project. It locates it. The same discipline I applied when reviewing pnpm workspaces cache issues in CI applies here: understand the limit first, then decide if it fits.

Where Needle makes sense and where it doesn't

Scenarios where it makes sense to try Needle:

Local agent pipelines where network latency to external APIs is the bottleneck
Edge devices or resource-constrained environments where a 26M model fits in memory comfortably
Systems with a bounded and stable set of tools — not dozens of shifting schemas
As a local fallback when external APIs are unavailable

Scenarios where it probably doesn't cut it:

Systems where reasoning between tool calling steps is complex — deciding when to call which tool, not just how to call it
APIs with deeply nested or polymorphic schemas
Flows where long conversational context matters — the 26M context limit is going to hurt
Environments that need auditable safety guarantees — a privately distilled model is a considerably more opaque box

The tension that surfaced in the Spring Boot Actuator in production post applies differently here: the comfort of "it works in the demo" can hide surface risks that only show up under load or with unexpected inputs.

What this signals for the small model ecosystem

The uncomfortable thing about Needle isn't the model itself. It's what it confirms: functional specialization is going to pressure the hegemony of large general models on structured tasks.

Tool calling, intent classification, entity extraction with fixed schemas — these are tasks where a well-trained distilled model can beat GPT-4 or Claude on cost and latency without sacrificing reliability. That changes the architecture calculation.

In my current stack with Claude Code for complex reasoning and Ollama for local tasks, there's a gap exactly where Needle would aim: the tool router that decides which function to call and with what arguments, without needing the overhead of a 70B model for that. I'm not saying I'll adopt it tomorrow. I'm saying the category makes sense and the experiment deserves follow-through.

Same as when I evaluated Jakarta EE vs Spring Boot tradeoffs or compared package managers in real monorepos, the honest answer isn't "adopt it now" or "ignore it" — it's "test it against your own criteria before committing."

FAQ: Needle, distillation, and tool calling in small models

What exactly is model distillation in the LLM context?
It's a process where a large model (teacher) generates a dataset of correct behavior — in this case, well-formed tool calling examples — which is used to train a small model (student). The student learns to imitate the teacher's output distribution on the specific tasks it was distilled for, without needing the teacher's full architecture.

Is 26M parameters enough for reliable tool calling?
Depends on the scope. For a bounded set of tools with simple schemas, probably yes. For systems with dozens of complex tools, long contexts, or multi-step reasoning, it's an open hypothesis. The project's own benchmark is optimistic; validation against your own schemas is mandatory before betting on it.

How do I test it locally without risking a production system?
With Ollama, if the model is available in the registry, it's as simple as ollama pull [name] and then evaluating with your own script against the schemas you already use. The validation checklist in this post is a starting point. Always against your real tools — never against the README examples.

What's the practical difference between Needle and using function calling from OpenAI or Anthropic?
Latency, cost, and privacy. A local model has no network RTT, no per-token cost, and doesn't send your tool schemas to an external API. The tradeoff is that reliability depends entirely on the local model's training quality, without the backing of a provider with an SLA.

Is it worth it for an individual stack or only for companies with infrastructure?
A 26M model runs on a MacBook with 8GB of RAM without drama. This isn't enterprise infrastructure. If you're already using Ollama for other tasks — like I am — adding a specialized model is operationally trivial. The real cost is evaluation time, not hardware.

What happens if the model hallucinates a tool name that doesn't exist in my system?
That's the worst case and you have to design for it as an expected failure. The routing layer that consumes the model's output has to validate that the tool call name corresponds to a registered tool before executing anything. If it doesn't exist, the error has to be explicit and not silent. This is basic defensive design, independent of which model you use.

Conclusion: test it with your eyes open

I'm not going to say Needle is the future or that it's noise. My position is more specific: functional distillation of large model behavior into small specialized models is a legitimate direction, and tool calling is a use case where it makes genuine technical sense.

What I don't buy is enthusiasm without friction. A 26M model has real limits around context, generalization, and reliability on unseen schemas. Those limits don't appear in the HN post and they will appear in production.

My concrete recommendation: if you have an agent pipeline with a stable set of tools and latency is a problem, build a test harness with your own schemas, run it against the acceptance criteria in this post, and measure. If it clears 99% valid JSON and 95% schema respected on your own cases, you have something useful. If not, you know exactly why.

That's more useful than any benchmark someone else wrote.

Are you using local models for tool calling? Tell me at juanchi.dev what stack you built and where you hit the limits.

This article was originally published on juanchi.dev

Show HN: Needle distilled Gemini tool calling en 26M parámetros — lectura técnica sin hype

Juan Torchia — Sun, 17 May 2026 12:30:38 +0000

Show HN: Needle distilled Gemini tool calling en 26M parámetros — lectura técnica sin hype

Estaba revisando mi pipeline de Ollama cuando apareció el post en HN: Needle, un modelo de 26M de parámetros destilado desde Gemini específicamente para tool calling. Mi primera reacción fue escéptica. 26M suena a juguete. Después leí con más calma y entendí que el punto interesante no es el tamaño: es el problema que están atacando.

Acá va mi lectura técnica, sin euforia y sin descarte fácil.

El problema real detrás de Needle y la destilación de Gemini para tool calling

Mi tesis es esta: el cuello de botella en sistemas con herramientas externas no es el razonamiento general del LLM, sino la parsabilidad del output. Si el modelo produce JSON mal formado, llama funciones con argumentos incorrectos o alucina nombres de tools que no existen, el sistema entero se rompe — no importa qué tan "inteligente" sea el modelo en otras tareas.

Esto lo experimenté directamente mientras armaba loops de agentes con Claude Code. La parte más frágil nunca fue el razonamiento; fue la confiabilidad del contrato de datos. Me acordé de cuando me resistí a TypeScript durante años pensando que los tipos eran burocracia. Después entendí que muchas fallas evitables empiezan como contratos de datos mal expresados. Con tool calling pasa exactamente lo mismo: un modelo puede ser brillante en prosa y pésimo para respetar un esquema JSON estricto bajo presión de latencia.

Needle ataca ese punto específico: toma el comportamiento de tool calling de Gemini — que es consistente y bien estructurado — y lo destila en un modelo pequeño y especializado. La hipótesis es que para esta tarea concreta, 26M entrenados con el comportamiento correcto pueden superar a modelos gigantes generalistas que no fueron ajustados para respetar esquemas de función con precisión.

¿Es verdad? En benchmarks propios, según el repositorio del proyecto, sí. En producción real propia, no lo sé todavía — y esa diferencia importa.

Qué es la destilación de conocimiento y por qué importa aquí

La destilación de conocimiento (knowledge distillation) es una técnica donde un modelo grande — el teacher — genera outputs que después se usan para entrenar un modelo pequeño — el student. El student no aprende de datos crudos: aprende a imitar el comportamiento del teacher en las distribuciones que más importan.

# Concepto simplificado del pipeline de destilación para tool calling:
# 1. Teacher (Gemini) genera miles de ejemplos de tool calling correcto
# 2. Student (Needle, 26M) entrena sobre esos ejemplos
# 3. El student aprende la distribución de outputs del teacher, no reglas escritas a mano

Para tool calling, esto tiene sentido particular. No necesitás que el modelo sepa historia universal. Necesitás que cuando le pasés este schema:

// Definición de herramienta — el modelo tiene que respetar esto al 100%
const tools = [
  {
    name: "buscar_producto",
    description: "Busca un producto por ID en el catálogo",
    parameters: {
      type: "object",
      properties: {
        producto_id: { type: "string" },
        incluir_stock: { type: "boolean" }
      },
      required: ["producto_id"]
    }
  }
]

El output sea exactamente:

{
  "name": "buscar_producto",
  "arguments": {
    "producto_id": "SKU-4821",
    "incluir_stock": true
  }
}

Y no alguna variación creativa con claves renombradas, tipos erróneos o campos inventados. En eso los modelos pequeños generalistas fallan bastante. Si Needle lo resuelve de forma confiable, el caso de uso existe.

Cómo probarlo en Ollama: checklist reproducible

Si querés validar si un modelo como Needle tiene lugar en tu stack, el criterio no debería ser un benchmark ajeno. Debería ser tu propio conjunto de herramientas bajo las condiciones reales de tu sistema.

# Paso 1: Instalar Ollama si no lo tenés
curl -fsSL https://ollama.com/install.sh | sh

# Paso 2: Cuando el modelo esté disponible en Ollama registry, pull directo
# (verificar disponibilidad en https://ollama.com/search)
ollama pull needle  # nombre tentativo — verificar el registry oficial

# Paso 3: Preparar un set de pruebas de tool calling propio
# No uses los ejemplos del README del modelo; usá TUS herramientas reales

// prueba-tool-calling.ts
// Criterios de validación que yo usaría para evaluar cualquier modelo pequeño

interface ResultadoPrueba {
  caso: string;
  esperado: object;
  obtenido: string;
  jsonValido: boolean;
  schemaRespetado: boolean;
  latenciaMs: number;
}

async function evaluarModeloToolCalling(
  modelo: string,
  casos: Array<{ prompt: string; schemaEsperado: object }>
): Promise<ResultadoPrueba[]> {
  const resultados: ResultadoPrueba[] = [];

  for (const caso of casos) {
    const inicio = Date.now();

    // Llamada al modelo vía API de Ollama
    const respuesta = await fetch("http://localhost:11434/api/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        model: modelo,
        messages: [{ role: "user", content: caso.prompt }],
        // Pasar las herramientas como parte del request
        tools: [caso.schemaEsperado],
        stream: false,
      }),
    });

    const data = await respuesta.json();
    const latencia = Date.now() - inicio;

    // Validar si el JSON es parseable y si respeta el schema
    let jsonValido = false;
    let schemaRespetado = false;
    let obtenido = "";

    try {
      // El tool_call debería estar en message.tool_calls[0]
      const toolCall = data.message?.tool_calls?.[0];
      obtenido = JSON.stringify(toolCall ?? data.message?.content ?? "");
      jsonValido = !!toolCall;
      // Validación básica de schema: las claves required tienen que estar presentes
      if (toolCall?.function?.arguments) {
        const args = toolCall.function.arguments;
        const requiredKeys = Object.keys(caso.schemaEsperado);
        schemaRespetado = requiredKeys.every((k) => k in args);
      }
    } catch {
      obtenido = "parse error";
    }

    resultados.push({
      caso: caso.prompt.slice(0, 50),
      esperado: caso.schemaEsperado,
      obtenido,
      jsonValido,
      schemaRespetado,
      latenciaMs: latencia,
    });
  }

  return resultados;
}

Mi criterio mínimo de aceptación para cualquier modelo de tool calling en un sistema real:

Métrica	Mínimo aceptable	Por qué
JSON válido	99%+	Un parse error en producción rompe el flujo entero
Schema respetado	95%+	Argumentos incorrectos son silenciosamente peligrosos
Latencia p95	< 500ms local	Si tarda más que una API externa, perdiste el punto
Hallucination de tool names	0%	Un nombre inventado es un error no recuperable

Los límites que el hype no menciona

Hay tres limitaciones que no aparecen en los titulares y que me parecen centrales antes de apostar por un modelo destilado en un sistema real.

Primero, la distribución del teacher define el techo. Si Gemini tiene sesgos en cómo genera tool calls — ciertos patrones de argumentos, ciertas convenciones de nombrado — el student los hereda sin filtro. Esto importa si tu API tiene convenciones que se alejan del estilo de Gemini.

Segundo, la generalización a schemas no vistos es una pregunta abierta. Un modelo destilado puede ser excelente en los patrones que aprendió y frágil frente a schemas complejos con anyOf, $ref anidados o validaciones condicionales. Hay que probarlo explícitamente con los schemas propios, no asumir que el benchmark general aplica.

Tercero, el tamaño de 26M parámetros implica capacidad de contexto limitada. En sistemas donde el prompt incluye muchas herramientas al mismo tiempo — algo común en backends con docenas de endpoints expuestos como tools — la degradación puede ser significativa. Es una hipótesis que hay que validar, no asumir.

Esto no invalida el proyecto. Lo ubica. La misma disciplina que apliqué al revisar problemas de caché en CI con pnpm workspaces aplica acá: primero entender el límite, después decidir si encaja.

Dónde Needle sí tiene sentido y dónde no

Escenarios donde tiene sentido probar Needle:

Pipelines de agentes locales donde la latencia de red hacia APIs externas es el cuello de botella
Edge devices o entornos con recursos limitados donde un modelo de 26M entra en memoria cómodamente
Sistemas con un conjunto acotado y estable de herramientas — no docenas de schemas cambiantes
Como fallback local cuando las APIs externas no están disponibles

Escenarios donde probablemente no alcanza:

Sistemas donde el razonamiento entre pasos de tool calling es complejo — decidir cuándo llamar qué tool, no solo cómo llamarla
APIs con schemas profundamente anidados o polimórficos
Flujos donde el contexto conversacional largo importa — el límite de contexto de 26M va a doler
Entornos que necesitan garantías de seguridad auditables — un modelo destilado privado es una caja más opaca

La tensión que señaló el post de Spring Boot Actuator en producción aplica de otra manera acá: la comodidad de "funciona en el demo" puede esconder riesgos de superficie que solo aparecen bajo carga o con inputs inesperados.

Lo que esto anticipa para el ecosistema de modelos pequeños

Lo incómodo de Needle no es el modelo en sí. Es lo que confirma: la especialización funcional va a presionar la hegemonía de los modelos grandes generales en tareas estructuradas.

Tool calling, clasificación de intents, extracción de entidades con schema fijo — son tareas donde un modelo destilado bien entrenado puede ganarle a GPT-4 o Claude en costo y latencia sin sacrificar confiabilidad. Eso cambia el cálculo de arquitectura.

En mi stack actual con Claude Code para razonamiento complejo y Ollama para tareas locales, hay un hueco exactamente donde Needle apuntaría: el router de herramientas que decide qué función llamar y con qué argumentos, sin necesitar el overhead de un modelo de 70B para eso. No digo que lo vaya a adoptar mañana. Digo que la categoría tiene sentido y que el experimento merece seguimiento.

Al igual que cuando evalué tradeoffs de Jakarta EE vs Spring Boot o comparé gestores de paquetes en monorepos reales, la respuesta honesta no es "adoptalo ya" ni "ignoralo": es "probalo con tus propios criterios antes de comprometerte".

FAQ: Needle, destilación y tool calling en modelos pequeños

¿Qué es exactamente la destilación de modelos en el contexto de LLMs?
Es un proceso donde un modelo grande (teacher) genera un dataset de comportamiento correcto — en este caso, ejemplos de tool calling bien formados — que se usa para entrenar un modelo pequeño (student). El student aprende a imitar la distribución de outputs del teacher en las tareas específicas para las que fue destilado, sin necesitar la arquitectura completa del teacher.

¿26M parámetros es suficiente para tool calling confiable?
Depende del scope. Para un conjunto acotado de herramientas con schemas simples, probablemente sí. Para sistemas con docenas de herramientas complejas, contextos largos o razonamiento multi-paso, es una hipótesis abierta. El benchmark del proyecto es optimista; la validación con schemas propios es obligatoria antes de apostar.

¿Cómo lo pruebo localmente sin comprometer un sistema en producción?
Con Ollama, si el modelo está disponible en el registry, es tan simple como ollama pull [nombre] y después evaluar con un script propio contra los schemas que ya usás. El checklist de validación de este post es un punto de partida. Siempre contra tus herramientas reales, nunca contra los ejemplos del README.

¿Cuál es la diferencia práctica entre Needle y usar function calling de OpenAI o Anthropic?
Latencia, costo y privacidad. Un modelo local no tiene RTT de red, no tiene costo por token y no manda los schemas de tus herramientas a una API externa. La contrapartida es que la confiabilidad depende enteramente de la calidad del entrenamiento del modelo local, sin el respaldo de un proveedor con SLA.

¿Vale la pena para un stack individual o solo para empresas con infraestructura?
Un modelo de 26M entra en una MacBook con 8GB de RAM sin drama. No es infraestructura de empresa. Si ya usás Ollama para otras tareas — como yo — agregar un modelo especializado es operativamente trivial. El costo real es el tiempo de evaluación, no el hardware.

¿Qué pasa si el modelo alucina un nombre de herramienta que no existe en mi sistema?
Es el peor caso y hay que diseñarlo como falla esperada. La capa de routing que consume el output del modelo tiene que validar que el name de la tool call corresponda a una herramienta registrada antes de ejecutar. Si no existe, el error tiene que ser explícito y no silencioso. Esto es diseño defensivo básico, independiente del modelo que uses.

Conclusión: probalo con los ojos abiertos

No voy a decir que Needle es el futuro ni que es ruido. Mi postura es más específica: la destilación funcional de comportamiento de modelos grandes en modelos pequeños especializados es una dirección legítima, y tool calling es un caso de uso donde tiene sentido técnico genuino.

Lo que no compro es el entusiasmo sin fricción. Un modelo de 26M tiene límites reales de contexto, de generalización y de confiabilidad bajo schemas no vistos. Esos límites no aparecen en el post de HN y aparecerán en producción.

Mi recomendación concreta: si tenés un pipeline de agentes con un conjunto estable de herramientas y latencia es un problema, armá un harness de prueba con los schemas propios, correlo contra los criterios de aceptación del post y medí. Si pasa el umbral de 99% de JSON válido y 95% de schema respetado en tus propios casos, tenés algo útil. Si no, sabés exactamente por qué.

Eso es más útil que cualquier benchmark ajeno.

¿Estás usando modelos locales para tool calling? Contame en juanchi.dev qué stack armaste y dónde encontraste los límites.

Este artículo fue publicado originalmente en juanchi.dev

OpenTelemetry on Spring Boot 3: when logs say OK and traces show the problem

Juan Torchia — Sat, 16 May 2026 19:06:15 +0000

There's a question I've asked myself many times while debugging backend systems: did the request take long because the DB was slow, because the downstream kept us waiting, or because some internal loop fired 60 queries to fetch 60 records? The log says duration_ms=340 and status=200. That's it. You start guessing.

That moment of uncertainty is where this lab came from. Not to measure OpenTelemetry overhead, not to compare Jaeger against Tempo, but to answer something more concrete: what signals do you lose when you only have good logs, and what shows up when you add a trace?

The repo is at github.com/JuanTorchia/opentelemetry-spring-boot-lab, commit c12ea4e848dc431c8bbd324318399172302fe053, tag editorial-final-diagnosis-comparison-v2.

The setup: a lab that produces evidence, not benchmarks

The stack is Spring Boot 3.5.7, Java 21, PostgreSQL 16, OpenTelemetry API 1.43.0, OpenTelemetry Java Agent 2.9.0, and Jaeger all-in-one. Everything starts with Docker Compose. To reproduce it:

# Quick smoke test with small dataset (1k tasks)
.\scripts\run-lab.ps1 -Mode smoke -Size small

# Full editorial run (50k tasks, 200 requests, warmup 20, concurrency 8)
.\scripts\run-lab.ps1 -Mode editorial -Size editorial -Runs 3 -Requests 200 -Warmup 20 -Concurrency 8

The runner starts Compose, downloads the agent into tools/, packages the jar, seeds Postgres with synthetic tables (organizations, users, projects, tasks, comments), runs the scenarios, queries Jaeger by traceId, and regenerates the reports in results/.

Jaeger was chosen for local simplicity: one image, web UI, REST API to query traces by traceId. Tempo is also valid, but needs more moving parts for a local editorial demo. This is not a production stack recommendation.

The editorial dataset has 50,000 tasks. The small dataset has 1,000. That difference matters so the N+1 produces visible fan-out rather than a microsecond gap that disappears into noise.

The instrumentation decision I care about most

The pom.xml has opentelemetry-api as a compile dependency, but the agent arrives at runtime. That means HTTP server, HTTP client, and JDBC are instrumented automatically without touching business code.

Manual spans are used only for business stages that the agent can't infer:

// LabService.java — manual span to mark business intent
Span span = tracer.spanBuilder("business.n_plus_one.load_tasks_then_comments").startSpan();
try (var ignored = span.makeCurrent()) {
    // first fetches tasks, then runs one query per task
    List<Map<String, Object>> tasks = jdbcTemplate.queryForList(
        "select t.id, t.title, u.display_name as assignee from tasks t "
        + "join users u on u.id = t.assignee_id order by t.id limit ?",
        limit);
    for (Map<String, Object> task : tasks) {
        Long taskId = ((Number) task.get("id")).longValue();
        // this query repeats per task → fan-out
        Integer comments = jdbcTemplate.queryForObject(
            "select count(*) from comments where task_id = ?",
            Integer.class, taskId);
        // ...
    }
    span.setAttribute("lab.n_plus_one.expected_extra_queries", enriched.size());
} finally {
    span.end();
}

That mix is more honest for the post: auto-instrumentation for infrastructure, manual spans to explain intent. If I had used only manual spans, the lab would require observability-specific code in every layer. If I had relied only on the agent, business spans would be invisible.

The logback-spring.xml injects traceId and spanId into every log line:

<!-- logback-spring.xml -->
<pattern>%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX} %-5level traceId=%X{trace_id:-none} spanId=%X{span_id:-none} %logger{36} - %msg%n</pattern>

That's what connects both worlds. A log with traceId lets you jump directly to the trace in Jaeger. Without it, logs and traces are islands.

The Matrix That Summarizes The Diagnosis

Scenario	p95	Avg spans	Avg DB spans	Error spans/request	Defensible diagnosis
baseline	55 ms	3.04	1.04	0	Healthy request, no weird story.
optimized	59 ms	3.04	1.04	0	Same functional shape, no DB fan-out.
n-plus-one	209 ms	63.38	61.38	0	DB fan-out visible inside one request.
downstream-slow	374 ms	4	0	0	Time concentrates in downstream.
mixed	395 ms	7.57	1.57	0	DB, downstream, and transformation compete.
partial-error	184 ms	6.27	1.27	3	Downstream error inside a partial response.

This table is not trying to crown a tool. It summarizes which signals are available for diagnosis. The strong point is not that one number is universal: it is that N+1 leaves a very different shape than the optimized case, and that shape does not appear in a flat log unless you enable SQL debug.

What the six scenarios reveal

The lab has six endpoints: baseline, n-plus-one, optimized, downstream-slow, mixed, and partial-error. Each produces different signals that the runner consolidates into results/comparison.md and results/diagnosis-comparison.md.

The finding I most want to defend:

N+1 vs optimized: both return the same response shape. The log for both says status=200. The difference lives in the trace: n-plus-one generates an average of 63.38 spans per request in the editorial run; optimized generates 3.04. That's not a universal performance claim — it's a diagnostic signal. With only logs and no SQL debug enabled, the difference is ambiguous. With the trace, DB fan-out is visible without extra configuration.

Downstream-slow: p95 sits at 374 ms, very close to the configured 300 ms delay. Logs show total duration and traceId. What they don't show is where that time went: was it DB? was it the downstream? was it in-memory transformation? The trace separates it: the downstream HTTP client span dominates the hierarchy. The local DB appears as a secondary span with low duration.

Mixed: this is where flat logs fail the most. Three stages compete (DB, downstream, transformation) and none is obviously dominant. p95 reaches 395 ms. The trace shows the temporal distribution per stage. The log just says it was slow.

Partial-error: the endpoint responds with HTTP 206 (partial content). The log records traceId, status, and error type. The trace goes further: the downstream span is marked with error, nested under a request that technically responded. Logs and trace don't replace each other here — they complement. The log alerts and lets you correlate. The trace places the error in the causal hierarchy.

The Screenshot That Changed The Diagnosis

In Jaeger, n-plus-one does not look like a request that is merely a bit slower. It looks like a request with DB fan-out: many repeated spans under the same business operation.

The optimized case, on the other hand, keeps a compact shape. I do not need to read the code to suspect that the previous case was not "Postgres is slow" in the abstract, but the query shape.

The partial-error case matters for another reason: the request can respond, while the downstream span is marked as errored. That nuance is exactly where logs and traces complement each other: the log alerts, the trace locates.

The honest limits of the metrics

The *_vs_root_pct fields in results/diagnosis-comparison.md are cumulative percentages of span durations exported by Jaeger. They can exceed 100% when there are nested spans, client/server pairs, or overlap. The duration_denominator_type field indicates what was used as the denominator: root_span, http_request_span, or largest_observed_span if the trace was ambiguous.

These are not overhead numbers. They are not an exact distribution of real request time. They are cumulative diagnostic signals. Treating them like CPU percentages would be a misread that this lab doesn't try to encourage.

Similarly, diagnosis_confidence_* is an editorial classification coded in ScenarioDiagnosis.java, not an automatically measured metric. For N+1, diagnosisConfidenceLogs is low and diagnosisConfidenceTrace is high. That reflects the fact that without SQL debug, the log is ambiguous. It's not a universal benchmark of which tool is better.

My position: what I accept and what I don't buy

I accept that OpenTelemetry with the Java Agent is a reasonable way to add structural visibility to a Spring Boot 3 app without polluting business code. JDBC and HTTP client auto-instrumentation works well for common scenarios.

I don't buy the narrative that traces replace logs. The lab's RequestCompletionLoggingFilter is a Servlet filter that records every completed request with scenario, method, path, status, and duration. Those logs are operationally useful even when Jaeger is unavailable. The traceId in the log is the bridge, not the replacement.

I also don't buy that Jaeger is the only valid option. It was chosen because it starts with one image and has a ready web UI. Tempo, Zipkin, or any OTLP-compatible backend would solve the same problem in this context.

The honest trade-off is this: auto-instrumentation reduces accidental work but adds an agent on the classpath that exports data in the background. In a local lab that's trivial. In production, agent overhead depends on load, exporter configuration, and sampling. This lab doesn't measure that, and claiming otherwise would be misleading.

What to do with this

If you already have structured logs in production with traceId and spanId, the next step isn't replacing anything. It's adding a trace backend and connecting both worlds. The lab shows that Spring Boot 3 auto-instrumentation with the Java Agent is enough for common scenarios, and that manual spans only make sense when you want to name business intent that the agent can't infer.

If you're evaluating whether the effort is worth it: the case where it's most clearly justified isn't the healthy baseline. It's the mixed scenario or the N+1, where logs give you a number and the trace gives you a shape. The difference between guessing and diagnosing.

After this lab, my rule is simple: logs tell you what happened; traces help you understand how it happened. If the flat log only gives you total duration, you do not have an explanation yet. You have a clue.

This article was originally published on juanchi.dev

OpenTelemetry en Spring Boot 3: cuando el log dice OK y el trace muestra el problema

Juan Torchia — Sat, 16 May 2026 19:06:09 +0000

Hay una pregunta que me hice muchas veces debuggeando sistemas backend: ¿la request tardó porque la DB fue lenta, porque el downstream nos clavó, o porque algún loop interno disparó 60 queries para traer 60 registros? El log dice duration_ms=340 y status=200. Eso es todo. Empezás a adivinar.

Ese momento de incertidumbre fue el origen de este laboratorio. No para medir overhead de OpenTelemetry, no para comparar Jaeger contra Tempo, sino para responder algo más concreto: ¿qué señales perdés cuando solo tenés logs buenos, y qué aparece cuando sumás un trace?

El repo está en github.com/JuanTorchia/opentelemetry-spring-boot-lab, commit c12ea4e848dc431c8bbd324318399172302fe053, tag editorial-final-diagnosis-comparison-v2.

El setup: un laboratorio que produce evidencia, no benchmarks

El stack es Spring Boot 3.5.7, Java 21, PostgreSQL 16, OpenTelemetry API 1.43.0, OpenTelemetry Java Agent 2.9.0 y Jaeger all-in-one. Todo levanta con Docker Compose. Para reproducirlo:

# Smoke rápido con dataset pequeño (1k tasks)
.\scripts\run-lab.ps1 -Mode smoke -Size small

# Corrida editorial completa (50k tasks, 200 requests, warmup 20, concurrencia 8)
.\scripts\run-lab.ps1 -Mode editorial -Size editorial -Runs 3 -Requests 200 -Warmup 20 -Concurrency 8

El runner levanta Compose, descarga el agente en tools/, empaqueta el jar, seedea Postgres con tablas sintéticas (organizations, users, projects, tasks, comments), ejecuta los escenarios, consulta Jaeger por traceId y regenera los reportes en results/.

Jaeger fue elegido por simplicidad local: una imagen, UI web, API REST para consultar traces por traceId. Tempo también es válido, pero necesita más piezas para una demo editorial local. No es una recomendación de stack productivo.

El dataset editorial tiene 50.000 tasks. El small tiene 1.000. La diferencia importa para que el N+1 produzca fan-out visible y no una diferencia de microsegundos que desaparece en el ruido.

La decisión de instrumentación que más me importa

El pom.xml tiene opentelemetry-api como dependencia de compilación, pero el agente llega en runtime. Eso significa que HTTP server, HTTP client y JDBC se instrumentan automáticamente sin tocar el código de negocio.

Los spans manuales se usan solo para etapas de negocio que el agente no puede inferir:

// LabService.java — span manual para marcar intención de negocio
Span span = tracer.spanBuilder("business.n_plus_one.load_tasks_then_comments").startSpan();
try (var ignored = span.makeCurrent()) {
    // primero trae tasks, luego hace una query por cada una
    List<Map<String, Object>> tasks = jdbcTemplate.queryForList(
        "select t.id, t.title, u.display_name as assignee from tasks t "
        + "join users u on u.id = t.assignee_id order by t.id limit ?",
        limit);
    for (Map<String, Object> task : tasks) {
        Long taskId = ((Number) task.get("id")).longValue();
        // esta query se repite por cada task → fan-out
        Integer comments = jdbcTemplate.queryForObject(
            "select count(*) from comments where task_id = ?",
            Integer.class, taskId);
        // ...
    }
    span.setAttribute("lab.n_plus_one.expected_extra_queries", enriched.size());
} finally {
    span.end();
}

Esa mezcla es más honesta para el post: auto-instrumentación para infraestructura, spans manuales para explicar intención. Si hubiera usado solo spans manuales, el lab requeriría código específico de observabilidad en cada capa. Si hubiera confiado solo en el agente, los spans de negocio serían invisibles.

El logback-spring.xml inyecta traceId y spanId en cada línea de log:

<!-- logback-spring.xml -->
<pattern>%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX} %-5level traceId=%X{trace_id:-none} spanId=%X{span_id:-none} %logger{36} - %msg%n</pattern>

Eso es lo que conecta ambos mundos. Un log con traceId te permite saltar directo al trace en Jaeger. Sin eso, logs y traces son islas.

La matriz que resume el diagnóstico

Escenario	p95	Spans promedio	DB spans promedio	Error spans/request	Diagnóstico defendible
baseline	55 ms	3,04	1,04	0	Request sana, sin historia rara.
optimized	59 ms	3,04	1,04	0	Misma forma funcional, sin fan-out DB.
n-plus-one	209 ms	63,38	61,38	0	Fan-out DB visible en una sola request.
downstream-slow	374 ms	4	0	0	El tiempo se concentra en downstream.
mixed	395 ms	7,57	1,57	0	DB, downstream y transformación compiten.
partial-error	184 ms	6,27	1,27	3	Error downstream dentro de una respuesta parcial.

Esta tabla no intenta coronar una herramienta. Resume qué señales quedan disponibles para diagnosticar. El dato fuerte no es que un número sea universal: es que el N+1 deja una forma muy distinta al caso optimizado, y esa forma no aparece en un log plano sin activar SQL debug.

Lo que revelan los seis escenarios

El laboratorio tiene seis endpoints: baseline, n-plus-one, optimized, downstream-slow, mixed y partial-error. Cada uno produce señales diferentes que el runner consolida en results/comparison.md y results/diagnosis-comparison.md.

El hallazgo que más me interesa defender:

N+1 vs optimized: ambos devuelven el mismo shape de respuesta. El log de ambos dice status=200. La diferencia está en el trace: n-plus-one genera un promedio de 63,38 spans por request en la corrida editorial; optimized genera 3,04. Eso no es un claim de performance universal, es una señal diagnóstica. Con solo los logs, sin activar SQL debug, la diferencia es ambigua. Con el trace, el fan-out DB es visible sin configuración extra.

Downstream-slow: el p95 está en 374 ms, muy cerca del delay configurado de 300 ms. Los logs muestran la duración total y el traceId. Lo que no muestran es dónde se fue ese tiempo: ¿fue DB? ¿fue el downstream? ¿fue transformación en memoria? El trace lo separa: el span HTTP client del downstream domina la jerarquía. La DB local aparece como span secundario de duración baja.

Mixed: aquí es donde los logs planos fallan más. Tres etapas compiten (DB, downstream, transformación) y ninguna es dominante de forma obvia. El p95 llega a 395 ms. El trace muestra la distribución temporal por etapa. El log solo dice que tardó.

Partial-error: el endpoint responde con HTTP 206 (partial content). El log registra el traceId, el status y el tipo de error. El trace va más lejos: el span del downstream está marcado con error, anidado bajo una request que técnicamente respondió. Logs y trace no se reemplazan acá, se complementan. El log avisa y permite correlacionar. El trace ubica el error en la jerarquía causal.

La captura que cambió el diagnóstico

En Jaeger, n-plus-one no se ve como una request apenas más lenta. Se ve como una request con fan-out DB: muchos spans repetidos bajo una misma operación de negocio.

El caso optimizado, en cambio, mantiene una forma compacta. No necesito mirar el código para sospechar que el problema del caso anterior no era "Postgres lento" en abstracto, sino el shape de queries.

El caso de error parcial también vale por otra razón: la request puede responder, pero el span del downstream queda marcado con error. Ese matiz es justo donde logs y traces se complementan: el log avisa, el trace ubica.

El límite honesto de las métricas

Los campos *_vs_root_pct en results/diagnosis-comparison.md son porcentajes acumulados de duración de spans exportados por Jaeger. Pueden superar el 100% cuando hay spans anidados, pares cliente/servidor o solapamiento. El campo duration_denominator_type indica qué se usó como denominador: root_span, http_request_span o largest_observed_span si la traza quedó ambigua.

No son overhead. No son distribución exacta del tiempo real de la request. Son señales diagnósticas acumuladas. Usarlas como si fueran porcentajes de CPU sería un error de interpretación que este lab no intenta fomentar.

De la misma forma, diagnosis_confidence_* es una clasificación editorial codificada en ScenarioDiagnosis.java, no una métrica medida automáticamente. Para N+1, diagnosisConfidenceLogs es low y diagnosisConfidenceTrace es high. Eso refleja que sin SQL debug, el log es ambiguo. No es un benchmark universal de qué herramienta es mejor.

Mi postura: qué acepto y qué no compro

Acepto que OpenTelemetry con el Java Agent es una forma razonable de agregar visibilidad estructural a una app Spring Boot 3 sin ensuciar el código de negocio. La auto-instrumentación de JDBC y HTTP client funciona bien para escenarios comunes.

No compro la narrativa de que los traces reemplazan los logs. El RequestCompletionLoggingFilter del lab es un filtro Servlet que registra cada request completada con escenario, método, path, status y duración. Esos logs son operativamente útiles aunque Jaeger no esté disponible. El traceId en el log es el puente, no el reemplazo.

Tampoco compro que Jaeger sea la única opción válida. Se eligió porque levanta con una imagen y tiene UI web lista. Tempo, Zipkin o cualquier backend compatible con OTLP resolverían el mismo problema en este contexto.

El trade-off honesto es este: la auto-instrumentación reduce trabajo accidental pero agrega un agente en el classpath que exporta datos en background. En un laboratorio local eso es trivial. En producción, el overhead del agente depende de la carga, la configuración del exporter y el sampling. Este lab no mide eso, y sería engañoso afirmar que sí.

Qué hacer con esto

Si ya tenés logs estructurados en producción con traceId y spanId, el paso siguiente no es reemplazar nada. Es agregar el backend de traces y conectar ambos mundos. El lab muestra que la auto-instrumentación de Spring Boot 3 con el Java Agent es suficiente para los escenarios comunes, y que los spans manuales tienen sentido solo cuando querés nombrar intención de negocio que el agente no puede inferir.

Si estás evaluando si vale la pena el esfuerzo: el caso donde más claramente lo justifica no es el baseline sano. Es el escenario mixto o el N+1, donde los logs te dan un número y el trace te da una forma. La diferencia entre adivinar y diagnosticar.

Después de este lab, mi regla queda así: logs para saber qué pasó; traces para entender cómo pasó. Si el log plano te da solo duración total, todavía no tenés una explicación. Tenés una pista.

Este artículo fue publicado originalmente en juanchi.dev

Prisma vs JDBC: the benchmark that almost made me blame the wrong ORM

Juan Torchia — Sat, 16 May 2026 01:36:53 +0000

There's a discussion that surfaces every time someone posts an ORM benchmark: "of course JDBC is faster, you're measuring the abstraction". They're right, but only halfway. What nobody says is that the abstraction isn't the only culprit — sometimes the culprit is you, because you let an N+1 slip through without noticing.

I built prismavsjdbc to test this in a controlled way. It's not a benchmark about who wins. It's a lab where the same PostgreSQL 16, the same 50k-task dataset, and the same business scenarios run against two stacks: Node.js 24 LTS + TypeScript + Prisma 5 on one side, and Spring Boot 3 + Java 21 LTS + JdbcTemplate on the other. The analyzed commit is 2cd33e32bd29a1d4b46a26af0b56d6a912f5e4f5, tag best-effort-editorial-final.

The thesis I'm defending is this: query shape, SQL/request, and N+1 explain more than the slogan "ORM vs raw SQL". When you optimize the shape, both stacks improve. When you don't, both stacks charge you.

The problem that almost made me draw the wrong conclusion

The first version of the lab had an obvious trap, even though I didn't see it at first. It compared the most comfortable Prisma implementation — using include to fetch relations — against a manual join in JDBC. The result was predictable: JDBC measured 1 SQL/request, idiomatic Prisma measured 4 SQL/request on read-by-id, and latency reflected that.

Incorrect conclusion I almost published: "Prisma is slower because it emits more queries".

Correct conclusion: I was comparing different shapes. Prisma's include fires separate queries per relation — that's not a bug, it's the documented contract of the API. JDBC did a join because I wrote it that way. It's not fair to compare them without acknowledging that.

That friction changed the entire lab design: I needed three levels within each stack.

Three levels: naive, idiomatic, best-effort

Adding the level column to results/comparison.csv was the most important decision in the project. Without it, any results table is a trap for the reader.

naive: the most direct implementation possible, with no thought given to performance. In both stacks, this includes deliberate N+1 — per-task queries inside a loop.
idiomatic: the normal, maintainable way to write code in each stack. Prisma with include and _count, JDBC with the join any Java dev would write without obsessing over micro-optimizations.
best-effort: the tightest code the team would accept without it becoming a hack. For Prisma, this means dropping to $queryRaw when the shape is aggregational.

The read-by-id scenario with idiomatic Prisma measured 4 SQL/request due to include. The read-by-id-best-effort variant with $queryRaw dropped to 1 SQL/request — the same join JDBC uses. The PostgreSQL plan for that query is clean:

-- read-by-id-best-effort: same SQL in Prisma $queryRaw and in JdbcTemplate
select t.id, t.title, t.status, t.created_at as "createdAt",
       p.id as "projectId", p.name as "projectName",
       o.id as "organizationId", o.name as "organizationName",
       u.id as "assigneeId", u.display_name as "assigneeName"
from tasks t
join projects p on p.id = t.project_id
join organizations o on o.id = p.organization_id
join users u on u.id = t.assignee_id
where t.id = '00000000-0000-4000-0100-000000000001'::uuid
limit 1;
-- Execution Time: 0.242 ms, Buffers: shared hit=9

When Prisma and JDBC emit the same SQL, the PostgreSQL plan is identical. That closes the runtime debate: the bottleneck was the shape, not the client.

N+1 is the usual villain, but the lab shows it with numbers

The n-plus-one-trap scenario exists to make explicit something every developer knows in theory but underestimates in practice. The naive level in both stacks fires individual queries per task — on a 50k-task dataset with concurrency 16, that scales brutally.

The biggest jump in the lab wasn't between Prisma and JDBC. It was between naive and idiomatic within Prisma. When you go from N+1 to include/_count, the reduction in SQL/request is immediate and visible in latency. After that, if you want to squeeze more, $queryRaw gives you another jump — but smaller than the first.

The interesting part on the Java side is that CountingJdbc — the wrapper over JdbcTemplate in apps/jdbc-service/src/main/java/com/example/jdbclab/CountingJdbc.java — uses an AtomicLong to count queries. That allows an objective SQL/request comparison without relying on logs or pg_stat_statements as the primary source:

// CountingJdbc.java — instrumentation with no magic, easy to audit
@Component
public class CountingJdbc {
  private final JdbcTemplate jdbc;
  private final AtomicLong queryCount = new AtomicLong();

  public <T> List<T> query(String sql, RowMapper<T> mapper, Object... args) {
    // each call to the wrapper adds 1 to the counter
    queryCount.incrementAndGet();
    return jdbc.query(sql, mapper, args);
  }

  public long count() {
    return queryCount.get();
  }
}

On the Prisma side, the equivalent lives in apps/prisma-client/src/db.ts: it hooks into the client's query event to count. That symmetry in instrumentation is what makes the SQL/request numbers comparable across stacks.

When $queryRaw makes sense and when it's a surrender

This is the part where a lot of Prisma posts aren't honest. $queryRaw exists and is valid, but using it for everything is admitting you don't want to use Prisma — you're using PostgreSQL with a fancy TypeScript client.

The decision in the lab was clear: best-effort with $queryRaw makes sense in relation-summary and report-aggregation because the shape is genuinely aggregational. Prisma groupBy doesn't cleanly express date_trunc + join by organization, and forcing it would be worse than writing SQL.

By contrast, paginated-list has no best-effort variant because idiomatic Prisma already emits 1 SQL/request with findMany and filters. Adding $queryRaw there wouldn't change anything meaningful — it would be complexity with no benefit.

The table in docs/brief-post.md models this well: the level column isn't a scale of "how much effort you put in" but of "how much the SQL shape changes when you apply the variant".

What the lab can't guarantee

The HTTP runner is homegrown — not k6 or wrk. The hardware is local. Docker Desktop, GC, plan cache, and indexes can shift absolute latencies between runs. The editorial run used 3 runs, 300 requests per run, 30 warmup requests, concurrency 16, and a 50k-task dataset — but those numbers on different hardware can produce different results.

The version matrix (docs/java-version-matrix.md) shows Java 21 vs Java 25: there are differences, but the main argument — that N+1 and SQL/request dominate — holds on both JVMs. Java 25 improved read-by-id by ~20% over Java 21 in the local run, but that doesn't change the fact that the problem in relation-summary-naive was the shape, not the JVM.

I wouldn't publish those absolute numbers as universal truth. I publish them as evidence of a pattern: when you change the shape, the delta is orders of magnitude larger than when you change the runtime.

The position I landed on

Prisma is not slow. Prisma with include emitting 4 queries where you could emit 1 is an ergonomics trade-off with an observable cost — and that cost is worth it for most endpoints in an API that isn't under extreme pressure. When shape genuinely matters, $queryRaw exists and works well.

JDBC with JdbcTemplate is not superior just because it's raw SQL. It's predictable because the developer controls the shape from the start. The risk is on the other side: that nobody checks whether those Java loops are also doing N+1 without an ORM to blame.

The lab is reproducible. If you have Docker, Node 24 LTS, and Java 21 or 25, you can run it:

# full editorial run — Bash
bash scripts/run-lab.sh --mode editorial --size editorial --runs 3 --requests 300 --warmup 30 --concurrency 16

And if you just want to verify the scenarios run without errors before committing time:

# quick smoke test to validate the setup
bash scripts/run-lab.sh --mode smoke --size small

The code is at github.com/JuanTorchia/prismavsjdbc. Editorial results are in results/comparison.csv and results/comparison.md.

What I'd like to know: in the stack you're using right now, do you have real visibility into the SQL/request count for each endpoint? Or do you assume the ORM handles it on its own?

This article was originally published on juanchi.dev.

Prisma vs JDBC: el benchmark que casi me hace culpar al ORM equivocado

Juan Torchia — Sat, 16 May 2026 01:36:44 +0000

Hay una discusión que aparece cada vez que alguien postea un benchmark de ORM: "claro que JDBC es más rápido, estás midiendo la abstracción". Y tienen razón, pero solo a medias. Lo que nadie dice es que la abstracción no es el único culpable — a veces el culpable sos vos, que dejaste pasar un N+1 sin darte cuenta.

Armé prismavsjdbc para probar esto de forma controlada. No es un benchmark de quién gana. Es un laboratorio donde el mismo PostgreSQL 16, el mismo dataset de 50k tasks y los mismos casos de negocio corren contra dos stacks: Node.js 24 LTS + TypeScript + Prisma 5 por un lado, y Spring Boot 3 + Java 21 LTS + JdbcTemplate por el otro. El commit analizado es 2cd33e32bd29a1d4b46a26af0b56d6a912f5e4f5, tag best-effort-editorial-final.

La tesis que defiendo es esta: query shape, SQL/request y N+1 explican más que el slogan "ORM vs SQL directo". Cuando optimizás el shape, los dos stacks mejoran. Cuando no, los dos te cobran.

El problema que casi me hace concluir mal

La primera versión del laboratorio tenía una trampa obvia, aunque no la vi al principio. Comparaba la implementación más cómoda de Prisma — usando include para traer relaciones — contra un join manual en JDBC. El resultado era predecible: JDBC medía 1 SQL/request, Prisma idiomatic medía 4 SQL/request en read-by-id, y la latencia lo reflejaba.

Conclusión incorrecta que casi publico: "Prisma es más lento porque emite más queries".

Conclusión correcta: estaba comparando shapes distintos. El include de Prisma hace queries separadas por relación — no es un bug, es el contrato documentado de la API. JDBC hacía un join porque yo lo escribí así. No es fair compararlos sin reconocerlo.

Esa es la fricción que cambió todo el diseño del lab: necesitaba tres niveles dentro de cada stack.

Tres niveles: naive, idiomatic, best-effort

Agregar la columna level al results/comparison.csv fue la decisión más importante del proyecto. Sin ella, cualquier tabla de resultados es una trampa para el lector.

naive: la implementación más directa posible, sin pensar en performance. En ambos stacks, esto incluye N+1 deliberado — consultas por task dentro de un loop.
idiomatic: la forma normal y mantenible de escribir el código en cada stack. Prisma con include y _count, JDBC con el join que escribiría cualquier dev Java sin obsesionarse con micro-optimizaciones.
best-effort: el código más ajustado que acepta el equipo sin convertirse en un hack. Para Prisma, esto significa bajar a $queryRaw cuando el shape es agregacional.

El escenario read-by-id con Prisma idiomatic midió 4 SQL/request por el include. La variante read-by-id-best-effort con $queryRaw bajó a 1 SQL/request — el mismo join que usa JDBC. El plan de PostgreSQL para ese query es limpio:

-- read-by-id-best-effort: mismo SQL en Prisma $queryRaw y en JdbcTemplate
select t.id, t.title, t.status, t.created_at as "createdAt",
       p.id as "projectId", p.name as "projectName",
       o.id as "organizationId", o.name as "organizationName",
       u.id as "assigneeId", u.display_name as "assigneeName"
from tasks t
join projects p on p.id = t.project_id
join organizations o on o.id = p.organization_id
join users u on u.id = t.assignee_id
where t.id = '00000000-0000-4000-0100-000000000001'::uuid
limit 1;
-- Execution Time: 0.242 ms, Buffers: shared hit=9

Cuando Prisma y JDBC emiten el mismo SQL, el plan de PostgreSQL es idéntico. Eso cierra la discusión del runtime: el cuello de botella era el shape, no el cliente.

El N+1 es el villano de siempre, pero el lab lo muestra con números

El escenario n-plus-one-trap existe para hacer explícito algo que cualquier desarrollador sabe en teoría pero subestima en práctica. El nivel naive en ambos stacks hace consultas individuales por task — en un dataset de 50k tasks con concurrencia 16, eso escala de manera brutal.

El salto más importante en el lab no fue entre Prisma y JDBC. Fue entre naive e idiomatic dentro de Prisma. Cuando pasás de N+1 a include/_count, la reducción de SQL/request es inmediata y visible en la latencia. Después, si querés apretarlo más, $queryRaw te da otro salto — pero menor que el primero.

Lo interesante del lado Java es que CountingJdbc — el wrapper sobre JdbcTemplate que está en apps/jdbc-service/src/main/java/com/example/jdbclab/CountingJdbc.java — usa un AtomicLong para contar queries. Eso permite comparar SQL/request de forma objetiva sin depender de logs ni de pg_stat_statements como fuente principal:

// CountingJdbc.java — instrumentación sin magia, fácil de auditar
@Component
public class CountingJdbc {
  private final JdbcTemplate jdbc;
  private final AtomicLong queryCount = new AtomicLong();

  public <T> List<T> query(String sql, RowMapper<T> mapper, Object... args) {
    // cada llamada al wrapper suma 1 al contador
    queryCount.incrementAndGet();
    return jdbc.query(sql, mapper, args);
  }

  public long count() {
    return queryCount.get();
  }
}

Del lado de Prisma, el equivalente está en apps/prisma-client/src/db.ts: se engancha al evento query del cliente para contar. Esa simetría en la instrumentación es lo que hace que los números de SQL/request sean comparables entre stacks.

Cuándo $queryRaw tiene sentido y cuándo es una rendición

Esta es la parte donde muchos posts sobre Prisma no son honestos. $queryRaw existe y es válido, pero usarlo para todo es admitir que no querés usar Prisma — estás usando PostgreSQL con un cliente TypeScript de lujo.

La decisión en el lab fue clara: best-effort con $queryRaw tiene sentido en relation-summary y report-aggregation porque el shape es genuinamente agregacional. Prisma groupBy no expresa limpiamente date_trunc + join por organization, y forzarlo sería peor que escribir SQL.

En cambio, paginated-list no tiene variante best-effort porque Prisma idiomatic ya emite 1 SQL/request con findMany y filtros. Agregar $queryRaw ahí no cambiaría nada relevante — sería complejidad sin beneficio.

La tabla en docs/brief-post.md lo modela bien: la columna level no es una escala de "cuánto esfuerzo pusiste" sino de "cuánto cambia el shape SQL cuando aplicás la variante".

Lo que el lab no puede garantizar

El runner HTTP es propio — no es k6 ni wrk. El hardware es local. Docker Desktop, GC, plan cache e índices pueden mover las latencias absolutas entre corridas. La corrida editorial usó 3 runs, 300 requests por run, warmup de 30, concurrencia 16 y dataset de 50k tasks, pero esos números en otro hardware pueden dar resultados distintos.

La matriz de versiones (docs/java-version-matrix.md) muestra Java 21 vs Java 25: hay diferencias, pero el argumento principal — que N+1 y SQL/request dominan — se mantiene en ambas JVMs. Java 25 mejoró read-by-id un ~20% sobre Java 21 en la corrida local, pero eso no cambia que el problema en relation-summary-naive era el shape, no la JVM.

No publicaría esos números absolutos como verdad universal. Los publico como evidencia de un patrón: cuando cambiás el shape, el delta es órdenes de magnitud mayor que cuando cambiás el runtime.

La postura que me quedé

Prisma no es lento. Prisma con include que emite 4 queries donde podrías emitir 1 es una decisión de ergonomía que tiene un costo observable — y ese costo vale la pena en la mayoría de los endpoints de una API que no está bajo presión extrema. Cuando el shape importa de verdad, $queryRaw existe y funciona bien.

JDBC con JdbcTemplate no es superior por ser SQL directo. Es predecible porque el desarrollador controla el shape desde el primer momento. El riesgo está en el lado opuesto: que nadie revise si esos loops en Java también están haciendo N+1 sin que el ORM sea el chivo expiatorio.

El lab es reproducible. Si tenés Docker, Node 24 LTS y Java 21 o 25, podés correrlo:

# corrida editorial completa — Bash
bash scripts/run-lab.sh --mode editorial --size editorial --runs 3 --requests 300 --warmup 30 --concurrency 16

Y si querés solo verificar que los escenarios corren sin errores antes de comprometer tiempo:

# smoke rápido para validar el setup
bash scripts/run-lab.sh --mode smoke --size small

El código está en github.com/JuanTorchia/prismavsjdbc. Los resultados editoriales están en results/comparison.csv y results/comparison.md.

Lo que me gustaría saber: en el stack que usás ahora mismo, ¿tenés visibilidad real del SQL/request de cada endpoint? ¿O asumís que el ORM lo resuelve solo?

Este articulo fue publicado originalmente en juanchi.dev.

Retry isn't free: budget, amplification, and the cost that never shows up in p95

Juan Torchia — Fri, 15 May 2026 15:55:35 +0000

There's a decision I've gotten wrong more than once: adding retry as if it were a free improvement. Configure three attempts with exponential backoff, the system looks more stable on the dashboard, done. What I wasn't watching was how many extra calls I was sending to the downstream on every failure.

This post comes from an experiment I built to measure exactly that: when retry buys real availability, when it multiplies pressure, and when it simply changes nothing because the problem isn't transient. The repo is retry-resilience-experiment, commit bdfc350, with Spring Boot 3.3.5, Java 21, Resilience4j 2.2.0, and k6 as the load generator.

My thesis is simple: retry is budget. Each extra attempt consumes user wait time, hits the real downstream, and can accelerate a degradation that was already in progress. It's not a feature you flip on and call it done.

The problem with only looking at success rate

When the downstream has simulated random failures at 35%, the difference between policies is visible. With no-retry-standard-timeout, the success rate in that run was 0.6529. With immediate-retry, it climbed to 0.955. That looks like a clear win.

But the number that matters is right next to it: retry_amplification_factor. With immediate-retry on random-failures it reached 1.465. That means for every user request, the system made 1.465 real calls to the downstream. In jitter-random-failures it was 1.471. The downstream received almost 47% more traffic than k6 generated.

For transient failures that might be acceptable. The downstream is failing for external reasons, retries land at different moments, and the outcome improves. But that 47% extra isn't abstract: downstream capacity has to exist to absorb it. If the service is already at its limit, that overhead is the nudge that tips it over.

The metric the repo defines as a contract for not fooling yourself is exactly that:

// MetricSnapshot.java — this line exists to prevent self-deception
double retryAmplificationFactor, // downstream_calls / total_requests

If you only look at successRate and errorRate, you can believe you won when you actually pushed 47% more load onto a system that was already struggling.

progressive-degradation: where retry can accelerate the collapse

This scenario is the most interesting one methodologically, and also the one with the most important warning.

The PROGRESSIVE_DEGRADATION downstream implements this:

// DownstreamScenario.java — delay grows with each real call received
case PROGRESSIVE_DEGRADATION ->
    Duration.ofMillis(Math.min(900, 80 + callNumber * 3));

The delay isn't external or fixed: it grows with callNumber, which is the counter of real calls to the downstream. That means a policy with more retries generates more calls, and those calls accelerate the degradation. It's not the same failure for everyone: policies with retry degrade faster because they push harder.

The numbers from the run show this clearly. With no-retry-standard-timeout, 7720 total requests were processed and 7720 downstream calls were initiated. With immediate-retry, total requests dropped to 2939 but downstream calls went up to 8699, with an amplification factor of 2.96. The retry policy processed fewer user requests but made more downstream calls.

To be clear: this isn't a design flaw, it's the point of the experiment. The lab documents it explicitly in docs/brief-post.md: progressive-degradation should be read as load-sensitive degradation, not as an identical external failure for all policies. If you treat it as a direct comparison between policies under the same conditions, the conclusion is framed wrong from the start.

What you can conclude: in scenarios where the degradation rate depends on the volume of calls received, retries can be an accelerant. That has a name in production: retry storm. And the lab reproduces it in a controlled way.

The percentiles that lie to you when there are timeouts

There's a technical detail that changed how I read the results, and the README documents it honestly.

The caller timeout is implemented with future.cancel(true) in the RetryExecutor:

// RetryExecutor.java — cancel(true) interrupts the attempt from the caller side
try {
    future.get(policy.timeout().toMillis(), TimeUnit.MILLISECONDS);
    return new AttemptResult(true, elapsedMs(started), "ok", true);
} catch (TimeoutException timeout) {
    future.cancel(true);
    return new AttemptResult(false, elapsedMs(started), "timeout", true);
}

When an attempt exceeds the timeout, the latency recorded for that attempt is capped by the caller timeout: STANDARD_TIMEOUT = Duration.ofMillis(260). That's why in progressive-degradation almost all all_attempt_p95_ms and all_attempt_p99_ms values show exactly 260. It's not that the downstream responded in 260 ms: it's that the caller stopped waiting at 260 ms and recorded that as the attempt latency.

What happens after the cancel(true) in the simulated downstream isn't fully modeled. In a real system with HTTP, a database, or a queue, the downstream may keep executing work even after the client has given up. The lab counts initiated calls but can't guarantee there's no residual work post-cancellation.

This also matters for reading successful_requests_per_second. The value of 0.95 that appears across several progressive-degradation scenarios isn't the system's maximum capacity: it's the useful work observed under that closed k6 load. With a different VU configuration, a different duration, or a real network, the numbers would differ.

circuit-breaker and bulkhead: visible rejections as a protection signal

In progressive-degradation, the circuit breaker produces something that looks contradictory at first glance. The 13-circuit-breaker-progressive-degradation run has total_requests = 44777 and circuit_breaker_rejected = 44718. The error rate is 0.9987. That looks catastrophic.

But look at the downstream calls: 198. Amplification factor: 0.004. The circuit breaker almost completely stopped sending calls to the downstream. The rejections are visible to the client, but the downstream is protected.

Compare that with immediate-retry-progressive-degradation, which has downstream_calls = 8699 and keeps failing at the same rate, and the trade-off becomes obvious. The circuit breaker chooses to reject fast rather than multiply pressure on something that can no longer respond.

The bulkhead in the same run shows a different variant: bulkhead_rejected = 22122 with downstream_calls = 3668. It limits concurrency instead of opening the circuit, but the effect is similar: it reduces downstream pressure at the cost of visible rejections.

Those concurrency signals (max_inflight_downstream = 16 for bulkhead, 40 for most other runs) are observations, not proof of saturation. The lab renamed the metric from saturationObservation to concurrencyObservation for exactly that reason: high max_inflight doesn't prove CPU, network, or connection pool saturation. It's a signal that invites investigation, not a conclusion.

What I conclude and what I don't

This experiment is a local simulation, a single published run, against a simulated downstream with in-memory delays. The numbers don't represent production, don't represent any real provider, and don't support claiming "this policy scales to X RPS". If you want to publish exact values with strong claims, the README says it clearly: run at least three editorial runs and look for consistency, not a single pass.

What I think can be sustained:

In transient failures, retry can improve success rate but always has an amplification factor greater than 1. That overhead exists and has to fit within the system.
In load-sensitive degradation, more retries can accelerate the degradation because they generate more calls. This isn't universal, but the scenario is real and the experiment reproduces it.
p95 and p99 of attempts don't tell you the real downstream latency when there are timeouts: they tell you how long the caller waited before giving up.
Circuit breaker and bulkhead produce visible rejections that can be exactly the right decision to protect the system.

What I don't conclude: that one policy is better than another in the abstract, that these numbers apply to a different system, or that max_inflight_downstream proves saturation.

The question I'm leaving open for further exploration: how much real residual work actually remains in the downstream after a future.cancel(true) in a system with an HTTP connection pool? The lab notes it as a known limitation. In production that's exactly where the difference lies between a timeout that protects and one that only hides the problem.

The repo is at github.com/JuanTorchia/retry-resilience-experiment. If you run it and get different numbers, I want to know.

This article was originally published on juanchi.dev.

Retry no es gratis: presupuesto, amplificación y el costo que no aparece en el p95

Juan Torchia — Fri, 15 May 2026 15:55:26 +0000

Hay una decisión que tomé mal más de una vez: agregar retry como si fuera una mejora sin costo. Configuro tres intentos con backoff exponencial, el sistema se ve más estable en el dashboard, y listo. Lo que no estaba mirando era cuántas llamadas extra le estaba mandando al downstream en cada falla.

Este post nace de un experimento que armé para medir eso con precisión: cuándo retry compra disponibilidad real, cuándo multiplica presión y cuándo simplemente no cambia nada porque el problema no es transitorio. El repo es retry-resilience-experiment, commit bdfc350, con Spring Boot 3.3.5, Java 21, Resilience4j 2.2.0 y k6 como generador de carga.

Mi tesis es simple: retry es presupuesto. Cada intento extra consume tiempo de espera del usuario, llama al downstream real y puede acelerar una degradación que ya estaba en curso. No es una feature que activás y listo.

El problema de mirar solo el success rate

Cuando el downstream tiene fallas aleatorias simuladas al 35%, la diferencia entre políticas es visible. Con no-retry-standard-timeout, el success rate en esa corrida fue 0.6529. Con immediate-retry, subió a 0.955. Eso parece una victoria clara.

Pero el número que importa está al lado: el retry_amplification_factor. Con immediate-retry en random-failures llegó a 1.465. Eso significa que por cada request del usuario, el sistema hizo 1.465 llamadas reales al downstream. En jitter-random-failures fue 1.471. El downstream recibió casi un 47% más de tráfico del que generó k6.

En fallas transitorias eso puede ser aceptable. El downstream está fallando por razones externas, los reintentos aterrizan en momentos distintos y el resultado mejora. Pero ese 47% extra no es abstracto: tiene que existir capacidad downstream para absorberlo. Si el servicio ya está al límite, ese overhead es el empujón que lo tira.

La métrica que el repo define como contrato para no engañarse es exactamente esa:

// MetricSnapshot.java — la razón de esta línea es evitar autoengaño
double retryAmplificationFactor, // downstream_calls / total_requests

Si solo mirás successRate y errorRate, podés creer que ganaste cuando en realidad le metiste 47% más de carga a un sistema que ya estaba sufriendo.

progressive-degradation: donde el retry puede acelerar la caída

Este escenario es el más interesante metodológicamente, y también el que tiene la advertencia más importante.

El downstream de PROGRESSIVE_DEGRADATION implementa esto:

// DownstreamScenario.java — el delay sube con cada llamada real recibida
case PROGRESSIVE_DEGRADATION ->
    Duration.ofMillis(Math.min(900, 80 + callNumber * 3));

El delay no es externo ni fijo: crece con callNumber, que es el contador de llamadas reales al downstream. Esto significa que una política con más retries genera más llamadas, y esas llamadas aceleran la degradación. No es la misma falla para todos: las políticas con retry se degradan más rápido porque presionan más.

Los números de la corrida muestran eso claramente. Con no-retry-standard-timeout se procesaron 7720 requests totales y se iniciaron 7720 llamadas downstream. Con immediate-retry, los requests totales bajaron a 2939 pero las llamadas downstream subieron a 8699, con un amplification factor de 2.96. La policy con retry procesó menos requests de usuarios pero le hizo más llamadas al downstream.

Ahora bien: esto no es un fallo de diseño, es el punto del experimento. El laboratorio lo documenta explícitamente en docs/brief-post.md: progressive-degradation debe leerse como degradación sensible a carga, no como falla externa idéntica para todos. Si lo tratás como comparación directa entre políticas bajo las mismas condiciones, la conclusión está mal planteada desde el vantage point.

Lo que sí podés concluir: en escenarios donde la velocidad de degradación depende del volumen de llamadas recibidas, los retries pueden ser un acelerador de la caída. Eso tiene nombre en producción: retry storm. Y el laboratorio lo reproduce de forma controlada.

Los percentiles que te mienten cuando hay timeouts

Hay un detalle técnico que cambió mi forma de leer los resultados, y que el README documenta con honestidad.

El timeout del caller se implementa con future.cancel(true) en el RetryExecutor:

// RetryExecutor.java — el cancel(true) interrumpe el intento desde el caller
try {
    future.get(policy.timeout().toMillis(), TimeUnit.MILLISECONDS);
    return new AttemptResult(true, elapsedMs(started), "ok", true);
} catch (TimeoutException timeout) {
    future.cancel(true);
    return new AttemptResult(false, elapsedMs(started), "timeout", true);
}

Cuando un intento vence el timeout, la latencia registrada para ese intento está capada por el timeout del caller: STANDARD_TIMEOUT = Duration.ofMillis(260). Por eso en progressive-degradation casi todos los all_attempt_p95_ms y all_attempt_p99_ms muestran exactamente 260. No es que el downstream respondió en 260 ms: es que el caller dejó de esperar a los 260 ms y registró eso como latencia del intento.

Lo que pasa después del cancel(true) en el downstream simulado no se modela completamente. En un sistema real con HTTP, base de datos o cola, el downstream puede seguir ejecutando trabajo aunque el cliente ya no espere. El laboratorio cuenta llamadas iniciadas, pero no puede garantizar que no hay trabajo residual post-cancelación.

Esto importa para leer successful_requests_per_second también. El valor de 0.95 que aparece en varios escenarios de progressive-degradation no es la capacidad máxima del sistema: es el trabajo útil observado bajo esa carga cerrada de k6. Con otra configuración de VUs, otra duración o una red real, los números serían distintos.

circuit-breaker y bulkhead: rechazos visibles como señal de protección

En progressive-degradation, el circuit breaker produce algo que parece contradictorio al primer vistazo. La corrida 13-circuit-breaker-progressive-degradation tiene total_requests = 44777 y circuit_breaker_rejected = 44718. El error rate es 0.9987. Eso parece catastrófico.

Pero mirá las llamadas downstream: 198. Amplification factor: 0.004. El circuit breaker dejó de mandar llamadas al downstream casi por completo. Los rechazos son visibles hacia el cliente, pero el downstream está protegido.

Si comparás con immediate-retry-progressive-degradation, que tiene downstream_calls = 8699 y sigue fallando igual, el trade-off se hace evidente. El circuit breaker elige rechazar rápido antes que multiplicar presión sobre algo que ya no puede responder.

El bulkhead en la misma corrida muestra una variante distinta: bulkhead_rejected = 22122 con downstream_calls = 3668. Limita concurrencia en lugar de cortar el circuito, pero el efecto es similar: reduce presión downstream a costa de rechazos visibles.

Esas señales de concurrencia (max_inflight_downstream = 16 para bulkhead, 40 para la mayoría de las otras corridas) son observaciones, no prueba de saturación. El laboratorio renombró la métrica de saturationObservation a concurrencyObservation exactamente por eso: max_inflight alto no prueba saturación de CPU, red ni pool de conexiones. Es una señal que invita a investigar, no una conclusión.

Qué concluyo y qué no

Este experimento es una simulación local, corrida única publicada, sobre un downstream simulado con delays en memoria. Los números no representan producción, no representan ningún proveedor real y no permiten afirmar "esta política escala a X RPS". Si querés publicar valores exactos con claims fuertes, el README lo dice claramente: hacé al menos tres corridas editorial y mirá consistencia, no una sola pasada.

Lo que sí creo que puede sostenerse:

En fallas transitorias, retry puede mejorar success rate pero siempre tiene un amplification factor mayor a 1. Ese overhead existe y tiene que caber en el sistema.
En degradación sensible a carga, más retries pueden acelerar la degradación porque generan más llamadas. Esto no es universal, pero el escenario es real y el experimento lo reproduce.
p95 y p99 de intentos no te cuentan la latencia real del downstream cuando hay timeouts: te cuentan cuánto esperó el caller antes de rendirse.
Circuit breaker y bulkhead producen rechazos visibles que pueden ser exactamente la decisión correcta para proteger el sistema.

Lo que no concluyo: que una política es mejor que otra en abstracto, que estos números aplican a otro sistema, o que max_inflight_downstream prueba saturación.

La pregunta que me dejo para seguir explorando: ¿cuánto trabajo residual real queda en el downstream después de un future.cancel(true) en un sistema con pool de conexiones HTTP? El laboratorio lo anota como limitación conocida. En producción eso es exactamente donde está la diferencia entre un timeout que protege y uno que solo esconde el problema.

El repo está en github.com/JuanTorchia/retry-resilience-experiment. Si lo corrés y obtenés números distintos, me interesa saberlo.

Este articulo fue publicado originalmente en juanchi.dev.

HikariCP: the p95 that lies to you and how to read the real pool signals

Juan Torchia — Fri, 15 May 2026 03:11:26 +0000

HikariCP: the p95 that lies to you and how to read the real pool signals

There was a version of this analysis that started wrong. I was looking at the p95 for the tiny scenario with a 500ms delay and seeing 260.78ms. Compared to the default scenario showing 2418.16ms, it looked almost five times faster. That's a classic trap, and I almost fell for it.

The tiny scenario had a 97.05% error rate. Out of 8139 attempts, 7899 failed. Those 260ms were the average rejection time, not the time for a useful response. It wasn't fast — it was failing fast. And that difference matters enormously when you're trying to understand whether your HikariCP configuration is working or not.

That led me to build hikaricp-pool-experiment: a reproducible lab with Java 21, Spring Boot 3.4.5, PostgreSQL 16, HikariCP, Docker Compose, and k6 0.51.0. The goal wasn't to simulate production or document a real incident. It was to build an environment where pool signals would be visible and measurable, so I could reason about them with actual numbers.

The experiment design

The app exposes two endpoints:

GET /api/query?delayMs=500: executes a real query against PostgreSQL and holds the connection using pg_sleep for the specified duration.
GET /api/pool: returns the pool state in real time — active, idle, total, threadsAwaitingConnection, and the effective configuration.

The delayMs is the central mechanism of the experiment. An instant query can hide contention even at high concurrency because connections get released before the next request needs them. With pg_sleep(0.5), each connection stays occupied for half a second. With 50 virtual users hitting in parallel, pressure on the pool becomes visible quickly.

The k6 script does something that the original draft didn't have cleanly separated: it records query_duration for all attempts and query_success_duration only for those that return HTTP 200. Without that distinction, the p95 aggregates fast rejections with slow successful queries and the resulting number doesn't represent any useful reality.

// load/hikari-pool.js — critical separation between all attempts and successful ones
const ok = check(queryResponse, {
  'query status is 200': (response) => response.status === 200,
});
queryDuration.add(queryResponse.timings.duration);
if (ok) {
  querySuccessDuration.add(queryResponse.timings.duration);
}
queryErrors.add(!ok);

The scenarios defined in application.yml are:

Scenario	`maximumPoolSize`	`connectionTimeout`
`default`	10 (Spring Boot default)	30000ms (HikariCP default)
`tiny`	2	250ms
`pool4`	4	1500ms
`pool8`	8	1500ms
`pool16`	16	1500ms
`pool32`	32	1500ms

The matrix was run with two delays — 50ms and 500ms — because the contrast matters: a query that releases its connection quickly and a query that holds it for half a second don't stress the pool the same way.

To reproduce it from scratch:

.\scripts\run-matrix.ps1 -Vus 50 -Duration 60s

Or scenario by scenario:

docker compose down -v
.\scripts\run-scenario.ps1 -Scenario tiny -Vus 50 -Duration 60s -DelayMs 500
.\scripts\run-scenario.ps1 -Scenario pool16 -Vus 50 -Duration 60s -DelayMs 500

Important limitation: all of this is a single local run from 2026-05-14 on Windows with Docker Desktop/WSL2. The numbers are useful for comparing scenarios within the same machine. They are not a universal benchmark and don't reflect behavior in any cloud environment, Railway, or otherwise. pg_sleep holds connections artificially to make the pressure visible — it doesn't represent a real production workload.

The full results — and what to read in them

This is the table generated by summarize-results.ps1 from the k6 JSON output:

Scenario	Delay	Attempts	Successful	Failed	Error rate	Successful/s	p95 all	p95 successful	Max active	Max waiting
default	50ms	11772	11772	0	0%	195.38	165.7ms	165.7ms	10	30
default	500ms	1240	1240	0	0%	19.85	2418.16ms	2418.16ms	10	39
tiny	50ms	8289	2325	5964	71.95%	38.53	298.81ms	304.84ms	2	47
tiny	500ms	8139	240	7899	97.05%	3.97	260.78ms	752.51ms	2	47
pool4	50ms	4712	4712	0	0%	77.75	557.55ms	557.55ms	4	43
pool4	500ms	1779	492	1287	72.34%	7.95	1962.83ms	1990.52ms	4	45
pool8	50ms	9253	9253	0	0%	153.4	365.15ms	365.15ms	8	41
pool8	500ms	1653	984	669	40.47%	15.87	1996.36ms	1998.83ms	8	41
pool16	50ms	18155	18155	0	0%	301.83	82.92ms	82.92ms	16	40
pool16	500ms	1948	1947	1	0.05%	31.62	1492.44ms	1492.44ms	16	31
pool32	50ms	18892	18892	0	0%	314.16	70.33ms	70.33ms	32	32
pool32	500ms	3830	3830	0	0%	63.00	784.9ms	784.9ms	32	24

There are several things worth reading together, not in isolation.

The trap of a low p95 with a high error rate

The tiny scenario with a 500ms delay is the most instructive in the experiment. The p95 for all attempts is 260.78ms. If you only look at that number, it looks like the pool responds very quickly. But the 97.05% error rate tells you that almost no query ever executed — HikariCP was rejecting requests after connectionTimeout: 250ms because there were no free connections.

The separation between query_duration and query_success_duration makes visible what the aggregated number was hiding: the p95 for successful queries is 752.51ms — almost three times higher. Those few queries that did get a connection took nearly a second, probably because they had to wait for one of the two pool connections to be released.

When active is pinned at the pool maximum (2/2) and waiting reaches 47, the system isn't processing load — it's rejecting it. The 260ms is the time to fail, not to succeed.

Signal that matters: if p95 all attempts ≪ p95 successful and the error rate is high, the pool is in exhaustion. You're not seeing query latency — you're seeing rejection latency.

How to read the four signals together

The experiment confirmed that no single metric is enough. The signals that make sense to cross-reference are:

1. Error rate + successful queries/s

These two together are the first filter. A 0% error rate with 19.85 successful/s (default, 500ms delay) is very different from a 97% error rate with 3.97 successful/s (tiny, 500ms delay). Successful throughput tells you how much useful work the system is doing; error rate tells you how much work it's throwing away.

With pool4 at 500ms delay: 72.34% error rate with only 7.95 successful/s. Four connections with 500ms queries give a theoretical ceiling of 8 successful/s (4 connections × 2 per second). The numbers match — the pool is at its limit and rejects the rest.

2. `active = maximumPoolSize` sustained + `waiting > 0`

This combination is the most direct operational signal that the pool is under pressure. When maxActiveConnections hits the configured ceiling and maxThreadsAwaitingConnection is greater than zero for a sustained period, application threads are waiting for a connection that isn't available.

From the experiment:

tiny 500ms delay: max active 2/2, max waiting 47. Pool exhausted from the start.
pool8 500ms delay: max active 8/8, max waiting 41, error rate 40.47%. High pressure but not total.
pool32 500ms delay: max active 32/32, max waiting 24, error rate 0%. The pool hits the ceiling but absorbs the load without rejecting requests.

In pool32 with 500ms delay, waiting = 24 with 0% error rate means threads are waiting but the connectionTimeout: 1500ms is enough — queries queue up and eventually get a connection. That's a system under pressure that still works, not one in crisis.

3. Attempt latency vs. successful latency

I already covered the tiny case. But it's worth generalizing: when there's significant error rate, the p95 of all attempts stops being an application performance metric and becomes a rejection speed metric. The real operational latency is that of successful queries.

With pool4 at 500ms delay: p95 all attempts 1962.83ms, p95 successful 1990.52ms. Here the numbers are similar because queries that do get through also wait a lot — the pool has 4 connections with 500ms queries, so almost all the time is spent waiting for one to free up.

4. The jump from 50ms to 500ms as a pressure revealer

With a 50ms delay, pool8 has zero errors and processes 153.4 successful/s. With a 500ms delay, it drops to 40.47% error rate and 15.87 successful/s. The pool didn't change — the connection hold time changed. If each connection takes ten times longer to release, a pool that was previously sufficient now isn't.

This is the variable most frequently ignored when calibrating a pool: it's not just how many connections exist, but how long each query holds them. A pool of 16 connections with 50ms queries is very different from a pool of 16 connections with 500ms queries.

The diminishing returns of going from pool16 to pool32 with a short delay

There's an observation from the experiment that I think is important to avoid the easy conclusion of "more connections = better".

With 50ms delay:

pool16: 301.83 successful/s, p95 82.92ms
pool32: 314.16 successful/s, p95 70.33ms

Doubling the pool size gave only about ~4% improvement in throughput. The jump from pool8 to pool16 was much larger (153.4 → 301.83, nearly double). Beyond a certain point, the bottleneck is no longer the pool — it becomes something else. In this case, probably the Docker Desktop CPU or PostgreSQL itself under load from 50 VUs.

This is consistent with the formula Brettwooldridge mentions in the HikariCP README: the optimal pool for database throughput is not simply "as large as possible". Beyond a certain threshold, adding connections creates overhead without real benefit, and in an environment with max_connections limits on PostgreSQL, you can run out of slots before throughput improves.

The practical conclusion from the experiment isn't that 32 is the right number. It's that pool16 with a 500ms delay has a 0.05% error rate and pool32 has 0%, with 2x higher throughput. Depending on your actual query times and your PostgreSQL limits, the trade-off is different in each case.

The metrics the experiment exposes via Actuator

The app has Actuator enabled with health, info, metrics, and prometheus. During a run you can query pool state directly:

# Pool state via custom endpoint
curl http://localhost:8080/api/pool

# Micrometer metrics via Actuator
curl http://localhost:8080/actuator/metrics/hikaricp.connections.active
curl http://localhost:8080/actuator/metrics/hikaricp.connections.pending
curl http://localhost:8080/actuator/metrics/hikaricp.connections.timeout

The /api/pool endpoint uses HikariPoolMXBean directly and returns active, idle, total, threadsAwaitingConnection, and the effective configuration. That's what k6 queries in parallel to record the hikari_pool_active, hikari_pool_idle, hikari_pool_total, and hikari_pool_threads_awaiting_connection metrics.

The hikaricp.connections.timeout metric from Actuator is the one I care most about in any real environment: it counts the number of times a thread waited for a connection and the connectionTimeout expired. If that counter is greater than zero, users are being affected — that's not a warning, it's a fact.

The experiment configuration vs. configuration for a real environment

The experiment uses values designed to make pool pressure visible in a lab, not values to copy into any system. The tiny profile has connectionTimeout: 250ms because 250ms makes the pool reject requests quickly and errors become immediately visible. In a real system, 250ms is probably too aggressive — you'll generate false positives during any brief spike.

What does translate are the reading principles:

On connectionTimeout: the value defines the speed of failure, not the speed of success. A short timeout generates errors faster and makes symptoms visible sooner. A long timeout accumulates blocked threads that consume memory and can saturate the web server's thread pool before the error becomes obvious. Which one you want depends on whether you have circuit breakers and retry logic, and on how long a user can wait before the experience breaks.

On maximumPoolSize: the right number depends on the average query hold time, expected concurrency, and your PostgreSQL's max_connections limits. There's no universal formula. What the experiment shows is that with 500ms queries and 50 VUs, you need at least 16 connections to get close to zero error rate — and that doubling to 32 gives diminishing returns on throughput.

On managed cloud databases: if you use Railway, Supabase, RDS, or another service where you don't directly control the server, there's an additional parameter that matters and that this experiment doesn't cover: maxLifetime. The server may close idle connections before HikariCP's 30-minute default, and a connection that the pool thinks is alive but the server has already closed will generate PSQLException: This connection has been closed on the next use. Setting maxLifetime below the server's timeout is a necessary adjustment in those environments — but it's not something this local Docker lab can measure.

My take after the experiment

The most valuable thing from this exercise wasn't picking a connection count. It was understanding that you can't tune HikariCP by looking at a single metric.

If you only look at the p95 of all attempts, you might conclude that a pool in crisis is "fast". If you only look at error rate, you can't tell whether the system is absorbing load or rejecting it. If you only look at active, you don't know whether the pool has headroom or is at its limit. You need to cross all four: error rate, successful queries/s, active vs. configured maximum, waiting, and successful latency.

The other takeaway that stuck with me: there are two ways a pool can fail under load. One is the long timeout — threads waiting 30 seconds and eventually blowing up the heap. The other is the short timeout — fast rejections that generate a high error rate but create the illusion of low latency. The lab made both visible with real numbers.

I don't buy the idea that there's a universally correct maximumPoolSize. What there is is a correct size for your combination of query hold time, expected concurrency, and database capacity. And that number only makes sense read alongside connection hold time and error rate — not in isolation.

The repo has everything needed to run it again in your environment and compare:

.\scripts\run-matrix.ps1 -Vus 50 -Duration 60s

If you change the delay, the concurrency, or the maximumPoolSize, the signals change. That's exactly the point.

→ github.com/JuanTorchia/hikaricp-pool-experiment

Reference:

HikariCP GitHub — Configuration: https://github.com/brettwooldridge/HikariCP#gear-configuration-knobs-baby

HikariCP: el p95 que te miente y cómo leer las señales reales del pool

Juan Torchia — Fri, 15 May 2026 03:11:20 +0000

HikariCP: el p95 que te miente y cómo leer las señales reales del pool

Hubo una versión de este análisis que empezaba mal. Miraba el p95 del escenario tiny con delay de 500ms y veía 260.78ms. Comparado con el escenario default que mostraba 2418.16ms, parecía casi cinco veces más rápido. Eso es una trampa clásica, y casi me la como.

El escenario tiny tenía 97.05% de error rate. De 8139 intentos, 7899 fallaban. Los 260ms eran el tiempo promedio de rechazo, no de respuesta útil. No era rápido — estaba fallando rápido. Y la diferencia importa muchísimo cuando estás intentando entender si la configuración de HikariCP sirve o no.

Eso me llevó a armar hikaricp-pool-experiment: un laboratorio reproducible con Java 21, Spring Boot 3.4.5, PostgreSQL 16, HikariCP, Docker Compose y k6 0.51.0. El objetivo no fue simular producción ni documentar un incidente real. Fue construir un entorno donde las señales del pool fueran visibles y medibles, para poder razonar sobre ellas con números en la mano.

El diseño del experimento

La app expone dos endpoints:

GET /api/query?delayMs=500: ejecuta una consulta real contra PostgreSQL y retiene la conexión usando pg_sleep durante el tiempo indicado.
GET /api/pool: devuelve el estado del pool en tiempo real — active, idle, total, threadsAwaitingConnection y la configuración efectiva.

El delayMs es el mecanismo central del experimento. Una query instantánea puede esconder contención aunque la concurrencia sea alta porque las conexiones se liberan antes de que el siguiente request las necesite. Con pg_sleep(0.5), cada conexión queda ocupada durante medio segundo. Con 50 usuarios virtuales golpeando en paralelo, la presión sobre el pool se vuelve visible rápido.

El script de k6 hace algo que el draft original no tenía bien separado: registra query_duration para todos los intentos y query_success_duration solo para los que devuelven HTTP 200. Sin esa distinción, el p95 agrega rechazos rápidos con queries exitosas lentas y el número resultante no representa ninguna realidad útil.

// load/hikari-pool.js — separación crítica entre intentos totales y exitosos
const ok = check(queryResponse, {
  'query status is 200': (response) => response.status === 200,
});
queryDuration.add(queryResponse.timings.duration);
if (ok) {
  querySuccessDuration.add(queryResponse.timings.duration);
}
queryErrors.add(!ok);

Los escenarios definidos en application.yml son:

Escenario	`maximumPoolSize`	`connectionTimeout`
`default`	10 (Spring Boot default)	30000ms (HikariCP default)
`tiny`	2	250ms
`pool4`	4	1500ms
`pool8`	8	1500ms
`pool16`	16	1500ms
`pool32`	32	1500ms

La matriz se corrió con dos delays — 50ms y 500ms — porque el contraste es importante: una query que libera la conexión rápido y una query que la retiene durante medio segundo no estresan el pool de la misma manera.

Para reproducirlo desde cero:

.\scripts\run-matrix.ps1 -Vus 50 -Duration 60s

O escenario por escenario:

docker compose down -v
.\scripts\run-scenario.ps1 -Scenario tiny -Vus 50 -Duration 60s -DelayMs 500
.\scripts\run-scenario.ps1 -Scenario pool16 -Vus 50 -Duration 60s -DelayMs 500

Limitación importante: todo esto es un single local run del 2026-05-14 en Windows con Docker Desktop/WSL2. Los números sirven para comparar escenarios dentro de la misma máquina. No son un benchmark universal ni reflejan comportamiento en ningún entorno en la nube, Railway o de otro tipo. pg_sleep retiene conexiones de forma artificial para hacer visible la presión — no representa una workload real de producción.

Los resultados completos — y qué leer en ellos

Esta es la tabla que generó summarize-results.ps1 a partir de los JSON de k6:

Escenario	Delay	Intentos	Exitosas	Fallidas	Error rate	Exitosas/s	p95 todos	p95 exitosas	Active máx.	Waiting máx.
default	50ms	11772	11772	0	0%	195.38	165.7ms	165.7ms	10	30
default	500ms	1240	1240	0	0%	19.85	2418.16ms	2418.16ms	10	39
tiny	50ms	8289	2325	5964	71.95%	38.53	298.81ms	304.84ms	2	47
tiny	500ms	8139	240	7899	97.05%	3.97	260.78ms	752.51ms	2	47
pool4	50ms	4712	4712	0	0%	77.75	557.55ms	557.55ms	4	43
pool4	500ms	1779	492	1287	72.34%	7.95	1962.83ms	1990.52ms	4	45
pool8	50ms	9253	9253	0	0%	153.4	365.15ms	365.15ms	8	41
pool8	500ms	1653	984	669	40.47%	15.87	1996.36ms	1998.83ms	8	41
pool16	50ms	18155	18155	0	0%	301.83	82.92ms	82.92ms	16	40
pool16	500ms	1948	1947	1	0.05%	31.62	1492.44ms	1492.44ms	16	31
pool32	50ms	18892	18892	0	0%	314.16	70.33ms	70.33ms	32	32
pool32	500ms	3830	3830	0	0%	63.00	784.9ms	784.9ms	32	24

Hay varias cosas que vale la pena leer juntas, no por separado.

La trampa del p95 bajo con error rate alto

El caso tiny con delay 500ms es el más instructivo del experimento. El p95 de todos los intentos es 260.78ms. Si solo mirás ese número, parecería que el pool responde muy rápido. Pero el 97.05% de error rate te dice que casi ninguna query llegó a ejecutarse — HikariCP estaba rechazando requests en connectionTimeout: 250ms porque no había conexiones libres.

La separación entre query_duration y query_success_duration hace visible lo que el número agregado escondía: el p95 de las queries exitosas es 752.51ms — casi tres veces más. Esas pocas queries que sí consiguieron una conexión tardaron casi un segundo, probablemente porque esperaron a que alguna de las dos conexiones del pool se liberara.

Cuando active está pegado al máximo del pool (2/2) y waiting llega a 47, el sistema no está procesando carga — la está rechazando. Los 260ms son el tiempo de fracaso, no de éxito.

Señal que importa: si p95 todos los intentos ≪ p95 exitosas y el error rate es alto, el pool está en exhaustion. No estás viendo latencia de queries: estás viendo latencia de rechazo.

Cómo leer las cuatro señales en conjunto

El experimento confirmó que ninguna métrica sola alcanza. Las señales que tiene sentido cruzar son:

1. Error rate + successful queries/s

Estas dos juntas son el primer filtro. Un error rate de 0% con 19.85 exitosas/s (default, delay 500ms) es muy diferente a un error rate de 97% con 3.97 exitosas/s (tiny, delay 500ms). El throughput de exitosas dice cuánto trabajo útil hace el sistema; el error rate dice cuánto trabajo está tirando a la basura.

En pool4 con delay 500ms: 72.34% de error rate con solo 7.95 exitosas/s. Cuatro conexiones con queries de 500ms dan un techo teórico de 8 exitosas/s (4 conexiones × 2 por segundo). Los números coinciden: el pool está al límite y rechaza el resto.

2. `active = maximumPoolSize` sostenido + `waiting > 0`

Esta combinación es la señal operativa más directa de que el pool está bajo presión. Cuando maxActiveConnections bate el techo configurado y maxThreadsAwaitingConnection es mayor que cero durante un período sostenido, los threads de la aplicación están esperando una conexión que no está disponible.

Del experimento:

tiny delay 500ms: active máx. 2/2, waiting máx. 47. Pool exhausto desde el principio.
pool8 delay 500ms: active máx. 8/8, waiting máx. 41, error rate 40.47%. Presión alta pero no total.
pool32 delay 500ms: active máx. 32/32, waiting máx. 24, error rate 0%. El pool llega al techo pero absorbe la carga sin rechazar.

En pool32 con delay 500ms, waiting = 24 con error rate 0% significa que los threads esperan pero el connectionTimeout: 1500ms alcanza — las queries encolan y eventualmente consiguen conexión. Es un sistema bajo presión que aún funciona, no uno en crisis.

3. Latencia de intentos vs. latencia de exitosas

Ya mencioné el caso tiny. Pero vale generalizar: cuando hay error rate significativo, el p95 de todos los intentos deja de ser una métrica de performance de la aplicación y pasa a ser una métrica de velocidad de rechazo. La latencia operativa real es la de las queries exitosas.

En pool4 delay 500ms: p95 todos los intentos 1962.83ms, p95 exitosas 1990.52ms. Acá los números son similares porque las queries que sí pasan también esperan mucho — el pool tiene 4 conexiones con queries de 500ms, así que casi todo el tiempo está esperando que alguna se libere.

4. El salto de 50ms a 500ms como revelador de presión

Con delay 50ms, pool8 no tiene un solo error y procesa 153.4 exitosas/s. Con delay 500ms, cae a 40.47% de error rate y 15.87 exitosas/s. El pool no cambió — cambió el tiempo de retención de la conexión. Si cada conexión tarda diez veces más en liberarse, el pool que antes era suficiente ahora no alcanza.

Esta es la variable que más frecuentemente se ignora cuando se calibra un pool: no es solo cuántas conexiones hay, sino cuánto tiempo cada query las retiene. Un pool de 16 conexiones con queries de 50ms es muy diferente a un pool de 16 conexiones con queries de 500ms.

El límite del salto de pool16 a pool32 con delay corto

Hay una observación del experimento que me parece importante para evitar la conclusión fácil de "más conexiones = mejor".

Con delay 50ms:

pool16: 301.83 exitosas/s, p95 82.92ms
pool32: 314.16 exitosas/s, p95 70.33ms

Doblar el tamaño del pool dio una mejora de apenas ~4% en throughput. El salto de pool8 a pool16 fue mucho mayor (153.4 → 301.83, casi el doble). A partir de cierto punto, el cuello de botella deja de ser el pool y pasa a ser otra cosa — en este caso, probablemente el CPU del Docker Desktop o el propio PostgreSQL bajo carga de 50 VUs.

Esto es consistente con la fórmula que Brettwooldridge menciona en el README de HikariCP: el pool óptimo para throughput de base de datos no es simplemente "el más grande posible". Más allá de cierto umbral, agregar conexiones genera overhead sin beneficio real, y en un entorno con límites de max_connections en PostgreSQL podés quedarte sin slots antes de que el throughput mejore.

La conclusión práctica del experimento no es que 32 sea el número correcto. Es que pool16 con delay 500ms tiene 0.05% de error rate y pool32 tiene 0%, con un throughput 2x mayor. Dependiendo de los tiempos reales de las queries y los límites de la PostgreSQL, el trade-off es diferente en cada caso.

Las métricas que expone el experimento vía Actuator

La app tiene Actuator habilitado con health, info, metrics y prometheus. Durante una corrida podés consultar el estado del pool directamente:

# Estado del pool vía endpoint propio
curl http://localhost:8080/api/pool

# Métricas Micrometer vía Actuator
curl http://localhost:8080/actuator/metrics/hikaricp.connections.active
curl http://localhost:8080/actuator/metrics/hikaricp.connections.pending
curl http://localhost:8080/actuator/metrics/hikaricp.connections.timeout

El endpoint /api/pool usa HikariPoolMXBean directamente y devuelve active, idle, total, threadsAwaitingConnection y la configuración efectiva. Es lo que k6 consulta en paralelo para registrar las métricas hikari_pool_active, hikari_pool_idle, hikari_pool_total y hikari_pool_threads_awaiting_connection.

La métrica hikaricp.connections.timeout de Actuator es la que más me interesa en cualquier entorno real: cuenta las veces que un thread esperó una conexión y se venció el connectionTimeout. Si ese contador es mayor que cero, hay usuarios afectados — no es una advertencia, es un hecho.

La configuración del experimento vs. configuración para un entorno real

El experimento usa valores diseñados para hacer visible la presión en un laboratorio, no valores para copiar en cualquier sistema. El perfil tiny tiene connectionTimeout: 250ms porque 250ms hace que el pool rechace requests rápido y los errores sean inmediatamente visibles. En un sistema real, 250ms es probablemente demasiado agresivo — vas a generar falsos positivos ante cualquier pico breve.

Lo que sí traslada son los principios de lectura:

Sobre connectionTimeout: el valor define la velocidad del fallo, no la velocidad del éxito. Un timeout corto genera errores más rápido y hace que los síntomas sean visibles antes. Un timeout largo acumula threads bloqueados que consumen memoria y pueden saturar el thread pool del servidor web antes de que el error sea obvio. Cuál de los dos querés depende de si tenés circuit breakers y retry logic, y de cuánto tiempo puede esperar un usuario antes de que la experiencia se rompa.

Sobre maximumPoolSize: el número correcto depende del tiempo promedio de retención de las queries, la concurrencia esperada, y los límites de max_connections de la PostgreSQL. No hay una fórmula universal. Lo que el experimento muestra es que con queries de 500ms y 50 VUs, necesitás al menos 16 conexiones para llegar a error rate cercano a cero — y que doblar a 32 da rendimientos marginales decrecientes en el throughput.

Sobre bases de datos gestionadas en la nube: si usás Railway, Supabase, RDS u otro servicio donde no controlás el servidor directamente, hay un parámetro adicional que importa y que el experimento no cubre: maxLifetime. El servidor puede cerrar conexiones inactivas antes del default de 30 minutos de HikariCP, y una conexión que desde el pool "está viva" pero el servidor ya cerró va a generar PSQLException: This connection has been closed en el próximo uso. Configurar maxLifetime por debajo del timeout del servidor es un ajuste necesario en esos entornos — pero no es algo que este laboratorio local con Docker pueda medir.

Mi postura después del experimento

Lo más valioso del ejercicio no fue elegir un número de conexiones. Fue entender que HikariCP no se ajusta mirando una sola métrica.

Si solo mirás el p95 de todos los intentos, podés concluir que un pool en crisis es "rápido". Si solo mirás el error rate, no sabés si el sistema está absorbiendo carga o rechazándola. Si solo mirás active, no sabés si el pool tiene margen o está al límite. Necesitás cruzar los cuatro: error rate, successful queries/s, active vs. máximo configurado, waiting, y latencia de exitosas.

El otro aprendizaje que me quedó: hay dos formas de que un pool falle bajo carga. Una es el timeout largo — threads que esperan 30 segundos y eventualmente explotan el heap. La otra es el timeout corto — rechazos rápidos que generan error rate alto pero dan la ilusión de baja latencia. El laboratorio hizo visible las dos con números reales.

No compro la idea de que hay un maximumPoolSize correcto universal. Lo que hay es un tamaño correcto para la combinación de tiempo de query, concurrencia esperada, y capacidad de la base de datos. Y ese número solo tiene sentido leído junto con el tiempo de retención de conexiones y la tasa de error — no en aislamiento.

El repo tiene todo lo necesario para correrlo de nuevo en la entorno y comparar:

.\scripts\run-matrix.ps1 -Vus 50 -Duration 60s

Si cambiás el delay, la concurrencia o el maximumPoolSize, las señales cambian. Eso es exactamente el punto.

→ github.com/JuanTorchia/hikaricp-pool-experiment

Referencia:

HikariCP GitHub — Configuration: https://github.com/brettwooldridge/HikariCP#gear-configuration-knobs-baby

pnpm workspaces: the CI cache that survived the fix and cost me 40 minutes per build

Juan Torchia — Tue, 12 May 2026 14:31:10 +0000

pnpm workspaces: the CI cache that survived the fix and cost me 40 minutes per build

I finished my previous post convinced the monorepo was solid. Tests green, deploy successful, pnpm workspaces configured exactly as the docs say. Went to bed happy.

Next morning I checked the third CI run and saw this in the logs:

Cache not found for input keys: node-modules-cache-abc123
Run pnpm install --frozen-lockfile
...
Progress: resolved 847, reused 0, downloaded 847, added 847

reused 0. Eight hundred and forty-seven packages downloaded from scratch. Forty minutes of build time where it should've been eight.

My thesis, before I get into the details: pnpm's cache in GitHub Actions does not work out-of-the-box with monorepos. Not because pnpm is broken — pnpm is excellent, I'll say that without ambiguity — but because the store-dir in CI behaves differently than it does locally, and most people never configure it explicitly. That invisible difference destroys any cache strategy that doesn't account for it.

The real problem: pnpm store-dir in CI isn't where you think it is

When you run pnpm install on your machine, the global store lives at ~/.local/share/pnpm/store (Linux) or ~/Library/pnpm/store (macOS). Every project on your system shares that store — if a package already exists, pnpm links it with hard links. Instantaneous.

In GitHub Actions, the runner starts clean on every execution. There's no previous store. So pnpm has two possible behaviors:

Without explicit configuration: pnpm picks a dynamic path for the store — sometimes inside the workspace, sometimes in a temp dir on the runner. The path changes between runners and between runs.
With an explicit --store-dir: pnpm always uses exactly that path. You can cache that path with actions/cache and restore it on the next run.

The problem with case 1 is that actions/cache needs a fixed path to work. If the store path varies, the restore never matches even if the key is identical. The cache exists in GitHub's S3, but it never gets restored because pnpm is looking in a different directory.

This is exactly what pnpm's official CI documentation covers — but it's buried in the advanced configuration section, not in the quickstart that everyone copies.

The YAML before the fix: what everyone was copying

This was the workflow I had, assembled from a handful of tutorials:

# workflow BEFORE — broken cache in monorepo
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          # ⚠️ cache: 'pnpm' here looks like it does something, but it doesn't configure store-dir
          cache: 'pnpm'

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm run build

The cache: 'pnpm' in setup-node caches node_modules at the root project level. In a monorepo with workspaces, that's not enough: each package has its own node_modules with symlinks pointing back to the global store. If the store doesn't restore correctly, those symlinks point to nothing and pnpm reinstalls everything.

The cache miss in the logs looked like this:

##[group]Cache not found
  Key: node-modules-pnpm-store-Linux-abc1234def5678
  Restore keys attempted:
    node-modules-pnpm-store-Linux-
    node-modules-pnpm-store-
  Cache Size: ~0 B
##[endgroup]

Cache restored: zero bytes. Every run started from scratch.

The YAML after: explicit store-dir and workspace lockfile hashing

The fix requires three concrete changes:

# workflow AFTER — cache that actually works in a monorepo
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    env:
      # Fixed store path — critical so actions/cache always finds the same thing
      PNPM_STORE_PATH: ~/.pnpm-store

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          # No cache: 'pnpm' here — we manage it manually below

      - name: Get pnpm store path
        id: pnpm-cache
        run: |
          # Force the explicit store-dir so the path is predictable
          pnpm config set store-dir $PNPM_STORE_PATH
          echo "store-path=$PNPM_STORE_PATH" >> $GITHUB_OUTPUT

      - name: Restore pnpm store cache
        uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-cache.outputs.store-path }}
          # Key includes lockfile hash — invalidates when dependencies change
          key: pnpm-store-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
          # Broader restore key in case the lockfile changed partially
          restore-keys: |
            pnpm-store-${{ runner.os }}-

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build workspaces
        run: pnpm run -r build

      - name: Tests
        run: pnpm run -r test

The critical changes are in three places:

1. PNPM_STORE_PATH as a fixed environment variable. Without this, every runner picks its own path. With this, the store always lives at ~/.pnpm-store and actions/cache knows exactly what to restore.

2. pnpm config set store-dir before install. Defining the environment variable isn't enough — you have to explicitly tell pnpm to use that path. This is the line missing from 90% of the examples I found.

3. `hashFiles('/pnpm-lock.yaml').** The matters. In a monorepo you can have lockfiles per workspace in addition to the root one. With /pnpm-lock.yaml, the cache key changes if any lockfile in the repo changes. With just pnpm-lock.yaml`, you miss changes in nested workspaces.

The gotchas nobody documents

A broad `restore-keys` can cause more damage than good

With restore-keys: pnpm-store-${{ runner.os }}- you're telling GitHub Actions "if you can't find the exact key, use the most recent cache that matches this prefix." Sounds reasonable. The problem is a partially-restored store (from a different lockfile) can cause subtle conflicts where pnpm thinks a package is installed but it's missing a transitive dependency.

My solution: use the broad restore-key only to reduce initial download time, but always run pnpm install --frozen-lockfile afterwards. The --frozen-lockfile guarantees consistency even if the store is partially stale.

`pnpm run -r build` doesn't respect dependency order between workspaces by default

If apps/web depends on packages/ui, you need packages/ui to build first. pnpm run -r build runs in parallel by default. The fix:

# Respect the workspace dependency graph order
- name: Build in topological order
  run: pnpm run --filter="..." --workspace-concurrency=1 build
  # Or better yet, using the --sort flag:
  # pnpm run -r --sort build

The --sort flag makes pnpm respect the workspace dependency graph. Without this, in a monorepo with shared packages you'll see import errors for things that don't exist yet because the package you depend on hasn't compiled yet.

The cache is saved at the end of the job, not the beginning

This is actions/cache behavior that burns a lot of people: the cache is persisted when the job finishes successfully. If the job fails on the build step (after installing dependencies), the new store cache doesn't get saved. The next run downloads everything again.

To mitigate this, you can split install into its own job:

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      # Only installs and caches — always finishes successfully if deps are fine
      ...

  build:
    needs: install
    runs-on: ubuntu-latest
    steps:
      # Restores the cache from the previous job and builds
      ...

The actual numbers

In a reproducible scenario with a three-workspace monorepo (apps/web, packages/ui, packages/config) and ~850 total dependencies:

Configuration	Install time	Total CI time
No cache (downloads everything)	~22 min	~40 min
`cache: 'pnpm'` in setup-node (broken cache)	~20 min	~38 min
Explicit store-dir + lockfile hash	~1.5 min	~8 min

The "broken cache" in the second row is the most treacherous case: the workflow shows the cache step exists, the log says "Cache found" on some runs, but the restore is partial. The time drops by barely 2 minutes because something is restored — just not enough to avoid most of the downloads.

The difference between 38 and 8 minutes is exactly the kind of overhead that accumulates silently. A team of four people doing ten PRs a day is 1,200 minutes of wasted build time per week.

FAQ: pnpm workspaces cache GitHub Actions CI

Why doesn't cache: 'pnpm' in actions/setup-node work well with monorepos?

Because it caches the node_modules in the root directory but not pnpm's global store. In a monorepo with workspaces, each package has its own node_modules with symlinks pointing to the store. If the store doesn't restore correctly, pnpm detects the broken symlinks and reinstalls everything from scratch. The fix is to cache the store directly with actions/cache and an explicit path.

What path does the pnpm store use in GitHub Actions runners?

Without explicit configuration, it varies. On Ubuntu runners it might be at /home/runner/.local/share/pnpm/store or in a temp path inside the workspace. That's exactly why the first rule is to define store-dir explicitly with pnpm config set store-dir before running pnpm install.

What's the right cache key strategy for pnpm in a monorepo?

Use hashFiles('**/pnpm-lock.yaml') with the double-asterisk glob. This includes the root lockfile and any lockfiles in subdirectories. Combined with runner.os to separate caches between Linux and macOS if you run on both. The broad restore-key without the hash works as a fallback but never as the primary key.

Do I need to change anything in pnpm-workspace.yaml for better cache behavior?

Not directly. pnpm-workspace.yaml defines the workspace structure, not store behavior. What does matter is that all packages have their dependencies properly declared in their respective package.json files. If a package uses a dependency that's only in the root without declaring it, pnpm might resolve it locally but fail in CI when the store is partially restored.

Is it worth separating the install job from the build job?

Depends on the size of the monorepo. For repos with more than 500 dependencies and builds that fail frequently (tests, linting) — yes, it's worth it: it guarantees the cache gets persisted even when the build fails. For small repos where install is fast, it's unnecessary overhead.

Does this work the same with pnpm 9 and Node.js 22?

Yes. The store-dir configuration has been stable since pnpm 8. With pnpm/action-setup@v4 and actions/setup-node@v4 the setup is identical regardless of Node version. What changes between pnpm versions are some command flags — --workspace-concurrency was renamed at some point — but the cache logic is the same.

The uncomfortable thing nobody says about pnpm and CI

pnpm is the best option for monorepos — I said it when I compared pnpm vs npm vs yarn with real benchmarks and I stand by it. But it has a CI configuration curve that's genuinely frustrating because the errors are silent. The workflow "works" — CI doesn't explode, tests pass — but the cache is broken and nobody notices until someone actually looks at the timing with some attention.

The previous post about pnpm workspaces in a monorepo with Next.js 16 ended with CI green. This post is what was left unresolved: the cache that survived the initial fix and kept silently costing time on every run. The lesson isn't that pnpm is poorly documented — the official CI docs are clear if you read them completely. The lesson is that "CI working" and "CI working efficiently" are two completely different states, and the second one requires you to watch the numbers, not just the green checkmark.

If you're starting a new monorepo today, copy the fixed YAML directly. Don't use cache: 'pnpm' from setup-node as your only strategy. Configure store-dir before install. Use the **/pnpm-lock.yaml glob for the hash. That's ten extra lines that save thirty minutes per run.

For architectures where CI time matters at scale — and if you're designing distributed systems, it does — these infrastructure details are part of the job. The same rigor I apply to digital signature system design or to analyzing Jakarta EE vs Spring Boot tradeoffs applies here: reasonable defaults are rarely the correct defaults for real-world cases.

Source:

pnpm Docs — Continuous Integration

This article was originally published on juanchi.dev

pnpm workspaces: el caché de CI que sobrevivió al fix y me costó 40 minutos de build

Juan Torchia — Tue, 12 May 2026 14:31:05 +0000

pnpm workspaces: el caché de CI que sobrevivió al fix y me costó 40 minutos de build

Terminé el post anterior convencido de que el monorepo andaba. Tests en verde, deploy exitoso, pnpm workspaces configurado como la documentación dice. Me fui a dormir contento.

Al día siguiente revisé el tercer run de CI y vi esto en los logs:

Cache not found for input keys: node-modules-cache-abc123
Run pnpm install --frozen-lockfile
...
Progress: resolved 847, reused 0, downloaded 847, added 847

reused 0. Ochocientos cuarenta y siete paquetes descargados de cero. Cuarenta minutos de build donde deberían ser ocho.

Mi tesis, antes de entrar al detalle: el caché de pnpm en GitHub Actions no funciona out-of-the-box con monorepos. No porque pnpm esté roto — pnpm es excelente, lo digo sin ambigüedad — sino porque el store-dir en CI tiene un comportamiento distinto al local que la mayoría no configura explícitamente. Y esa diferencia invisible destruye cualquier estrategia de caché que no la tenga en cuenta.

El problema real: pnpm store-dir en CI no es donde pensás

Cuando corrés pnpm install en tu máquina, el store global está en ~/.local/share/pnpm/store (Linux) o ~/Library/pnpm/store (macOS). Todos los proyectos del sistema comparten ese store: si un paquete ya existe, pnpm lo linkea con hard links. Instantáneo.

En GitHub Actions, el runner arranca limpio con cada ejecución. No hay un store previo. Entonces pnpm tiene dos comportamientos posibles:

Sin configuración explícita: pnpm elige una ruta dinámica para el store — a veces dentro del workspace, a veces en un temp dir del runner. El path cambia entre runners y entre runs.
Con --store-dir explícito: pnpm siempre usa exactamente esa ruta. Podés cachear esa ruta con actions/cache y recuperarla en el próximo run.

El problema con el caso 1 es que actions/cache necesita un path fijo para funcionar. Si el path del store varía, el restore nunca hace match aunque el key sea idéntico. El caché existe en S3 de GitHub, pero nunca se restaura porque pnpm busca en otro directorio.

Esto es exactamente lo que muestra la documentación oficial de pnpm para CI — pero está enterrado en la sección de configuración avanzada, no en el quickstart que todos copian.

El YAML antes del fix: lo que copiaba todo el mundo

Este era el workflow que tenía, armado a partir de varios tutoriales:

# workflow ANTES — caché roto en monorepo
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          # ⚠️ cache: 'pnpm' acá parece que hace algo, pero no configura el store-dir
          cache: 'pnpm'

      - name: Instalar dependencias
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm run build

El cache: 'pnpm' en setup-node cachea node_modules a nivel de proyecto raíz. En un monorepo con workspaces, eso es insuficiente: cada package tiene su propio node_modules con symlinks al store global. Si el store no se restaura correctamente, los symlinks apuntan a la nada y pnpm reinstala todo.

El cache miss en los logs se veía así:

##[group]Cache not found
  Key: node-modules-pnpm-store-Linux-abc1234def5678
  Restore keys attempted:
    node-modules-pnpm-store-Linux-
    node-modules-pnpm-store-
  Cache Size: ~0 B
##[endgroup]

Tamaño de caché restaurado: cero bytes. Cada run partía de cero.

El YAML después: store-dir explícito y hash por workspace

La solución requiere tres cambios concretos:

# workflow DESPUÉS — caché que realmente funciona en monorepo
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    env:
      # Path fijo del store — crítico para que actions/cache encuentre siempre lo mismo
      PNPM_STORE_PATH: ~/.pnpm-store

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          # Sin cache: 'pnpm' acá — lo manejamos manualmente abajo

      - name: Obtener path del store de pnpm
        id: pnpm-cache
        run: |
          # Forzamos el store-dir explícito para que el path sea predecible
          pnpm config set store-dir $PNPM_STORE_PATH
          echo "store-path=$PNPM_STORE_PATH" >> $GITHUB_OUTPUT

      - name: Restaurar caché del store de pnpm
        uses: actions/cache@v4
        with:
          path: ${{ steps.pnpm-cache.outputs.store-path }}
          # Key con hash del lockfile — invalida cuando cambian dependencias
          key: pnpm-store-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
          # Restore key más amplia por si el lockfile cambió parcialmente
          restore-keys: |
            pnpm-store-${{ runner.os }}-

      - name: Instalar dependencias
        run: pnpm install --frozen-lockfile

      - name: Build workspaces
        run: pnpm run -r build

      - name: Tests
        run: pnpm run -r test

El cambio crítico está en tres lugares:

1. PNPM_STORE_PATH como variable de entorno fija. Sin esto, cada runner elige su propio path. Con esto, el store siempre vive en ~/.pnpm-store y actions/cache sabe exactamente qué restaurar.

2. pnpm config set store-dir antes del install. No alcanza con definir la variable de entorno: hay que decirle explícitamente a pnpm que use ese path. Esta es la línea que faltaba en el 90% de los ejemplos que encontré.

3. `hashFiles('/pnpm-lock.yaml').** El es importante. En un monorepo podés tener lockfiles por workspace además del raíz. Con /pnpm-lock.yaml el key de caché cambia si cualquier lockfile del repo cambia. Con solo pnpm-lock.yaml` te perdés cambios en workspaces anidados.

Los gotchas que nadie documenta

El `restore-keys` amplio puede hacer más daño que bien

Con restore-keys: pnpm-store-${{ runner.os }}- le decís a GitHub Actions "si no encontrás el key exacto, usá el caché más reciente que matchee este prefijo". Suena razonable. El problema es que un store parcialmente restaurado (de un lockfile diferente) puede causar conflictos sutiles donde pnpm cree que un paquete está instalado pero le falta una dependencia transitiva.

Mi solución: usar el restore-key amplio solo para reducir el tiempo de descarga inicial, pero siempre correr pnpm install --frozen-lockfile después. El --frozen-lockfile garantiza consistencia aunque el store esté parcialmente stale.

`pnpm run -r build` no respeta el orden de dependencias entre workspaces por default

Si el package apps/web depende de packages/ui, necesitás que packages/ui se buildee primero. pnpm run -r build corre en paralelo por default. La solución:

# Respetar el orden del workspace graph
- name: Build en orden topológico
  run: pnpm run --filter="..." --workspace-concurrency=1 build
  # O mejor aún, usando el flag --sort:
  # pnpm run -r --sort build

El flag --sort hace que pnpm respete el grafo de dependencias del workspace. Sin esto, en un monorepo con shared packages vas a ver errores de imports que no existen todavía porque el package del que dependés todavía no compiló.

El caché se guarda al final del job, no al principio

Esto es un comportamiento de actions/cache que quema a mucha gente: el caché se persiste cuando el job termina exitosamente. Si el job falla en el step de build (después de instalar dependencias), el nuevo caché del store no se guarda. El próximo run vuelve a descargar todo.

Para mitigar esto, podés separar el install en un job propio:

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      # Solo instala y cachea — siempre termina exitoso si las deps están bien
      ...

  build:
    needs: install
    runs-on: ubuntu-latest
    steps:
      # Restaura el caché del job anterior y buildea
      ...

Los números concretos

En un escenario reproducible con un monorepo de tres workspaces (apps/web, packages/ui, packages/config) y un total de ~850 dependencias:

Configuración	Tiempo de install	Tiempo total de CI
Sin caché (descarga todo)	~22 min	~40 min
`cache: 'pnpm'` en setup-node (caché roto)	~20 min	~38 min
Store-dir explícito + lockfile hash	~1.5 min	~8 min

El "caché roto" de la segunda fila es el caso más traicionero: el workflow muestra que el paso de caché existe, el log dice "Cache found" en algunas corridas, pero el restore es parcial. El tiempo baja apenas 2 minutos porque algo se restaura — pero no lo suficiente para evitar la mayoría de las descargas.

La diferencia entre 38 y 8 minutos es exactamente el tipo de overhead que se acumula silencioso. Un equipo de cuatro personas haciendo diez PRs por día son 1200 minutos de build time desperdiciado por semana.

FAQ: pnpm workspaces cache GitHub Actions CI

¿Por qué cache: 'pnpm' en actions/setup-node no funciona bien con monorepos?

Porque cachea el node_modules del directorio raíz pero no el store global de pnpm. En un monorepo con workspaces, cada package tiene su propio node_modules con symlinks al store. Si el store no se restaura correctamente, pnpm detecta que los symlinks están rotos y reinstala todo de cero. La solución es cachear el store directamente con actions/cache y un path explícito.

¿Qué path tiene el store de pnpm en GitHub Actions runners?

Sin configuración explícita, varía. En runners Ubuntu puede estar en /home/runner/.local/share/pnpm/store o en un path temporal dentro del workspace. Por eso la primera regla es definir store-dir explícitamente con pnpm config set store-dir antes de correr pnpm install.

¿Cuál es la estrategia correcta de key para el caché de pnpm en monorepo?

Usar hashFiles('**/pnpm-lock.yaml') con el glob doble asterisco. Esto incluye el lockfile raíz y cualquier lockfile en subdirectorios. Combinado con runner.os para separar caché entre Linux y macOS si corrés en ambos. El restore-key amplio sin el hash sirve como fallback pero nunca como key principal.

¿Tengo que cambiar algo en pnpm-workspace.yaml para que el caché funcione mejor?

No directamente. pnpm-workspace.yaml define la estructura del workspace, no el comportamiento del store. Lo que sí importa es que todos los packages tengan sus dependencias declaradas correctamente en sus respectivos package.json: si un package usa una dependencia que solo está en el raíz sin declararlo, pnpm puede resolver localmente pero fallar en CI cuando el store se restaura parcialmente.

¿Vale la pena separar el job de install del job de build?

Depende del tamaño del monorepo. Para repos con más de 500 dependencias y builds que pueden fallar frecuentemente (tests, linting), sí vale: garantiza que el caché se persiste incluso cuando el build falla. Para repos chicos donde el install es rápido, es overhead innecesario.

¿Esto funciona igual con pnpm 9 y Node.js 22?

Sí. La configuración del store-dir es estable desde pnpm 8. Con pnpm/action-setup@v4 y actions/setup-node@v4 el setup es el mismo independientemente de la versión de Node. Lo que cambia entre versiones de pnpm son los flags de algunos comandos — por ejemplo, --workspace-concurrency fue renombrado en algún punto — pero la lógica de caché es idéntica.

Lo incómodo que nadie dice sobre pnpm y CI

pnpm es la mejor opción para monorepos — lo dije cuando comparé pnpm vs npm vs yarn con benchmarks reales y lo sostengo. Pero tiene una curva de configuración en CI que es genuinamente frustrante porque los errores son silenciosos. El workflow "funciona" — el CI no explota, los tests pasan — pero el caché está roto y nadie lo ve hasta que alguien mira los tiempos con atención.

El post anterior sobre pnpm workspaces en monorepo con Next.js 16 terminaba con el CI verde. Este post es lo que quedó sin resolver: el caché que sobrevivió al fix inicial y siguió costando tiempo en silencio. La lección no es que pnpm esté mal documentado — la documentación oficial de CI es clara si la leés completa. La lección es que "CI funcionando" y "CI funcionando eficientemente" son dos estados completamente distintos, y el segundo requiere que prestés atención a los números, no solo al check verde.

Si arrancás un monorepo nuevo hoy, copiá el YAML del fix directamente. No uses el cache: 'pnpm' de setup-node como única estrategia. Configurá el store-dir antes del install. Usá el glob **/pnpm-lock.yaml para el hash. Son diez líneas extra que ahorran treinta minutos por run.

Para arquitecturas donde el tiempo de CI importa a escala — y si estás diseñando sistemas distribuidos, importa — estos detalles de infraestructura son parte del trabajo. El mismo criterio que aplico al diseño de sistemas de firma digital o al análisis de tradeoffs de Jakarta EE vs Spring Boot aplica acá: los defaults razonables raramente son los defaults correctos para casos reales.

Fuente original:

pnpm Docs — Continuous Integration

Este artículo fue publicado originalmente en juanchi.dev

DEV Community: Juan Torchia

Show HN: Needle distilled Gemini tool calling into 26M parameters — technical read, zero hype

Show HN: Needle distilled Gemini tool calling into 26M parameters — technical read, zero hype

The real problem behind Needle and Gemini tool calling distillation

What knowledge distillation is and why it matters here

How to test it in Ollama: a reproducible checklist

The limits that the hype doesn't mention

Where Needle makes sense and where it doesn't

What this signals for the small model ecosystem

FAQ: Needle, distillation, and tool calling in small models

Conclusion: test it with your eyes open

Show HN: Needle distilled Gemini tool calling en 26M parámetros — lectura técnica sin hype

Show HN: Needle distilled Gemini tool calling en 26M parámetros — lectura técnica sin hype

El problema real detrás de Needle y la destilación de Gemini para tool calling

Qué es la destilación de conocimiento y por qué importa aquí

Cómo probarlo en Ollama: checklist reproducible

Los límites que el hype no menciona

Dónde Needle sí tiene sentido y dónde no

Lo que esto anticipa para el ecosistema de modelos pequeños

FAQ: Needle, destilación y tool calling en modelos pequeños

Conclusión: probalo con los ojos abiertos

OpenTelemetry on Spring Boot 3: when logs say OK and traces show the problem

The setup: a lab that produces evidence, not benchmarks

The instrumentation decision I care about most

The Matrix That Summarizes The Diagnosis

What the six scenarios reveal

The Screenshot That Changed The Diagnosis

The honest limits of the metrics

My position: what I accept and what I don't buy

What to do with this

OpenTelemetry en Spring Boot 3: cuando el log dice OK y el trace muestra el problema

El setup: un laboratorio que produce evidencia, no benchmarks

La decisión de instrumentación que más me importa

La matriz que resume el diagnóstico

Lo que revelan los seis escenarios

La captura que cambió el diagnóstico

El límite honesto de las métricas

Mi postura: qué acepto y qué no compro

Qué hacer con esto

Prisma vs JDBC: the benchmark that almost made me blame the wrong ORM

The problem that almost made me draw the wrong conclusion

Three levels: naive, idiomatic, best-effort

N+1 is the usual villain, but the lab shows it with numbers

When $queryRaw makes sense and when it's a surrender

What the lab can't guarantee

The position I landed on

Prisma vs JDBC: el benchmark que casi me hace culpar al ORM equivocado

El problema que casi me hace concluir mal

Tres niveles: naive, idiomatic, best-effort

El N+1 es el villano de siempre, pero el lab lo muestra con números

Cuándo $queryRaw tiene sentido y cuándo es una rendición

Lo que el lab no puede garantizar

La postura que me quedé

Retry isn't free: budget, amplification, and the cost that never shows up in p95

The problem with only looking at success rate

progressive-degradation: where retry can accelerate the collapse

The percentiles that lie to you when there are timeouts

circuit-breaker and bulkhead: visible rejections as a protection signal

What I conclude and what I don't

Retry no es gratis: presupuesto, amplificación y el costo que no aparece en el p95

El problema de mirar solo el success rate

progressive-degradation: donde el retry puede acelerar la caída

Los percentiles que te mienten cuando hay timeouts

circuit-breaker y bulkhead: rechazos visibles como señal de protección

Qué concluyo y qué no

HikariCP: the p95 that lies to you and how to read the real pool signals

HikariCP: the p95 that lies to you and how to read the real pool signals

The experiment design

The full results — and what to read in them

The trap of a low p95 with a high error rate

How to read the four signals together

1. Error rate + successful queries/s

2. active = maximumPoolSize sustained + waiting > 0

3. Attempt latency vs. successful latency

4. The jump from 50ms to 500ms as a pressure revealer

The diminishing returns of going from pool16 to pool32 with a short delay

The metrics the experiment exposes via Actuator

The experiment configuration vs. configuration for a real environment

My take after the experiment

HikariCP: el p95 que te miente y cómo leer las señales reales del pool

2. `active = maximumPoolSize` sustained + `waiting > 0`

2. `active = maximumPoolSize` sostenido + `waiting > 0`

A broad `restore-keys` can cause more damage than good

`pnpm run -r build` doesn't respect dependency order between workspaces by default

El `restore-keys` amplio puede hacer más daño que bien

`pnpm run -r build` no respeta el orden de dependencias entre workspaces por default