DEV Community: apsis-cc

Dashboards no Grafana - combinando PromQL e LogQL para acompanhar uma aplicação de ponta a ponta

Rafael Dutra — Sat, 26 Sep 2026 09:30:37 +0000

1. Retomando: dados prontos, falta visualizar

A stack unificada do artigo anterior já coleta métricas das duas mini apps, recebe seus logs e processa seus traces. Mas até aqui, toda consulta foi feita manualmente — uma expressão PromQL de cada vez no Prometheus, uma query LogQL de cada vez no Explore do Grafana. Este artigo constrói um dashboard real, com vários painéis lado a lado, para acompanhar as duas mini apps sem precisar reabrir consultas soltas toda vez.

2. Criando o dashboard e o primeiro painel

No Grafana, em Dashboards → New → New Dashboard → Add visualization, escolhendo o datasource Prometheus, o primeiro painel é a taxa de requisições da mini app Python:

rate(app_requests_total{job="python-app"}[1m])

Configurações relevantes desse painel:

Visualization: Time series (o padrão, adequado para qualquer métrica ao longo do tempo).
Title: "Taxa de Requisições — Python App".
Unit (na aba Standard options): "requests/sec", para o eixo Y ficar legível sem precisar interpretar o número bruto.

3. Painel de latência com histogram_quantile

Um segundo painel, usando o histogram de duração criado no artigo 3 para a mini app PHP:

histogram_quantile(0.50, rate(orders_duration_seconds_bucket{job="php-app"}[5m]))
histogram_quantile(0.95, rate(orders_duration_seconds_bucket{job="php-app"}[5m]))
histogram_quantile(0.99, rate(orders_duration_seconds_bucket{job="php-app"}[5m]))

Adicionando as três expressões como três queries (A, B, C) no mesmo painel de Time series, cada uma vira uma linha — p50, p95 e p99 sobrepostas no mesmo gráfico é o padrão mais comum para visualizar latência, porque a distância entre as três linhas já mostra visualmente o quão "cauda longa" (long tail) a latência está: linhas próximas indicam latência consistente, p99 muito acima do p50 indica que uma fração pequena de requisições está bem mais lenta que a maioria.

4. Painel de taxa de erro (gauge)

Um painel do tipo Gauge (ponteiro/velocímetro) para o tamanho atual da fila de pedidos da mini app PHP — útil por mostrar o valor instantâneo de forma proeminente, sem exigir interpretar um gráfico de linha:

orders_queue_size{job="php-app"}

Na aba Thresholds desse painel, vale configurar faixas de cor — verde até 5, amarelo até 15, vermelho acima disso — para o painel comunicar "tudo bem" ou "atenção" de relance, sem precisar ler o número.

5. Painel de logs com LogQL

Adicionando um novo painel, agora com o datasource Loki, tipo Logs:

{app=~"python-app|php-app"}

A expressão =~ faz correspondência por regex no valor do label — nesse caso, trazendo logs das duas aplicações no mesmo painel, empilhados por tempo. Um segundo painel de logs, filtrado só para eventos de erro (útil para manter visível mesmo quando o volume geral de log é alto):

{app=~"python-app|php-app", level="error"}

6. Painel de volume de logs ao longo do tempo

O LogQL também permite agregações numéricas sobre logs, não só listagem de linhas — útil para correlacionar visualmente um pico de volume de log de erro com um painel de métricas ao lado:

sum(count_over_time({app=~"python-app|php-app", level="error"}[1m]))

Esse painel, como Time series (mesmo vindo de uma query LogQL), mostra quantas linhas de log de erro por minuto cada aplicação produziu — o equivalente, em logs, ao que rate() faz para um counter do Prometheus.

7. Organizando o dashboard

Com os cinco painéis criados — taxa de requisições, latência p50/p95/p99, tamanho da fila, logs recentes e volume de erro — a organização recomendada segue uma convenção comum em dashboards de observabilidade: do geral para o específico, de cima para baixo.

┌─────────────────────────┬─────────────────────────┐
│ Taxa de Requisições      │ Latência p50/p95/p99     │
├─────────────────────────┼─────────────────────────┤
│ Tamanho da Fila (gauge)  │ Volume de Erros / min     │
├─────────────────────────┴─────────────────────────┤
│ Logs Recentes (filtrados por app e nível)           │
└─────────────────────────────────────────────────────┘

Painéis de métrica agregada (o "o quê") ficam no topo, e o painel de logs detalhado (o "por quê") fica embaixo — assim, o fluxo natural de investigação (ver o problema no topo, entender a causa embaixo) segue a ordem visual do próprio dashboard. Salvando o dashboard com um nome como "Mini Apps — Visão Geral" e uma tag observabilidade, ele fica disponível na lista principal de dashboards do Grafana.

8. Variável de template para alternar entre apps

Para não duplicar o dashboard inteiro entre Python e PHP, o Grafana permite criar uma variável que filtra os painéis dinamicamente. Em Dashboard settings → Variables → Add variable:

Name: app
Type: Query
Data source: Prometheus
Query: label_values(app_requests_total, job) (ou, mais genérico, label_values(job) para listar todos os jobs configurados no prometheus.yml)

Com a variável criada, cada query dos painéis passa a usar $app no lugar do valor fixo:

rate(app_requests_total{job="$app"}[1m])

Um seletor aparece no topo do dashboard, permitindo trocar entre python-app e php-app sem editar nenhum painel manualmente — o mesmo dashboard serve para as duas mini apps, e para qualquer aplicação nova que a stack venha a ganhar no futuro.

9. Conclusão e próximos passos

Construímos um dashboard real combinando métricas via PromQL (taxa de requisições, latência por percentil, tamanho de fila) e logs via LogQL (eventos recentes, volume de erro), organizados do geral para o específico e parametrizados com uma variável de template para reutilização entre aplicações. No último artigo desta série, esse dashboard vira ferramenta de investigação de verdade: vamos simular um incidente real nas mini apps e usar métricas, logs e traces juntos para encontrar a causa raiz.

Imagem de capa: Logo oficial do Prometheus — repositório prometheus/prometheus, licença Apache 2.0 (convertido para PNG via wsrv.nl)

Referências:

Stack completa de observabilidade com Docker Compose - Python, PHP, Prometheus, Loki, OpenTelemetry e Grafana

Rafael Dutra — Fri, 25 Sep 2026 09:30:38 +0000

1. Retomando: as peças soltas até aqui

Cada artigo desta série subiu uma peça isolada: Prometheus + Loki + Grafana no artigo 1, a mini app Python no artigo 2, a mini app PHP no artigo 3, envio de logs para o Loki no artigo 4, e instrumentação de traces (por enquanto só impressos no console) no artigo 5. Este artigo une tudo em um único docker-compose.yml, com uma peça nova: um coletor OpenTelemetry, responsável por receber os traces das mini apps via OTLP e encaminhá-los adiante.

2. Por que um coletor no meio do caminho

No artigo 5, as mini apps exportavam spans diretamente para o console (ConsoleSpanExporter). Isso prova que a instrumentação funciona, mas não é assim que uma aplicação real se comunica com uma stack de observabilidade — cada aplicação teria que saber exportar diretamente para cada backend final, duplicando configuração de endpoint, autenticação e formato em todas elas.

O OpenTelemetry Collector resolve isso ficando no meio: as aplicações exportam sempre para o mesmo lugar (o coletor, via OTLP), e é o coletor — configurado uma vez, centralmente — quem decide para onde os dados seguem depois: um backend de traces, processamento adicional (amostragem, enriquecimento de atributos), ou múltiplos destinos ao mesmo tempo. Trocar de backend passa a ser uma mudança de configuração do coletor, não um redeploy de cada aplicação instrumentada.

3. Trocando o exportador de console por OTLP

Nas duas mini apps, o único ponto que muda em relação ao artigo 5 é o exportador — a forma como os spans saem do processo — não a instrumentação em si (os tracer.start_as_current_span e spanBuilder(...)->startSpan() continuam idênticos).

# tracing.py (Python) — troca do ConsoleSpanExporter por OTLP
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
    OTLPSpanExporter,
)

provider = TracerProvider()
exporter = OTLPSpanExporter(endpoint="http://otel-collector:4318/v1/traces")
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("python-app")

pip install opentelemetry-exporter-otlp-proto-http

<?php
// tracing.php (PHP) — troca do ConsoleSpanExporter por OTLP
use OpenTelemetry\Contrib\Otlp\SpanExporter;
use OpenTelemetry\SDK\Common\Transport\Http\PsrTransportFactory;

$transport = (new PsrTransportFactory())->create(
    'http://otel-collector:4318/v1/traces',
    'application/x-protobuf'
);
$exporter = new SpanExporter($transport);
$tracerProvider = new TracerProvider(new SimpleSpanProcessor($exporter));
$tracer = $tracerProvider->getTracer('php-app');

O hostname otel-collector usado nos dois casos é o nome do serviço do Compose que aparece na seção 5.

4. Configurando o coletor

O coletor precisa de um arquivo de configuração declarando três coisas: receivers (como os dados entram), processors (transformações opcionais no meio do caminho) e exporters (para onde os dados saem):

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

Este exemplo usa o exportador debug (o sucessor do antigo logging exporter), que imprime os traces recebidos no log do próprio coletor — suficiente para confirmar que o pipeline completo funciona de ponta a ponta: mini app → coletor → saída. Visualizar traces de forma gráfica, com uma árvore de spans navegável, exigiria um backend de tracing dedicado (como Grafana Tempo ou Jaeger) recebendo esse mesmo exportador — fora do escopo desta stack mínima, mas um próximo passo natural para quem quiser aprofundar depois desta série.

5. O docker-compose.yml unificado

Juntando tudo o que a série construiu até aqui em um único arquivo:

# docker-compose.yml
services:
  prometheus:
    image: prom/prometheus:v2.55.0
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro

  loki:
    image: grafana/loki:3.2.0
    ports:
      - "3100:3100"

  otel-collector:
    image: otel/opentelemetry-collector:0.112.0
    command: ["--config=/etc/otel-collector-config.yaml"]
    volumes:
      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml:ro
    ports:
      - "4318:4318"

  grafana:
    image: grafana/grafana:11.3.0
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    depends_on:
      - prometheus
      - loki

  python-app:
    image: python:3.12-slim
    working_dir: /app
    volumes:
      - ./python-app:/app:ro
    command: ["sh", "-c", "pip install --no-cache-dir opentelemetry-sdk opentelemetry-exporter-otlp-proto-http && python3 app.py"]
    ports:
      - "8000:8000"
    depends_on:
      - otel-collector
      - loki

  php-app:
    image: php:8.3-cli
    working_dir: /app
    volumes:
      - ./php-app:/app
    command: ["php", "-S", "0.0.0.0:8001", "app.php"]
    ports:
      - "8001:8001"
    depends_on:
      - otel-collector
      - loki

E o prometheus.yml reunindo os alvos dos artigos 2 e 3:

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]
  - job_name: "python-app"
    static_configs:
      - targets: ["python-app:8000"]
  - job_name: "php-app"
    static_configs:
      - targets: ["php-app:8001"]

Subindo tudo de uma vez:

docker compose up -d
docker compose ps

Seis serviços devem aparecer no ar: prometheus, loki, otel-collector, grafana, python-app e php-app.

6. Configurando os datasources no Grafana

Com todos os serviços na mesma rede do Compose, em Connections → Data sources no Grafana, dois datasources apontam para os serviços pelo nome:

Prometheus — http://prometheus:9090
Loki — http://loki:3100

Esses são os dois datasources que o artigo 7 desta série vai efetivamente usar em dashboards. O coletor OpenTelemetry não aparece como datasource do Grafana neste setup — ele só encaminha traces para o exportador debug configurado na seção 4; ligar um datasource de traces é o passo seguinte caso um backend de tracing seja adicionado à stack.

7. Confirmando que o pipeline completo funciona

Gerando tráfego nas duas aplicações e conferindo cada ponta:

curl http://localhost:8000/
curl http://localhost:8001/

# metricas
curl http://localhost:8000/metrics
curl http://localhost:8001/metrics

# logs do coletor, onde os traces devem aparecer impressos
docker compose logs otel-collector --tail 50

Se o docker compose logs otel-collector mostrar blocos com TraceID, SpanID e Name para as requisições feitas, o pipeline de ponta a ponta está funcionando: as mini apps geram spans, o coletor os recebe via OTLP e os processa.

8. Conclusão e próximos passos

Unimos as seis peças construídas ao longo da série em uma stack única e reproduzível: duas mini aplicações instrumentadas para métricas, logs e traces, Prometheus fazendo scraping, Loki recebendo logs, um coletor OpenTelemetry recebendo traces via OTLP, e Grafana com os datasources de Prometheus e Loki configurados. No próximo artigo, o foco volta para o Grafana: construir dashboards reais que combinam PromQL e LogQL para acompanhar as mini apps de ponta a ponta em um único painel.

Imagem de capa: Logo oficial do Prometheus — repositório prometheus/prometheus, licença Apache 2.0 (convertido para PNG via wsrv.nl)

Referências:

OpenTelemetry - o que é, por que virou padrão e como instrumentar traces

Rafael Dutra — Thu, 24 Sep 2026 09:30:37 +0000

1. Retomando: métricas e logs prontos, falta conectar os pontos

As mini apps desta série já expõem métricas (artigos 2 e 3) e enviam logs para o Loki (artigo 4). O que ainda falta é o terceiro pilar visto no artigo 1: traces, que mostram o caminho de uma requisição específica e onde exatamente o tempo foi gasto. Este artigo apresenta o OpenTelemetry, o padrão atual para gerar esse tipo de dado, e instrumenta as duas mini apps para produzir traces reais.

2. O que é o OpenTelemetry

OpenTelemetry (frequentemente abreviado "OTel") é um projeto da CNCF que define um conjunto de APIs, SDKs e um protocolo de transporte (o OTLP — OpenTelemetry Protocol) para gerar, processar e exportar dados de telemetria — métricas, logs e, principalmente neste artigo, traces — de forma neutra em relação a qual backend vai efetivamente armazenar e visualizar esses dados.

Na prática, isso significa que a aplicação se instrumenta uma vez, contra a API do OpenTelemetry, e decide depois, por configuração, para onde exportar — Prometheus, Loki, Jaeger, um vendor comercial, ou, como esta série vai fazer no próximo artigo, um coletor OpenTelemetry intermediário. Trocar de backend de observabilidade deixa de exigir reescrever a instrumentação.

3. Por que virou o padrão dominante

Antes do OpenTelemetry, existiam dois projetos concorrentes e incompatíveis tentando resolver o mesmo problema: OpenTracing (focado em traces) e OpenCensus (traces e métricas, liderado pelo Google). Cada biblioteca de instrumentação precisava escolher um dos dois, fragmentando o ecossistema — uma biblioteca instrumentada para OpenTracing não conversava com um backend pensado para OpenCensus sem camadas de tradução.

Em 2019, os dois projetos se fundiram no OpenTelemetry, sob a CNCF (a mesma fundação que abriga Kubernetes e Prometheus). Isso resolveu a fragmentação e, mais importante, deu ao projeto neutralidade de fornecedor: nenhum vendor de observabilidade controla o padrão, o que fez praticamente todos os grandes players (Datadog, New Relic, Grafana, AWS, Google Cloud, Azure) apoiarem OTLP como protocolo de entrada nativo. Hoje, instrumentar com OpenTelemetry é a opção que menos prende a aplicação a um fornecedor específico.

4. Conceitos de tracing: trace, span e contexto

Retomando e aprofundando o que o artigo 1 introduziu:

Span — a unidade básica: representa uma operação com início, fim e duração (uma chamada HTTP, uma query, um cálculo). Carrega um nome, atributos (pares chave-valor arbitrários) e, opcionalmente, eventos pontuais dentro do seu intervalo de tempo.
Trace — o conjunto de todos os spans gerados para atender uma única requisição de ponta a ponta, conectados entre si por um trace id compartilhado.
Span pai/filho — um span pode iniciar outros spans "dentro" dele (por exemplo, o span da requisição HTTP inicia um span filho para a query de banco que ela dispara). Essa relação de aninhamento é o que permite reconstruir a árvore de tempo vista no artigo 1.
Propagação de contexto — quando uma requisição atravessa um limite de processo (chamada HTTP entre dois serviços), o trace id e o span id atual viajam como cabeçalhos HTTP (o formato padrão é o traceparent, definido pela especificação W3C Trace Context), permitindo que o serviço seguinte continue o mesmo trace em vez de iniciar um novo.

5. Instrumentando a mini app Python

O SDK oficial do Python precisa ser instalado (não é parte da biblioteca padrão, diferente do que as mini apps fizeram até aqui para métricas e logs — gerar spans manualmente sem SDK é possível, mas reimplementar amostragem, contexto e propagação à mão perde o sentido de usar um padrão justamente feito para isso):

pip install opentelemetry-sdk

Instrumentação manual, criando um span por requisição:

# tracing.py
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    BatchSpanProcessor,
    ConsoleSpanExporter,
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("python-app")

Integrando no app.py do artigo 2, envolvendo o processamento da requisição em um span:

from tracing import tracer

# dentro do do_GET, no branch que nao eh /metrics
with tracer.start_as_current_span("handle_request") as span:
    span.set_attribute("http.path", self.path)
    request_count += 1
    log_to_loki(f"requisicao recebida em {self.path}")
    span.set_attribute("http.status_code", 200)

Por enquanto, o exportador usado é o ConsoleSpanExporter, que apenas imprime cada span no stdout — suficiente para confirmar que a instrumentação está gerando dados, sem depender de nenhuma infraestrutura adicional ainda. Rodando a aplicação e fazendo uma requisição, o terminal deve mostrar um bloco JSON com trace_id, span_id, name e start_time/end_time.

6. Instrumentando a mini app PHP

O equivalente em PHP usa o SDK oficial, instalado via Composer:

composer require open-telemetry/sdk open-telemetry/exporter-otlp

<?php
// tracing.php
require __DIR__ . '/vendor/autoload.php';

use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
use OpenTelemetry\SDK\Trace\SpanExporter\ConsoleSpanExporter;

$exporter = new ConsoleSpanExporter();
$tracerProvider = new TracerProvider(
    new SimpleSpanProcessor($exporter)
);
$tracer = $tracerProvider->getTracer('php-app');

Integrando no app.php do artigo 3, ao redor do processamento de um pedido:

require __DIR__ . '/tracing.php';

$span = $tracer->spanBuilder('process_order')->startSpan();
$scope = $span->activate();

try {
    // ... logica de processamento do pedido, ja existente ...
    $span->setAttribute('order.duration_ms', $state['durations'][count($state['durations']) - 1] * 1000);
} finally {
    $span->end();
    $scope->detach();
}

O padrão try/finally garante que o span é finalizado mesmo se o processamento lançar uma exceção no meio do caminho — um span que nunca termina (por um end() que não é alcançado) é um erro comum de instrumentação manual, e polui o backend de traces com spans "presos".

7. Conclusão e próximos passos

Vimos o que é o OpenTelemetry, por que a fusão de OpenTracing e OpenCensus em 2019 o tornou o padrão neutro de instrumentação, os conceitos de span, trace e propagação de contexto, e instrumentamos manualmente as duas mini apps para gerar spans — por enquanto, só visíveis no console de cada aplicação. No próximo artigo, a stack inteira é unificada em um único docker-compose.yml: as mini apps trocam o ConsoleSpanExporter por um exportador OTLP de verdade, apontando para um coletor OpenTelemetry, ao lado de Prometheus, Loki e Grafana já configurados.

Imagem de capa: Logo oficial do Prometheus — repositório prometheus/prometheus, licença Apache 2.0 (convertido para PNG via wsrv.nl)

Referências:

Loki na prática - enviando logs via API HTTP a partir das mini apps Python e PHP

Rafael Dutra — Wed, 23 Sep 2026 09:30:35 +0000

1. Retomando: métricas prontas, falta o segundo pilar

As duas mini aplicações desta série — a de Python (artigo 2) e a de PHP (artigo 3) — já expõem métricas consumidas pelo Prometheus. Métricas respondem "quantos pedidos falharam nos últimos 5 minutos", mas não respondem "por que o pedido 4821 falhou especificamente". Essa é a pergunta que logs respondem, e este artigo cobre como enviá-los para o Loki diretamente das mini apps.

2. Por que a indexação do Loki é diferente

Ferramentas de log tradicionais, como o Elasticsearch, indexam o conteúdo completo de cada linha — todo termo de texto vira pesquisável, o que permite buscas ricas, mas exige estruturas de índice caras em disco e CPU, que crescem proporcionalmente ao volume de log.

O Loki toma uma decisão deliberadamente diferente, inspirada diretamente no modelo do Prometheus: indexa só um conjunto pequeno de labels — como app="python-app", env="production" — e trata o conteúdo da linha de log como texto opaco, comprimido e armazenado em blocos (chunks), sem índice próprio. Quando uma consulta pede um filtro de texto (|= "erro", por exemplo), o Loki varre os chunks relevantes (já filtrados pelos labels) no momento da consulta, em vez de consultar um índice pré-construído.

O resultado prático dessa troca:

Armazenamento muito mais barato — sem índice invertido de texto completo, o custo de disco cresce bem mais devagar com o volume de logs.
Buscas por label são muito rápidas — "todos os logs do serviço X, no ambiente Y" é uma operação barata, porque os labels são de fato indexados.
Buscas por texto livre são mais lentas conforme o volume cresce — porque envolvem varredura, não um lookup de índice. Na prática, isso empurra o usuário a sempre filtrar primeiro por labels (que reduzem drasticamente o volume a varrer) antes de aplicar um filtro de texto.
Cardinalidade de labels importa tanto quanto no Prometheus — usar um label com alta cardinalidade (como um user_id único por requisição) quebra a mesma premissa de eficiência nos dois sistemas, e é um erro comum de quem vem de ferramentas que indexam tudo.

3. A API HTTP de push do Loki

Diferente do Prometheus (que faz pull), o Loki recebe logs por push: a aplicação envia ativamente cada lote de linhas para um endpoint HTTP, POST /loki/api/v1/push. O corpo da requisição é um JSON com o seguinte formato:

{
  "streams": [
    {
      "stream": {
        "app": "python-app",
        "level": "info"
      },
      "values": [
        ["1735689600000000000", "requisicao recebida em /"]
      ]
    }
  ]
}

Pontos importantes desse formato:

stream carrega os labels — o que o Loki de fato indexa. Poucos e de baixa cardinalidade, como visto acima.
values é uma lista de [timestamp, linha], onde o timestamp é uma string em nanosegundos desde epoch (não segundos, nem milissegundos — um detalhe fácil de errar).
É possível enviar múltiplas linhas do mesmo stream de uma vez, o que é mais eficiente do que uma requisição HTTP por linha de log.

4. Enviando logs a partir da mini app Python

Usando só a biblioteca padrão (urllib, sem instalar um client HTTP externo), uma função de log que envia diretamente para o Loki:

# logger.py
import json
import time
import urllib.request

LOKI_URL = "http://loki:3100/loki/api/v1/push"


def log_to_loki(message, level="info", app="python-app"):
    timestamp_ns = str(time.time_ns())
    payload = {
        "streams": [
            {
                "stream": {"app": app, "level": level},
                "values": [[timestamp_ns, message]],
            }
        ]
    }
    req = urllib.request.Request(
        LOKI_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    try:
        urllib.request.urlopen(req, timeout=2)
    except Exception as exc:
        # nunca deixar uma falha de log derrubar a aplicacao
        print(f"falha ao enviar log para o Loki: {exc}")

Integrando no app.py do artigo 2, chamando log_to_loki a cada requisição de negócio:

# dentro do do_GET, no branch que nao eh /metrics
log_to_loki(f"requisicao recebida em {self.path}")

5. Enviando logs a partir da mini app PHP

O mesmo endpoint, chamado a partir do PHP puro com file_get_contents e um stream context (sem precisar de cURL nem bibliotecas externas):

<?php
// logger.php

function logToLoki($message, $level = 'info', $app = 'php-app') {
    // microtime(true) da segundos com fracao decimal; convertendo para
    // nanossegundos desde epoch, o formato que o Loki espera
    $timestampNs = sprintf('%.0f', microtime(true) * 1e9);

    $payload = json_encode([
        'streams' => [[
            'stream' => ['app' => $app, 'level' => $level],
            'values' => [[$timestampNs, $message]],
        ]],
    ]);

    $context = stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => "Content-Type: application/json\r\n",
            'content' => $payload,
            'timeout' => 2,
            'ignore_errors' => true,
        ],
    ]);

    @file_get_contents('http://loki:3100/loki/api/v1/push', false, $context);
}

Integrando no app.php do artigo 3, logo após processar um pedido:

require __DIR__ . '/logger.php';
logToLoki("pedido processado em {$state['requests_total']} ms de fila");

6. Consultando os logs no Grafana com LogQL

Com o datasource do Loki já configurado no Grafana desde o artigo 1, em Explore, selecionando o datasource Loki, uma consulta LogQL básica:

{app="python-app"}

Isso retorna todas as linhas de log com o label app="python-app" — o equivalente a um grep pré-filtrado pelos labels indexados. Para refinar com um filtro de texto:

{app="python-app"} |= "erro"

{app="php-app", level="info"} != "healthcheck"

|= filtra linhas que contêm o texto; != filtra linhas que não contêm. Esses filtros de texto rodam sobre o conteúdo já restrito pelos labels — daí a importância de sempre começar a query pelos labels certos, como discutido na seção 2.

7. Conclusão e próximos passos

Vimos por que o Loki indexa só labels e trata o conteúdo da linha como texto não indexado — uma troca deliberada de riqueza de busca por custo —, como enviar logs diretamente via API HTTP sem bibliotecas externas em Python e PHP, e como consultar esses logs com LogQL no Grafana. Com métricas e logs das duas mini apps já fluindo para a stack, falta o terceiro pilar: o próximo artigo introduz o OpenTelemetry e instrumenta as mesmas aplicações para gerar traces.

Imagem de capa: Logo oficial do Prometheus — repositório prometheus/prometheus, licença Apache 2.0 (convertido para PNG via wsrv.nl)

Referências:

Métricas customizadas - counters, gauges e histograms com uma mini app PHP

Rafael Dutra — Tue, 22 Sep 2026 09:30:28 +0000

1. Retomando: de uma métrica a um conjunto completo

No artigo anterior, a mini aplicação em Python expunha uma única métrica — uma contagem de requisições. Na prática, uma aplicação real quer responder perguntas de negócio mais específicas: quantos pedidos foram criados? Quanto tempo cada requisição levou? Quantas conexões estão abertas agora? Cada uma dessas perguntas pede um tipo diferente de métrica. Este artigo cobre os três tipos que cobrem praticamente todo caso de uso — counter, gauge e histogram — com uma segunda mini aplicação, desta vez em PHP puro, expondo métricas de negócio.

2. Counter: só sobe (até o processo reiniciar)

Um counter é um valor que só aumenta (ou zera, se o processo reinicia). É o tipo certo para "quantas vezes algo aconteceu": número de requisições, número de erros, número de pedidos criados. A mini app do artigo anterior já usava um counter (app_requests_total).

O sufixo _total no nome é uma convenção do Prometheus para deixar explícito que a métrica é um counter cumulativo, não um valor instantâneo — vale seguir essa convenção mesmo implementando o texto à mão.

# HELP orders_created_total Total de pedidos criados
# TYPE orders_created_total counter
orders_created_total 187

3. Gauge: sobe e desce livremente

Um gauge representa um valor que pode aumentar ou diminuir a qualquer momento — é o tipo certo para "quanto existe agora": número de conexões abertas, itens numa fila, memória em uso, temperatura. Diferente do counter, não existe uma direção esperada.

# HELP orders_queue_size Numero de pedidos aguardando processamento
# TYPE orders_queue_size gauge
orders_queue_size 4

4. Histogram: distribuição de valores em buckets

Um histogram captura a distribuição de uma medida contínua — o caso mais comum é tempo de resposta. Em vez de guardar cada valor individual (inviável em alta escala) ou só uma média (que esconde outliers), um histogram conta quantas observações caíram dentro de faixas pré-definidas, chamadas buckets.

# HELP orders_duration_seconds Tempo de processamento de um pedido
# TYPE orders_duration_seconds histogram
orders_duration_seconds_bucket{le="0.1"} 120
orders_duration_seconds_bucket{le="0.5"} 180
orders_duration_seconds_bucket{le="1"} 195
orders_duration_seconds_bucket{le="+Inf"} 200
orders_duration_seconds_sum 42.7
orders_duration_seconds_count 200

Cada linha _bucket{le="X"} é cumulativa: "quantas observações foram menores ou iguais a X segundos". _sum é a soma de todos os valores observados, e _count é o total de observações (igual ao último bucket, +Inf). Com essas peças, o Prometheus consegue calcular percentis aproximados (p50, p95, p99) em tempo de consulta, via histogram_quantile — sem que a aplicação precise calcular percentil nenhum sozinha.

5. Mini app em PHP puro com métricas de negócio

Sem nenhum framework, usando apenas o servidor embutido do PHP (php -S), uma aplicação que simula processamento de pedidos e expõe as três métricas vistas acima:

<?php
// app.php

$stateFile = __DIR__ . '/metrics_state.json';

function readState($file) {
    if (!file_exists($file)) {
        return ['requests_total' => 0, 'queue_size' => 0, 'durations' => []];
    }
    return json_decode(file_get_contents($file), true);
}

function writeState($file, $state) {
    file_put_contents($file, json_encode($state));
}

$state = readState($stateFile);

if ($_SERVER['REQUEST_URI'] === '/metrics') {
    $buckets = [0.1, 0.5, 1.0];
    $durations = $state['durations'];
    $sum = array_sum($durations);
    $count = count($durations);

    header('Content-Type: text/plain; version=0.0.4');

    echo "# HELP orders_created_total Total de pedidos criados\n";
    echo "# TYPE orders_created_total counter\n";
    echo "orders_created_total {$state['requests_total']}\n";

    echo "# HELP orders_queue_size Numero de pedidos aguardando processamento\n";
    echo "# TYPE orders_queue_size gauge\n";
    echo "orders_queue_size {$state['queue_size']}\n";

    echo "# HELP orders_duration_seconds Tempo de processamento de um pedido\n";
    echo "# TYPE orders_duration_seconds histogram\n";
    $cumulative = 0;
    foreach ($buckets as $le) {
        $cumulative = count(array_filter($durations, fn($d) => $d <= $le));
        echo "orders_duration_seconds_bucket{le=\"{$le}\"} {$cumulative}\n";
    }
    echo "orders_duration_seconds_bucket{le=\"+Inf\"} {$count}\n";
    echo "orders_duration_seconds_sum {$sum}\n";
    echo "orders_duration_seconds_count {$count}\n";
    exit;
}

// Simula o processamento de um novo pedido
$start = microtime(true);
$state['queue_size']++;
usleep(random_int(20_000, 400_000)); // simula trabalho real, 20-400ms
$state['queue_size']--;
$state['requests_total']++;
$state['durations'][] = round(microtime(true) - $start, 3);

writeState($stateFile, $state);

header('Content-Type: text/plain');
echo "pedido processado\n";

Subindo com o servidor embutido do PHP:

php -S 0.0.0.0:8001 app.php

Gerando alguns pedidos e conferindo as métricas:

for i in $(seq 1 10); do curl -s http://localhost:8001/ > /dev/null; done
curl http://localhost:8001/metrics

O estado é persistido em um arquivo JSON local só para manter o exemplo simples e sem dependências — em uma aplicação real, esses contadores normalmente vivem em memória do próprio processo (e cada worker/processo exporia os seus, deixando a agregação entre réplicas por conta do Prometheus).

6. Adicionando a app PHP à stack

# docker-compose.yml (trecho adicionado)
services:
  php-app:
    image: php:8.3-cli
    working_dir: /app
    volumes:
      - ./app.php:/app/app.php
    command: ["php", "-S", "0.0.0.0:8001", "app.php"]
    ports:
      - "8001:8001"

# prometheus.yml (job adicionado)
  - job_name: "php-app"
    static_configs:
      - targets: ["php-app:8001"]

7. Consultando um histogram com histogram_quantile

Com dados fluindo, a consulta mais útil sobre um histogram no PromQL é o percentil de latência:

# p95 de tempo de processamento nos ultimos 5 minutos
histogram_quantile(0.95, rate(orders_duration_seconds_bucket[5m]))

# tamanho atual da fila
orders_queue_size

# taxa de pedidos criados por segundo
rate(orders_created_total[1m])

histogram_quantile reconstrói o percentil aproximado a partir da distribuição por buckets — quanto mais granulares os buckets ao redor do percentil de interesse, mais precisa a estimativa. É uma aproximação, não um cálculo exato sobre os valores individuais (que o Prometheus nunca armazena um a um), mas suficiente para a grande maioria dos casos de uso de observação de latência em produção.

8. Conclusão e próximos passos

Cobrimos os três tipos fundamentais de métrica — counter para contagens cumulativas, gauge para valores que sobem e descem, histogram para distribuições como latência — e construímos uma segunda mini aplicação, agora em PHP puro, expondo métricas de negócio reais. Com duas aplicações diferentes já enviando métricas para o Prometheus, o próximo artigo muda de pilar: como enviar logs dessas mesmas aplicações para o Loki, e por que o modelo de indexação dele é tão diferente do Prometheus.

Imagem de capa: Logo oficial do Prometheus — repositório prometheus/prometheus, licença Apache 2.0 (convertido para PNG via wsrv.nl)

Referências:

Prometheus na prática - scraping, o endpoint /metrics e uma mini app Python expondo métricas

Rafael Dutra — Mon, 21 Sep 2026 03:16:08 +0000

1. Retomando: da stack vazia à primeira fonte de dados

No primeiro artigo desta série, subimos Prometheus, Loki e Grafana com Docker Compose, mas sem nenhuma aplicação real enviando dados — o Prometheus só monitorava a si mesmo. Este artigo resolve isso: vamos entender como o Prometheus efetivamente coleta métricas de uma aplicação (scraping) e construir uma mini aplicação em Python puro, sem nenhum framework, que expõe métricas nesse formato.

2. Pull vs push: o modelo de scraping do Prometheus

Existem duas formas de uma ferramenta de métricas obter dados de uma aplicação:

Push — a aplicação envia ativamente os valores para um servidor central sempre que quiser (ou em intervalos definidos por ela mesma). StatsD funciona assim.
Pull (scraping) — a aplicação apenas expõe seus valores atuais em um endpoint HTTP, e é o servidor de métricas que periodicamente visita esse endpoint e lê o estado atual. É o modelo do Prometheus.

O Prometheus escolheu pull deliberadamente, por algumas razões práticas:

Descoberta centralizada de falhas — se o Prometheus não consegue fazer scraping de um alvo, ele mesmo já sabe e registra isso (métrica up == 0), sem depender da aplicação perceber que parou de enviar dados.
Facilidade de testar manualmente — como o endpoint é só HTTP, dá para abrir /metrics num navegador ou com curl e ver exatamente o que será coletado, sem precisar simular o lado do Prometheus.
Controle central do intervalo de coleta — quem decide a frequência é quem consome os dados (o Prometheus), não cada aplicação individualmente.

A exceção fica por conta de jobs de curta duração (um script batch que roda e termina em segundos, sem ficar no ar para ser "scrapeado") — para esses casos existe o Pushgateway, um componente auxiliar que aceita push e fica exposto para o Prometheus fazer pull dele. Para aplicações de vida longa como as desta série (servidores HTTP), o modelo pull padrão é suficiente.

3. O formato de exposição: o que vive em /metrics

Um endpoint /metrics do Prometheus é simplesmente texto plano, em um formato específico chamado exposition format. Cada métrica segue esta estrutura:

# HELP app_requests_total Total de requisições recebidas
# TYPE app_requests_total counter
app_requests_total 42

A linha # HELP é uma descrição legível por humanos (opcional, mas boa prática).
A linha # TYPE declara o tipo da métrica — counter, gauge, histogram ou summary (o artigo 3 desta série detalha cada tipo).
A linha de dados é nome_da_metrica{labels_opcionais="valor"} valor.

Nenhuma biblioteca é estritamente necessária para gerar esse texto — é só formatação de string. Isso torna o formato fácil de implementar em qualquer linguagem, mesmo sem um cliente oficial, o que é exatamente o que esta mini aplicação vai fazer.

4. Uma mini app em Python puro com http.server

Usando apenas a biblioteca padrão do Python (módulo http.server, sem Flask, Django ou qualquer outro framework), uma aplicação mínima que conta requisições e expõe essa contagem em /metrics:

# app.py
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

start_time = time.time()
request_count = 0


class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        global request_count

        if self.path == "/metrics":
            uptime = time.time() - start_time
            body = (
                "# HELP app_requests_total Total de requisicoes recebidas\n"
                "# TYPE app_requests_total counter\n"
                f"app_requests_total {request_count}\n"
                "# HELP app_uptime_seconds Tempo desde que o processo iniciou\n"
                "# TYPE app_uptime_seconds gauge\n"
                f"app_uptime_seconds {uptime:.2f}\n"
            )
            self.send_response(200)
            self.send_header("Content-Type", "text/plain; version=0.0.4")
            self.end_headers()
            self.wfile.write(body.encode("utf-8"))
            return

        request_count += 1
        self.send_response(200)
        self.send_header("Content-Type", "text/plain")
        self.end_headers()
        self.wfile.write(b"ola do app em python\n")

    def log_message(self, format, *args):
        pass  # silencia o log padrao do http.server no stdout


if __name__ == "__main__":
    server = ThreadingHTTPServer(("0.0.0.0", 8000), Handler)
    print("app rodando em http://0.0.0.0:8000")
    server.serve_forever()

Rodando localmente:

python3 app.py

Cada requisição a qualquer path diferente de /metrics incrementa o contador app_requests_total — importante notar que a própria requisição ao /metrics não conta como requisição de negócio, propositalmente, para não distorcer a métrica. Testando:

curl http://localhost:8000/
curl http://localhost:8000/
curl http://localhost:8000/metrics

A última chamada deve mostrar app_requests_total 2.

5. Configurando o prometheus.yml para coletar a nova app

Com o endpoint funcionando, o próximo passo é adicionar um job ao prometheus.yml do artigo anterior, apontando para essa aplicação:

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]

  - job_name: "python-app"
    static_configs:
      - targets: ["python-app:8000"]

E incluir a aplicação no docker-compose.yml, na mesma rede dos outros serviços (por isso o hostname python-app funciona no target acima — é o nome do serviço no Compose):

# docker-compose.yml (trecho adicionado ao do artigo anterior)
services:
  python-app:
    image: python:3.12-slim
    working_dir: /app
    volumes:
      - ./app.py:/app/app.py:ro
    command: ["python3", "app.py"]
    ports:
      - "8000:8000"

Depois de docker compose up -d, o Prometheus passa a fazer scraping da aplicação a cada 15 segundos (o scrape_interval global). Para confirmar que o alvo está saudável, em http://localhost:9090/targets o job python-app deve aparecer com estado UP.

6. Consultando os dados no Prometheus

Com alguns minutos de coleta (gerando tráfego manualmente com curl em loop, se necessário), já é possível consultar no campo de expressão do Prometheus (http://localhost:9090/graph):

# valor bruto do contador, acumulado desde que o processo subiu
app_requests_total

# taxa de requisições por segundo, calculada sobre a janela de 1 minuto
rate(app_requests_total[1m])

rate() é a função mais usada sobre contadores no PromQL: como um contador só cresce (e zera se o processo reiniciar), o valor bruto não diz muito sozinho — o que importa é a velocidade de crescimento, que é exatamente o que rate() calcula, já lidando corretamente com o caso de reinício do contador.

7. Conclusão e próximos passos

Vimos por que o Prometheus escolhe pull em vez de push, como o formato de exposição em /metrics é apenas texto simples — implementável sem biblioteca alguma —, construímos uma mini aplicação Python que expõe uma métrica real, e configuramos o Prometheus para coletá-la periodicamente. No próximo artigo, a mini aplicação passa a ser em PHP puro, e o foco vai para os três tipos de métrica — counters, gauges e histograms — aplicados a métricas de negócio, não só contagem de requisições.

Imagem de capa: Logo oficial do Prometheus — repositório prometheus/prometheus, licença Apache 2.0 (convertido para PNG via wsrv.nl)

Referências:

Observabilidade - o que é, métricas vs logs vs traces e a stack Prometheus + Loki + Grafana

Rafael Dutra — Mon, 21 Sep 2026 03:16:06 +0000

1. Por que "monitoramento" não é mais suficiente

Por muito tempo, "monitorar" um sistema significava basicamente uma coisa: configurar alguns alertas (CPU alta, disco cheio, processo caiu) e torcer para que eles cubram os problemas que realmente vão acontecer. Isso funciona enquanto o sistema é simples e as formas de falhar são poucas e conhecidas de antemão.

O problema aparece quando o sistema cresce: dezenas de serviços, comunicando-se entre si, rodando em múltiplos containers ou máquinas, com falhas que emergem de combinações imprevisíveis de fatores. Nesse cenário, a pergunta deixa de ser "esse alerta específico disparou?" e passa a ser "por que essa requisição específica ficou lenta, agora, nesse serviço, para esse usuário?" — uma pergunta que ninguém pensou em antecipar com um alerta configurado de antemão.

Observabilidade é a propriedade de um sistema que permite responder a esse tipo de pergunta nova, não prevista, olhando apenas para os dados que ele expõe externamente — sem precisar adicionar instrumentação nova ou fazer deploy de novo código toda vez que surge uma dúvida diferente. Ela se apoia em três tipos de dados, chamados informalmente de "os três pilares": métricas, logs e traces. Esta é a primeira parte de uma série sobre observabilidade que vai construir, artigo a artigo, uma stack completa e funcional com exemplos práticos em Docker Compose.

2. Métricas: números agregados ao longo do tempo

Uma métrica é um valor numérico associado a um timestamp, coletado repetidamente ao longo do tempo — uma série temporal. Exemplos: número de requisições por segundo, uso de memória, tempo de resposta médio, número de erros nos últimos 5 minutos.

Características importantes:

Baratas de armazenar em volume e por longo prazo — um número por intervalo de tempo ocupa muito menos espaço que um log de texto completo, o que permite guardar meses ou anos de histórico sem custo proibitivo.
Ótimas para alertas e dashboards — perguntas como "a taxa de erro passou de 5%?" ou "a latência p99 está subindo?" são naturalmente respondidas por métricas.
Agregadas, não individuais — uma métrica de "tempo de resposta médio" não diz nada sobre qual requisição específica foi lenta, só que, em média, algo mudou. Para investigar o "qual" e o "por quê", é preciso recorrer aos outros dois pilares.

3. Logs: eventos discretos com contexto rico

Um log é um registro textual e datado de um evento específico: uma requisição recebida, um erro capturado, uma conexão de banco aberta. Ao contrário de uma métrica, um log carrega contexto arbitrário — uma mensagem de erro completa, um stack trace, o payload de uma requisição.

Essa riqueza tem um custo: logs são muito mais caros de armazenar e indexar do que métricas, principalmente se cada linha de log for indexada integralmente (busca full-text). É por isso que ferramentas modernas de log, como o Loki (artigo 4 desta série), tomam uma decisão deliberada de indexar só um conjunto pequeno de labels e tratar o conteúdo da linha como texto não indexado — um equilíbrio diferente do Elasticsearch tradicional, que indexa tudo.

4. Traces: o caminho de uma requisição entre serviços

Um trace captura o caminho completo de uma requisição individual à medida que ela atravessa múltiplos serviços — quanto tempo foi gasto em cada etapa, em qual ordem, e onde exatamente uma falha ou lentidão aconteceu. Um trace é composto de spans: cada span representa uma unidade de trabalho (uma chamada HTTP, uma query de banco, uma chamada RPC), com início, fim e metadados.

Enquanto métricas respondem "algo mudou?" e logs respondem "o que aconteceu nesse evento específico?", traces respondem "onde exatamente, entre dez serviços, o tempo está sendo gasto para essa requisição em particular?" — uma pergunta que se torna essencial (e quase impossível de responder sem traces) assim que um sistema deixa de ser um monólito. O artigo 5 desta série cobre OpenTelemetry, o padrão atual para gerar traces.

Requisição do usuário
  │
  ├─ Span: API Gateway (2ms)
  │    │
  │    └─ Span: Serviço de Pedidos (45ms)
  │         │
  │         ├─ Span: Query no banco (38ms)  ← gargalo aqui
  │         └─ Span: Chamada ao Serviço de Estoque (5ms)

5. A stack desta série: Prometheus + Loki + Grafana

Esta série vai construir uma stack de observabilidade mínima, mas funcional, usando três ferramentas open source que se tornaram um padrão de fato:

Prometheus — coleta e armazena métricas, usando um modelo de "scraping" (ele busca ativamente as métricas de cada aplicação, em vez de esperar que a aplicação as envie). Vem com o PromQL, uma linguagem de consulta específica para séries temporais.
Loki — agregação de logs, criado pela mesma empresa por trás do Grafana, com uma filosofia deliberada de "indexar como o Prometheus": poucos labels indexados, conteúdo da linha buscado por varredura em tempo de consulta. Isso o torna significativamente mais barato de operar que stacks tradicionais baseadas em Elasticsearch.
Grafana — a camada de visualização, capaz de consultar tanto Prometheus (PromQL) quanto Loki (LogQL) — e, mais adiante nesta série, também dados de tracing — em dashboards unificados.

Nenhuma das três aparece isolada por acaso: métricas dizem "o quê", logs dizem "por quê" e traces dizem "onde" — e a stack só cumpre seu papel de observabilidade quando as três se completam.

6. Subindo a versão básica com Docker Compose

Para experimentar a stack sem instalar nada localmente além do Docker, um docker-compose.yml mínimo já sobe as três ferramentas:

# docker-compose.yml
services:
  prometheus:
    image: prom/prometheus:v2.55.0
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro

  loki:
    image: grafana/loki:3.2.0
    ports:
      - "3100:3100"

  grafana:
    image: grafana/grafana:11.3.0
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    depends_on:
      - prometheus
      - loki

O Prometheus precisa de um arquivo de configuração mínimo para não falhar ao subir — por enquanto, só para ele monitorar a si mesmo:

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]

Subindo tudo:

docker compose up -d

Prometheus fica acessível em http://localhost:9090 — vale abrir e rodar uma query como up no campo de expressão, que deve retornar 1 para o próprio Prometheus.
Loki fica acessível em http://localhost:3100 (sem interface visual própria — ele é consultado através do Grafana ou de sua API HTTP).
Grafana fica acessível em http://localhost:3000 (login admin / admin, conforme a variável de ambiente definida acima).

Dentro do Grafana, em Connections → Data sources, adicionar o Prometheus (http://prometheus:9090, usando o nome do serviço do Compose como hostname, já que os containers estão na mesma rede) e o Loki (http://loki:3100) como fontes de dados. A partir daqui, a stack está de pé — mas ainda vazia, sem nenhuma aplicação real enviando dados.

7. Conclusão e próximos passos

Vimos o problema que a observabilidade resolve — responder perguntas não antecipadas sobre um sistema em produção —, os papéis complementares de métricas, logs e traces, e subimos a versão mínima da stack desta série: Prometheus, Loki e Grafana rodando via Docker Compose. No próximo artigo, a stack ganha sua primeira fonte de dados real: uma mini aplicação em Python puro que expõe métricas em /metrics, e o Prometheus configurado para fazer scraping delas.

Imagem de capa: Logo oficial do Prometheus — repositório prometheus/prometheus, licença Apache 2.0 (convertido para PNG via wsrv.nl)

Referências:

GitOps avançado - automação de deploy, rollback e boas práticas para produção

Rafael Dutra — Mon, 21 Sep 2026 03:16:05 +0000

1. Retomando: da sincronização manual à confiança em produção

Esta série cobriu, até aqui, o suficiente para operar Kubernetes com GitOps no dia a dia: conceitos fundamentais de Pods, Deployments e Services, kubectl, namespaces, ConfigMaps e Secrets, e uma introdução ao ArgoCD com uma Application sincronizando um repositório ao cluster. Este último artigo fecha a lacuna entre "o ArgoCD está instalado" e "confio nesse pipeline para colocar mudanças em produção sem supervisão constante": automação completa de deploy, rollback automático, sync policies mais refinadas e as boas práticas que separam um setup de demonstração de um setup pronto para produção.

2. Automatizando o deploy de ponta a ponta

Um pipeline GitOps completo normalmente combina CI (que constrói e testa a aplicação) com CD via ArgoCD (que aplica o resultado ao cluster). O CI não aplica nada diretamente ao cluster — sua única responsabilidade é atualizar o repositório de manifests com a nova versão, deixando o ArgoCD detectar e aplicar a mudança:

# .github/workflows/deploy.yml
name: build-and-release
on:
  push:
    branches: [main]

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

      - name: Build e push da imagem
        run: |
          docker build -t registry.exemplo.com/minha-app:${{ github.sha }} .
          docker push registry.exemplo.com/minha-app:${{ github.sha }}

      - name: Atualizar tag da imagem no repositório de manifests
        run: |
          git clone https://github.com/minha-org/minha-app-manifests.git
          cd minha-app-manifests
          kustomize edit set image minha-app=registry.exemplo.com/minha-app:${{ github.sha }}
          git commit -am "deploy: minha-app@${{ github.sha }}"
          git push

Esse último passo — um commit automatizado no repositório de manifests, trocando a tag da imagem — é o gatilho que faz o ArgoCD (com syncPolicy.automated configurado, como visto no artigo anterior) detectar a diferença e aplicar o rollout automaticamente, sem que o pipeline de CI precise de nenhuma credencial de acesso ao cluster. Essa separação — CI só escreve no Git, só o ArgoCD escreve no cluster — é o núcleo do que torna GitOps mais seguro que um pipeline de CI tradicional com kubectl apply direto.

3. Rollback automático

Um dos ganhos mais concretos de GitOps aparece quando um deploy dá errado. Como cada mudança é um commit, reverter um deploy problemático é, em princípio, tão simples quanto reverter o commit:

# Reverter o último commit que trocou a tag da imagem
git revert HEAD
git push

O ArgoCD detecta essa reversão como qualquer outra mudança no repositório e aplica automaticamente, voltando o cluster para o estado anterior. Isso pode (e deve) ser combinado com verificações automáticas de saúde, para que o rollback aconteça sem esperar alguém perceber manualmente que algo quebrou:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: minha-app
  namespace: argocd
spec:
  # ...
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    retry:
      limit: 3
      backoff:
        duration: 30s
        factor: 2
        maxDuration: 5m

O bloco retry faz o ArgoCD tentar novamente uma sincronização que falhou, com backoff exponencial — útil para falhas transitórias (um readiness probe que demora um pouco mais que o normal, por exemplo) sem exigir intervenção manual. Para rollback automático baseado na saúde real da aplicação (não só no sucesso da sincronização), ferramentas complementares como o Argo Rollouts adicionam estratégias de deploy progressivo — canary ou blue-green — que promovem ou revertem uma nova versão automaticamente com base em métricas (taxa de erro, latência) coletadas durante o rollout.

4. Sync policies mais refinadas

Nem toda mudança deveria ser sincronizada automaticamente e sem revisão. O ArgoCD permite refinar isso por Application:

spec:
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ApplyOutOfSyncOnly=true
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas

CreateNamespace=true cria o namespace de destino automaticamente, se ainda não existir — evita um passo manual de setup antes do primeiro deploy de uma aplicação nova.
ApplyOutOfSyncOnly=true aplica só os recursos que de fato divergem do Git, reduzindo o "ruído" de reaplicar tudo a cada sincronização.
ignoreDifferences diz ao ArgoCD para ignorar divergências em um campo específico — no exemplo, spec/replicas de Deployments, útil quando um Horizontal Pod Autoscaler (HPA) ajusta o número de réplicas dinamicamente e não se quer que o ArgoCD reverta esse ajuste para o valor fixo declarado no Git.

Em ambientes com múltiplos times, é comum também restringir permissões via AppProject do ArgoCD — limitando quais repositórios, clusters e namespaces cada Application pode usar como fonte ou destino, em vez de dar acesso irrestrito a todo o cluster para qualquer Application criada.

5. Boas práticas para produção

Algumas práticas que separam um cluster GitOps de demonstração de um pronto para produção:

Nunca commitar Secrets em texto plano — retomando o ponto levantado no Artigo 2 desta série: use Sealed Secrets, SOPS ou integração com um cofre externo (Vault, AWS Secrets Manager) para versionar segredos com segurança dentro do fluxo GitOps.
Separar repositórios de aplicação e de manifests — o repositório com o código-fonte da aplicação e o repositório com os manifests Kubernetes costumam ser diferentes, cada um com seu próprio controle de acesso; isso também evita que um push no código dispare acidentalmente uma sincronização do ArgoCD antes de a imagem estar pronta.
Revisão obrigatória para produção — mesmo com sincronização automática ligada, proteger a branch/pasta que aponta para produção com exigência de pull request revisado, para que nenhuma mudança chegue ao cluster sem pelo menos um segundo par de olhos.
Monitorar o próprio ArgoCD — um controlador GitOps fora do ar (ou com a sincronização travada) significa que mudanças urgentes, incluindo rollbacks, não chegam ao cluster; alertas sobre a saúde do ArgoCD são tão importantes quanto alertas sobre a aplicação em si.
Começar com sync manual, migrar para automático aos poucos — para aplicações críticas, é razoável começar sem syncPolicy.automated, validar o processo com sincronizações manuais revisadas, e só ligar a automação depois que o time confia no pipeline de CI e nos testes que o precedem.

6. Conclusão da série

Ao longo desses quatro artigos, esta série foi do "o que é um Pod" a um pipeline GitOps completo: os conceitos fundamentais do Kubernetes (Pods, Deployments, Services), o kubectl e a organização de recursos com namespaces, ConfigMaps e Secrets, a introdução ao GitOps e ao ArgoCD, e finalmente automação de deploy de ponta a ponta, rollback automático via Git e as boas práticas que tornam esse fluxo seguro o suficiente para produção. A partir daqui, a base está posta para explorar tópicos mais específicos — deploys progressivos com Argo Rollouts, gestão de segredos com Sealed Secrets ou Vault, observabilidade de clusters — mas o par Kubernetes + GitOps, bem implementado, já resolve a maior parte do desafio de operar aplicações em produção com confiança e rastreabilidade.

Imagem de capa: Logo oficial do Kubernetes — repositório kubernetes/kubernetes

Referências:

GitOps na prática - ArgoCD e estrutura de repositório

Rafael Dutra — Mon, 21 Sep 2026 03:16:04 +0000

1. Retomando: do `kubectl apply` manual a um fluxo automatizado

Nas duas primeiras partes desta série, todo Deployment foi aplicado com kubectl apply -f arquivo.yaml, rodado à mão a partir da máquina de quem estava operando o cluster. Isso funciona para aprender e para clusters pequenos, mas expõe problemas reais em produção: não há registro confiável de quem aplicou o quê e quando, é fácil um manifesto aplicado manualmente divergir silenciosamente do que está versionado no Git, e cada pessoa do time precisa de acesso direto (e credenciais) ao cluster para fazer deploy. Este artigo introduz GitOps, a prática que resolve exatamente isso, e o ArgoCD, uma das ferramentas mais usadas para implementá-la.

2. O que é GitOps

GitOps é a aplicação da ideia de infraestrutura como código a um extremo específico: o Git como única fonte de verdade do estado desejado de um cluster Kubernetes, com um agente rodando dentro do próprio cluster que observa o repositório continuamente e aplica qualquer mudança automaticamente — sem que ninguém precise rodar kubectl apply manualmente.

O fluxo típico é:

Alguém abre um pull request alterando um manifesto YAML (por exemplo, mudando replicas: 2 para replicas: 4, ou atualizando a tag de uma imagem).
O PR passa por revisão e CI, como qualquer outra mudança de código.
Ao ser mesclado (merge) na branch principal, um agente GitOps rodando no cluster detecta a diferença entre o que está no Git e o que está rodando, e aplica a mudança automaticamente.
O cluster converge para o estado descrito no repositório — sem que ninguém tenha rodado um comando manual contra o cluster.

Pull Request → Review/CI → Merge no Git
                                  │
                     (agente GitOps observa o repo)
                                  │
                                  ▼
                    Cluster Kubernetes converge
                    automaticamente para o estado
                          descrito no Git

3. Por que isso faz sentido em infraestrutura como código

Comparado a aplicar manifestos manualmente (mesmo que a partir de um pipeline de CI que roda kubectl apply), GitOps traz três ganhos concretos:

Auditoria natural: o histórico do Git — quem propôs a mudança, quem revisou, quando foi mesclada — já é o registro de auditoria de tudo que aconteceu no cluster, sem precisar de uma ferramenta separada de log de mudanças.
Reconciliação contínua: o agente GitOps não só aplica mudanças, mas continua comparando o estado real do cluster com o Git em intervalos regulares. Se alguém alterar algo manualmente no cluster (um kubectl edit de emergência, por exemplo), o agente detecta a divergência e pode reverter automaticamente para o que está declarado no Git — ou pelo menos alertar que há um "drift".
Menos acesso direto ao cluster: times não precisam mais de credenciais de kubectl com permissão de escrita no cluster de produção para fazer deploy — a mudança passa pelo Git, e só o agente GitOps (com suas próprias credenciais, geridas separadamente) tem acesso de escrita direto.

Isso é uma extensão natural do que a série já vinha construindo: Deployments e Services declarativos (Artigo 1), organizados com namespaces e configuração externa via ConfigMaps/Secrets (Artigo 2) — GitOps apenas formaliza que a fonte de verdade desses YAMLs é um repositório Git, e que a aplicação ao cluster é automática, não manual.

4. Introdução ao ArgoCD

O ArgoCD é um dos controladores GitOps mais usados para Kubernetes. Ele roda como uma aplicação dentro do próprio cluster e introduz um novo tipo de recurso, a Application, que aponta para um caminho em um repositório Git e para um cluster/namespace de destino.

Instalação básica em um cluster (local, como o criado com Minikube/Kind no Artigo 1, ou um cluster real):

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Depois de instalado, uma Application do ArgoCD conecta um repositório a um destino no cluster:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: minha-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/minha-org/minha-app-manifests.git
    targetRevision: main
    path: k8s/producao
  destination:
    server: https://kubernetes.default.svc
    namespace: minha-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

source diz onde está o estado desejado: repositório, branch/tag e caminho dentro do repo.
destination diz onde aplicar: qual cluster (https://kubernetes.default.svc é o próprio cluster onde o ArgoCD roda) e namespace.
syncPolicy.automated liga a sincronização automática: selfHeal: true faz o ArgoCD reverter mudanças manuais feitas fora do Git (o "drift" mencionado acima); prune: true remove do cluster recursos que foram removidos do repositório.

Sem syncPolicy.automated, o ArgoCD ainda detecta divergências e mostra o diff entre Git e cluster, mas espera uma sincronização manual (via UI ou argocd app sync) — uma opção mais conservadora para começar, antes de confiar totalmente no modo automático.

5. Alternativa: Flux

O Flux é a alternativa mais usada ao ArgoCD, com a mesma proposta — observar um repositório Git e reconciliar o cluster com o que está nele — mas com uma filosofia mais "nativa" ao modelo de controladores do Kubernetes (sem uma UI própria tão robusta quanto a do ArgoCD, focado em CRDs e composição via kustomize). Este artigo usa o ArgoCD como exemplo principal por ter a curva de entrada mais suave (UI web incluída), mas os conceitos de GitOps — Git como fonte de verdade, reconciliação automática, sync policies — se aplicam igualmente às duas ferramentas, e a escolha entre elas costuma depender mais de preferência de equipe do que de uma diferença técnica decisiva.

6. Estruturando um repositório de manifests

Uma dúvida comum ao adotar GitOps é como organizar o repositório de manifests. Uma estrutura comum, que separa aplicações e ambientes:

minha-app-manifests/
├── base/
│   ├── deployment.yaml
│   ├── service.yaml
│   └── kustomization.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   └── patch-replicas.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── producao/
        ├── kustomization.yaml
        └── patch-replicas.yaml

Essa estrutura usa kustomize (embutido no kubectl e nativamente suportado por ArgoCD e Flux): a pasta base/ tem os manifestos comuns, e cada overlay aplica só as diferenças daquele ambiente (número de réplicas, limites de recursos, variáveis específicas) por cima da base, evitando duplicar o YAML inteiro para cada ambiente. Uma Application do ArgoCD apontando para overlays/producao (como no exemplo da seção anterior) sempre aplica a base mais os ajustes específicos de produção.

Para projetos que usam Helm em vez de manifestos YAML puros, o mesmo princípio se aplica: o repositório versiona o values.yaml de cada ambiente, e a Application do ArgoCD aponta para o chart e para o arquivo de valores correspondente ao ambiente de destino.

7. Conclusão e próximos passos

Neste artigo, vimos o que é GitOps e por que ele resolve problemas reais de auditoria, drift de configuração e acesso direto ao cluster que o kubectl apply manual não resolve, uma introdução prática ao ArgoCD com uma Application real, uma menção ao Flux como alternativa, e uma forma comum de estruturar um repositório de manifests com kustomize para múltiplos ambientes. No próximo e último artigo desta série, os exemplos ficam mais avançados: automação completa de deploy com GitOps, rollback automático, sync policies mais refinadas e boas práticas para rodar isso tudo com confiança em produção.

Imagem de capa: Logo oficial do Kubernetes — repositório kubernetes/kubernetes

Referências:

Kubernetes no dia a dia - kubectl, Namespaces, ConfigMaps e Secrets

Rafael Dutra — Mon, 21 Sep 2026 03:16:03 +0000

1. Retomando: de conceitos a comandos

Na primeira parte desta série vimos o que é o Kubernetes, o problema que ele resolve e os três conceitos fundamentais — Pods, Deployments e Services — aplicando-os em um Deployment mínimo de Nginx. Agora que a base teórica está posta, o foco deste artigo é prático: o kubectl no dia a dia, como organizar recursos com namespaces, como gerenciar configuração e segredos com ConfigMaps e Secrets, e um primeiro deploy de uma aplicação real (não só um Nginx de exemplo).

2. `kubectl` além do `apply` e do `get`

O artigo anterior já usou kubectl apply e kubectl get. No dia a dia, alguns outros comandos aparecem o tempo todo:

# Descrever um recurso em detalhes (eventos, status, configuração completa)
kubectl describe pod nginx-7d9f8c6b4-x2z9k

# Ver os logs de um container dentro de um Pod
kubectl logs nginx-7d9f8c6b4-x2z9k
kubectl logs -f nginx-7d9f8c6b4-x2z9k    # segue o log em tempo real

# Abrir um shell dentro de um container em execução
kubectl exec -it nginx-7d9f8c6b4-x2z9k -- bash

# Remover um recurso
kubectl delete -f nginx-deployment.yaml

# Encaminhar uma porta local para um Pod, sem precisar expor um Service externo
kubectl port-forward pod/nginx-7d9f8c6b4-x2z9k 8080:80

kubectl describe costuma ser o primeiro comando rodado ao investigar um Pod que não sobe como esperado — a seção Events no final da saída normalmente aponta a causa (imagem não encontrada, falta de recursos no cluster, falha no readiness probe, etc.) antes mesmo de olhar os logs da aplicação.

3. Organizando recursos com Namespaces

Um namespace é uma forma de dividir um cluster em espaços lógicos isolados — times, ambientes (dev, staging, prod) ou aplicações diferentes podem viver em namespaces separados, com nomes de recursos que não colidem entre si e (com as políticas certas) sem visibilidade de rede umas nas outras.

# Criar um namespace
kubectl create namespace minha-app

# Listar todos os namespaces do cluster
kubectl get namespaces

# Aplicar um manifesto em um namespace específico
kubectl apply -f deployment.yaml -n minha-app

# Listar recursos de um namespace específico
kubectl get pods -n minha-app

# Listar recursos de TODOS os namespaces
kubectl get pods -A

Sem indicar -n, todo comando kubectl opera no namespace default — o que funciona para experimentos, mas rapidamente vira confusão em um cluster real com várias aplicações. A prática recomendada é sempre criar um namespace por aplicação ou por time, e declará-lo explicitamente nos manifestos:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: minha-app
spec:
  # ...

4. ConfigMaps: configuração fora da imagem

Uma boa prática de containers (reforçada também na série de Docker deste blog) é nunca hardcodar configuração dentro da imagem — ela deve poder rodar em qualquer ambiente, recebendo a configuração de fora. O ConfigMap é o objeto do Kubernetes para isso: um conjunto de pares chave-valor não sensíveis, injetados em Pods como variáveis de ambiente ou arquivos.

apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
  namespace: minha-app
data:
  LOG_LEVEL: "info"
  FEATURE_FLAG_NOVO_CHECKOUT: "true"

Consumindo o ConfigMap em um Deployment, como variáveis de ambiente:

spec:
  containers:
    - name: api
      image: minha-app/api:1.0
      envFrom:
        - configMapRef:
            name: api-config

5. Secrets: configuração sensível

Secrets têm a mesma forma de uso que ConfigMaps, mas são destinados a dados sensíveis — senhas, tokens, chaves de API. A diferença mais importante não é técnica (por padrão, o conteúdo de um Secret só é codificado em base64, não criptografado) e sim de intenção: o Kubernetes trata Secrets de forma diferente em alguns pontos (não fica visível por padrão em kubectl describe, por exemplo), e é o objeto certo para integrar com soluções de criptografia em repouso ou cofres externos (Vault, AWS Secrets Manager) em clusters de produção.

# Criar um Secret diretamente pela CLI, sem escrever a senha em um YAML versionado
kubectl create secret generic api-db-credentials \
  --from-literal=DB_USER=app \
  --from-literal=DB_PASSWORD='troque-por-um-valor-real' \
  -n minha-app

Consumindo o Secret, também como variáveis de ambiente:

spec:
  containers:
    - name: api
      image: minha-app/api:1.0
      envFrom:
        - configMapRef:
            name: api-config
        - secretRef:
            name: api-db-credentials

Um ponto importante — e que volta com força no Artigo 3 desta série, sobre GitOps: nunca commitar um Secret com valores reais em texto plano em um repositório Git, nem mesmo privado. Ferramentas como Sealed Secrets ou integrações com cofres externos existem exatamente para permitir versionar segredos com segurança dentro de um fluxo GitOps.

6. Um deploy real: API com configuração e banco

Juntando os conceitos, um exemplo mais próximo de uma aplicação real: uma API que lê configuração de um ConfigMap, credenciais de um Secret, e é exposta dentro do cluster por um Service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: minha-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: minha-app/api:1.0
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef:
                name: api-config
            - secretRef:
                name: api-db-credentials
---
apiVersion: v1
kind: Service
metadata:
  name: api
  namespace: minha-app
spec:
  selector:
    app: api
  ports:
    - port: 80
      targetPort: 8080

kubectl apply -f api-deployment.yaml
kubectl rollout status deployment/api -n minha-app

kubectl rollout status acompanha o deploy até todas as réplicas ficarem prontas (ou aponta o erro, se alguma falhar) — útil tanto em terminal manual quanto como passo de verificação em um pipeline de CI/CD.

7. Conclusão e próximos passos

Com kubectl describe/logs/exec para investigar, namespaces para organizar, e ConfigMaps/Secrets para separar configuração do código da aplicação, já é possível fazer deploys reais de forma organizada em um cluster Kubernetes. Até aqui, porém, todo kubectl apply foi rodado à mão, a partir da máquina de quem está operando o cluster — o que não escala bem para times e não deixa rastro confiável do que foi aplicado e quando. No próximo artigo, a série entra em GitOps: o que é, por que faz sentido tratar infraestrutura como código versionado, e uma introdução ao ArgoCD para aplicar automaticamente o que está em um repositório Git ao cluster.

Imagem de capa: Logo oficial do Kubernetes — repositório kubernetes/kubernetes

Referências:

Kubernetes - o que é, para que serve e conceitos iniciais

Rafael Dutra — Mon, 21 Sep 2026 03:16:02 +0000

1. O problema que o Kubernetes resolve

Rodar um container isolado, à mão, com docker run, resolve bem o problema de empacotar e distribuir uma aplicação. Mas assim que essa aplicação precisa rodar em produção — com múltiplas réplicas, tolerância a falhas, atualizações sem downtime e escalando conforme a demanda — o "container solto" vira um problema de gestão manual: quem reinicia um container que caiu? Quem distribui a carga entre várias instâncias? Quem decide em qual máquina cada container roda quando há dezenas de servidores disponíveis? Scripts caseiros de docker run e cron para verificar se o processo ainda está vivo resolvem por um tempo, mas não escalam além de poucos serviços.

O Kubernetes (às vezes abreviado como k8s) é um orquestrador de containers: um sistema que recebe uma descrição de "o que" deve estar rodando (quantas réplicas, quanto de CPU/memória, quais portas expor) e se encarrega do "como" — decide em qual máquina cada container roda, reinicia o que falhar, distribui tráfego entre réplicas saudáveis e reagenda containers automaticamente se um servidor inteiro cair. Esta é a primeira parte de uma série que vai do zero ao avançado em Kubernetes e GitOps: hoje o foco é entender o problema que o Kubernetes resolve e os conceitos iniciais que sustentam tudo o que vem depois.

2. Containers soltos e VMs vs orquestração

Comparado a rodar containers "soltos" (um docker run por servidor, gerenciado manualmente ou por scripts), o Kubernetes automatiza justamente o que se torna inviável de fazer à mão em escala:

Auto-recuperação (self-healing): se um container trava ou o processo morre, o Kubernetes detecta e sobe um novo automaticamente — sem intervenção humana e, idealmente, sem impacto perceptível para quem usa a aplicação.
Escalonamento: aumentar de 2 para 10 réplicas de uma aplicação é uma mudança de configuração (ou automática, via métricas de uso), não um processo manual de logar em servidores e rodar comandos um por um.
Distribuição de carga: o Kubernetes decide em qual máquina (node) cada container roda, considerando recursos disponíveis, e distribui tráfego entre as réplicas saudáveis de um serviço automaticamente.
Atualizações sem downtime: trocar a versão de uma aplicação pode ser feito substituindo réplicas gradualmente (rolling update), mantendo o serviço no ar durante todo o processo.

Comparado a máquinas virtuais geridas manualmente (uma aplicação por VM, escalada criando mais VMs), o ganho é semelhante ao que containers já trazem sobre VMs isoladamente: densidade muito maior (várias aplicações compartilhando os mesmos servidores físicos com isolamento adequado) e inicialização em segundos em vez de minutos — mas agora com um sistema que decide automaticamente onde cada carga roda, em vez de alguém escolher manualmente em qual VM cada aplicação vai.

Isso não significa que toda aplicação precisa de Kubernetes — um sistema pequeno, com um ou dois serviços e baixa necessidade de escala, pode viver tranquilamente com docker run bem configurado ou Docker Compose (veja a série sobre Docker deste blog). O Kubernetes compensa o esforço quando a quantidade de serviços, a necessidade de alta disponibilidade ou a variação de carga tornam a gestão manual inviável.

3. Conceitos fundamentais: Pods, Deployments e Services

O Kubernetes organiza tudo em torno de objetos descritos declarativamente (normalmente em YAML), que dizem ao cluster o estado desejado. Três deles aparecem em praticamente toda aplicação:

Pod: a menor unidade que o Kubernetes gerencia diretamente. Um Pod contém um ou mais containers que compartilham rede e armazenamento — na prática, a grande maioria dos Pods tem exatamente um container, com containers adicionais reservados para casos específicos (como um "sidecar" que coleta logs). Pods são efêmeros: quando um Pod morre, ele não é "recriado" no sentido de reviver o mesmo Pod — um novo Pod é criado do zero em seu lugar.
Deployment: descreve quantas réplicas de um Pod devem existir e como atualizá-las. É o Deployment que garante que, se um Pod morrer, outro toma seu lugar automaticamente, e que gerencia rolling updates ao trocar a versão de uma imagem.
Service: como Pods são efêmeros e ganham um IP novo cada vez que são recriados, não é possível apontar diretamente para o IP de um Pod de forma confiável. Um Service resolve isso expondo um endereço estável (nome DNS interno e IP fixo dentro do cluster) que distribui tráfego entre todos os Pods saudáveis que casam com um determinado rótulo (label) — independentemente de quantos Pods existem ou de terem sido recriados.

Deployment "api"
  ├── garante 3 réplicas do Pod
  ├── Pod (réplica 1) ── container: api:1.2
  ├── Pod (réplica 2) ── container: api:1.2
  └── Pod (réplica 3) ── container: api:1.2

Service "api" (IP estável, DNS interno "api")
  └── distribui tráfego entre as 3 réplicas do Pod acima

Essa relação — Deployment garantindo réplicas de Pods, Service expondo um endereço estável para eles — é o alicerce sobre o qual praticamente todo o resto do Kubernetes (ConfigMaps, Secrets, Ingress, volumes, e os conceitos de GitOps discutidos mais adiante nesta série) se apoia.

4. Experimentando localmente com Minikube ou Kind

Não é preciso um cluster de produção para começar a aprender Kubernetes. Duas ferramentas populares criam um cluster completo rodando localmente, dentro do Docker ou de uma VM leve:

# Minikube — cria um cluster local em uma VM/container
minikube start

# Kind (Kubernetes in Docker) — cria o cluster inteiro dentro de containers Docker
kind create cluster

Ambas resultam em um cluster funcional acessível pelo kubectl (a CLI oficial do Kubernetes, assunto completo do próximo artigo desta série). Para confirmar que o cluster está de pé:

kubectl cluster-info
kubectl get nodes

O segundo comando lista os nodes (máquinas, reais ou virtuais, que compõem o cluster) — em um cluster local, normalmente apenas um node fazendo o papel de servidor e worker ao mesmo tempo.

5. Um primeiro deploy na prática

Com o cluster local de pé, um Deployment mínimo já ilustra os três conceitos vistos acima. Em um arquivo nginx-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80
  type: ClusterIP

Aplicando ao cluster:

kubectl apply -f nginx-deployment.yaml
kubectl get pods
kubectl get deployments
kubectl get services

O primeiro comando (kubectl apply) é a forma declarativa de trabalhar com Kubernetes: em vez de dizer passo a passo o que fazer, descreve-se o estado desejado (três réplicas do Nginx, expostas por um Service) e o Kubernetes se encarrega de fazer a realidade convergir para essa descrição — criando os três Pods, e mantendo-os assim mesmo que algum caia. Esse modelo declarativo, aplicado a partir de arquivos versionados em um repositório Git, é exatamente a ideia que a série vai aprofundar no Artigo 3, ao introduzir GitOps.

6. Conclusão e próximos passos

Nesta primeira parte, vimos o problema real que o Kubernetes resolve — orquestrar containers em escala, algo inviável de gerenciar manualmente —, como ele se compara a containers soltos e VMs geridas manualmente, os três conceitos que sustentam qualquer aplicação no cluster (Pods, Deployments e Services) e subimos um primeiro Deployment de ponta a ponta em um cluster local. No próximo artigo, o foco vai para o kubectl no dia a dia: comandos essenciais, organização de recursos com namespaces, ConfigMaps e Secrets, e os primeiros deploys de aplicações reais.

Imagem de capa: Logo oficial do Kubernetes — repositório kubernetes/kubernetes

Referências:

IaC além do Terraform - testando infraestrutura como código

Rafael Dutra — Sat, 05 Sep 2026 09:30:58 +0000

1. Código de infraestrutura também quebra

Nos dois artigos anteriores desta série, vimos o OpenTofu como alternativa para provisionar infraestrutura e o Ansible para configurá-la depois de criada. Mas há uma pergunta que fica no ar em qualquer um desses fluxos: como saber, antes de rodar apply em produção, que um módulo Terraform não vai abrir uma porta que não deveria, destruir um recurso por engano, ou simplesmente ter um erro de sintaxe? Testar infraestrutura como código é tão importante quanto testar qualquer outro software — só que, diferente de uma função pura, os "efeitos colaterais" de um teste malfeito aqui podem ser uma conta de nuvem inesperada ou um serviço em produção fora do ar.

Este artigo fecha a série cobrindo três camadas complementares de teste: análise estática com tflint, verificação de segurança e compliance com checkov, e testes de integração de verdade com Terratest.

2. As camadas de teste em IaC

Vale pensar nessas ferramentas como camadas que rodam em momentos diferentes do ciclo de vida do código, da mais rápida/barata para a mais lenta/cara:

Lint e análise estática (tflint): roda em segundos, sem precisar de credenciais de nuvem nem de rodar terraform plan. Pega erros de sintaxe, más práticas e problemas específicos de cada provider.
Análise de segurança e compliance (checkov): também estática, mas focada em identificar configurações inseguras (bucket público, criptografia desabilitada, security group aberto para 0.0.0.0/0) comparando o código contra um catálogo de políticas.
Testes de integração (Terratest): a camada mais próxima da realidade — de fato roda terraform apply num ambiente isolado, valida o resultado, e depois roda terraform destroy. Mais lento e mais caro (usa recursos reais de nuvem), mas é o único jeito de garantir que o módulo realmente funciona de ponta a ponta.

Um pipeline de CI/CD maduro roda as três, nessa ordem, falhando rápido nas camadas mais baratas antes de chegar nas mais caras.

3. tflint na prática

O tflint foca em problemas que o terraform validate não pega, porque validate só garante que a sintaxe HCL e os tipos estão corretos — não que o uso de um recurso específico faz sentido para aquele provider.

# Instalação (Linux/macOS via script oficial)
curl -s https://raw.githubusercontent.com/terraform-linters/tflint/master/install_linux.sh | bash

# Rodar no diretório do módulo
tflint --init   # baixa o plugin do provider (ex.: AWS)
tflint

Exemplo de configuração habilitando o plugin da AWS, que traz regras específicas (tipos de instância inválidos, uso de AMIs deprecated, etc.):

# .tflint.hcl
plugin "aws" {
  enabled = true
  version = "0.31.0"
  source  = "github.com/terraform-linters/tflint-ruleset-aws"
}

rule "terraform_deprecated_interpolation" {
  enabled = true
}

rule "terraform_unused_declarations" {
  enabled = true
}

Com isso, tflint sinaliza coisas como variáveis declaradas e nunca usadas, ou um instance_type que não existe na AWS — erros que só apareceriam em produção, na hora do apply, sem essa checagem prévia.

4. checkov na prática

O checkov (da Bridgecrew/Prisma Cloud) analisa o código Terraform contra centenas de políticas de segurança e compliance prontas (CIS Benchmarks, PCI-DSS, HIPAA, entre outras), sem precisar aplicar nada:

pip install checkov

checkov -d ./terraform

Exemplo de um recurso com problema de segurança óbvio:

resource "aws_s3_bucket" "data" {
  bucket = "minha-empresa-dados"
}

resource "aws_s3_bucket_public_access_block" "data" {
  bucket                  = aws_s3_bucket.data.id
  block_public_acls       = false
  block_public_policy     = false
  ignore_public_acls      = false
  restrict_public_buckets = false
}

Rodar checkov contra esse arquivo reporta uma falha correspondente à política CKV_AWS_53 ("Ensure S3 bucket has block public ACLs enabled"), com o número da linha e uma explicação do risco. É possível suprimir uma regra pontualmente quando a exceção é intencional e documentada:

resource "aws_s3_bucket_public_access_block" "data" {
  # checkov:skip=CKV_AWS_53:bucket de assets públicos do site, intencional
  bucket                  = aws_s3_bucket.data.id
  block_public_acls       = false
  block_public_policy     = false
  ignore_public_acls      = false
  restrict_public_buckets = false
}

Isso documenta a exceção diretamente no código, em vez de silenciar o alerta de forma invisível em algum lugar do pipeline.

5. Terratest na prática

O Terratest é uma biblioteca Go (mantida pela Gruntwork) para escrever testes de integração reais contra código Terraform. O padrão típico de um teste é: apply → validar → destroy, sempre em um ambiente descartável.

// test/webserver_test.go
package test

import (
    "testing"
    "time"

    "github.com/gruntwork-io/terratest/modules/http-helper"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

func TestWebServerModule(t *testing.T) {
    terraformOptions := &terraform.Options{
        TerraformDir: "../examples/webserver",
        Vars: map[string]interface{}{
            "environment": "test",
        },
    }

    // Garante que 'terraform destroy' roda no final,
    // mesmo se o teste falhar no meio do caminho.
    defer terraform.Destroy(t, terraformOptions)

    terraform.InitAndApply(t, terraformOptions)

    publicIP := terraform.Output(t, terraformOptions, "public_ip")
    url := "http://" + publicIP

    http_helper.HttpGetWithRetry(
        t,
        url,
        nil,
        200,
        "Welcome",
        30,          // tentativas
        5*time.Second, // intervalo entre tentativas
    )

    assert.NotEmpty(t, publicIP, "o output public_ip não deveria estar vazio")
}

Rodando:

cd test
go test -v -timeout 30m

O defer terraform.Destroy(...) logo após criar as opções é o detalhe mais importante desse padrão: garante que o destroy roda mesmo se uma das validações (HttpGetWithRetry, assert) falhar no meio do teste, evitando deixar recursos reais de nuvem órfãos e gerando custo desnecessário.

6. Juntando tudo num pipeline de CI/CD

# .github/workflows/terraform-test.yml
name: Terraform Test Pipeline

on:
  pull_request:
    paths:
      - "terraform/**"

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

      - name: tflint
        uses: terraform-linters/setup-tflint@v4
      - run: tflint --init && tflint --chdir=terraform

      - name: checkov
        uses: bridgecrewio/checkov-action@master
        with:
          directory: terraform

  integration-tests:
    needs: static-checks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.22"
      - name: Terratest
        working-directory: test
        run: go test -v -timeout 30m

O job integration-tests só roda depois que static-checks passa — falhar rápido nas checagens estáticas (segundos) evita gastar tempo e dinheiro rodando apply/destroy reais (minutos) para um código que já tinha um problema óbvio de lint ou segurança.

7. Evitando drift em produção

Testes automatizados evitam que código com problema chegue à produção, mas não evitam drift — divergência entre o que o state do Terraform diz que existe e o que de fato existe na nuvem (alguém mudou algo manual pelo console, por exemplo). Para isso, a prática recomendada é rodar terraform plan (ou tofu plan) periodicamente contra o ambiente de produção, fora do fluxo de deploy, e alertar se houver diferença:

# Rodado por um cron/job agendado, não por um deploy
terraform plan -detailed-exitcode
# exit code 0 = sem mudanças, 1 = erro, 2 = há diferenças (drift)

O -detailed-exitcode é o que torna isso automatizável: um pipeline pode checar o código de saída e abrir um alerta apenas quando o valor for 2, sem precisar fazer parsing do output textual do plano.

8. Conclusão da série

Fechamos esta série de três artigos indo além do Terraform puro: o OpenTofu como alternativa de provisionamento nascida de uma crise de licenciamento, o Ansible cobrindo a configuração do que já foi provisionado, e agora as três camadas de teste — tflint, checkov e Terratest — que dão confiança de que o código de infraestrutura faz exatamente o que deveria antes de chegar em produção. Nenhuma dessas ferramentas substitui o Terraform; todas ampliam o que é possível fazer em volta dele, e é essa combinação — provisionar, configurar e testar — que sustenta um pipeline de IaC realmente confiável.

Imagem de capa: Logo oficial do Terraform — Wikimedia Commons

Referências:

DEV Community: apsis-cc

Dashboards no Grafana - combinando PromQL e LogQL para acompanhar uma aplicação de ponta a ponta

1. Retomando: dados prontos, falta visualizar

2. Criando o dashboard e o primeiro painel

3. Painel de latência com histogram_quantile

4. Painel de taxa de erro (gauge)

5. Painel de logs com LogQL

6. Painel de volume de logs ao longo do tempo

7. Organizando o dashboard

8. Variável de template para alternar entre apps

9. Conclusão e próximos passos

Stack completa de observabilidade com Docker Compose - Python, PHP, Prometheus, Loki, OpenTelemetry e Grafana

1. Retomando: as peças soltas até aqui

2. Por que um coletor no meio do caminho

3. Trocando o exportador de console por OTLP

4. Configurando o coletor

5. O docker-compose.yml unificado

6. Configurando os datasources no Grafana

7. Confirmando que o pipeline completo funciona

8. Conclusão e próximos passos

OpenTelemetry - o que é, por que virou padrão e como instrumentar traces

1. Retomando: métricas e logs prontos, falta conectar os pontos

2. O que é o OpenTelemetry

3. Por que virou o padrão dominante

4. Conceitos de tracing: trace, span e contexto

5. Instrumentando a mini app Python

6. Instrumentando a mini app PHP

7. Conclusão e próximos passos

Loki na prática - enviando logs via API HTTP a partir das mini apps Python e PHP

1. Retomando: métricas prontas, falta o segundo pilar

2. Por que a indexação do Loki é diferente

3. A API HTTP de push do Loki

4. Enviando logs a partir da mini app Python

5. Enviando logs a partir da mini app PHP

6. Consultando os logs no Grafana com LogQL

7. Conclusão e próximos passos

Métricas customizadas - counters, gauges e histograms com uma mini app PHP

1. Retomando: de uma métrica a um conjunto completo

2. Counter: só sobe (até o processo reiniciar)

3. Gauge: sobe e desce livremente

4. Histogram: distribuição de valores em buckets

5. Mini app em PHP puro com métricas de negócio

6. Adicionando a app PHP à stack

7. Consultando um histogram com histogram_quantile

8. Conclusão e próximos passos

Prometheus na prática - scraping, o endpoint /metrics e uma mini app Python expondo métricas

1. Retomando: da stack vazia à primeira fonte de dados

2. Pull vs push: o modelo de scraping do Prometheus

3. O formato de exposição: o que vive em /metrics

4. Uma mini app em Python puro com http.server

5. Configurando o prometheus.yml para coletar a nova app

6. Consultando os dados no Prometheus

7. Conclusão e próximos passos

Observabilidade - o que é, métricas vs logs vs traces e a stack Prometheus + Loki + Grafana

1. Por que "monitoramento" não é mais suficiente

2. Métricas: números agregados ao longo do tempo

3. Logs: eventos discretos com contexto rico

4. Traces: o caminho de uma requisição entre serviços

5. A stack desta série: Prometheus + Loki + Grafana

6. Subindo a versão básica com Docker Compose

7. Conclusão e próximos passos

GitOps avançado - automação de deploy, rollback e boas práticas para produção

1. Retomando: da sincronização manual à confiança em produção

2. Automatizando o deploy de ponta a ponta

3. Rollback automático

4. Sync policies mais refinadas

5. Boas práticas para produção

6. Conclusão da série

GitOps na prática - ArgoCD e estrutura de repositório

1. Retomando: do kubectl apply manual a um fluxo automatizado

2. O que é GitOps

3. Por que isso faz sentido em infraestrutura como código

4. Introdução ao ArgoCD

5. Alternativa: Flux

6. Estruturando um repositório de manifests

7. Conclusão e próximos passos

Kubernetes no dia a dia - kubectl, Namespaces, ConfigMaps e Secrets

1. Retomando: de conceitos a comandos

2. kubectl além do apply e do get

3. Organizando recursos com Namespaces

1. Retomando: do `kubectl apply` manual a um fluxo automatizado

2. `kubectl` além do `apply` e do `get`