DEV Community: apsis-cc

AWS na prática - balanceamento de carga via DNS com o Route 53

Rafael Dutra — Wed, 14 Oct 2026 09:30:29 +0000

1. Um outro tipo de balanceamento

No artigo anterior desta série, subimos instâncias EC2 e as agrupamos em um target group, prontas para receber tráfego de um balanceador de carga tradicional. Mas existe uma camada de decisão que acontece antes de qualquer pacote chegar a um Application Load Balancer: a resolução de nome. Quando um cliente pergunta "qual é o IP de api.minhaempresa.com?", quem responde pode já estar escolhendo, com base em latência, saúde do destino ou uma política de peso, para qual região ou endpoint mandar esse cliente. É esse balanceamento — feito no Route 53, o serviço de DNS da AWS — que vamos explorar aqui.

2. Por que balancear no DNS, se já existe um load balancer

Um ALB/NLB distribui tráfego entre instâncias dentro de uma região. O Route 53 resolve um problema diferente: distribuir tráfego entre regiões, entre contas ou entre serviços completamente distintos, antes mesmo de uma conexão TCP ser aberta. Os dois não são concorrentes — na prática, é comum que registros no Route 53 apontem justamente para ALBs em regiões diferentes, formando duas camadas de balanceamento:

Cliente → Route 53 (escolhe a região) → ALB da região → Target Group → EC2

A diferença central de mecanismo importa: um ALB decide por requisição, em tempo real, olhando para o estado atual de cada destino. O Route 53 decide por resposta de consulta DNS, e o cliente (ou, mais frequentemente, o resolver DNS dele) fica com essa resposta em cache pelo tempo definido no TTL do registro — o que torna o balanceamento por DNS mais grosseiro, porém indispensável quando o requisito é geográfico ou cruza fronteiras que um load balancer sozinho não alcança.

3. Políticas de roteamento do Route 53

O Route 53 suporta várias políticas de roteamento no mesmo nome, cada uma resolvendo um problema diferente:

Simple: um registro, uma resposta fixa (ou uma lista, escolhida aleatoriamente pelo cliente). Sem balanceamento real.
Weighted: distribui consultas entre múltiplos endpoints por peso relativo — útil para canary release ou para migrar tráfego gradualmente de um ambiente para outro.
Latency-based: responde com o endpoint na região com menor latência medida a partir da localização do resolver que fez a pergunta.
Failover: mantém um endpoint primário e um secundário, alternando automaticamente quando o health check do primário falha.
Geolocation / Geoproximity: roteia com base na localização geográfica de quem pergunta, útil para requisitos de residência de dados ou conteúdo localizado.
Multivalue answer: retorna várias respostas saudáveis por consulta, funcionando como um DNS round-robin com health check embutido.

4. Roteamento ponderado (weighted) na prática

Para migrar tráfego gradualmente entre dois ALBs (por exemplo, uma versão antiga e uma nova da aplicação), dois registros com o mesmo nome e pesos diferentes:

aws route53 change-resource-record-sets \
  --hosted-zone-id Z1234567890ABC \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "api.minhaempresa.com",
        "Type": "A",
        "SetIdentifier": "versao-atual",
        "Weight": 90,
        "AliasTarget": {
          "HostedZoneId": "Z35SXDOTRQ7X7K",
          "DNSName": "alb-antigo-123456.us-east-1.elb.amazonaws.com",
          "EvaluateTargetHealth": true
        }
      }
    }]
  }'

E o segundo registro, apontando para o novo ALB com 10% do tráfego:

aws route53 change-resource-record-sets \
  --hosted-zone-id Z1234567890ABC \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "api.minhaempresa.com",
        "Type": "A",
        "SetIdentifier": "versao-nova",
        "Weight": 10,
        "AliasTarget": {
          "HostedZoneId": "Z35SXDOTRQ7X7K",
          "DNSName": "alb-novo-654321.us-east-1.elb.amazonaws.com",
          "EvaluateTargetHealth": true
        }
      }
    }]
  }'

Aumentar gradualmente o peso do "versao-nova" (10 → 50 → 100) e reduzir o do "versao-atual" na mesma proporção é uma forma simples de canary release sem depender de lógica de roteamento na aplicação.

5. O mesmo cenário em Terraform

O provider da AWS modela cada registro ponderado como um aws_route53_record com set_identifier e bloco weighted_routing_policy:

resource "aws_route53_record" "api_atual" {
  zone_id        = aws_route53_zone.principal.zone_id
  name           = "api.minhaempresa.com"
  type           = "A"
  set_identifier = "versao-atual"

  weighted_routing_policy {
    weight = 90
  }

  alias {
    name                   = aws_lb.antigo.dns_name
    zone_id                = aws_lb.antigo.zone_id
    evaluate_target_health = true
  }
}

resource "aws_route53_record" "api_nova" {
  zone_id        = aws_route53_zone.principal.zone_id
  name           = "api.minhaempresa.com"
  type           = "A"
  set_identifier = "versao-nova"

  weighted_routing_policy {
    weight = 10
  }

  alias {
    name                   = aws_lb.novo.dns_name
    zone_id                = aws_lb.novo.zone_id
    evaluate_target_health = true
  }
}

6. Failover automático com health check

Para um cenário de disaster recovery — um ambiente primário e um standby em outra região — o Route 53 monitora o endpoint primário e só resolve para o secundário quando ele falha:

aws route53 create-health-check \
  --caller-reference "hc-api-primario-$(date +%s)" \
  --health-check-config '{
    "IPAddress": "203.0.113.10",
    "Port": 443,
    "Type": "HTTPS",
    "ResourcePath": "/healthz",
    "RequestInterval": 30,
    "FailureThreshold": 3
  }'

O HealthCheckId retornado é referenciado nos dois registros de failover:

resource "aws_route53_record" "primario" {
  zone_id         = aws_route53_zone.principal.zone_id
  name            = "api.minhaempresa.com"
  type            = "A"
  set_identifier  = "primario"
  health_check_id = aws_route53_health_check.primario.id

  failover_routing_policy {
    type = "PRIMARY"
  }

  alias {
    name                   = aws_lb.regiao_principal.dns_name
    zone_id                = aws_lb.regiao_principal.zone_id
    evaluate_target_health = true
  }
}

resource "aws_route53_record" "secundario" {
  zone_id        = aws_route53_zone.principal.zone_id
  name           = "api.minhaempresa.com"
  type           = "A"
  set_identifier = "secundario"

  failover_routing_policy {
    type = "SECONDARY"
  }

  alias {
    name                   = aws_lb.regiao_dr.dns_name
    zone_id                = aws_lb.regiao_dr.zone_id
    evaluate_target_health = true
  }
}

Enquanto o health check do primário estiver saudável, todas as consultas recebem o endpoint principal. Assim que três checagens consecutivas falham, o Route 53 passa a responder com o endpoint secundário — sem nenhuma intervenção manual, embora o efeito completo dependa do TTL do registro e do quanto os resolvers dos clientes respeitam esse cache.

7. Uma ressalva importante: TTL e propagação

Diferente de um ALB, que reage a mudanças de saúde de um destino em segundos, uma mudança de resposta no Route 53 só se propaga para novos clientes conforme o TTL do registro expira em cada resolver intermediário — e alguns resolvers ignoram TTLs muito baixos. Para cenários de failover, é comum usar um TTL de 30 a 60 segundos nos registros críticos, aceitando uma janela de indisponibilidade parcial maior do que a de um balanceador de camada 4/7, em troca da capacidade de rotear entre regiões inteiras.

8. Conclusão

Combinar as duas camadas — instâncias EC2 agrupadas em um target group, como vimos no artigo anterior, e políticas de roteamento no Route 53 por cima delas — cobre tanto o balanceamento fino dentro de uma região quanto decisões de mais alto nível: canary release gradual, redução de latência por geografia e failover entre regiões inteiras. A escolha de política (weighted, latency-based, failover) depende do problema: migração gradual de versão pede weighted, presença global pede latency-based, disaster recovery pede failover — e nada impede combinar mais de uma, já que o Route 53 permite políticas aninhadas apontando um conjunto de registros para outro.

Imagem de capa: Logo da AWS — Wikimedia Commons, marca da Amazon.com, Inc. (convertido para PNG via wsrv.nl)

Referências:

AWS na prática - subindo instâncias EC2 e um target group do zero

Rafael Dutra — Tue, 13 Oct 2026 09:30:20 +0000

1. Uma nova série: balanceamento de carga na AWS

Colocar uma aplicação em produção quase nunca significa "uma máquina rodando o código". Significa várias instâncias idênticas, distribuição de tráfego entre elas, substituição automática de quem falhar e, cada vez mais, decisões de roteamento que acontecem antes mesmo do tráfego chegar a um balanceador — no próprio DNS. Nesta nova série de dois artigos, vamos construir esse cenário na AWS: primeiro, subindo instâncias EC2 e organizando-as em um target group; depois, no próximo artigo, olhando para o Route 53 e como balanceamento de carga também acontece na camada de resolução de nomes.

Começamos pela base: o que é uma instância EC2, como criar algumas delas de forma repetível, e como agrupá-las para que um balanceador (ou outro consumidor) saiba para onde mandar tráfego.

2. O que é o EC2

O Amazon EC2 (Elastic Compute Cloud) é o serviço de máquinas virtuais da AWS. Cada instância roda em um tipo (t3.micro, m5.large, etc.) que define CPU, memória e características de rede, a partir de uma AMI (Amazon Machine Image) — uma imagem de disco com o sistema operacional e, opcionalmente, software já instalado. Os elementos que mais importam ao planejar uma frota de instâncias por trás de um balanceador são:

Subnet: em qual sub-rede (e portanto em qual zona de disponibilidade) a instância nasce. Distribuir instâncias em subnets de AZs diferentes é o que garante que a queda de um datacenter não tire a aplicação do ar.
Security Group: o firewall da instância, controlando portas de entrada e saída.
Key pair: o par de chaves usado para acesso SSH inicial.
User data: um script executado no primeiro boot, útil para instalar e subir a aplicação sem depender de uma AMI customizada.

3. Criando uma instância EC2 via CLI

Para ilustrar de forma reprodutível, os exemplos abaixo usam a AWS CLI. Primeiro, um security group liberando HTTP e SSH:

aws ec2 create-security-group \
  --group-name web-servers-sg \
  --description "SG para instancias web atras do target group" \
  --vpc-id vpc-0123456789abcdef0

aws ec2 authorize-security-group-ingress \
  --group-id sg-0123456789abcdef0 \
  --protocol tcp --port 80 --cidr 0.0.0.0/0

aws ec2 authorize-security-group-ingress \
  --group-id sg-0123456789abcdef0 \
  --protocol tcp --port 22 --cidr 10.0.0.0/16

Com o security group pronto, sobe-se a instância com um user data que instala e inicia um servidor web mínimo:

aws ec2 run-instances \
  --image-id ami-0abcdef1234567890 \
  --instance-type t3.micro \
  --key-name minha-chave \
  --security-group-ids sg-0123456789abcdef0 \
  --subnet-id subnet-0aaa111122223333 \
  --count 1 \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=web-01}]' \
  --user-data '#!/bin/bash
yum install -y nginx
systemctl enable nginx
systemctl start nginx'

Repetir o comando trocando subnet-id (para uma subnet em outra AZ) e a tag Name cria uma segunda instância idêntica em termos de aplicação, mas fisicamente isolada da primeira — o ponto de partida para alta disponibilidade.

4. O mesmo cenário em Terraform

Rodar run-instances manualmente não escala nem é repetível. Em um projeto real, o mesmo cenário costuma ser descrito em Terraform, usando count para gerar N instâncias distribuídas em subnets diferentes:

variable "subnet_ids" {
  default = ["subnet-0aaa111122223333", "subnet-0bbb444455556666"]
}

resource "aws_instance" "web" {
  count                  = length(var.subnet_ids)
  ami                    = "ami-0abcdef1234567890"
  instance_type          = "t3.micro"
  subnet_id              = var.subnet_ids[count.index]
  vpc_security_group_ids = [aws_security_group.web.id]
  key_name               = "minha-chave"

  user_data = <<-EOF
    #!/bin/bash
    yum install -y nginx
    systemctl enable nginx
    systemctl start nginx
  EOF

  tags = {
    Name = "web-${count.index + 1}"
  }
}

5. Criando o target group

Um target group é a lista de destinos (instâncias EC2, IPs ou funções Lambda) para onde um balanceador de carga da AWS (ALB ou NLB) encaminha tráfego, junto com a configuração de health check que decide se cada destino está saudável o suficiente para receber requisições:

aws elbv2 create-target-group \
  --name web-servers-tg \
  --protocol HTTP \
  --port 80 \
  --vpc-id vpc-0123456789abcdef0 \
  --health-check-protocol HTTP \
  --health-check-path /healthz \
  --health-check-interval-seconds 15 \
  --healthy-threshold-count 2 \
  --unhealthy-threshold-count 3

O comando retorna um TargetGroupArn, usado tanto para registrar instâncias quanto para, no próximo artigo, anexar o target group a um listener de balanceador.

6. Registrando as instâncias no target group

Com as instâncias no ar e o target group criado, o passo final é registrar cada instância como um destino:

aws elbv2 register-targets \
  --target-group-arn arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/web-servers-tg/abcdef1234567890 \
  --targets Id=i-0123456789abcdef0 Id=i-0fedcba9876543210

A partir daí, o próprio target group passa a monitorar a saúde de cada instância via o health check configurado no passo anterior:

aws elbv2 describe-target-health \
  --target-group-arn arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/web-servers-tg/abcdef1234567890

A saída mostra o estado (healthy, unhealthy, initial) de cada instância registrada — é esse estado que um Application Load Balancer usa para decidir se deve ou não rotear tráfego para um destino específico.

7. Por que isso importa antes de falar em balanceador

Vale notar que, até aqui, nenhum balanceador de carga foi criado — só a infraestrutura que ele vai consumir. Essa separação é deliberada: um target group existe de forma independente do listener/load balancer que o usa, o que permite trocar de estratégia de roteamento (um ALB clássico, regras baseadas em path, ou o roteamento por DNS que veremos a seguir) sem recriar as instâncias nem o agrupamento delas.

8. Conclusão

Instâncias EC2 distribuídas em múltiplas zonas de disponibilidade e agrupadas em um target group com health check ativo são a base de qualquer arquitetura de alta disponibilidade na AWS — é esse agrupamento que qualquer balanceador, do ALB clássico a estratégias mais avançadas, vai consultar para saber quem está apto a receber tráfego. No próximo artigo desta série, vamos sair da camada de balanceador tradicional e olhar para o Route 53: como o próprio DNS pode distribuir tráfego entre regiões e endpoints, com políticas de roteamento ponderado, por latência e failover automático.

Imagem de capa: Logo da AWS — Wikimedia Commons, marca da Amazon.com, Inc. (convertido para PNG via wsrv.nl)

Referências:

Segurança e governança em infraestrutura - IAM com menor privilégio na prática

Rafael Dutra — Wed, 07 Oct 2026 09:30:37 +0000

1. O problema: privilégio excessivo é a norma, não a exceção

Nos dois artigos anteriores desta série, vimos como evitar que segredos vazem em texto puro e como bloquear recursos inseguros antes do apply com Policy as Code. Fechamos a série com um problema mais silencioso, porque não gera erro nem alerta: permissões de IAM concedidas com mais alcance do que o necessário. Uma role de aplicação com s3:* quando só precisa de s3:GetObject em um bucket específico. Um usuário de CI com AdministratorAccess porque "assim resolve na hora e ninguém precisa pedir mais permissão depois". Nada disso quebra nada — até o dia em que uma credencial é comprometida, e o raio de ação do atacante é exatamente do tamanho da permissão que ninguém restringiu.

2. Erros comuns de permissão excessiva

Actions com wildcard: "Action": "s3:*" ou "Action": "*" em vez de listar exatamente as operações necessárias (s3:GetObject, s3:PutObject).
Resources com wildcard: "Resource": "*" quando a intenção real era restringir a um bucket ou prefixo específico.
Roles compartilhadas entre serviços diferentes: uma única role "backend-role" usada por várias Lambdas/serviços com necessidades distintas, acumulando permissões de todos ao longo do tempo porque é mais fácil reaproveitar do que criar uma nova.
Credenciais de longa duração: access keys de usuário IAM sem rotação, em vez de roles assumidas temporariamente (via sts:AssumeRole) ou identidades federadas (OIDC em pipelines de CI).
Permissões concedidas e nunca revisadas: um acesso liberado para resolver um incidente pontual ("dá acesso de admin no S3 pra debugar isso rápido") que nunca é removido depois.

3. Desenhando políticas mínimas: metodologia

Least privilege na prática raramente é "acertar de primeira" — é um processo iterativo:

Comece restritivo, não permissivo. Ao criar uma role nova, liste apenas as actions que o código efetivamente chama, mesmo que isso signifique testar e ajustar algumas vezes até funcionar.
Use os logs de acesso reais para calibrar. Ferramentas como o IAM Access Analyzer (AWS) geram recomendações de política baseadas no uso real registrado em CloudTrail — em vez de adivinhar quais actions são necessárias, você vê quais foram efetivamente chamadas em um período.
Restrinja por Resource, não só por Action. Permitir s3:GetObject em * ainda é privilégio excessivo se a aplicação só precisa de um bucket. Sempre que a API do serviço suportar, especifique o ARN exato.
Adicione condições (Condition) quando possível. Restringir por IP de origem, exigir MFA, ou limitar por tag do recurso são camadas adicionais que reduzem o impacto de uma credencial vazada.

4. Exemplo prático: de permissivo a mínimo

Política de partida, comum em código copiado de um tutorial genérico:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:*",
      "Resource": "*"
    }
  ]
}

Versão com least privilege, depois de identificar que a aplicação só lê objetos de um bucket específico, sob um prefixo específico:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::app-uploads-prod",
        "arn:aws:s3:::app-uploads-prod/incoming/*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:PrincipalTag/environment": "production"
        }
      }
    }
  ]
}

Em Terraform, o mesmo desenho, evitando reescrever o JSON manualmente:

data "aws_iam_policy_document" "app_uploads_read" {
  statement {
    effect = "Allow"

    actions = [
      "s3:GetObject",
      "s3:ListBucket",
    ]

    resources = [
      aws_s3_bucket.app_uploads.arn,
      "${aws_s3_bucket.app_uploads.arn}/incoming/*",
    ]

    condition {
      test     = "StringEquals"
      variable = "aws:PrincipalTag/environment"
      values   = ["production"]
    }
  }
}

resource "aws_iam_policy" "app_uploads_read" {
  name   = "app-uploads-read-only"
  policy = data.aws_iam_policy_document.app_uploads_read.json
}

5. Automatizando a auditoria de acessos

Desenhar a política mínima na criação não é suficiente — permissões tendem a acumular ao longo do tempo, e é preciso um processo contínuo para detectar isso:

IAM Access Analyzer identifica automaticamente recursos acessíveis por entidades externas à conta (buckets, roles, chaves KMS) e também gera relatórios de "permissões concedidas versus permissões usadas nos últimos 90 dias", apontando o que pode ser removido:

aws accessanalyzer list-findings \
  --analyzer-arn arn:aws:access-analyzer:us-east-1:123456789012:analyzer/default \
  --filter '{"status": {"eq": ["ACTIVE"]}}'

cloudsplaining, uma ferramenta open source, escaneia políticas IAM de uma conta AWS inteira e sinaliza padrões arriscados (wildcards, privilege escalation, ausência de resource constraints) em um relatório HTML:

pip install cloudsplaining

cloudsplaining download --profile production
cloudsplaining scan --input-file default.json --output results/

Integrando com o pipeline de IaC: o mesmo conftest/OPA visto no artigo anterior desta série pode avaliar documentos de política IAM gerados pelo Terraform antes do apply, bloqueando qualquer "Resource": "*" combinado com uma action de escrita, por exemplo:

package terraform.iam

deny[msg] {
    resource := input.resource_changes[_]
    resource.type == "aws_iam_policy"

    statement := resource.change.after.policy.Statement[_]
    statement.Effect == "Allow"
    statement.Resource == "*"

    msg := sprintf(
        "política '%s' usa Resource=\"*\" — restrinja ao ARN específico",
        [resource.address],
    )
}

6. Rotação e identidades temporárias

Além de restringir o que uma credencial pode fazer, reduzir por quanto tempo ela é válida limita ainda mais o impacto de um vazamento:

Prefira roles assumidas via sts:AssumeRole a usuários IAM com access key fixa sempre que possível.
Em pipelines de CI, use OIDC federation (GitHub Actions, GitLab CI já suportam nativamente) para que o pipeline assuma uma role temporária sem nenhuma credencial de longa duração armazenada como secret:

# GitHub Actions assumindo uma role via OIDC, sem access key fixa
permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
      aws-region: us-east-1

7. Conclusão da série

Segredos guardados corretamente, recursos validados por política antes do apply e permissões desenhadas com o mínimo privilégio necessário são três frentes independentes, mas que se reforçam: um segredo vazado importa menos se a credencial associada tem alcance limitado; uma política de IAM bem desenhada é, ela mesma, um alvo natural de checagem via Policy as Code. Nenhuma automação de infraestrutura está completa sem tratar segurança e governança como parte do pipeline, não como uma revisão manual que acontece (ou não) antes de ir para produção.

Imagem de capa: Logo oficial da HashiCorp, mantenedora do Vault — Wikimedia Commons

Referências:

Segurança e governança em infraestrutura - policy as code com OPA

Rafael Dutra — Mon, 05 Oct 2026 09:30:54 +0000

1. O problema: erros que só aparecem depois do apply

No artigo anterior desta série, vimos como evitar que segredos vazem em texto puro. Mas existe uma categoria de erro igualmente comum e mais sutil: um terraform apply tecnicamente correto — sem erro de sintaxe, sem segredo exposto — que ainda assim cria um recurso inseguro: um bucket S3 público, um security group liberando 0.0.0.0/0 na porta 22, um disco sem criptografia. Nada disso quebra o plan. Só um revisor humano atento (ou um incidente) descobre depois.

Revisão manual de código não escala e é falível — ninguém lê 40 arquivos .tf de um PR grande linha a linha procurando um cidr_blocks errado. É exatamente esse problema que o Policy as Code resolve: transformar regras de segurança em código executável, que roda automaticamente antes do apply e bloqueia o que violar a política — sem depender de alguém lembrar de olhar.

2. O que é policy as code

Policy as Code é a prática de escrever regras de governança (segurança, compliance, convenções de nomenclatura, tags obrigatórias) como código versionado, testável e executado automaticamente em algum ponto do pipeline — geralmente entre o plan e o apply. As duas ferramentas mais usadas no ecossistema de IaC são:

OPA (Open Policy Agent), um motor de políticas open source e agnóstico de ferramenta, mantido pela CNCF, com sua própria linguagem de regras chamada Rego.
Sentinel, a solução proprietária da HashiCorp, disponível no Terraform Cloud/Enterprise, com integração nativa ao plano do Terraform.

Vamos focar no OPA por ser open source, gratuito e utilizável em qualquer pipeline (GitHub Actions, GitLab CI, Jenkins), independente de estar ou não no Terraform Cloud.

3. Rego: a linguagem de políticas do OPA

Rego é uma linguagem declarativa focada em fazer perguntas sobre dados estruturados (tipicamente JSON). Uma política Rego não "executa passos" — ela declara condições que, se verdadeiras, geram uma violação (deny) ou uma decisão (allow). O bloco básico:

package terraform.security

deny[msg] {
    # condição que, se verdadeira, gera uma mensagem de violação
    msg := "exemplo de violação"
}

O padrão mais comum ao avaliar Terraform é gerar o plano em JSON e alimentar essa estrutura para o OPA avaliar contra as políticas.

4. Exemplo prático: bloquear bucket S3 público

Considere este recurso, que qualquer pessoa pode escrever por engano ao copiar um exemplo de blog desatualizado:

resource "aws_s3_bucket" "logs" {
  bucket = "app-logs-prod"
}

resource "aws_s3_bucket_public_access_block" "logs" {
  bucket = aws_s3_bucket.logs.id

  block_public_acls       = false
  block_public_policy     = false
  ignore_public_acls      = false
  restrict_public_buckets = false
}

Uma política Rego para bloquear esse padrão, avaliando o plano em JSON gerado por terraform show -json:

package terraform.security

import future.keywords.in

deny[msg] {
    resource := input.resource_changes[_]
    resource.type == "aws_s3_bucket_public_access_block"

    change := resource.change.after

    some field in ["block_public_acls", "block_public_policy",
                   "ignore_public_acls", "restrict_public_buckets"]
    change[field] == false

    msg := sprintf(
        "recurso '%s' permite acesso público (%s = false)",
        [resource.address, field],
    )
}

5. Rodando a política com Conftest

O Conftest é uma CLI que facilita testar arquivos estruturados (JSON, YAML, planos de Terraform) contra políticas Rego, sem precisar montar toda a infraestrutura de servidor do OPA:

# Gera o plano em formato binário e depois em JSON
terraform plan -out=tfplan.binary
terraform show -json tfplan.binary > tfplan.json

# Avalia o plano contra as políticas no diretório policy/
conftest test --policy policy/ tfplan.json

Se a política do passo anterior for violada, a saída é algo como:

FAIL - tfplan.json - terraform.security - recurso 'aws_s3_bucket_public_access_block.logs' permite acesso público (block_public_acls = false)

1 test, 0 passed, 1 failed, 0 warnings

O código de saída não-zero do conftest é o que permite usar esse comando como um gate de CI: se falhar, o pipeline para antes de chegar no apply.

6. Sentinel como alternativa

Para quem já usa Terraform Cloud/Enterprise, o Sentinel oferece o mesmo conceito com integração nativa — as políticas rodam automaticamente entre plan e apply, sem precisar montar o pipeline de conftest manualmente:

import "tfplan/v2" as tfplan

s3_buckets_publicos = filter tfplan.resource_changes as _, rc {
    rc.type is "aws_s3_bucket_public_access_block" and
    rc.change.after.block_public_acls is false
}

main = rule {
    length(s3_buckets_publicos) is 0
}

A sintaxe é diferente do Rego, mas a ideia é idêntica: inspecionar o plano e recusar o apply se alguma condição de segurança não for satisfeita. A escolha entre OPA e Sentinel tende a ser menos sobre capacidade técnica e mais sobre onde o time já está: fora do Terraform Cloud, OPA/Conftest é a opção sem lock-in; dentro dele, o Sentinel remove a etapa de integração.

7. Onde rodar as políticas no pipeline

O ganho de Policy as Code só se realiza se a checagem for obrigatória, não opcional. Um pipeline típico de GitHub Actions:

# .github/workflows/terraform.yml
jobs:
  plan-and-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-terraform@v3

      - run: terraform init
      - run: terraform plan -out=tfplan.binary
      - run: terraform show -json tfplan.binary > tfplan.json

      - name: Instalar conftest
        run: |
          curl -fsSL https://github.com/open-policy-agent/conftest/releases/latest/download/conftest_linux_x86_64.tar.gz | tar xz
          sudo mv conftest /usr/local/bin

      - name: Avaliar políticas de segurança
        run: conftest test --policy policy/ tfplan.json

      # O apply só roda se o passo anterior não falhar
      - run: terraform apply -auto-approve tfplan.binary

Colocar a checagem antes do apply, como um passo que pode falhar o job, é o que transforma a política de "documentação que ninguém lê" em "barreira que ninguém consegue pular sem querer".

8. Conclusão

Policy as Code fecha uma lacuna que revisão manual de código não cobre bem: garantir, de forma automática e repetível, que todo recurso criado por IaC respeita as regras de segurança da organização — sem depender da atenção de quem está revisando o PR. OPA com Rego (via Conftest) e Sentinel resolvem o mesmo problema com integrações diferentes; o que importa é que a checagem rode como gate obrigatório no pipeline, não como sugestão. No próximo e último artigo desta série, entramos em outro pilar de governança: como desenhar permissões de IAM com o mínimo privilégio necessário — e como auditar, de forma automatizada, quando isso deixa de ser verdade.

Imagem de capa: Logo oficial da HashiCorp, mantenedora do Vault — Wikimedia Commons

Referências:

Segurança e governança em infraestrutura - secrets management na prática

Rafael Dutra — Mon, 05 Oct 2026 09:30:52 +0000

1. Uma nova série: segurança e governança em infraestrutura

Provisionar infraestrutura com código, versionar tudo em Git e automatizar o deploy resolve boa parte dos problemas operacionais de um time — mas também cria uma nova superfície de risco. Um terraform apply errado pode expor um bucket ao mundo; um segredo comitado por engano fica para sempre no histórico do repositório; uma role com permissão de mais é só uma credencial roubada de distância de um incidente grave. Nesta nova série, vamos tratar de três pilares de segurança e governança que toda automação de infraestrutura precisa levar em conta: gestão de segredos, policy as code e least privilege em IAM.

Começamos pelo problema mais básico e, ainda assim, um dos mais comuns em auditorias de segurança: como guardar e distribuir segredos sem deixá-los em texto puro em lugar nenhum.

2. O problema de guardar segredos em texto puro

É extremamente comum encontrar, em projetos reais, segredos vazando por canais aparentemente inofensivos:

Um terraform.tfvars com db_password = "supersecreta123" comitado "só para testar localmente" — e que nunca foi removido do histórico do Git.
Variáveis de ambiente com credenciais de nuvem definidas direto no arquivo de configuração do CI (visíveis em texto puro para qualquer pessoa com acesso de leitura ao pipeline).
O próprio state file do Terraform, que guarda em texto puro todos os atributos dos recursos que gerencia — incluindo senhas de banco de dados criadas via random_password ou strings de conexão completas.

O problema não é só o vazamento inicial. Um segredo comitado no Git continua acessível no histórico mesmo depois de removido do arquivo atual — é preciso reescrever o histórico (git filter-repo, BFG) e ainda assim tratar o segredo como comprometido, porque qualquer clone anterior já o tem. A prática correta é nunca deixar o segredo chegar ao repositório: ele deve viver em um sistema dedicado, com controle de acesso, auditoria e rotação.

3. Introdução ao Vault

O HashiCorp Vault é o sistema de gestão de segredos mais usado no ecossistema de IaC. Os conceitos centrais são:

Secrets engines: módulos plugáveis que definem como os segredos são gerados e armazenados. O mais simples é o KV (key-value), que guarda pares chave-valor estáticos, criptografados em repouso. Outros, como o engine da AWS, geram segredos dinâmicos: credenciais IAM criadas sob demanda, com tempo de vida limitado.
Leases: todo segredo dinâmico tem um lease (contrato de validade). Quando o lease expira, o Vault revoga a credencial automaticamente — sem depender de ninguém lembrar de fazer rotação manual.
Políticas de acesso: definem quem pode ler/escrever em quais paths do Vault, integradas com métodos de autenticação (tokens, AppRole, Kubernetes service accounts, OIDC, etc.).

A alternativa mais comum fora do universo HashiCorp é o AWS Secrets Manager (ou seu equivalente no Azure/GCP), que resolve o mesmo problema de forma mais simples quando o time já está 100% dentro de uma única nuvem, trocando flexibilidade multi-cloud por integração nativa e menos operação própria. Os exemplos abaixo usam Vault, mas o raciocínio de "nunca commitar segredo, sempre buscar em runtime" é o mesmo nos dois.

4. Subindo um Vault local para experimentar

Para fins de estudo, o Vault tem um modo de desenvolvimento que roda tudo em memória, sem persistência real:

vault server -dev -dev-root-token-id="root-token-local"

Em outro terminal, apontando o cliente para o servidor local:

export VAULT_ADDR="http://127.0.0.1:8200"
export VAULT_TOKEN="root-token-local"

vault status

5. Guardando e lendo segredos no KV

# Habilita o secrets engine KV versão 2 no path "secret/"
vault secrets enable -path=secret kv-v2

# Guarda um segredo
vault kv put secret/app/database \
  username="app_user" \
  password="uma-senha-bem-forte"

# Lê o segredo de volta
vault kv get secret/app/database

O KV v2 guarda versões de cada segredo, o que permite auditar quando um valor mudou e fazer rollback se necessário — algo que uma variável de ambiente jogada num .env nunca oferece.

6. Integrando Vault com Terraform

O provider oficial do Vault para Terraform permite ler segredos em tempo de plan/apply, sem que eles apareçam em nenhum arquivo .tf versionado:

provider "vault" {
  address = "http://127.0.0.1:8200"
}

data "vault_kv_secret_v2" "database" {
  mount = "secret"
  name  = "app/database"
}

resource "aws_db_instance" "app" {
  identifier     = "app-db"
  engine         = "postgres"
  instance_class = "db.t3.micro"

  username = data.vault_kv_secret_v2.database.data["username"]
  password = data.vault_kv_secret_v2.database.data["password"]
}

Um cuidado importante: o valor lido ainda vai parar no state file, em texto puro, porque é assim que o Terraform rastreia atributos de recursos. Isso não elimina a necessidade de um backend de state criptografado (S3 com SSE, ou o encryption nativo do OpenTofu visto na série anterior) — o Vault resolve o problema de "de onde o segredo vem", não o de "onde o resultado final fica guardado depois".

7. Segredos dinâmicos: indo além do KV estático

O ganho real de segurança do Vault aparece nos secrets engines dinâmicos. Em vez de guardar uma credencial fixa da AWS, o Vault pode gerar uma nova a cada solicitação, com expiração automática:

# Habilita o secrets engine da AWS
vault secrets enable aws

vault write aws/config/root \
  access_key="AKIA..." \
  secret_key="..." \
  region="us-east-1"

# Define uma role que gera credenciais com uma policy IAM específica
vault write aws/roles/deploy-readonly \
  credential_type="iam_user" \
  policy_document=-<<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "s3:GetObject", "Resource": "*" }
  ]
}
EOF

# Gera uma credencial temporária, válida por um tempo limitado
vault read aws/creds/deploy-readonly

Cada vault read acima gera um par de chaves novo, com lease próprio. Se uma pipeline de CI usa esse fluxo, uma credencial vazada em um log específico expira sozinha em minutos ou horas, em vez de ficar válida indefinidamente como uma chave de usuário IAM tradicional.

8. Conclusão

Segredos em texto puro no repositório — ou em variáveis de ambiente de CI sem controle — são um dos vetores de incidente mais comuns e mais fáceis de evitar em automação de infraestrutura. Um secrets manager dedicado (Vault, AWS Secrets Manager ou equivalente) resolve isso com armazenamento criptografado, controle de acesso granular e, no melhor caso, credenciais dinâmicas de curta duração. No próximo artigo desta série, vamos olhar para outro tipo de risco: recursos inseguros que passam pelo apply porque nenhuma regra automatizada os bloqueou antes — e como o Policy as Code resolve isso com OPA.

Imagem de capa: Logo oficial da HashiCorp, mantenedora do Vault — Wikimedia Commons

Referências:

Debugando um incidente real - métricas, logs e traces juntos na prática

Rafael Dutra — Sun, 27 Sep 2026 09:30:45 +0000

1. Retomando: chegou a hora de usar a stack de verdade

Ao longo desta série, a stack cresceu peça por peça: métricas (artigos 2 e 3), logs (artigo 4), traces (artigo 5), tudo unificado em Docker Compose (artigo 6) e visualizado em dashboards (artigo 7). Este último artigo inverte o roteiro: em vez de adicionar mais uma peça, vamos quebrar a mini app PHP de propósito e usar a stack inteira — dashboard, logs e traces — para investigar o problema do zero, como em um incidente real.

2. Simulando o problema

No app.php construído no artigo 3, uma mudança pequena e deliberada introduz um bug de performance: uma fração dos pedidos passa a demorar muito mais que o normal, e uma fração menor passa a falhar de verdade.

// dentro do processamento do pedido, logo apos $state['queue_size']++
if (random_int(1, 100) <= 15) {
    // simula uma dependencia externa lenta (ex.: um servico de pagamento)
    usleep(random_int(2_000_000, 4_000_000)); // 2-4 segundos, bem acima do normal
}

if (random_int(1, 100) <= 5) {
    http_response_code(500);
    logToLoki("falha ao processar pedido: timeout no servico de pagamento", "error");
    $state['queue_size']--;
    writeState($stateFile, $state);
    echo "erro interno\n";
    exit;
}

Essa mudança fica no ar, e a investigação a seguir segue exatamente o caminho que alguém sem acesso a este código-fonte teria: só olhando para o que a stack de observabilidade mostra.

3. Passo 1: o dashboard aponta o sintoma

Gerando tráfego contínuo contra a mini app PHP e observando o dashboard construído no artigo 7 (com a variável $app em php-app), dois painéis mudam de forma visível:

O painel de latência p50/p95/p99 mostra o p50 relativamente estável, mas o p95 e p99 disparando bem acima — o padrão clássico de "uma minoria de requisições muito mais lentas que a maioria", coerente com os 15% de chance de lentidão introduzidos no passo anterior.
O painel de volume de erros por minuto (baseado em count_over_time sobre logs com level="error") sai de zero e passa a mostrar uma taxa constante de erros.

Neste ponto, o dashboard já respondeu a primeira pergunta — "algo está errado, e é especificamente na mini app PHP" — mas não o "por quê". Essa é a fronteira natural entre o que métricas conseguem responder sozinhas e onde é preciso descer um nível.

4. Passo 2: os logs explicam o erro

Voltando ao painel de logs do dashboard (ou ao Explore, filtrando diretamente):

{app="php-app", level="error"}

A mensagem falha ao processar pedido: timeout no servico de pagamento aparece repetida, associada aos horários em que o painel de erro subiu. Já é uma pista concreta — não é um erro genérico de PHP, é um erro específico de negócio, com uma causa nomeada no próprio texto do log (o "serviço de pagamento"). Mas o log sozinho não diz quanto tempo foi gasto antes do erro acontecer, nem se as requisições lentas (vistas no painel de latência) são o mesmo fenômeno que as requisições que falham, ou dois problemas diferentes acontecendo ao mesmo tempo.

5. Passo 3: os traces confirmam onde o tempo foi gasto

Com a instrumentação dos artigos 5 e 6, cada requisição gera um span process_order. Consultando os logs do coletor OpenTelemetry (ou, em uma stack com backend de tracing dedicado, navegando visualmente pela árvore de spans) durante o mesmo intervalo de tempo do pico visto no dashboard:

docker compose logs otel-collector --since 5m | grep -A 5 process_order

Os spans capturados no período do incidente mostram uma duração (end_time - start_time) concentrada em dois grupos bem separados: a maioria na faixa de dezenas de milissegundos (comportamento normal) e um grupo secundário na faixa de 2 a 4 segundos — exatamente a faixa introduzida artificialmente na simulação. O atributo order.duration_ms (adicionado ao span no artigo 5) confirma numericamente essa distribuição bimodal em cada span individual, span a span, algo que nem o painel de latência agregada (que mostra percentis, não casos individuais) nem o log de erro (que só aparece nos 5% que efetivamente falham, não nos 15% que só ficam lentos) conseguiam mostrar isoladamente.

6. Juntando as três pontas

A investigação completa, remontada:

Métricas apontaram que algo mudou e quando — p95/p99 subindo, taxa de erro saindo de zero — sem precisar que ninguém soubesse previamente que aquele problema existia (exatamente a definição de observabilidade do artigo 1: responder a uma pergunta não antecipada).
Logs explicaram o quê estava falhando, com uma mensagem específica de negócio ("timeout no serviço de pagamento"), restrita rapidamente pelos labels app e level graças ao modelo de indexação do Loki (artigo 4).
Traces confirmaram onde, dentro da requisição, o tempo estava de fato sendo gasto, com granularidade por requisição individual — não apenas em agregado — e conectaram as requisições lentas (visíveis só na cauda do histograma) às requisições que geravam log de erro.

Nenhum dos três pilares sozinho reconstrói essa história completa: métricas sem logs mostram que algo mudou, mas não por quê; logs sem métricas exigiriam vasculhar volume gigantesco de texto sem saber onde procurar primeiro; traces sem os outros dois não teriam sido acionados a tempo, já que ninguém estaria olhando spans individuais sem antes ver o dashboard disparar.

7. Conclusão da série

Ao longo desses oito artigos, esta série construiu uma stack de observabilidade completa a partir do zero: o que são métricas, logs e traces e por que nenhum substitui os outros dois; Prometheus coletando métricas via scraping de duas mini aplicações reais, em Python e PHP puros; Loki recebendo logs via API HTTP, com um modelo de indexação deliberadamente mais barato que ferramentas tradicionais; OpenTelemetry como padrão neutro para gerar traces, primeiro isolado, depois unificado via um coletor OTLP; dashboards no Grafana combinando PromQL e LogQL; e, neste último artigo, os três pilares trabalhando juntos para investigar um incidente simulado do sintoma até a causa raiz. A stack construída aqui é deliberadamente mínima — sem alta disponibilidade, sem retenção de longo prazo configurada, sem backend de tracing visual — mas os conceitos e o fluxo de investigação são exatamente os mesmos usados em stacks de observabilidade de produção, em qualquer escala.

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

Referências:

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: