Cloud Server
Como configurar Grafana Tempo em Cloud Server
Aprenda a configurar Grafana Tempo em Cloud Server, integrar OpenTelemetry, receber traces de APIs e ajustar armazenamento, segurança e retenção de dados.
Resposta direta
Para configurar Grafana Tempo em um Cloud Server, execute o Tempo como backend de traces, use o OpenTelemetry Collector para receber e processar telemetria via OTLP e conecte o Grafana ao endpoint HTTP do Tempo. Uma instalação inicial pode funcionar com 2 vCPUs, 4 GB de RAM e 40 GB de SSD, mas produção costuma exigir 4 vCPUs, 8 GB de RAM e armazenamento dimensionado pela taxa de spans e retenção. O endpoint OTLP não deve ficar aberto na internet sem autenticação, TLS, firewall ou rede privada. Em ambientes pequenos, o modo monolítico simplifica a operação. Quando a ingestão, a disponibilidade ou o número de equipes cresce, a arquitetura distribuída com armazenamento de objetos se torna mais adequada.
Resumo rápido
- Grafana Tempo armazena traces, enquanto o Grafana oferece consulta e visualização.
- OpenTelemetry Collector recebe, agrupa, filtra e encaminha spans pelo protocolo OTLP.
- Um laboratório pode começar com 2 vCPUs, 4 GB de RAM e 40 GB de SSD.
- Produção pequena fica mais confortável com 4 vCPUs, 8 GB de RAM e 100 GB de disco.
- As portas OTLP 4317 e 4318 não devem ser publicadas sem controles de acesso.
- Retenção de 3 a 7 dias reduz o risco de o disco local encher durante a fase inicial.
- Docker Compose atende implantações simples, mas não substitui alta disponibilidade.
Como Grafana Tempo e OpenTelemetry se conectam
O caminho completo de um trace
O Grafana Tempo não instrumenta a aplicação sozinho. O processo começa dentro da API, worker ou microsserviço, onde um SDK do OpenTelemetry cria spans para operações como uma requisição HTTP, uma consulta PostgreSQL ou a publicação de uma mensagem. Esses spans formam um trace por meio de identificadores compartilhados. Uma chamada que passa por gateway, serviço de pedidos e serviço de pagamentos pode, por exemplo, gerar três ou mais spans associados ao mesmo trace_id.
A aplicação envia os dados para o OpenTelemetry Collector usando OTLP sobre gRPC, normalmente na porta 4317, ou OTLP sobre HTTP, na porta 4318. O Collector aplica processadores de lote e controle de memória antes de exportar os spans para o Tempo. Esse intermediário evita que cada aplicação precise conhecer detalhes do backend e permite trocar destinos sem alterar todos os serviços. Se a equipe quiser enviar uma cópia para outro sistema durante uma migração, basta adicionar um segundo exporter ao pipeline.
O Tempo grava os blocos de traces em disco local ou armazenamento de objetos. O Grafana consulta a API HTTP do Tempo, geralmente na porta 3200, e apresenta a busca por TraceQL, trace ID ou correlação com métricas e logs. Para montar uma pilha de observabilidade mais ampla, o artigo sobre Cloud Server para OpenTelemetry em produção aprofunda a função do Collector e os cuidados com pipelines compartilhados.
Modo monolítico ou distribuído
No modo monolítico, um único processo do Tempo executa distributor, ingester, querier, compactor e demais componentes. É uma escolha prática para laboratório, homologação e produção de baixo volume, pois reduz o número de serviços operados. O custo dessa simplicidade é a concentração de falhas. Se o processo ou o servidor parar, ingestão e consulta ficam indisponíveis até a recuperação.
O modo distribuído separa componentes e permite escalar ingestão e consulta de forma independente. Essa arquitetura combina melhor com Kubernetes, múltiplas instâncias e armazenamento compatível com S3, Google Cloud Storage ou Azure Blob Storage. Um Cloud Server isolado não oferece alta disponibilidade apenas porque executa contêineres. Para começar com até algumas centenas de spans por segundo, o monolítico costuma ser suficiente. Acima disso, a decisão deve considerar testes de carga, duração dos traces, retenção e picos reais, não apenas a média diária.
Dimensionamento do Cloud Server
CPU, memória e disco
O primeiro dimensionamento deve considerar três cargas diferentes: ingestão de spans, compactação dos blocos e consultas feitas no Grafana. Um ambiente de desenvolvimento com até 50 spans por segundo pode começar com 2 vCPUs, 4 GB de RAM e 40 GB de SSD. Para uma equipe pequena, com várias APIs e picos próximos de 300 spans por segundo, 4 vCPUs, 8 GB de RAM e 100 GB de SSD oferecem margem mais segura para o Tempo, o Collector e o Grafana compartilharem o mesmo servidor.
A memória não depende apenas da quantidade de traces armazenados. O ingester mantém dados recentes antes de formar blocos, enquanto o Collector usa filas e lotes. Consultas amplas também consomem CPU e RAM. Se o servidor tiver somente 2 GB, uma busca extensa pode disputar memória com a ingestão e acionar o OOM killer. Swap de 2 a 4 GB pode amortecer um pico curto, mas não corrige subdimensionamento constante.
| Perfil | Tráfego de referência | Recursos iniciais | Disco e retenção | Arquitetura sugerida |
|---|---|---|---|---|
| Laboratório | Até 50 spans/s | 2 vCPUs, 4 GB RAM | 40 GB SSD, 3 dias | Tempo monolítico e disco local |
| Equipe pequena | Até 300 spans/s | 4 vCPUs, 8 GB RAM | 100 GB SSD ou NVMe, 7 dias | Monolítico com Collector separado |
| Produção crescente | Acima de 1.000 spans/s | 8 vCPUs, 16 GB RAM ou mais | Object storage e 14 a 30 dias | Componentes distribuídos e redundância |
Esses valores são pontos de partida, não benchmarks universais. O volume final muda conforme o número de atributos, o tamanho dos eventos, o sampling e o comportamento da aplicação. SSD atende cargas moderadas. NVMe pode ajudar em compactação, WAL e consultas concorrentes, mas não compensa CPU insuficiente, cardinalidade descontrolada ou retenção mal calculada.
Estimativa de ingestão
Uma aproximação simples usa spans por segundo, tamanho médio e período de retenção. Se o ambiente receber 200 spans por segundo e cada span ocupar, após serialização e compressão, uma média hipotética de 700 bytes, o volume bruto diário ficará perto de 12 GB antes de considerar variações e overhead operacional. Como o tamanho real pode ser bem diferente, meça a taxa no Collector durante pelo menos sete dias.
Reserve ainda 20% a 30% do disco para WAL, compactação e crescimento inesperado. Em um volume de 100 GB, não planeje usar os 100 GB para blocos. Crie alertas em 70%, 80% e 90% de ocupação. Se Grafana, Prometheus e Tempo dividirem a máquina, consulte também o projeto de monitoramento com Grafana e Prometheus, pois a retenção das métricas precisa entrar na mesma conta de capacidade.
Instalação do Grafana Tempo com Docker Compose
Preparação do servidor
O exemplo abaixo usa Ubuntu Server, Docker Engine e Docker Compose. Antes de instalar os contêineres, atualize os pacotes, configure sincronização de horário e restrinja o firewall. Relógios desalinhados produzem traces confusos, com spans aparentemente fora de ordem. O NTP do systemd-timesyncd ou o Chrony deve estar ativo tanto no Cloud Server quanto nos hosts das aplicações.
Crie a estrutura de trabalho e defina permissões persistentes:
sudo mkdir -p /opt/observability/tempo-data
sudo mkdir -p /opt/observability/config
cd /opt/observability
sudo chown -R $USER:$USER /opt/observability
Em seguida, salve /opt/observability/config/tempo.yaml. A configuração usa backend local, retenção de sete dias e receptores OTLP. Ela funciona como referência para uma instalação monolítica. Antes de adotar uma tag de imagem em produção, valide a versão estável na documentação oficial e registre a versão no controle de mudanças.
server:
http_listen_port: 3200
distributor:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
ingester:
max_block_duration: 5m
compactor:
compaction:
block_retention: 168h
storage:
trace:
backend: local
wal:
path: /var/tempo/wal
local:
path: /var/tempo/blocks
Subida dos contêineres
O arquivo compose.yaml executa Tempo, OpenTelemetry Collector e Grafana na mesma rede. Somente a interface web do Grafana é publicada para acesso externo. A API do Tempo fica presa ao endereço local, enquanto OTLP permanece disponível apenas na rede Docker neste primeiro estágio.
services:
tempo:
image: grafana/tempo:2.6.1
command: -config.file=/etc/tempo.yaml
volumes:
- ./config/tempo.yaml:/etc/tempo.yaml:ro
- ./tempo-data:/var/tempo
ports:
- 127.0.0.1:3200:3200
restart: unless-stopped
collector:
image: otel/opentelemetry-collector-contrib:0.116.0
command: --config=/etc/otelcol/config.yaml
volumes:
- ./config/otel-collector.yaml:/etc/otelcol/config.yaml:ro
depends_on:
- tempo
restart: unless-stopped
grafana:
image: grafana/grafana:11.3.1
ports:
- 3000:3000
volumes:
- grafana-data:/var/lib/grafana
depends_on:
- tempo
restart: unless-stopped
volumes:
grafana-data:
Execute docker compose config para detectar erros de sintaxe e depois docker compose up -d. Confira o estado com docker compose ps e acompanhe a inicialização usando docker compose logs -f tempo collector. Fixar versões torna a implantação reproduzível, mas as tags apresentadas são exemplos técnicos e precisam passar por revisão de segurança e compatibilidade antes da publicação ou uso produtivo.
Integração com OpenTelemetry Collector e Grafana
Pipeline do Collector
O Collector precisa de receivers, processors, exporters e um pipeline que ligue essas etapas. Crie /opt/observability/config/otel-collector.yaml com limites coerentes para a memória disponível. Em um servidor com 8 GB de RAM, reservar até 1 GB para o Collector é um começo conservador. O processador batch reduz o número de envios, enquanto memory_limiter impede crescimento sem controle.
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
memory_limiter:
check_interval: 1s
limit_mib: 1024
spike_limit_mib: 256
batch:
timeout: 5s
send_batch_size: 1024
exporters:
otlp/tempo:
endpoint: tempo:4317
tls:
insecure: true
service:
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [otlp/tempo]
O insecure: true aparece apenas porque Collector e Tempo trafegam dentro da rede privada criada pelo Compose. Não replique essa configuração em uma conexão pela internet. Para aplicações externas, use VPN, rede privada do provedor ou um proxy que termine TLS e aplique autenticação. Outra opção é executar um Collector como agente perto de cada aplicação e encaminhar os lotes para um Collector gateway central.
Instrumentação de uma aplicação
Uma API Node.js pode exportar traces definindo variáveis de ambiente antes da inicialização. O nome do serviço precisa ser estável, pois será usado em filtros e correlações. Um exemplo seria OTEL_SERVICE_NAME=api-pedidos, OTEL_EXPORTER_OTLP_PROTOCOL=grpc e OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317. Em Docker Compose, a aplicação pode usar o nome DNS collector; fora da rede, use um endereço privado resolvível.
Para uma API Python instrumentada automaticamente, instale os pacotes do OpenTelemetry, execute opentelemetry-bootstrap -a install e inicie o processo com opentelemetry-instrument. Uma aplicação Java pode carregar o agente Java e apontar o mesmo endpoint OTLP. Em todos os casos, inclua atributos controlados, como deployment.environment=production e service.version=2026.11.1. Evite colocar CPF, token, corpo completo de requisição ou credenciais nos atributos dos spans.
Datasource do Grafana
No Grafana, acesse Connections, Data sources, Add data source e selecione Tempo. Use http://tempo:3200 como URL quando os contêineres compartilham a rede. Depois de salvar, abra Explore e procure um trace ID capturado na aplicação. Para correlacionar traces com logs, uma pilha baseada em logs centralizados com Loki pode usar o mesmo trace_id nos registros estruturados. Essa correlação permite partir de um erro no log e chegar à sequência completa de chamadas sem procurar manualmente em cada microsserviço.
Retenção, armazenamento e segurança
Política de retenção
A retenção deve responder a uma necessidade operacional concreta. Sete dias podem ser suficientes para investigar incidentes recentes em uma equipe pequena. Ambientes regulados ou com análise histórica podem exigir 30 dias ou mais, mas o custo e a complexidade aumentam. No backend local, block_retention: 168h remove blocos após sete dias durante a compactação. A exclusão não ocorre necessariamente no segundo exato em que o prazo termina, por isso o disco precisa comportar uma margem adicional.
Use df -h, métricas do node exporter ou alertas do provedor para acompanhar ocupação. Um exemplo prático é alertar em 70% como aviso, 80% como criticidade e 90% para intervenção imediata. Se a ingestão dobra durante uma campanha, reduza temporariamente a retenção ou aumente o volume antes que o filesystem fique sem espaço. Disco cheio pode interromper a formação de blocos e afetar outros serviços instalados na mesma máquina.
Para produção crescente, armazenamento de objetos separa a vida útil dos traces da instância de computação. S3 e APIs compatíveis, Google Cloud Storage e Azure Blob Storage são opções suportadas conforme a versão e o modo de implantação. Credenciais devem ser entregues por secret manager, variável protegida ou identidade da instância. Nunca grave chaves diretamente no compose.yaml versionado.
Proteção dos endpoints OTLP
As portas 4317 e 4318 aceitam telemetria e podem ser abusadas para consumir banda, CPU e armazenamento. Mantenha-as fechadas no firewall público. Se uma aplicação estiver em outro servidor, prefira uma rede privada ou WireGuard. Quando isso não for possível, OTLP/HTTP pode passar por Nginx ou outro proxy com TLS, autenticação e limite de requisições. OTLP/gRPC também suporta TLS, mas exige configuração compatível com HTTP/2.
A interface do Grafana precisa de senha forte, controle de usuários e HTTPS. Troque a credencial administrativa inicial, limite o cadastro de usuários e evite publicar a porta 3000 diretamente quando houver proxy reverso. O endpoint 3200 do Tempo também deve permanecer privado, pois consultas amplas podem consumir recursos mesmo sem alterar dados.
Backup e recuperação
Snapshots do Cloud Server ajudam na recuperação da máquina, mas não substituem um backup consistente. Para disco local, documente como parar a ingestão, copiar os blocos e restaurar permissões. Teste a restauração em uma instância separada a cada trimestre. Se a perda de traces de alguns minutos for aceitável, o plano pode priorizar reconstrução rápida do serviço. Para requisitos mais rígidos, use object storage com versionamento e componentes redundantes.
Validação, consultas e troubleshooting
Como confirmar a ingestão
Depois de subir a pilha, valide cada salto em vez de testar tudo de uma vez. Primeiro, confirme que os contêineres estão ativos com docker compose ps. Depois, consulte a API do Tempo localmente com curl http://127.0.0.1:3200/ready. Uma resposta de prontidão mostra que o processo iniciou, mas ainda não prova que os spans chegam ao armazenamento.
Gere tráfego em uma API instrumentada e acompanhe docker compose logs -f collector tempo. O Collector deve registrar exportações sem erros persistentes. No Grafana Explore, selecione a fonte Tempo e filtre pelo nome do serviço, ambiente ou duração. Um teste útil consiste em criar uma rota /slow que aguarde 500 ms antes de responder. O trace esperado deve exibir um span próximo desse tempo, além dos spans de framework, banco ou cliente HTTP que estiverem instrumentados.
Outro cenário prático é provocar uma resposta HTTP 500 controlada em homologação. Verifique se o status do span aparece como erro e se os atributos não carregam dados sensíveis. Por fim, copie o trace_id para os logs estruturados. Se Loki estiver integrado, o mesmo identificador deve levar do log ao trace e do trace ao log.
Falhas mais comuns
Quando nenhum trace aparece, confira primeiro o endpoint configurado na aplicação. Dentro da rede Docker, localhost:4317 aponta para o próprio contêiner da aplicação, não para o Collector. O destino correto costuma ser collector:4317. Para aplicações externas, confirme rota, firewall, DNS e certificado. Use grpcurl em conexões gRPC ou curl em endpoints HTTP para separar falha de rede de falha na instrumentação.
Erros como context deadline exceeded indicam indisponibilidade, latência ou fila saturada. Mensagens de connection refused sugerem porta fechada ou processo não iniciado. Se o Collector reiniciar por memória, reduza send_batch_size, ajuste limit_mib e avalie mais RAM. Se o Tempo consumir CPU durante consultas, diminua o intervalo pesquisado e evite buscas amplas sem filtros.
Traces incompletos costumam apontar para propagação de contexto quebrada. Um serviço pode receber o cabeçalho traceparent, mas iniciar um trace novo em vez de continuar o existente. Confirme que proxies e filas preservam os metadados necessários. Em mensageria, produtor e consumidor precisam usar propagadores compatíveis.
Métricas para acompanhar
Monitore spans recebidos, spans recusados, falhas de exportação, tamanho da fila, uso de memória, CPU, latência de consulta e espaço em disco. Um alerta de fila crescente no Collector pode antecipar a perda de dados. Compare também a contagem de requisições da API com a quantidade amostrada de traces. Uma queda abrupta nessa proporção pode sinalizar erro de instrumentação, mudança no sampling ou bloqueio de rede.
Recomendações por perfil
Desenvolvedor solo e laboratório
Para estudar rastreamento distribuído ou observar uma aplicação pequena, comece com 2 vCPUs, 4 GB de RAM e 40 GB de SSD. Execute Tempo, Collector e Grafana no mesmo Cloud Server, mantenha retenção de três dias e envie apenas traces de desenvolvimento ou homologação. O modo monolítico reduz o esforço operacional e facilita entender o caminho dos spans. Mesmo em laboratório, feche as portas 3200, 4317 e 4318 no firewall público. Publique apenas o Grafana atrás de HTTPS ou acesse tudo por túnel SSH. Limite o sampling se testes de carga gerarem milhares de requisições, pois uma experiência curta pode preencher o disco rapidamente.
Equipe pequena
Uma equipe com cinco a quinze desenvolvedores e várias APIs pode iniciar com 4 vCPUs, 8 GB de RAM e 100 GB de SSD, usando retenção de sete dias. Separe o Collector em um contêiner próprio e aplique limites de memória, lotes e filas. Padronize nomes como service.name, service.version e deployment.environment para evitar filtros inconsistentes. Use um Collector agente em cada host quando as aplicações estiverem distribuídas e encaminhe tudo para um gateway central. Configure alertas de disco, falhas de exportação e reinício dos contêineres. Um teste mensal de restauração ajuda a confirmar que a documentação continua válida depois de atualizações.
Produção com alta ingestão
Em produção com mais de 1.000 spans por segundo, múltiplas equipes ou exigência de disponibilidade, não trate um único Cloud Server como solução final. Avalie Tempo distribuído, object storage, dois ou mais Collectors gateway e balanceamento de tráfego. Comece os testes com pelo menos 8 vCPUs e 16 GB de RAM por nó relevante, mas dimensione a partir de métricas reais e ensaios de carga. Adote tail sampling quando a prioridade for preservar erros e traces lentos, lembrando que essa técnica exige manter spans em memória até a decisão. Defina orçamento de cardinalidade, política para dados sensíveis e um processo de atualização gradual. A arquitetura precisa sobreviver à falha de uma instância sem perder toda a capacidade de ingestão e consulta.
Continue lendo
Perguntas frequentes
Qual configuração mínima para executar Grafana Tempo em um Cloud Server?
Um laboratório com baixo volume pode começar com 2 vCPUs, 4 GB de RAM e 40 GB de SSD. Essa máquina pode hospedar Tempo, OpenTelemetry Collector e Grafana, desde que a retenção seja curta e não existam consultas concorrentes pesadas. Para produção pequena, 4 vCPUs, 8 GB de RAM e 100 GB de disco oferecem margem melhor. A configuração final depende de spans por segundo, tamanho médio dos spans, política de sampling, retenção e quantidade de usuários consultando traces. Meça esses fatores antes de ampliar ou reduzir recursos.
Grafana Tempo precisa do OpenTelemetry Collector?
O Tempo pode receber OTLP diretamente, portanto o Collector não é obrigatório em todos os cenários. Ainda assim, ele é recomendado porque centraliza processamento, agrupamento, limitação de memória, filas, filtros e exportação para um ou mais destinos. Sem o Collector, cada aplicação fica mais acoplada ao backend de traces. Em produção, um Collector também ajuda a controlar picos e padronizar atributos. Para ambientes distribuídos, é comum executar agentes próximos das aplicações e um gateway central responsável por encaminhar os spans ao Tempo.
É seguro expor as portas 4317 e 4318 na internet?
Não é seguro publicá-las sem proteção. As portas 4317 e 4318 recebem telemetria e podem ser usadas por terceiros para consumir armazenamento, banda e processamento. O caminho preferencial é uma rede privada, VPN ou conexão entre Collectors autenticados. Quando o tráfego precisa atravessar a internet, configure TLS, autenticação, limites de requisição e regras de firewall. OTLP/HTTP pode passar por um proxy reverso, enquanto OTLP/gRPC exige suporte adequado a HTTP/2. Credenciais e certificados devem ser rotacionados e armazenados fora de arquivos versionados.
Quanto espaço em disco os traces do Tempo consomem?
O consumo depende da taxa de spans, quantidade de atributos, eventos anexados, compressão, sampling e retenção. Como exemplo de planejamento, 200 spans por segundo com tamanho médio hipotético de 700 bytes representam aproximadamente 12 GB por dia antes de variações e overhead operacional. O número real precisa ser medido no ambiente. Reserve de 20% a 30% do volume para WAL, compactação e picos. Configure alertas de ocupação e revise a retenção sempre que novos serviços ou atributos forem adicionados ao pipeline.
Quando migrar do Tempo monolítico para o modo distribuído?
A migração faz sentido quando um único processo deixa de atender ingestão e consultas com estabilidade, quando a equipe precisa escalar componentes de forma independente ou quando a falha de um servidor não pode interromper toda a observabilidade. Outros sinais são filas persistentes, consultas lentas, compactação consumindo CPU excessiva e crescimento para milhares de spans por segundo. O modo distribuído adiciona componentes e esforço operacional, então não deve ser adotado apenas por expectativa de crescimento. Faça testes de carga e defina objetivos de disponibilidade antes da mudança.
Como correlacionar traces do Tempo com logs do Loki?
Inclua o `trace_id` nos logs estruturados da aplicação e preserve o mesmo contexto durante chamadas entre serviços. No Grafana, configure a fonte de dados Loki com um derived field que reconheça esse identificador e crie um link para o Tempo. Também é possível configurar links do Tempo para consultas de logs usando atributos como `service.name`. A correlação funciona melhor quando nomes de serviço, ambiente e versão seguem um padrão comum. Evite registrar tokens, documentos pessoais ou corpos completos de requisições junto ao identificador.
Fontes consultadas
- Grafana Tempo Documentation · coletado em 14/11/2026
- OpenTelemetry Collector Documentation · coletado em 14/11/2026
- OpenTelemetry Protocol Specification · coletado em 14/11/2026
- Docker Compose Documentation · coletado em 14/11/2026