CS Fundamentals Trainer · Guias

Observabilidade: logs, métricas e traces

O que cada um dos três sinais responde, por que médias escondem requisições lentas e percentis não podem ser tirados em média, cardinalidade de labels, custo de logs, propagação e amostragem de traces e alertas baseados em burn rate de SLO, com um exemplo de dois serviços em Python.

27 min de leitura

Quando um sistema se comporta mal em produção, você não pode anexar um depurador, e o código que rodou está em uma máquina que você não tocou. Observabilidade é o quanto você consegue descobrir o que um sistema está fazendo, e por quê, a partir dos dados que ele emite. Na prática, esses dados vêm de três tipos: métricas (números ao longo do tempo), logs (registros de eventos) e traces (o caminho de uma requisição por muitos serviços). Eles respondem a perguntas diferentes, custam quantias diferentes, e cada um tem um jeito clássico de dar errado. Este guia mostra os três em um pequeno exemplo de dois serviços e depois cobre as armadilhas que mais importam: médias que escondem requisições lentas, percentis que não podem ser somados, labels que explodem o número de séries de métricas, logs que custam mais do que valem, traces amostrados de um jeito que perde exatamente os de que você precisa e alertas construídos a partir de error budgets. O código está no apêndice; cada número é uma execução em uma máquina pequena, então importa o comportamento e não as cifras exatas.

1. Três sinais, três perguntas

MétricasLogsTraces
O que énúmeros agregados ao longo do tempo (contagens, taxas, durações)um registro por evento, com detalhesa árvore de passos cronometrados que uma requisição percorreu entre serviços
RespondeHá algo errado, e quanto?Por que isso aconteceu?Para onde foi o tempo (ou de onde veio o erro)?
O custo cresce como número de séries distintas (labels), não com o tráfegoo tráfego e a quantidade que você escreve por eventoo tráfego (a menos que você amostre)
Bom paradashboards e alertasdepurar em detalhe um incidenteachar o salto lento ou com falha
Fraco emnenhum detalhe sobre requisições individuaisdifícil de ver padrões, caro de guardar para sempreexige que todo serviço repasse o contexto

Eles funcionam melhor juntos: um alerta dispara a partir de uma métrica, um trace mostra qual serviço e qual chamada estão lentos, e os logs daquele trace dizem por quê. A chave de junção é um identificador, o trace id, escrito em cada linha de log e em cada span.

Um exemplo prático

Escrevi dois pequenos serviços e os instrumentei à mão para mostrar as ideias: um serviço web cujo /checkout chama um serviço catalog para obter um preço. (O código feito à mão é uma ferramenta de ensino. Não é uma implementação do modelo de dados do OpenTelemetry: não tem informações de recurso ou de escopo de instrumentação, tipos de span, códigos de status, eventos, links, atributos com nomes padrão, tracestate, baggage nem exportadores, e não age sobre a flag sampled. Em serviços reais, use as bibliotecas do OpenTelemetry e sua instrumentação automática.) A cada cinco produtos novos, um não está no cache do catálogo, então essa requisição lê o banco de dados (um sleep de 300 ms no teste). Quarenta checkouts depois:

As métricas disseram que algo estava errado: a média foi de 46 ms, mas o percentil 95 estimado a partir do histograma foi de cerca de 417 ms. Seis das 40 requisições caíram no balde de 250 a 500 ms e as outras 34 no primeiro balde.

O trace da requisição mais lenta mostrou para onde foi o tempo:

web      GET /checkout       302 ms
  web      call catalog        302 ms
    catalog  GET /price          300 ms
      catalog  db.query            300 ms
      catalog  cache.lookup          0 ms

Os logs com esse trace id disseram por quê:

{"level": "INFO", "service": "web",     "msg": "checkout started",                  "trace_id": "021e8cdc...", "sku": "sku-15"}
{"level": "WARN", "service": "catalog", "msg": "cache miss, reading the database",  "trace_id": "021e8cdc...", "sku": "sku-15"}
{"level": "INFO", "service": "web",     "msg": "checkout finished",                 "trace_id": "021e8cdc...", "sku": "sku-15"}

A métrica não conseguiu dizer qual requisição, o trace não conseguiu dizer que foi um cache miss, e o log sozinho seria uma linha entre milhares. Cada sinal forneceu o que faltava aos outros.

Diagram: The trace context travels with the request

2. Métricas

Uma métrica é um número com um nome e labels (http_requests_total{route="/checkout", status="200"}). Cada conjunto distinto de valores de labels é uma série temporal separada. Quatro tipos cobrem quase tudo:

O que medir primeiro: para um serviço que trata requisições, os sinais RED: Rate (taxa), Errors (erros) e Duration (duração), por rota. Para um recurso (CPU, disco, um pool de conexões), os sinais USE: Utilization (utilização), Saturation (saturação) e Errors (erros). O livro de SRE do Google nomeia quatro sinais dourados: latência, tráfego, erros e saturação. É a mesma ideia com outras palavras.

Médias escondem as requisições que doem

Em um teste de 100 000 requisições em que 98% levaram cerca de 20 ms e 2% levaram cerca de 2 s (um caminho lento):

EstatísticaValor
média60 ms
mediana (p50)20 ms
p9026 ms
p991 995 ms
p99,92 506 ms

A média de 60 ms não descreve nenhuma requisição real: não é nem as rápidas nem as lentas. A mediana e o p90 parecem perfeitos enquanto uma em cada cinquenta requisições leva dois segundos. Trace sempre percentis (p50, p95, p99) e não a média da latência.

A latência de cauda também se multiplica com o fan-out. Se uma página faz várias chamadas ao backend e cada uma tem 2% de chance de ser lenta, a chance de um carregamento de página atingir pelo menos uma chamada lenta é 1 - 0,98^n: 2% para uma chamada, 9,6% para cinco, 33% para vinte e 64% para cinquenta. Chamadas que parecem raras em um único serviço dominam a experiência de uma página.

Percentis não podem ser tirados em média

Dois servidores: A está ocupado (10 000 requisições, 0,5% lentas) e B está tranquilo (100 requisições, 10% lentas). O p99 do servidor A foi de 30 ms e o p99 de B foi de 1 087 ms. A média dos dois, 559 ms, não significa nada: o p99 de todas as 10 100 requisições juntas foi de 31 ms. Um dashboard que tira a média dos valores de p99 por instância relata um problema que a maioria dos usuários não tem (ou, com outro tráfego, esconde um que eles têm).

A correção é registrar histogramas e somar seus baldes entre as instâncias, e então calcular o quantil a partir dos baldes combinados. É por isso que o Prometheus aconselha histogramas em vez de summaries quando você precisa agregar. O preço é a precisão: o quantil é estimado por interpolação dentro de um balde, então os baldes precisam ser adequados à sua latência:

Baldes (ms)Estimativa de p99p99 exatoEstimativa de p50p50 exato
10, 100, 1000, 100005 5001 9955620
5, 10, 25, 50, 100, 250, 500, 1000, 25001 7911 9951920

Baldes grosseiros transformaram um p99 de 2 s em 5,5 s. Ponha os limites dos baldes em volta dos valores que importam, como a sua meta de latência.

Labels são um orçamento

Cada combinação de valores de labels é uma nova série que o sistema de monitoramento armazena, indexa e plota. Labels como method, route e status dão algumas centenas de séries. Um label com valores ilimitados, como user_id, request_id, um e-mail ou uma URL completa com ids, cria uma série por valor. Em um registro de brinquedo, 100 000 valores de user_id ocuparam 37 MB para uma métrica (cerca de 370 bytes por série), antes de multiplicar por cada rota e código de status, e os sistemas reais guardam bem mais por série. Isso se chama explosão de cardinalidade e é uma das formas mais comuns de derrubar um sistema de monitoramento. Regra prática: ponha identificadores em logs e traces, e nos labels de métricas ponha apenas conjuntos pequenos e limitados de valores (templates de rota como /orders/{id}, classes de status).

3. Logs

Uma linha de log é barata de escrever e cara de ler em escala. Faça-a útil:

O que custa uma chamada de log

Medido no Python 3.13, escrevendo na memória (portanto sem disco nem rede), em 200 000 chamadas:

ChamadaTempo por chamada
DEBUG desligado, mensagem montada antes com uma f-string1 225 ns
DEBUG desligado, argumentos %s preguiçosos154 ns
INFO ligado, texto simples7 727 ns
INFO ligado, JSON10 633 ns

Duas lições. Uma chamada de log desligada não é de graça se você monta a mensagem por conta própria: a f-string formatou a lista antes de o logger poder decidir não usá-la, o que a tornou cerca de oito vezes mais lenta do que passar os argumentos de forma preguiçosa. E uma chamada ligada custa microssegundos antes de qualquer tempo de disco ou rede, então registrar dentro de um laço quente é um bug de desempenho. Os loggers de produção também escrevem de forma assíncrona por um buffer, para que um destino de log lento não trave as requisições (e você precisa decidir o que descartar se o buffer encher).

4. Traces

Um trace é o registro de uma requisição pelo sistema. É feito de spans: cada span tem um nome, um instante de início, uma duração e um pai, de modo que os spans formam uma árvore como a de cima. O contexto do trace (o trace id e o id do span atual) é passado entre os serviços em um cabeçalho, mais comumente o traceparent do W3C:

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
             version  trace id (16 bytes)          parent span id   flags (01 = sampled)

O serviço receptor cria seus spans como filhos do span do cabeçalho. Isso só funciona se todo salto propaga o contexto: um cliente HTTP que esquece o cabeçalho, um pool de threads que descarta a variável de contexto ou uma fila de mensagens cujas mensagens não carregam cabeçalho cortam o trace em dois. Para uma fila (filas de mensagens e garantias de entrega), ponha o contexto do trace nos cabeçalhos da mensagem e ligue o span do consumidor a ele. O OpenTelemetry é o conjunto padrão de APIs, SDKs e convenções para produzir os três sinais, de modo que a instrumentação não dependa do fornecedor que os armazena.

Trace ids e request ids

Um request id (muitas vezes um cabeçalho X-Request-Id) identifica uma requisição HTTP de entrada, normalmente na borda ou em um serviço. Um trace id identifica uma cadeia causal de trabalho inteira, e essa cadeia pode ser maior que uma requisição: pode passar por muitos serviços, se dividir em chamadas paralelas, continuar por uma fila minutos depois ou começar de um job agendado que não tem nenhuma requisição de entrada. Não são intercambiáveis:

Escolha a estratégia de propósito: use o trace id como chave de correlação onde existir tracing, mantenha um request id (ou um id de pedido, ou um id de job) como identificador de negócio adicional nos logs e registre por escrito qual deles é dado à equipe de suporte e aos clientes.

Privacidade nos traces

Os spans e seus atributos são dados que você armazena, pesquisa e compartilha, e capturam mais do que as pessoas esperam: URLs com query strings (tokens, e-mails), instruções de banco de dados com seus valores, ids de usuário e de conta, cabeçalhos, mensagens de erro que repetem a entrada e itens de baggage que são repassados a todo serviço que a requisição toca, inclusive terceiros. A regra do logging vale aqui também: sem segredos e sem dados pessoais de que você não precisa. Oculte ou descarte atributos sensíveis no SDK ou no collector antes de serem armazenados, prefira instruções de banco de dados parametrizadas nos spans, use templates de rota e não URLs brutas, limite quem pode consultar traces e defina um período de retenção que corresponda às suas obrigações de privacidade (um pedido de exclusão pode ter de alcançar traces e logs, além do banco de dados).

Amostragem: você não pode guardar tudo, então o que guarda?

Rastrear toda requisição custa armazenamento e alguma CPU. A amostragem na cabeça (head sampling) decide no início da requisição, antes de alguém saber como ela vai terminar (por exemplo, "guarde 1%"). A amostragem na cauda (tail sampling) espera o trace estar completo e então decide (guarde todo trace que foi lento ou teve erro, mais uma pequena parte do resto).

Uma simulação de 1 000 000 de requisições, das quais 0,1% foram lentas ou falharam (949 requisições):

EstratégiaTraces armazenadosTraces interessantes guardados
Head sampling a 1%cerca de 10 0006 de 949
Tail sampling (todos os lentos ou com falha, mais 1% do resto)cerca de 10 860949 de 949

O head sampling armazena quase a mesma quantidade e joga fora 99% dos traces que você realmente vai querer. Leia a segunda linha como resultado de um collector ideal, não como garantia: na simulação, quem tomava a decisão recebia todos os spans de todas as requisições, tinha memória ilimitada e esperava o quanto precisasse. Um tail sampler real guarda todos os traces lentos ou com falha somente se receber todos os spans de que precisa (um span que chega depois da decisão, ou de um serviço que não é instrumentado, se perde), tiver memória e CPU suficientes para os traces que esperam por uma decisão (uma espera de decisão de 30 segundos a 10 000 requisições por segundo significa centenas de milhares de traces abertos), aplicar uma regra que realmente corresponda ao que você quer e guardar o resultado por tempo suficiente para ser examinado. Sob sobrecarga, o collector descarta dados, e em geral são os traces incomuns que sofrem. O tail sampling exige um collector que mantenha na memória todos os spans de um trace até ele ficar completo (e todo span do trace precisa chegar ao mesmo collector), e é por isso que custa mais para operar. Um compromisso comum: faça head sampling barato para o volume e force a retenção de traces de requisições marcadas como erro ou que excedam um limite de latência na borda.

5. Dos sinais aos alertas

Um alerta deve significar uma pessoa precisa agir agora. Alertar sobre causas (a CPU está em 85%) acorda pessoas por coisas que os usuários nunca notam; alerte sobre sintomas (os usuários estão vendo erros ou lentidão) e use os outros sinais para diagnosticar.

Um service level indicator (SLI) é uma razão medida, como "a parcela de requisições que tiveram sucesso e levaram menos de 300 ms". Um service level objective (SLO) é a meta para ele (99,9% em 30 dias). A diferença entre a meta e 100% é o error budget (orçamento de erro), a quantidade de falha que você pode pagar:

SLO em 30 diasFalha permitida
99,0%432 minutos (7,2 horas)
99,9%43,2 minutos
99,95%21,6 minutos
99,99%4,3 minutos

Um burn rate é a rapidez com que você gasta o orçamento: 1 significa que você usaria exatamente todo ele em 30 dias, e 14,4 significa que gastaria 2% dele em uma hora. O método do SRE workbook do Google aciona uma pessoa com um burn rate alto em uma janela curta (por exemplo, 14,4 em uma hora) e abre um ticket para uma queima lenta em uma janela longa (1 em três dias), cada um confirmado por uma janela curta, para que um alerta se desfaça logo depois que o problema é corrigido. Isso evita tanto alarmes por oscilações breves quanto o silêncio durante um vazamento lento. Muitas equipes também acrescentam um SLI de latência a partir do histograma, já que um endpoint que responde a toda requisição depois de 10 segundos está "no ar" e é inútil.

6. Erros comuns

  1. Traçar a latência média em vez de percentis, ou tirar a média de percentis de várias instâncias.
  2. Baldes de histograma que não cercam a meta de latência, de modo que o quantil é um palpite.
  3. Valores ilimitados (ids de usuário, ids de requisição, URLs brutas) como labels de métricas.
  4. Logs não estruturados sem id de correlação.
  5. Registrar segredos, tokens ou corpos de requisição inteiros.
  6. Registrar dentro de laços quentes, ou montar a mensagem antes de checar o nível.
  7. Um trace que se quebra na primeira fila, pool de threads ou cliente HTTP que não repassa o contexto.
  8. Apenas head sampling, de modo que requisições raras, lentas ou com falha são descartadas.
  9. Alertas sobre causas (CPU, memória) em vez de sintomas, de modo que as pessoas aprendem a ignorar o pager.
  10. Dashboards que ninguém olha e alertas em que ninguém age, sem dono e sem runbook.

7. Coisas a mencionar em uma entrevista

Perguntas que os entrevistadores gostam de acrescentar:

Resumo rápido

  1. As métricas dizem que algo está errado, os traces dizem onde, os logs dizem por quê, e um trace id nos três os une.
  2. A latência tem uma cauda: com 2% de requisições lentas, a média foi de 60 ms, a mediana de 20 ms e o p99 de 1 995 ms; uma página com vinte chamadas atingiu uma lenta um terço das vezes.
  3. Percentis não podem ser tirados em média (uma média de p99 deu 559 ms; o p99 real foi de 31 ms); registre histogramas, some os baldes e escolha baldes perto da sua meta.
  4. Os labels de métricas precisam ser limitados; identificadores pertencem a logs e traces. Um label user_id custou 37 MB por 100 000 usuários em um registro de brinquedo.
  5. Registre como eventos estruturados com um id de correlação e nunca segredos; uma chamada desligada com argumentos preguiçosos custou 154 ns contra 1 225 ns quando a mensagem foi montada antes.
  6. Propague o traceparent em todo salto, inclusive filas. Em uma simulação, o head sampling a 1% guardou 6 de 949 traces lentos ou com falha, e um tail sampler que viu todos os spans guardou todos; um collector real só os guarda dentro da sua capacidade e da sua janela de decisão.
  7. Alerte sobre sintomas usando SLOs e burn rates: uma meta de 99,9% permite 43,2 minutos de falha por mês.

Apêndice: o código dos experimentos

Python 3.13, apenas a biblioteca padrão. São esboços de ensino, não instrumentação de produção (veja a nota na seção 1). Execute cada arquivo com python3. Os resultados variam um pouco com a semente aleatória e com a máquina.

Estatísticas de latência: médias, percentis, mesclagem e erro de balde

import random, statistics, bisect
random.seed(7)

# 1. mean vs percentiles: 98% of requests take about 20 ms, 2% hit a slow path of about 2 s
lat = [random.gauss(20, 4) for _ in range(98_000)] + [random.gauss(2000, 300) for _ in range(2_000)]
lat = sorted(max(1, x) for x in lat)
q = lambda p: lat[int(len(lat) * p) - 1]
print("1. 100,000 requests")
print(f"   mean {statistics.mean(lat):.0f} ms   p50 {q(.5):.0f} ms   p90 {q(.9):.0f} ms   p99 {q(.99):.0f} ms   p99.9 {q(.999):.0f} ms   max {lat[-1]:.0f} ms")

# 2. a page makes 20 backend calls: how often does a user hit at least one slow one?
for n in (1, 5, 20, 50):
    print(f"   page with {n:>2} calls: {100 * (1 - 0.98 ** n):4.1f}% of page loads include a call from the slow 2%")

# 3. percentiles cannot be averaged: two servers, very different traffic
a = [random.gauss(20, 4) for _ in range(9_950)] + [random.gauss(900, 100) for _ in range(50)]      # busy, 0.5% slow
b = [random.gauss(20, 4) for _ in range(90)] + [random.gauss(900, 100) for _ in range(10)]        # quiet, 10% slow
p99 = lambda xs: sorted(xs)[int(len(xs) * .99) - 1]
print("3. two servers")
print(f"   p99 A (10,000 requests) {p99(a):.0f} ms, p99 B (100 requests) {p99(b):.0f} ms, average of the two {(p99(a) + p99(b)) / 2:.0f} ms, p99 of all the requests together {p99(a + b):.0f} ms")

# 4. percentiles estimated from histogram buckets
def estimate(xs, bounds, p):
    counts = [0] * (len(bounds) + 1)
    for x in xs: counts[bisect.bisect_left(bounds, x)] += 1
    target, seen = p * len(xs), 0
    for i, c in enumerate(counts):
        if seen + c >= target:
            lo = bounds[i - 1] if i > 0 else 0
            hi = bounds[i] if i < len(bounds) else bounds[-1]
            return lo + (hi - lo) * (target - seen) / c      # linear interpolation inside the bucket
        seen += c
exact = p99(lat)
for name, bounds in (("buckets 10, 100, 1000, 10000", [10, 100, 1000, 10000]),
                     ("buckets 5, 10, 25, 50, 100, 250, 500, 1000, 2500", [5, 10, 25, 50, 100, 250, 500, 1000, 2500])):
    print(f"4. p99 from {name}: estimate {estimate(lat, bounds, .99):.0f} ms, exact {exact:.0f} ms")
for name, bounds in (("buckets 10, 100, 1000, 10000", [10, 100, 1000, 10000]),
                     ("buckets 5, 10, 25, 50, 100, 250, 500, 1000, 2500", [5, 10, 25, 50, 100, 250, 500, 1000, 2500])):
    print(f"   p50 from {name}: estimate {estimate(lat, bounds, .5):.0f} ms, exact {q(.5):.0f} ms")

Um exemplo de dois serviços com métricas, traces e logs

import bisect, contextvars, json, secrets, threading, time, urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

# ---------------- the three signals, hand-made ----------------
ctx = contextvars.ContextVar("ctx", default=None)          # (trace_id, current span id)
LOGS, SPANS, LOCK = [], [], threading.Lock()

def log(service, level, msg, **fields):                     # structured log line: one JSON object
    c = ctx.get() or (None, None)
    rec = {"ts": round(time.time(), 3), "level": level, "service": service, "msg": msg,
           "trace_id": c[0], **fields}
    with LOCK: LOGS.append(rec)

class span:                                                  # a timed unit of work with a parent
    def __init__(self, service, name, trace_id=None, parent=None):
        c = ctx.get()
        self.service, self.name = service, name
        self.trace_id = trace_id or (c[0] if c else secrets.token_hex(16))
        self.parent = parent or (c[1] if c else None)
        self.id = secrets.token_hex(8)
    def __enter__(self):
        self.t0 = time.perf_counter(); self.token = ctx.set((self.trace_id, self.id)); return self
    def __exit__(self, *e):
        ctx.reset(self.token)
        with LOCK: SPANS.append(dict(trace_id=self.trace_id, id=self.id, parent=self.parent, service=self.service,
                                     name=self.name, ms=(time.perf_counter() - self.t0) * 1000))
    def header(self): return f"00-{self.trace_id}-{self.id}-01"   # W3C traceparent

BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5]
class Histogram:
    def __init__(self): self.counts = [0] * (len(BUCKETS) + 1); self.sum = 0; self.n = 0
    def observe(self, s): self.counts[bisect.bisect_left(BUCKETS, s)] += 1; self.sum += s; self.n += 1
    def render(self, name):
        out, run = [], 0
        for b, c in zip(BUCKETS, self.counts): run += c; out.append(f'{name}_bucket{{le="{b}"}} {run}')
        out.append(f'{name}_bucket{{le="+Inf"}} {self.n}'); out.append(f"{name}_sum {self.sum:.3f}"); out.append(f"{name}_count {self.n}")
        return "\n".join(out)
    def quantile(self, p):
        target, seen = p * self.n, 0
        for i, c in enumerate(self.counts):
            if seen + c >= target and c:
                lo = BUCKETS[i - 1] if i else 0; hi = BUCKETS[i] if i < len(BUCKETS) else BUCKETS[-1]
                return lo + (hi - lo) * (target - seen) / c
            seen += c
LAT, REQS = Histogram(), {}

def parse_parent(h):
    if not h: return None, None
    _, tid, sid, _ = h.split("-"); return tid, sid

# ---------------- two services ----------------
cache = {"sku-1": 12, "sku-2": 15}
class Catalog(BaseHTTPRequestHandler):
    def log_message(self, *a): pass
    def do_GET(self):
        tid, parent = parse_parent(self.headers.get("traceparent"))
        sku = self.path.split("=")[1]
        with span("catalog", "GET /price", tid, parent):
            with span("catalog", "cache.lookup"):
                hit = sku in cache
            if hit: log("catalog", "INFO", "cache hit", sku=sku)
            else:
                log("catalog", "WARN", "cache miss, reading the database", sku=sku)
                with span("catalog", "db.query"): time.sleep(0.3)
                cache[sku] = 20
            body = json.dumps({"sku": sku, "price": cache[sku]}).encode()
        self.send_response(200); self.send_header("Content-Length", str(len(body))); self.end_headers(); self.wfile.write(body)

class Web(BaseHTTPRequestHandler):
    def log_message(self, *a): pass
    def do_GET(self):
        t0 = time.perf_counter()
        with span("web", "GET /checkout") as root:
            sku = self.path.split("=")[1]
            log("web", "INFO", "checkout started", sku=sku)
            with span("web", "call catalog") as s:
                req = urllib.request.Request(f"http://127.0.0.1:{CATALOG_PORT}/price?sku={sku}", headers={"traceparent": s.header()})
                urllib.request.urlopen(req).read()
            log("web", "INFO", "checkout finished", sku=sku)
        dt = time.perf_counter() - t0
        LAT.observe(dt); REQS[200] = REQS.get(200, 0) + 1
        self.send_response(200); self.send_header("Content-Length", "2"); self.end_headers(); self.wfile.write(b"ok")

cat = ThreadingHTTPServer(("127.0.0.1", 0), Catalog); CATALOG_PORT = cat.server_address[1]
web = ThreadingHTTPServer(("127.0.0.1", 0), Web); WEB_PORT = web.server_address[1]
for s in (cat, web): threading.Thread(target=s.serve_forever, daemon=True).start()

# 40 checkouts; every fifth one asks for a SKU that is not cached yet
for i in range(40):
    sku = f"sku-{i}" if i % 5 == 0 and i >= 10 else ("sku-1" if i % 2 else "sku-2")
    urllib.request.urlopen(f"http://127.0.0.1:{WEB_PORT}/checkout?sku={sku}").read()

print("== METRICS: the question 'is something wrong?'")
print(f"requests={REQS[200]}  mean={LAT.sum / LAT.n * 1000:.0f} ms  p50~{LAT.quantile(.5) * 1000:.0f} ms  p95~{LAT.quantile(.95) * 1000:.0f} ms  p99~{LAT.quantile(.99) * 1000:.0f} ms")
print(LAT.render("checkout_duration_seconds"))
roots = [s for s in SPANS if s["name"] == "GET /checkout"]
slow = max(roots, key=lambda s: s["ms"])
print(f"\n== TRACES: the question 'where did the time go?' (slowest trace {slow['trace_id'][:8]}..., {slow['ms']:.0f} ms)")
mine = sorted((s for s in SPANS if s["trace_id"] == slow["trace_id"]), key=lambda s: -s["ms"])
depth = {None: -1}
byid = {s["id"]: s for s in mine}
def d(s): return 0 if s["parent"] not in byid else 1 + d(byid[s["parent"]])
for s in sorted(mine, key=lambda s: (d(s), -s["ms"])): print("  " * d(s) + f"{s['service']:8} {s['name']:16} {s['ms']:6.0f} ms")
print(f"\n== LOGS: the question 'why?' (only this trace)")
for r in LOGS:
    if r["trace_id"] == slow["trace_id"]: print(json.dumps(r))

Cardinalidade, custo de logs, amostragem e error budgets

import io, json, logging, random, time, tracemalloc

# ---- 1. metric cardinality: every distinct label combination is a separate time series
class Series:                                    # roughly what a histogram series holds: 12 counters + a sum
    __slots__ = ("counts", "sum")
    def __init__(self): self.counts = [0] * 12; self.sum = 0.0
def memory_for(n_series):
    tracemalloc.start(); reg = {}
    for i in range(n_series): reg[("GET", "/checkout", "200", f"user-{i}")] = Series()
    cur, _ = tracemalloc.get_traced_memory(); tracemalloc.stop(); return cur
print("1. cost of a label")
print("   method x route x status = 4 x 25 x 6 = 600 series")
for n in (10_000, 100_000):
    m = memory_for(n); print(f"   a user_id label with {n:>7,} users: {m / 1e6:6.1f} MB in memory for one metric ({m / n:.0f} bytes per series), before multiplying by routes and statuses")

# ---- 2. what a log call costs
N = 200_000
def timed(fn):
    t = time.perf_counter(); fn(); return (time.perf_counter() - t) / N * 1e9
buf = io.StringIO()
lg = logging.getLogger("t"); lg.propagate = False
h = logging.StreamHandler(buf); lg.addHandler(h)
user, items = "u-42", list(range(20))
lg.setLevel(logging.WARNING)                   # DEBUG is off
r = {}
r["disabled, f-string built first"] = timed(lambda: [lg.debug(f"cart for {user}: {items!r}") for _ in range(N)])
r["disabled, lazy % arguments"] = timed(lambda: [lg.debug("cart for %s: %r", user, items) for _ in range(N)])
lg.setLevel(logging.INFO)
r["enabled, plain text"] = timed(lambda: [lg.info("cart for %s: %r", user, items) for _ in range(N)])
class J(logging.Formatter):
    def format(self, rec): return json.dumps({"level": rec.levelname, "msg": rec.getMessage(), "user": user, "n_items": len(items)})
h.setFormatter(J())
r["enabled, JSON"] = timed(lambda: [lg.info("cart for %s: %r", user, items) for _ in range(N)])
print("2. cost of one log call (nanoseconds, Python 3.13, output to memory)")
for k, v in r.items(): print(f"   {k:32} {v:8.0f} ns")

# ---- 3. sampling traces
random.seed(3)
TOTAL, P_BAD = 1_000_000, 0.001                  # 0.1% of requests are slow or failed
bad = sum(1 for _ in range(TOTAL) if random.random() < P_BAD)
print("3. sampling 1,000,000 requests of which about 0.1% are slow or failed")
head = sum(1 for _ in range(bad) if random.random() < 0.01)
print(f"   head sampling at 1%: stores about {TOTAL * 0.01:,.0f} traces; of the {bad} interesting ones it kept {head}")
tail_kept = bad + sum(1 for _ in range(TOTAL - bad) if random.random() < 0.01)
print(f"   tail sampling (keep every slow or failed trace, plus 1% of the rest): stores about {tail_kept:,} traces; kept {bad} of {bad}")

# ---- 4. SLO arithmetic
print("4. error budget over 30 days (43,200 minutes)")
for slo in (99.0, 99.9, 99.95, 99.99):
    mins = 43200 * (1 - slo / 100); print(f"   {slo}% -> {mins:7.1f} minutes of failure allowed ({mins / 60:5.2f} hours)")
print("   burn rate 14.4 spends 2% of a 30-day budget in 1 hour; burn rate 1 spends it exactly in 30 days")

Fontes

  1. Betsy Beyer et al., Site Reliability Engineering, capítulo "Monitoring Distributed Systems". Os quatro sinais dourados, sintomas versus causas.
  2. Google, The Site Reliability Workbook, capítulo "Alerting on SLOs". Error budgets e alertas de burn rate em várias janelas.
  3. W3C, Trace Context. O formato do cabeçalho traceparent.
  4. Prometheus, Histograms and summaries. Por que quantis de histogramas podem ser agregados e os de summaries não.
  5. Documentação do OpenTelemetry. Conceitos de traces, métricas e logs, e amostragem.

Pratique este tema: DevOps & Cloud

Mais guias