Semana 2 — Atributos de calidad: escribirlos, medirlos y priorizarlos
Objetivos
- Escribir un atributo de calidad como un escenario de seis partes cuya medida de respuesta se pueda comprobar.
- Medir la latencia de un sistema con percentiles y explicar por qué el promedio esconde lo que importa; calcular la disponibilidad a partir del tiempo caído y componerla en serie.
- Priorizar escenarios con un utility tree según su valor para el negocio y su dificultad técnica.
- Reconocer que los atributos compiten entre sí y expresar una decisión como un trade-off explícito.
Sesión A — Atributos de calidad y escenarios de seis partes
Lecturas:
- Software Architecture in Practice, cap. 3 Understanding Quality Attributes.
- Lectura libre: Barbacci, Klein, Longstaff y Weinstock, Quality Attributes (reporte del SEI, 1995), secciones 1 y 2.
Lecturas complementarias:
- El modelo de calidad de ISO/IEC 25010: nueve características con sus subcaracterísticas.
- Software Architecture in Practice, cap. 14 Working with Other Quality Attributes.
Temas:
- Requisitos funcionales, atributos de calidad y restricciones. La funcionalidad no determina la arquitectura; los atributos de calidad sí. Un atributo de calidad es una propiedad medible del sistema que indica qué tan bien satisface a sus stakeholders, más allá de lo que hace.
- El problema de las palabras: “rendimiento”, “escalable”, “robusto” significan cosas distintas para cada persona, y un mismo hecho (un servidor saturado que rechaza pedidos) puede llamarse problema de rendimiento, de disponibilidad o de seguridad. La solución del libro: dejar de discutir el nombre y escribir un escenario.
- El escenario de seis partes: fuente del estímulo, estímulo, artefacto, entorno, respuesta y medida de la respuesta. Ejemplo de Tinkuy: 5 000 compradores (fuente) piden la lista de asientos de un mismo evento durante un minuto (estímulo) al servicio de catálogo (artefacto) en operación normal con la venta recién abierta (entorno); el sistema responde todas las consultas (respuesta) con latencia p95 menor que 300 ms y menos de 0,1 % de errores (medida).
- Escenario general y escenario concreto: el general es una tabla de valores posibles para cada parte de un atributo (los capítulos 4 a 13 del libro traen una por atributo); el concreto es uno de un sistema, con números.
- Los atributos que más se verán en el curso y su estímulo típico: disponibilidad (una falla), rendimiento (llegan eventos), modificabilidad (llega un cambio), seguridad (un ataque), capacidad de prueba, capacidad de despliegue, escalabilidad. ISO/IEC 25010 ofrece otra clasificación; ninguna lista es completa y los nombres importan menos que el escenario.
- Tácticas, primera mención: una táctica es una decisión de diseño que influye sobre la respuesta a un estímulo. Se estudian en la semana 6.
- Error común: un escenario sin medida (“el sistema responde rápido”), o con una medida que nadie podría comprobar (“nunca falla”).
- Error común: un escenario sin entorno. “Responde en 300 ms” no dice nada si no se sabe con cuánta carga y en qué estado está el sistema (normal, degradado, con un servicio caído).
Sesión B — Medir y priorizar: percentiles, disponibilidad, utility tree y trade-offs
Lecturas:
- Kleppmann y Riccomini, Designing Data-Intensive Applications (2.ª ed.), cap. 2 Defining Nonfunctional Requirements, secciones Describing Performance y Reliability and Fault Tolerance.
- Software Architecture in Practice, cap. 19, la sección del utility tree.
- Lectura libre: Site Reliability Engineering, cap. 4, Service Level Objectives.
Lecturas complementarias:
- Grafana k6, Metrics y Thresholds.
- Software Architecture in Practice, cap. 9 Performance, el escenario general.
Temas:
- Latencia, tiempo de respuesta y throughput. El tiempo de respuesta es una distribución, no un número: la misma petición tarda distinto cada vez.
- Percentiles: p50 (la mediana), p95, p99. Por qué no el promedio: con 98 respuestas de 50 ms y 2 de 5 s, el promedio es 149 ms y no describe a ningún usuario. Los percentiles altos importan porque los usuarios con más datos suelen ser los más lentos, y porque una página que hace muchas llamadas casi siempre cae en la cola de alguna.
- Cómo se mide sin engañarse: carga realista, calentamiento, medir desde quien llama, y cuidar el error de omisión coordinada (un generador que espera cada respuesta antes de enviar la siguiente deja de medir justo cuando el sistema se pone lento). Los percentiles no se promedian entre máquinas.
- Disponibilidad: fracción del tiempo en que el sistema responde bien. Los “nueves”: 99,9 % permite unas 8,8 horas caído al año; 99,99 %, unos 53 minutos. En serie se multiplican: un sistema que necesita a tres servicios de 99,9 % queda en 99,7 %. MTBF y MTTR: se mejora fallando menos o recuperándose más rápido.
- SLI, SLO y SLA, primera mención: el indicador que se mide, el objetivo que el equipo se fija y el contrato con consecuencias. Un SLO es un escenario de calidad que se vigila en producción (semana 14).
- Utility tree: la raíz es “utilidad”, debajo los atributos, debajo sus refinamientos y en las hojas los escenarios, cada uno con dos notas (A, M o B): valor para el negocio y dificultad o riesgo técnico. Los (A, A) son los que definen la arquitectura.
- Trade-offs: mejorar un atributo suele costar otro. Una cache mejora la latencia y complica la consistencia; una réplica mejora la disponibilidad y cuesta dinero y operación; más seguridad agrega pasos y latencia. Decidir en arquitectura es elegir qué se sacrifica, para este sistema, y escribirlo.
- Error común: fijar el umbral después de medir (“salió 420 ms, entonces el requisito es 500”). El umbral sale de lo que necesita el stakeholder.
- Error común: medir en una laptop y presentar el número como una propiedad del sistema. La medida depende de la máquina; lo que se traslada es la comparación entre dos diseños medidos en la misma.
Laboratorio — Escribir escenarios para Tinkuy y medirlos con k6
Referencias: k6, Thresholds; el README de Tinkuy. Material: code/week-02/. En parejas.
- Tomar los tres candidatos a ASR de la semana 1 y reescribir cada uno como escenario de seis partes, con el template de
code/week-02/. Intercambiarlos con otra pareja: ¿podrían comprobar la medida sin preguntarles nada? - Levantar Tinkuy (
make db,make gateway,make start) y corrermake load-browse. Leer el resumen de k6:http_req_duration(p50, p95),http_reqsyhttp_req_failed. Anotar los números y la máquina. - Repetir la corrida tres veces. ¿Cuánto varía el p95 entre corridas? ¿Y el promedio? Decidir cuántas corridas hacen falta para afirmar que un cambio mejoró algo.
- Con el script de
code/week-02/que separa las métricas por endpoint, encontrar cuál es el más lento y explicar por qué leyendo su código. - Agregar a una copia de
load/browse.jsun umbral que exprese su escenario (por ejemplohttp_req_duration: ['p(95)<300']) y correrlo: k6 termina con código distinto de cero si no se cumple. Ese umbral es la medida de su escenario, convertida en una prueba. - Correr
make load-saley anotar latencia, throughput y errores. Después corrermake oversell. ¿Qué atributo de calidad se está incumpliendo en cada caso? Escribir el escenario que lo describe. - Calcular: si Tinkuy tiene 99,9 % de disponibilidad, la pasarela 99,5 % y el servidor de correo 99 %, y una compra necesita a los tres, ¿cuál es la disponibilidad de comprar? ¿Qué cambia si el correo deja de ser necesario para completar la compra?
- Armar el utility tree de Tinkuy con al menos seis escenarios en tres atributos, con sus dos notas, y marcar los (A, A).
Entregas
Sin entregas esta semana. Los escenarios y las mediciones de este laboratorio son la segunda parte de P0, que se entrega en la semana 3.
Preguntas de repaso
- Escriban las seis partes de un escenario de disponibilidad para Tinkuy cuando se cae la pasarela de pagos.
- Un servicio reporta latencia promedio de 80 ms y p99 de 2,4 s. Describan una situación que produzca esos números y digan a quién afecta.
- ¿Por qué no se puede obtener el p95 de un sistema promediando los p95 de sus cuatro servidores?
- Un sistema depende de cuatro servicios, cada uno con 99,9 % de disponibilidad. ¿Cuántos minutos al mes puede estar caído, en el mejor caso? ¿Qué supuesto hay detrás de multiplicar?
- En un utility tree, un escenario tiene notas (A, B) y otro (M, A). ¿Cuál atenderían primero y por qué?
- Den un ejemplo, en Tinkuy, de una decisión que mejora el rendimiento y empeora otro atributo. Digan cuál.
Código de la semana
Compilar y probar dentro del contenedor del curso con make y make test.
Ejemplos (15)Errores (1)Pruebas (3)Compilación (3)
Ejemplos
Los programas que usan los apuntes y la clase.
// Calculadora de la semana 2. Tres usos:
//
// node calc.ts percentiles data/latencies.txt resumen de una lista de tiempos (uno por línea, en ms)
// node calc.ts nines tiempo caído permitido para 1 a 5 nueves
// node calc.ts series 99.9 99.9 99.9 disponibilidad de una operación que necesita a todos
// node calc.ts parallel 99 99 disponibilidad cuando basta con que responda uno
//
// Los percentiles se calculan por rango más cercano (ver stats.ts).
import { readFileSync } from 'node:fs';
import {
availabilityInParallel,
availabilityInSeries,
downtimeHoursPerYear,
downtimeMinutesPerMonth,
formatDuration,
nines,
summarize,
} from './stats.ts';
const [command, ...args] = process.argv.slice(2);
function usage(): never {
console.error('Uso: node calc.ts percentiles <archivo> | nines | series <%>... | parallel <%>...');
process.exit(2);
}
function percentages(texts: string[]): number[] {
if (texts.length === 0) usage();
return texts.map((text) => {
const value = Number(text.replace(',', '.'));
if (!Number.isFinite(value) || value < 0 || value > 100) {
console.error(`No es un porcentaje entre 0 y 100: ${text}`);
process.exit(2);
}
return value / 100;
});
}
function report(label: string, fraction: number): void {
console.log(`${label}: ${(fraction * 100).toFixed(4)} %`);
console.log(` caído al año: ${formatDuration(downtimeHoursPerYear(fraction))}`);
console.log(` caído al mes: ${downtimeMinutesPerMonth(fraction).toFixed(1)} min`);
}
if (command === 'percentiles') {
const file = args[0] ?? usage();
const values = readFileSync(file, 'utf8')
.split('\n')
.map((line) => line.trim())
.filter((line) => line !== '' && !line.startsWith('#'))
.map(Number);
if (values.length === 0 || values.some((value) => !Number.isFinite(value))) {
console.error(`${file}: se espera un número por línea`);
process.exit(2);
}
const s = summarize(values);
console.log(`n = ${s.count}`);
console.log(`promedio = ${s.mean.toFixed(1)} ms`);
console.log(`p50 = ${s.p50} ms p95 = ${s.p95} ms p99 = ${s.p99} ms máx = ${s.max} ms`);
} else if (command === 'nines') {
console.log('nueves disponibilidad caído al año caído al mes');
for (let count = 1; count <= 5; count++) {
const fraction = nines(count);
const percent = `${(fraction * 100).toFixed(Math.max(0, count - 2))} %`;
const perYear = formatDuration(downtimeHoursPerYear(fraction));
const perMonth = `${downtimeMinutesPerMonth(fraction).toFixed(1)} min`;
console.log(`${String(count).padEnd(8)}${percent.padEnd(16)}${perYear.padEnd(15)}${perMonth}`);
}
} else if (command === 'series') {
report('En serie', availabilityInSeries(percentages(args)));
} else if (command === 'parallel') {
report('En paralelo', availabilityInParallel(percentages(args)));
} else {
usage();
}// Revisa archivos de escenarios de calidad escritos con scenario-template.md.
//
// node scenario-check.ts docs/scenarios.md [otro.md ...]
//
// Comprueba la forma, no el fondo: que cada escenario tenga sus seis partes,
// que ninguna esté vacía o con el texto del template, y que la medida de la
// respuesta tenga al menos un número y ninguna palabra que no se pueda
// comprobar ("rápido", "nunca"). No sabe si el número es el que necesita el
// stakeholder ni si el entorno es realista: eso lo revisa otra pareja.
//
// Termina con código 1 si algún escenario tiene problemas.
import { readFileSync } from 'node:fs';
import { pathToFileURL } from 'node:url';
export const PARTS = ['source', 'stimulus', 'artifact', 'environment', 'response', 'measure'] as const;
export type Part = (typeof PARTS)[number];
/** Cómo se llama cada parte en el archivo (lo que va entre ** y :**). */
export const PART_LABELS: Record<Part, string> = {
source: 'Fuente del estímulo',
stimulus: 'Estímulo',
artifact: 'Artefacto',
environment: 'Entorno',
response: 'Respuesta',
measure: 'Medida de la respuesta',
};
export type Scenario = {
title: string;
/** Línea del archivo donde empieza, contando desde 1. */
line: number;
parts: Partial<Record<Part, string>>;
};
export type Problem = { part: Part; message: string };
const normalize = (text: string) => text.trim().toLowerCase().replace(/\s+/g, ' ');
const LABEL_TO_PART = new Map<string, Part>(PARTS.map((part) => [normalize(PART_LABELS[part]), part]));
// Nombres cortos que también se aceptan.
LABEL_TO_PART.set('fuente', 'source');
LABEL_TO_PART.set('medida', 'measure');
// Una parte es un ítem de lista: "- **Entorno:** operación normal..."
const PART_LINE = /^\s*[-*]\s+\*\*([^*:]+):\*\*\s*(.*)$/;
const HEADING = /^(#{2,6})\s+(.*)$/;
/**
* Separa un archivo en escenarios. Cada título de nivel 2 o más profundo
* (## ...) empieza un escenario; el texto que sigue a una parte, hasta la
* próxima parte o línea en blanco, pertenece a esa parte.
*/
export function parseScenarios(markdown: string): Scenario[] {
const scenarios: Scenario[] = [];
let current: Scenario | undefined;
let openPart: Part | undefined;
markdown.split('\n').forEach((line, index) => {
const heading = HEADING.exec(line);
if (heading) {
current = { title: heading[2]!.trim(), line: index + 1, parts: {} };
scenarios.push(current);
openPart = undefined;
return;
}
const partLine = PART_LINE.exec(line);
if (partLine) {
const part = LABEL_TO_PART.get(normalize(partLine[1]!));
openPart = undefined;
if (!part) return; // otro dato del escenario, como el atributo de calidad
if (!current) {
current = { title: '(sin título)', line: index + 1, parts: {} };
scenarios.push(current);
}
current.parts[part] = partLine[2]!.trim();
openPart = part;
return;
}
if (line.trim() === '' || /^\s*[-*]\s/.test(line)) {
openPart = undefined;
return;
}
if (current && openPart) {
current.parts[openPart] = `${current.parts[openPart]} ${line.trim()}`.trim();
}
});
// Un título sin ninguna parte es una sección del documento, no un escenario.
return scenarios.filter((scenario) => Object.keys(scenario.parts).length > 0);
}
// Texto que quedó del template: vacío, puntos suspensivos o <una indicación>.
const isPlaceholder = (text: string) => text === '' || /^(…|\.\.\.)$/.test(text) || /^<[^>]*>$/.test(text);
// Palabras que suenan a medida y no lo son: nadie puede comprobar "rápido" ni "nunca".
const VAGUE =
/(?<!\p{L})(rápid[oa]s?|rápidamente|pronto|inmediat[oa]s?|inmediatamente|aceptable|razonable|adecuad[oa]s?|eficiente|eficientemente|nunca|siempre|jamás)(?!\p{L})/iu;
export function checkScenario(scenario: Scenario): Problem[] {
const problems: Problem[] = [];
for (const part of PARTS) {
const text = scenario.parts[part];
if (text === undefined) problems.push({ part, message: 'falta' });
else if (isPlaceholder(text)) problems.push({ part, message: 'está vacía o con el texto del template' });
}
const measure = scenario.parts.measure;
if (measure !== undefined && !isPlaceholder(measure)) {
if (!/\d/.test(measure)) {
problems.push({ part: 'measure', message: 'no tiene ningún número: ¿cómo se comprueba?' });
}
const vague = VAGUE.exec(measure);
if (vague) {
problems.push({ part: 'measure', message: `"${vague[1]}" no se puede comprobar: escriban el número` });
}
}
return problems;
}
export type FileReport = { scenarios: { scenario: Scenario; problems: Problem[] }[]; ok: boolean };
export function checkMarkdown(markdown: string): FileReport {
const scenarios = parseScenarios(markdown).map((scenario) => ({ scenario, problems: checkScenario(scenario) }));
// Un archivo sin escenarios tampoco pasa: probablemente no siguió el formato.
const ok = scenarios.length > 0 && scenarios.every((entry) => entry.problems.length === 0);
return { scenarios, ok };
}
function main(files: string[]): number {
if (files.length === 0) {
console.error('Uso: node scenario-check.ts <archivo.md> [...]');
return 2;
}
let failed = false;
for (const file of files) {
const report = checkMarkdown(readFileSync(file, 'utf8'));
console.log(file);
if (report.scenarios.length === 0) console.log(' ✖ no se encontró ningún escenario con el formato del template');
for (const { scenario, problems } of report.scenarios) {
console.log(` ${problems.length === 0 ? '✔' : '✖'} ${scenario.title} (línea ${scenario.line})`);
for (const problem of problems) console.log(` ${PART_LABELS[problem.part]}: ${problem.message}`);
}
if (!report.ok) failed = true;
}
return failed ? 1 : 0;
}
// Solo cuando se ejecuta como programa, no cuando lo importan las pruebas.
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
process.exitCode = main(process.argv.slice(2));
}# Escenarios de calidad de <sistema>
<!--
Template de escenario de calidad de seis partes. Copien el bloque de abajo una
vez por escenario y reemplacen cada <indicación> por su texto. Revisen el
archivo con:
node scenario-check.ts <este archivo>
El revisor exige las seis partes y un número en la medida. No reemplaza la
prueba que importa: que otra pareja pueda comprobar la medida sin preguntarles
nada.
-->
## <Título corto: qué pasa y a qué parte del sistema>
- **Atributo de calidad:** <rendimiento, disponibilidad, modificabilidad, seguridad…>
- **Fuente del estímulo:** <quién o qué lo produce: cuántos compradores, un desarrollador, la pasarela, un atacante>
- **Estímulo:** <qué llega al sistema: pedidos, una falla, un cambio; con su cantidad y su duración>
- **Artefacto:** <qué parte del sistema lo recibe: un endpoint, un módulo, la base de datos, todo el sistema>
- **Entorno:** <en qué estado está el sistema cuando llega: carga normal o pico, datos cargados, algo degradado o caído>
- **Respuesta:** <qué hace el sistema, visto desde afuera>
- **Medida de la respuesta:** <el número que dice si se cumplió, con su unidad y la forma de medirlo>// Las cuentas de la Sesión B: percentiles, promedio y disponibilidad.
// Son funciones puras: reciben números y devuelven números, sin leer nada.
/** El promedio aritmético. Con una lista vacía no hay promedio que dar. */
export function mean(values: readonly number[]): number {
if (values.length === 0) throw new RangeError('No hay promedio de una lista vacía');
return values.reduce((sum, value) => sum + value, 0) / values.length;
}
/**
* El percentil p (0 < p <= 100) por el método del rango más cercano
* (nearest-rank): se ordenan los n valores de menor a mayor y se toma el que
* ocupa la posición ceil(p/100 * n), contando desde 1.
*
* El resultado siempre es uno de los valores medidos: "el p95 es 300 ms"
* quiere decir que al menos el 95 % de las mediciones fue de 300 ms o menos,
* y que hubo una que tardó exactamente 300 ms.
*
* Otras herramientas interpolan entre los dos valores vecinos (k6 lo hace):
* con pocas muestras, su resultado puede diferir de este.
*/
export function percentile(values: readonly number[], p: number): number {
if (values.length === 0) throw new RangeError('No hay percentiles de una lista vacía');
if (!(p > 0 && p <= 100)) throw new RangeError(`El percentil debe estar en (0, 100]: ${p}`);
const sorted = [...values].sort((a, b) => a - b);
// Se redondea antes del techo: en punto flotante, 7 / 100 * 100 no da 7 exacto.
const rank = Math.ceil(Number(((p / 100) * sorted.length).toFixed(9)));
return sorted[rank - 1]!;
}
/** Los números con que se resume una distribución de tiempos de respuesta. */
export type Summary = { count: number; mean: number; p50: number; p95: number; p99: number; max: number };
export function summarize(values: readonly number[]): Summary {
return {
count: values.length,
mean: mean(values),
p50: percentile(values, 50),
p95: percentile(values, 95),
p99: percentile(values, 99),
max: percentile(values, 100),
};
}
/**
* Probabilidad de que una página que hace `calls` llamadas independientes
* reciba al menos una respuesta más lenta que el percentil `p` del servicio.
* Cada llamada cae bajo el percentil con probabilidad p/100.
*/
export function probabilityOfSlowCall(p: number, calls: number): number {
if (!(p > 0 && p <= 100)) throw new RangeError(`El percentil debe estar en (0, 100]: ${p}`);
if (!Number.isInteger(calls) || calls < 0) throw new RangeError(`Cantidad de llamadas inválida: ${calls}`);
return 1 - (p / 100) ** calls;
}
// ---------------------------------------------------------------------------
// Disponibilidad. Aquí siempre es una fracción entre 0 y 1: 99,9 % es 0.999.
const HOURS_PER_YEAR = 365 * 24;
function assertFraction(value: number): void {
if (!(value >= 0 && value <= 1)) throw new RangeError(`La disponibilidad es una fracción entre 0 y 1: ${value}`);
}
/** Fracción del tiempo en que el sistema respondió bien. */
export function availability(uptime: number, downtime: number): number {
if (uptime < 0 || downtime < 0 || uptime + downtime === 0) throw new RangeError('Tiempos inválidos');
return uptime / (uptime + downtime);
}
/**
* Disponibilidad a partir del tiempo medio entre fallas (cuánto funciona
* antes de fallar) y del tiempo medio de reparación, en la misma unidad.
*/
export function availabilityFromMtbf(mtbf: number, mttr: number): number {
return availability(mtbf, mttr);
}
/**
* En serie: la operación necesita a todos. Se multiplican, bajo el supuesto
* de que las fallas de cada parte son independientes.
*/
export function availabilityInSeries(parts: readonly number[]): number {
parts.forEach(assertFraction);
return parts.reduce((product, part) => product * part, 1);
}
/**
* En paralelo: basta con que una copia responda. Falla solo si fallan todas
* a la vez; otra vez, suponiendo fallas independientes.
*/
export function availabilityInParallel(parts: readonly number[]): number {
parts.forEach(assertFraction);
return 1 - parts.reduce((product, part) => product * (1 - part), 1);
}
/** La disponibilidad de "N nueves": 3 nueves es 0.999. */
export function nines(count: number): number {
if (!Number.isInteger(count) || count < 1) throw new RangeError(`Cantidad de nueves inválida: ${count}`);
return 1 - 10 ** -count;
}
/** Horas al año que puede estar caído un sistema con esa disponibilidad (año de 365 días). */
export function downtimeHoursPerYear(fraction: number): number {
assertFraction(fraction);
return (1 - fraction) * HOURS_PER_YEAR;
}
/** Minutos al mes que puede estar caído (mes de 30 días). */
export function downtimeMinutesPerMonth(fraction: number): number {
assertFraction(fraction);
return (1 - fraction) * 30 * 24 * 60;
}
/** Una duración en horas, escrita en la unidad que se lee mejor. */
export function formatDuration(hours: number): string {
if (hours >= 48) return `${(hours / 24).toFixed(2)} días`;
if (hours >= 1) return `${hours.toFixed(2)} h`;
if (hours * 60 >= 1) return `${(hours * 60).toFixed(2)} min`;
return `${(hours * 3600).toFixed(2)} s`;
}# Utility tree de Qhatu
Ejemplo de la semana 2. El árbol va de lo general a lo comprobable: la raíz
es la utilidad del sistema, debajo están los atributos de calidad, debajo sus
refinamientos y en las hojas los escenarios, que están completos (con sus
seis partes) en `scenarios/qhatu.md`.
Cada hoja lleva dos notas, cada una Alta (A), Media (M) o Baja (B):
1. **Valor para el negocio:** qué tanto pierde el negocio si el escenario no
se cumple. La ponen quienes conocen el negocio.
2. **Dificultad o riesgo técnico:** qué tanto cuesta cumplirlo con lo que el
equipo sabe y con el diseño que tiene. La pone el equipo técnico.
| Atributo | Refinamiento | Escenario (resumen) | Negocio | Técnica |
|---|---|---|---|---|
| Rendimiento | Latencia de búsqueda | E1. 2 000 compradores buscan en hora punta: p95 < 400 ms, errores < 0,5 % | A | M |
| Rendimiento | Frescura del seguimiento | E2. 3 000 repartidores reportan cada 5 s: el 99 % de las posiciones se ve con menos de 10 s de antigüedad | M | A |
| Disponibilidad | Falla de un sistema externo | E3. El procesador de pagos no responde 10 min: toda respuesta en 5 s o menos, 0 pedidos perdidos | A | A |
| Disponibilidad | Falla propia | E4. Se cae 1 de 2 instancias: errores < 0,5 % en 60 s o menos, 0 pedidos perdidos | A | M |
| Modificabilidad | Nuevos mercados | E5. Abrir una ciudad: 2 días-persona o menos, 1 módulo, sin interrumpir el servicio | A | B |
| Seguridad | Confidencialidad | E6. Un comprador pide pedidos ajenos 1 000 veces: 0 devueltos, alerta en 5 min o menos | A | M |
El mismo árbol, como lista con sangría:
- Utilidad
- Rendimiento
- Latencia de búsqueda
- E1 (A, M)
- Frescura del seguimiento
- E2 (M, A)
- Disponibilidad
- Falla de un sistema externo
- **E3 (A, A)**
- Falla propia
- E4 (A, M)
- Modificabilidad
- Nuevos mercados
- E5 (A, B)
- Seguridad
- Confidencialidad
- E6 (A, M)
## Cómo se lee
- **(A, A): E3.** Vale mucho y es difícil. Es el que define la arquitectura:
obliga a decidir cómo se habla con el procesador de pagos (con qué timeout,
qué pasa con un pedido a medio confirmar), y esa decisión toca el flujo
central del sistema.
- **(A, M): E1, E4 y E6.** Valen mucho y el equipo sabe cómo cumplirlos. Hay
que diseñarlos y comprobarlos, pero no deberían dar sorpresas.
- **(M, A): E2.** Es difícil y vale menos. Antes de pagarlo conviene
preguntar si el negocio aceptaría una medida más floja (30 segundos de
antigüedad en vez de 10): se negocia.
- **(A, B): E5.** Vale mucho y es fácil: se hace, y no condiciona el resto.
Las notas son de un momento y de un equipo. Si Qhatu firma con un segundo
procesador de pagos, E3 baja de dificultad; si el negocio decide competir
por la precisión del seguimiento, E2 sube de valor. El árbol se revisa cuando
cambia el negocio o el diseño.# 98 respuestas de 50 ms y 2 de 5000 ms (tiempos en milisegundos)
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
50
5000
5000// ¿Cuál es el endpoint lento? Este script recorre los cinco endpoints de
// lectura de Tinkuy y reporta la latencia y los errores de cada uno por
// separado, además del total.
//
// make endpoints (con Tinkuy corriendo: make tinkuy-up, o
// make db, make gateway y make start en tinkuy/)
// BASE_URL=http://localhost:3000 dónde está Tinkuy
//
// Solo lee: se puede repetir sin volver a crear la base de datos.
import http from 'k6/http';
import { check, sleep } from 'k6';
const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000';
const EVENTS = 24; // eventos de los datos de ejemplo
const ORDERS = 1303; // órdenes de los datos de ejemplo (semilla 7)
// Cada pedido lleva una etiqueta `name` con su endpoint. Sin ella, k6 trataría
// /events/1 y /events/2 como URLs distintas.
const ENDPOINTS = [
'GET /events',
'GET /events/:id',
'GET /events/:id/seats',
'GET /orders/:id',
'GET /reports/sales',
];
// k6 solo muestra en el resumen una métrica filtrada por etiqueta si tiene un
// umbral. Estos umbrales se cumplen siempre (max>=0): no juzgan nada, solo
// piden la fila. Un umbral de verdad se escribe igual, con el número del
// escenario: 'http_req_duration{name:GET /events}': ['p(95)<300'].
// Los errores por endpoint se ven en los checks.
const thresholds = {};
for (const name of ENDPOINTS) {
thresholds[`http_req_duration{name:${name}}`] = ['max>=0'];
}
export const options = {
scenarios: {
// 20 usuarios virtuales durante 20 segundos.
readers: { executor: 'constant-vus', vus: 20, duration: '20s' },
},
thresholds,
summaryTrendStats: ['avg', 'med', 'p(95)', 'p(99)', 'max'],
};
function get(name, path) {
const response = http.get(`${BASE_URL}${path}`, { tags: { name } });
check(response, { [`${name} responde 200`]: (r) => r.status === 200 });
sleep(0.2);
}
export default function () {
const eventId = 1 + Math.floor(Math.random() * EVENTS);
const orderId = 1 + Math.floor(Math.random() * ORDERS);
get('GET /events', '/events');
get('GET /events/:id', `/events/${eventId}`);
get('GET /events/:id/seats', `/events/${eventId}/seats`);
get('GET /orders/:id', `/orders/${orderId}`);
get('GET /reports/sales', `/reports/sales?eventId=${eventId}`);
}// Omisión coordinada, parte 1: el modelo cerrado.
//
// 10 usuarios virtuales en un ciclo: enviar, esperar la respuesta, descansar
// 50 ms. Mientras el servidor responde en 2 ms, eso da unos 190 pedidos por
// segundo. Cuando el servidor se detiene, cada usuario se queda esperando su
// respuesta y deja de enviar: en un segundo de detención solo se miden 10
// pedidos lentos.
//
// make omission (levanta omission/stall-server.ts y corre los dos scripts)
import http from 'k6/http';
import { sleep } from 'k6';
const BASE_URL = __ENV.STALL_URL || 'http://localhost:3100';
export const options = {
scenarios: {
closed: { executor: 'constant-vus', vus: 10, duration: '30s' },
},
// El mismo umbral en los dos scripts: la medida de un escenario de rendimiento.
thresholds: { http_req_duration: ['p(95)<300'] },
summaryTrendStats: ['avg', 'med', 'p(90)', 'p(95)', 'p(99)', 'max'],
};
// Reinicia el reloj del servidor: las detenciones caen en los segundos 4, 14 y 24.
export function setup() {
http.post(`${BASE_URL}/reset`);
}
export default function () {
http.get(`${BASE_URL}/work`);
sleep(0.05);
}// Omisión coordinada, parte 2: el modelo abierto.
//
// 200 pedidos por segundo, a ritmo fijo, responda o no el servidor: así llega
// la gente de verdad, que no sabe que el servidor está detenido. Durante un
// segundo de detención salen los 200 pedidos que tocaban, y todos esperan.
//
// preAllocatedVUs: k6 necesita un usuario virtual libre para cada pedido que
// sale. Con 200 pedidos por segundo y esperas de hasta 1 s hacen falta unos
// 200 a la vez; se reservan 400. Si no alcanzaran, k6 lo diría en la métrica
// dropped_iterations, y la medición volvería a esconder la cola. Para verlo:
// PRE_VUS=20 k6 run --quiet load/open-model.js (con el servidor corriendo).
//
// make omission (levanta omission/stall-server.ts y corre los dos scripts)
import http from 'k6/http';
const BASE_URL = __ENV.STALL_URL || 'http://localhost:3100';
export const options = {
scenarios: {
open: {
executor: 'constant-arrival-rate',
rate: 200,
timeUnit: '1s',
duration: '30s',
preAllocatedVUs: Number(__ENV.PRE_VUS || 400),
},
},
// El mismo umbral en los dos scripts: la medida de un escenario de rendimiento.
thresholds: { http_req_duration: ['p(95)<300'] },
summaryTrendStats: ['avg', 'med', 'p(90)', 'p(95)', 'p(99)', 'max'],
};
// Reinicia el reloj del servidor: las detenciones caen en los segundos 4, 14 y 24.
export function setup() {
http.post(`${BASE_URL}/reset`);
}
export default function () {
http.get(`${BASE_URL}/work`);
}// ¿Cómo calcula k6 un percentil? Este script no hace ningún pedido: carga en
// una métrica diez valores conocidos (10, 20, ..., 100 ms) y deja que k6 los
// resuma. Con el método del rango más cercano (stats.ts), el p50 es 50 y el
// p95 es 100; k6 interpola entre los dos valores vecinos y reporta otros.
//
// k6 run --quiet load/percentiles.js
import { Trend } from 'k6/metrics';
const sample = new Trend('sample', true);
export const options = {
vus: 1,
iterations: 1,
summaryTrendStats: ['avg', 'med', 'p(90)', 'p(95)', 'p(99)', 'max'],
};
export default function () {
for (let value = 10; value <= 100; value += 10) sample.add(value);
}// La omisión coordinada, sin red ni reloj: una simulación en tiempo virtual
// de los dos modelos de generador de carga contra el mismo servidor que se
// detiene. Sirve para ver de dónde sale la diferencia que después se mide
// con k6 (make omission).
//
// node omission/simulate.ts
//
// Modelo cerrado: N usuarios virtuales; cada uno envía, espera la respuesta,
// descansa y vuelve a enviar. Si el servidor se detiene, el usuario también.
// Modelo abierto: los pedidos salen a un ritmo fijo, responda o no el servidor.
import { summarize, type Summary } from '../stats.ts';
import { stallRemaining, type StallPattern } from './stall.ts';
export type Server = StallPattern & { serviceMs: number };
/** Tiempo de respuesta de un pedido que llega en el instante `at` (ms). */
export function responseTime(server: Server, at: number): number {
return stallRemaining(server, at) + server.serviceMs;
}
/** Modelo cerrado: `vus` usuarios en un ciclo enviar, esperar, descansar `thinkMs`. */
export function closedModel(server: Server, vus: number, thinkMs: number, durationMs: number): number[] {
const latencies: number[] = [];
for (let vu = 0; vu < vus; vu++) {
// Cada usuario empieza un poco después del anterior, para que no vayan en fila.
let now = (vu * (server.serviceMs + thinkMs)) / vus;
while (now < durationMs) {
const latency = responseTime(server, now);
latencies.push(latency);
now += latency + thinkMs; // no envía el siguiente hasta recibir este
}
}
return latencies;
}
/** Modelo abierto: `ratePerSecond` pedidos por segundo, pase lo que pase. */
export function openModel(server: Server, ratePerSecond: number, durationMs: number): number[] {
const latencies: number[] = [];
const total = Math.floor((ratePerSecond * durationMs) / 1000);
for (let i = 0; i < total; i++) {
latencies.push(responseTime(server, (i * 1000) / ratePerSecond));
}
return latencies;
}
/** El caso de la clase: 2 ms de servicio y 1 s detenido cada 10 s, durante 30 s. */
export const CLASS_SERVER: Server = { serviceMs: 2, periodMs: 10_000, stallMs: 1_000, firstStallMs: 4_000 };
export const DURATION_MS = 30_000;
function row(name: string, s: Summary, slow: number): string {
const cells = [s.count, s.mean.toFixed(1), s.p50.toFixed(0), s.p95.toFixed(0), s.p99.toFixed(0), s.max.toFixed(0), slow];
return name.padEnd(10) + cells.map((cell) => String(cell).padStart(10)).join('');
}
if (import.meta.main) {
const closed = closedModel(CLASS_SERVER, 10, 50, DURATION_MS);
const open = openModel(CLASS_SERVER, 200, DURATION_MS);
const slow = (latencies: number[]) => latencies.filter((latency) => latency > 100).length;
console.log('Servidor: 2 ms por pedido; detenido 1 s de cada 10 s. Simulación de 30 s.');
console.log('modelo'.padEnd(10) + ['pedidos', 'promedio', 'p50', 'p95', 'p99', 'máx', '> 100 ms'].map((h) => h.padStart(10)).join(''));
console.log(row('cerrado', summarize(closed), slow(closed)));
console.log(row('abierto', summarize(open), slow(open)));
}// Un servidor que se queda pegado: responde en SERVICE_MS, salvo durante una
// ventana de STALL_MS que se repite cada PERIOD_MS. Lo que llega durante la
// ventana espera hasta que termine, como pasa con una pausa del recolector de
// basura, un lock tomado mucho tiempo o un disco que no responde.
//
// node omission/stall-server.ts escucha en el puerto 3100
// GET /work el pedido que se mide
// POST /reset reinicia el reloj: la próxima ventana empieza en FIRST_STALL_MS
//
// Es el servidor de la demostración de omisión coordinada (make omission).
import { createServer } from 'node:http';
import { stallRemaining, type StallPattern } from './stall.ts';
const PORT = Number(process.env.STALL_PORT ?? 3100);
const SERVICE_MS = Number(process.env.SERVICE_MS ?? 2);
const pattern: StallPattern = {
periodMs: Number(process.env.PERIOD_MS ?? 10_000),
stallMs: Number(process.env.STALL_MS ?? 1_000),
firstStallMs: Number(process.env.FIRST_STALL_MS ?? 4_000),
};
let epoch = Date.now();
const server = createServer((request, response) => {
if (request.method === 'POST' && request.url === '/reset') {
epoch = Date.now();
response.writeHead(204).end();
return;
}
if (request.method === 'GET' && request.url === '/work') {
const wait = stallRemaining(pattern, Date.now() - epoch) + SERVICE_MS;
setTimeout(() => {
response.writeHead(200, { 'content-type': 'application/json' });
response.end('{"ok":true}');
}, wait);
return;
}
response.writeHead(404).end();
});
server.listen(PORT, () => {
console.log(
`stall-server en http://localhost:${PORT}: responde en ${SERVICE_MS} ms y se detiene ` +
`${pattern.stallMs} ms cada ${pattern.periodMs} ms`,
);
});
// make lo detiene con SIGTERM: cierra y termina.
process.on('SIGTERM', () => {
server.close(() => process.exit(0));
server.closeAllConnections();
});// Cuándo está detenido el servidor de la demostración. Lo usan el servidor
// real (stall-server.ts) y la simulación (simulate.ts), para que los dos
// hablen del mismo comportamiento.
export type StallPattern = {
/** Cada cuánto se repite la ventana, en ms. */
periodMs: number;
/** Cuánto dura la ventana en que el servidor no responde, en ms. */
stallMs: number;
/** En qué momento del período empieza la ventana, en ms. */
firstStallMs: number;
};
/**
* Cuánto falta para que el servidor vuelva a responder, si un pedido llega
* `elapsedMs` después de arrancar. Es 0 fuera de la ventana.
*/
export function stallRemaining(pattern: StallPattern, elapsedMs: number): number {
const phase = ((elapsedMs % pattern.periodMs) + pattern.periodMs) % pattern.periodMs;
const start = pattern.firstStallMs;
const end = start + pattern.stallMs;
return phase >= start && phase < end ? end - phase : 0;
}# Escenarios de calidad de Qhatu
Qhatu (*mercado*, en quechua) es el sistema de ejemplo de la semana 2: una
aplicación para pedir abarrotes a las bodegas del barrio, con reparto en
moto. No existe: sirve para mostrar la técnica con un sistema que no es
Tinkuy. Estos seis escenarios son las hojas de `utility-tree-example.md`.
## E1. Búsqueda de productos en la hora punta
- **Atributo de calidad:** rendimiento
- **Fuente del estímulo:** 2 000 compradores con la aplicación abierta
- **Estímulo:** buscan productos por nombre, 1 búsqueda cada 10 segundos por comprador, durante 30 minutos
- **Artefacto:** el endpoint de búsqueda del catálogo
- **Entorno:** hora punta (de 7 a 9 de la noche), con el catálogo de 800 bodegas cargado
- **Respuesta:** el sistema devuelve los productos que coinciden, con precio y bodega
- **Medida de la respuesta:** latencia p95 menor que 400 ms y menos de 0,5 % de errores, medidos desde el celular de prueba
## E2. Posición del repartidor
- **Atributo de calidad:** rendimiento
- **Fuente del estímulo:** 3 000 repartidores en ruta
- **Estímulo:** cada uno envía su posición cada 5 segundos
- **Artefacto:** el servicio de seguimiento de pedidos
- **Entorno:** hora punta, con 3 000 pedidos en camino a la vez
- **Respuesta:** el comprador ve en el mapa la posición de su repartidor
- **Medida de la respuesta:** en el 99 % de las actualizaciones, la posición que ve el comprador tiene menos de 10 segundos de antigüedad
## E3. El procesador de pagos deja de responder
- **Atributo de calidad:** disponibilidad
- **Fuente del estímulo:** el procesador de pagos con tarjeta, un sistema externo
- **Estímulo:** deja de responder durante 10 minutos
- **Artefacto:** el flujo de confirmación de un pedido
- **Entorno:** hora punta, con unos 40 pedidos por minuto
- **Respuesta:** el sistema avisa al comprador que la tarjeta no está disponible y le ofrece pagar contra entrega; los pedidos pagados contra entrega siguen su curso
- **Medida de la respuesta:** el 100 % de los intentos de pago recibe una respuesta en 5 segundos o menos, y se pierden 0 pedidos ya confirmados
## E4. Se cae una instancia del servidor
- **Atributo de calidad:** disponibilidad
- **Fuente del estímulo:** la máquina donde corre una de las instancias del servidor
- **Estímulo:** se apaga sin aviso
- **Artefacto:** la API que usan compradores, bodegas y repartidores
- **Entorno:** operación normal, con 2 instancias en servicio
- **Respuesta:** los pedidos se atienden con la instancia que queda y la caída se registra para quien opera el sistema
- **Medida de la respuesta:** la tasa de errores vuelve a menos de 0,5 % en 60 segundos o menos, y se pierden 0 pedidos confirmados
## E5. Abrir el servicio en una ciudad nueva
- **Atributo de calidad:** modificabilidad
- **Fuente del estímulo:** el área comercial
- **Estímulo:** pide abrir Qhatu en una ciudad nueva, con sus propias zonas y tarifas de reparto
- **Artefacto:** el módulo de zonas y tarifas
- **Entorno:** en mantenimiento, con el sistema en producción en 3 ciudades
- **Respuesta:** la ciudad queda disponible sin modificar el código de pedidos ni el de pagos
- **Medida de la respuesta:** 2 días-persona o menos de trabajo, con cambios en 1 solo módulo y 0 horas de servicio interrumpido
## E6. Un comprador pide datos de otro
- **Atributo de calidad:** seguridad
- **Fuente del estímulo:** una persona con una cuenta de comprador válida
- **Estímulo:** pide los pedidos de otros compradores cambiando el identificador en la URL, 1 000 veces en una hora
- **Artefacto:** el endpoint de consulta de pedidos
- **Entorno:** operación normal
- **Respuesta:** el sistema rechaza cada pedido que no es de esa cuenta y registra el intento
- **Medida de la respuesta:** 0 pedidos ajenos devueltos, y el equipo de operación recibe una alerta en 5 minutos o menos desde el primer intento# Un escenario de Tinkuy
El ejemplo de la clase, escrito con `scenario-template.md`. Es un escenario
concreto: tiene los números de un sistema y de una situación.
## La lista de asientos cuando se abre una venta
- **Atributo de calidad:** rendimiento
- **Fuente del estímulo:** 5 000 compradores
- **Estímulo:** piden la lista de asientos de un mismo evento durante un minuto
- **Artefacto:** el servicio de catálogo (`GET /events/:id/seats`)
- **Entorno:** operación normal, con la venta del evento recién abierta
- **Respuesta:** el sistema responde todas las consultas
- **Medida de la respuesta:** latencia p95 menor que 300 ms y menos de 0,1 % de
errores, medidos desde quien llama durante ese minutoErrores
Ejemplos con errores a propósito: no compilan, fallan o dan un resultado incorrecto. Los apuntes explican cada uno.
# Escenarios que no se pueden comprobar
Tres escenarios con errores a propósito. `node scenario-check.ts
errors/vague-scenarios.md` los rechaza; los apuntes explican por qué.
## Sin medida: "responde rápido"
- **Atributo de calidad:** rendimiento
- **Fuente del estímulo:** los compradores
- **Estímulo:** buscan productos
- **Artefacto:** el catálogo
- **Entorno:** hora punta
- **Respuesta:** el sistema muestra los resultados
- **Medida de la respuesta:** el sistema responde rápido
## Con una medida que nadie puede comprobar: "nunca falla"
- **Atributo de calidad:** disponibilidad
- **Fuente del estímulo:** el procesador de pagos
- **Estímulo:** deja de responder
- **Artefacto:** el flujo de confirmación de un pedido
- **Entorno:** hora punta
- **Respuesta:** el sistema sigue atendiendo
- **Medida de la respuesta:** el sistema nunca falla y está disponible el 100 % del tiempo
## Sin entorno
- **Atributo de calidad:** rendimiento
- **Fuente del estímulo:** 2 000 compradores
- **Estímulo:** buscan productos por nombre
- **Artefacto:** el endpoint de búsqueda del catálogo
- **Respuesta:** el sistema devuelve los productos que coinciden
- **Medida de la respuesta:** latencia p95 menor que 400 msPruebas
Comprueban lo que afirman los apuntes; se ejecutan con make test.
// Comprueban el revisor de escenarios con los archivos de la semana.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import { checkMarkdown, checkScenario, parseScenarios, PARTS } from './scenario-check.ts';
const read = (file: string) => readFileSync(new URL(file, import.meta.url), 'utf8');
const run = (...files: string[]) =>
spawnSync(process.execPath, ['scenario-check.ts', ...files], { cwd: import.meta.dirname, encoding: 'utf8' });
test('el escenario de Tinkuy de la clase tiene sus seis partes y una medida con números', () => {
const report = checkMarkdown(read('scenarios/tinkuy-seat-list.md'));
assert.equal(report.scenarios.length, 1);
const { scenario, problems } = report.scenarios[0]!;
assert.deepEqual(problems, []);
for (const part of PARTS) assert.ok(scenario.parts[part], `falta ${part}`);
assert.equal(scenario.parts.source, '5 000 compradores');
// La medida ocupa dos líneas en el archivo: se leen como una sola.
assert.match(scenario.parts.measure!, /p95 menor que 300 ms y menos de 0,1 % de errores, medidos/);
assert.ok(report.ok);
});
test('los seis escenarios de Qhatu pasan', () => {
const report = checkMarkdown(read('scenarios/qhatu.md'));
assert.equal(report.scenarios.length, 6);
assert.deepEqual(
report.scenarios.map((entry) => entry.scenario.title.slice(0, 2)),
['E1', 'E2', 'E3', 'E4', 'E5', 'E6'],
);
assert.ok(report.ok);
});
test('el template sin llenar no pasa: todas sus partes siguen con la indicación', () => {
const report = checkMarkdown(read('scenario-template.md'));
assert.equal(report.scenarios.length, 1);
assert.equal(report.scenarios[0]!.problems.length, 6);
assert.ok(!report.ok);
});
test('errors/: sin medida, con una medida que no se puede comprobar y sin entorno', () => {
const report = checkMarkdown(read('errors/vague-scenarios.md'));
assert.equal(report.scenarios.length, 3);
const [noMeasure, uncheckable, noEnvironment] = report.scenarios.map((entry) => entry.problems);
assert.deepEqual(
noMeasure!.map((problem) => problem.part),
['measure', 'measure'],
);
assert.match(noMeasure![0]!.message, /ningún número/);
assert.match(noMeasure![1]!.message, /"rápido"/);
// Tiene un número (100 %), pero "nunca" no se puede comprobar.
assert.equal(uncheckable!.length, 1);
assert.match(uncheckable![0]!.message, /"nunca"/);
assert.deepEqual(noEnvironment, [{ part: 'environment', message: 'falta' }]);
assert.ok(!report.ok);
});
test('un escenario con una parte vacía se rechaza', () => {
const [scenario] = parseScenarios(
['## Algo', '- **Fuente del estímulo:** un comprador', '- **Estímulo:**', '- **Artefacto:** …'].join('\n'),
);
const problems = checkScenario(scenario!);
assert.deepEqual(
problems.map((problem) => `${problem.part}: ${problem.message}`),
[
'stimulus: está vacía o con el texto del template',
'artifact: está vacía o con el texto del template',
'environment: falta',
'response: falta',
'measure: falta',
],
);
});
test('las palabras vagas se detectan como palabras completas', () => {
const measure = (text: string) =>
checkScenario({ title: 't', line: 1, parts: { source: 'a', stimulus: 'b', artifact: 'c', environment: 'd', response: 'e', measure: text } });
assert.deepEqual(measure('p95 menor que 300 ms'), []);
// "prontuario" contiene "pronto", pero no es la palabra "pronto".
assert.deepEqual(measure('el prontuario se genera en 2 s o menos'), []);
assert.equal(measure('responde pronto, en 2 s').length, 1);
assert.equal(measure('Siempre en menos de 2 s').length, 1);
});
test('un archivo sin escenarios no pasa', () => {
assert.ok(!checkMarkdown('# Notas\n\nTexto sin formato de escenario.\n').ok);
});
test('como programa: código 0 si todo pasa, 1 si hay problemas, 2 sin argumentos', () => {
const good = run('scenarios/tinkuy-seat-list.md', 'scenarios/qhatu.md');
assert.equal(good.status, 0, good.stdout + good.stderr);
assert.match(good.stdout, /✔ E3\. El procesador de pagos deja de responder \(línea \d+\)/);
const bad = run('errors/vague-scenarios.md');
assert.equal(bad.status, 1);
assert.match(bad.stdout, /✖ Sin entorno \(línea \d+\)\n\s+Entorno: falta/);
assert.equal(run().status, 2);
});// Comprueban las cuentas que hacen los apuntes de la semana 2.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
availability,
availabilityFromMtbf,
availabilityInParallel,
availabilityInSeries,
downtimeHoursPerYear,
downtimeMinutesPerMonth,
formatDuration,
mean,
nines,
percentile,
probabilityOfSlowCall,
summarize,
} from './stats.ts';
const close = (actual: number, expected: number, tolerance = 1e-9) =>
assert.ok(Math.abs(actual - expected) <= tolerance, `${actual} no está a ${tolerance} de ${expected}`);
test('percentil por rango más cercano: posición ceil(p/100 * n)', () => {
const values = [15, 20, 35, 40, 50];
assert.equal(percentile(values, 5), 15); // ceil(0.25) = 1
assert.equal(percentile(values, 30), 20); // ceil(1.5) = 2
assert.equal(percentile(values, 40), 20); // ceil(2.0) = 2
assert.equal(percentile(values, 50), 35); // ceil(2.5) = 3
assert.equal(percentile(values, 100), 50);
});
test('el percentil no depende del orden de llegada ni modifica la lista', () => {
const values = [50, 15, 40, 20, 35];
assert.equal(percentile(values, 50), 35);
assert.deepEqual(values, [50, 15, 40, 20, 35]);
});
test('el percentil siempre es uno de los valores medidos', () => {
const values = [3, 9, 27, 81, 243, 729, 2187];
for (let p = 1; p <= 100; p++) assert.ok(values.includes(percentile(values, p)));
});
test('con un solo valor, todos los percentiles son ese valor', () => {
assert.equal(percentile([42], 1), 42);
assert.equal(percentile([42], 99), 42);
});
test('percentiles inválidos y listas vacías se rechazan', () => {
assert.throws(() => percentile([], 50), RangeError);
assert.throws(() => percentile([1, 2], 0), RangeError);
assert.throws(() => percentile([1, 2], 101), RangeError);
assert.throws(() => mean([]), RangeError);
});
test('98 respuestas de 50 ms y 2 de 5 s: el promedio es 149 ms y no describe a nadie', () => {
const values = [...Array<number>(98).fill(50), 5000, 5000];
const summary = summarize(values);
assert.equal(summary.mean, 149);
assert.equal(summary.p50, 50);
assert.equal(summary.p95, 50);
assert.equal(summary.p99, 5000);
assert.equal(summary.max, 5000);
// Ninguna respuesta tardó algo parecido al promedio.
assert.ok(values.every((value) => Math.abs(value - summary.mean) > 90));
});
test('los percentiles no se promedian entre máquinas', () => {
// Un servidor rápido que atiende casi todo y uno lento que atiende poco.
const fast = Array<number>(900).fill(20);
const slow = Array<number>(100).fill(800);
const averageOfP95 = (percentile(fast, 95) + percentile(slow, 95)) / 2;
const realP95 = percentile([...fast, ...slow], 95);
assert.equal(averageOfP95, 410);
assert.equal(realP95, 800);
});
test('una página con muchas llamadas casi siempre cae en la cola de alguna', () => {
close(probabilityOfSlowCall(99, 1), 0.01);
close(probabilityOfSlowCall(99, 10), 0.0956, 1e-4);
close(probabilityOfSlowCall(99, 100), 0.634, 1e-3);
assert.equal(probabilityOfSlowCall(99, 0), 0);
});
test('disponibilidad como fracción del tiempo', () => {
close(availability(999, 1), 0.999);
// 30 días sin fallar y 43,2 minutos de reparación: tres nueves.
close(availabilityFromMtbf(30 * 24 * 60 - 43.2, 43.2), 0.999);
});
test('fallar la mitad de veces o reparar en la mitad del tiempo mejoran casi lo mismo', () => {
const base = availabilityFromMtbf(100, 1);
const failsLess = availabilityFromMtbf(200, 1);
const recoversFaster = availabilityFromMtbf(100, 0.5);
assert.ok(failsLess > base && recoversFaster > base);
close(failsLess, recoversFaster, 1e-12);
});
test('los nueves y su tiempo caído al año', () => {
close(nines(2), 0.99);
close(nines(3), 0.999);
close(downtimeHoursPerYear(nines(2)), 87.6, 1e-6);
close(downtimeHoursPerYear(nines(3)), 8.76, 1e-6); // unas 8,8 horas
close(downtimeHoursPerYear(nines(4)) * 60, 52.56, 1e-6); // unos 53 minutos
close(downtimeHoursPerYear(nines(5)) * 60, 5.256, 1e-6);
close(downtimeMinutesPerMonth(nines(3)), 43.2, 1e-6);
});
test('en serie se multiplican: tres servicios de 99,9 % quedan en 99,7 %', () => {
const total = availabilityInSeries([0.999, 0.999, 0.999]);
close(total, 0.997002999, 1e-9);
assert.equal((total * 100).toFixed(1), '99.7');
// El conjunto es peor que la peor de sus partes.
assert.ok(availabilityInSeries([0.999, 0.99]) < 0.99);
assert.equal(availabilityInSeries([]), 1);
});
test('en paralelo, dos copias de 99 % dan 99,99 % si fallan de forma independiente', () => {
close(availabilityInParallel([0.99, 0.99]), 0.9999);
});
test('las fracciones fuera de [0, 1] se rechazan', () => {
assert.throws(() => availabilityInSeries([99.9]), RangeError);
assert.throws(() => downtimeHoursPerYear(1.5), RangeError);
assert.throws(() => nines(0), RangeError);
});
test('formatDuration elige la unidad', () => {
assert.equal(formatDuration(87.6), '3.65 días');
assert.equal(formatDuration(8.76), '8.76 h');
assert.equal(formatDuration(0.876), '52.56 min');
assert.equal(formatDuration(0.00876), '31.54 s');
});// Comprueban lo que los apuntes afirman sobre la omisión coordinada, con la
// simulación en tiempo virtual: no dependen del reloj ni de la máquina.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { percentile } from '../stats.ts';
import { stallRemaining } from './stall.ts';
import { CLASS_SERVER, closedModel, DURATION_MS, openModel, responseTime } from './simulate.ts';
const VUS = 10;
const THINK_MS = 50;
const RATE = 200;
const isSlow = (latency: number) => latency > 100;
test('el servidor se detiene 1 s de cada 10 s', () => {
assert.equal(stallRemaining(CLASS_SERVER, 0), 0);
assert.equal(stallRemaining(CLASS_SERVER, 3_999), 0);
assert.equal(stallRemaining(CLASS_SERVER, 4_000), 1_000);
assert.equal(stallRemaining(CLASS_SERVER, 4_750), 250);
assert.equal(stallRemaining(CLASS_SERVER, 5_000), 0);
assert.equal(stallRemaining(CLASS_SERVER, 14_500), 500);
assert.equal(responseTime(CLASS_SERVER, 100), 2);
assert.equal(responseTime(CLASS_SERVER, 4_000), 1_002);
});
test('los dos modelos envían una carga parecida mientras el servidor responde', () => {
const closed = closedModel(CLASS_SERVER, VUS, THINK_MS, DURATION_MS);
const open = openModel(CLASS_SERVER, RATE, DURATION_MS);
assert.equal(open.length, 6_000);
// 10 usuarios con un ciclo de 52 ms son unos 192 pedidos por segundo.
assert.ok(closed.length > 5_000 && closed.length < 6_000, `cerrado: ${closed.length}`);
});
test('modelo cerrado: en cada detención queda atrapado un pedido por usuario, y nada más', () => {
const closed = closedModel(CLASS_SERVER, VUS, THINK_MS, DURATION_MS);
// 3 detenciones en 30 s, 10 usuarios: 30 pedidos lentos.
assert.equal(closed.filter(isSlow).length, 3 * VUS);
});
test('modelo abierto: todo lo que debía salir durante la detención sale, y espera', () => {
const open = openModel(CLASS_SERVER, RATE, DURATION_MS);
// 3 detenciones de 1 s a 200 pedidos por segundo: 600 pedidos esperan.
// (Los que llegan en los últimos 100 ms de la ventana esperan menos de 100 ms.)
const waited = open.filter((latency) => latency > CLASS_SERVER.serviceMs).length;
assert.equal(waited, 3 * RATE);
});
test('el mismo servidor, dos conclusiones: el p95 y el p99 del modelo cerrado no ven la detención', () => {
const closed = closedModel(CLASS_SERVER, VUS, THINK_MS, DURATION_MS);
const open = openModel(CLASS_SERVER, RATE, DURATION_MS);
assert.equal(percentile(closed, 95), 2);
assert.equal(percentile(closed, 99), 2);
// El servidor está detenido el 10 % del tiempo: con llegadas a ritmo fijo,
// el 10 % de los pedidos espera, y la mitad de ellos espera más de 500 ms.
assert.ok(percentile(open, 95) >= 500, `p95 abierto: ${percentile(open, 95)}`);
assert.ok(percentile(open, 99) >= 900, `p99 abierto: ${percentile(open, 99)}`);
// El máximo sí coincide: los dos vieron algún pedido de cerca de un segundo.
assert.ok(percentile(closed, 100) > 900 && percentile(open, 100) > 900);
});
test('la fracción de pedidos lentos del modelo cerrado no se parece a la fracción de tiempo detenido', () => {
const closed = closedModel(CLASS_SERVER, VUS, THINK_MS, DURATION_MS);
const open = openModel(CLASS_SERVER, RATE, DURATION_MS);
const stalledFraction = CLASS_SERVER.stallMs / CLASS_SERVER.periodMs; // 0.10
const slowFraction = (latencies: number[]) => latencies.filter(isSlow).length / latencies.length;
assert.ok(slowFraction(closed) < 0.01);
assert.ok(Math.abs(slowFraction(open) - stalledFraction) < 0.015);
});Compilación
Cómo se compilan y ejecutan los ejemplos.
# Semana 2: atributos de calidad: escribirlos, medirlos y priorizarlos. Se usa
# dentro del contenedor del curso.
#
# make copia Tinkuy en build/tinkuy (para medirlo sin tocar ../../tinkuy)
# make test revisa los tipos (tsc) y corre las pruebas (*.test.ts), que
# comprueban lo que dicen los apuntes
# make scenarios revisa los escenarios de ejemplo con scenario-check.ts
# make errors lo mismo con los escenarios mal escritos de errors/ (falla a propósito)
# make nines tabla de nueves: disponibilidad y tiempo caído permitido
# make simulate la omisión coordinada en una simulación, sin red
# make omission la omisión coordinada medida con k6: modelo cerrado y modelo
# abierto contra un servidor que se detiene (unos 65 s)
# make tinkuy-up crea la base de datos y levanta Tinkuy v0 y su pasarela en
# segundo plano (logs en build/)
# make endpoints k6 contra Tinkuy, con las métricas separadas por endpoint (20 s)
# make tinkuy-down detiene Tinkuy y la pasarela
# make clean borra build/
#
# Nada de esto modifica el Tinkuy del curso (../../tinkuy).
TINKUY ?= ../../tinkuy
BASE_URL ?= http://localhost:3000
STALL_URL ?= http://localhost:3100
export BASE_URL STALL_URL
.PHONY: all test scenarios errors nines simulate omission tinkuy-up tinkuy-down endpoints clean
all: build/tinkuy
build/tinkuy:
mkdir -p build
cp -r $(TINKUY) $@
test:
tsc -p .
node --test "*.test.ts" "omission/*.test.ts"
scenarios:
node scenario-check.ts scenarios/tinkuy-seat-list.md scenarios/qhatu.md
# El revisor termina con error cuando encuentra algo: aquí eso es lo que se quiere ver.
errors:
@node scenario-check.ts errors/vague-scenarios.md ; echo "scenario-check terminó con código $$?"
nines:
@node calc.ts nines
simulate:
@node omission/simulate.ts
# El mismo servidor y el mismo umbral, con los dos modelos de generador. k6
# termina con código 99 cuando un umbral no se cumple.
omission:
@mkdir -p build
@node omission/stall-server.ts > build/stall-server.log 2>&1 & echo $$! > build/stall-server.pid
@sleep 1
@echo "== Modelo cerrado: 10 usuarios virtuales (constant-vus)"
@k6 run --quiet load/closed-model.js ; echo "k6 terminó con código $$?"
@echo "== Modelo abierto: 200 pedidos por segundo (constant-arrival-rate)"
@k6 run --quiet load/open-model.js ; echo "k6 terminó con código $$?"
@kill `cat build/stall-server.pid` ; rm -f build/stall-server.pid
tinkuy-up: build/tinkuy
$(MAKE) --no-print-directory -C build/tinkuy db
@cd build/tinkuy && (node tools/fake-gateway.ts > ../gateway.log 2>&1 & echo $$! > ../gateway.pid)
@cd build/tinkuy && (node src/main.ts > ../tinkuy.log 2>&1 & echo $$! > ../tinkuy.pid)
@sleep 1
@curl -s $(BASE_URL)/health ; echo
tinkuy-down:
@-kill `cat build/tinkuy.pid build/gateway.pid 2>/dev/null` 2>/dev/null ; rm -f build/tinkuy.pid build/gateway.pid
endpoints:
k6 run --quiet load/by-endpoint.js
clean: tinkuy-down
rm -rf build{"private": true, "type": "module"}{
"compilerOptions": {
"target": "es2024",
"lib": ["es2024"],
"module": "nodenext",
"moduleResolution": "nodenext",
"types": ["node"],
"strict": true,
"noEmit": true,
"allowImportingTsExtensions": true,
"erasableSyntaxOnly": true,
"verbatimModuleSyntax": true,
"skipLibCheck": true
},
"include": ["*.ts", "omission/*.ts"]
}