Instalação da Stack de Observabilidade no Kubernetes

Este é o caminho recomendado para ambientes Kubernetes quando você quer um baseline moderno, padronizado e pronto para produção, sem precisar montar Prometheus, Collector, Operator e pipeline de logs


Sumário

  • Visão geral

  • O que a stack instala

  • Pré-requisitos

  • Antes de começar: tenant e token

  • Quick start

  • Instalação passo a passo

  • O que pode ser customizado

  • Como a instrumentação funciona

  • Métricas Prometheus de aplicação

  • Logs das aplicações

  • Validação após a instalação

  • Atualização da stack

  • Remoção da stack

  • Troubleshooting

  • Checklist final

  • Veja também


Visão geral

A stack Kubernetes da Elven segue esta divisão de responsabilidade:

Componente
Responsabilidade

Prometheus

métricas de infraestrutura e Kubernetes

OpenTelemetry Collector

OTLP das aplicações e scrape genérico de métricas de app

OpenTelemetry Operator

auto-instrumentação e inject-sdk

Grafana Alloy

logs stdout/stderr para Loki

collector-fe

telemetria frontend via Faro, quando esse fluxo for usado

Beyla

opcional, desligado por padrão

Resumo do fluxo:

Pontos importantes do baseline atual:

  • o Prometheus continua responsável por métricas de infra e cluster

  • o elven-otel-collector recebe OTLP das apps e também pode fazer scrape genérico de pods anotados com prometheus.io/*

  • os logs do cluster seguem por Alloy -> Loki

  • o Instrumentation é aplicado automaticamente pela stack, mas a injeção continua sendo opt-in por annotation

  • Beyla fica preparado no template, mas não sobe no helmfile apply padrão


O que a stack instala

No fluxo padrão, o helmfile apply sobe:

  1. cert-manager

  2. kube-prometheus-stack

  3. Grafana Alloy

  4. collector-fe

  5. elven-otel-collector

  6. elven-instrumentation-operator

  7. Instrumentation nos namespaces elegíveis

Arquivos principais do template:

Arquivo
Função

helmfile.yaml

orquestra a instalação da stack

monitoring-namespace.yaml

cria o namespace monitoring

elven-prometheus/values-prometheus.yaml

Prometheus e remote write

elven-logs-collector/values-alloy.yaml

logs via Alloy

elven-collector-fe/values.yaml

release do collector-fe

elven-collector-fe/collector-fe-env-secret.yaml

envs do collector-fe

elven-otel-collector/collector-config.yaml

configuração do collector

elven-otel-operator/opentelemetry-operator.yaml

manifesto do Operator

elven-otel-operator/instrumentation.yaml

perfil global de instrumentação


Pré-requisitos

Você vai precisar de:

  • cluster Kubernetes funcional

  • kubectl

  • helm

  • helmfile

  • acesso ao repositório stack-observability-k8s

  • credenciais da Elven:

    • tenantId

    • apiToken

Também é importante saber:

  • quais namespaces do cluster devem ser instrumentados

  • quais workloads vão usar auto-instrumentação

  • se alguma aplicação já usa outro agente APM ou SDK legado

Se uma aplicação já tiver agente legado ativo, não habilite a auto-instrumentação da Elven em paralelo sem validar antes. Dupla instrumentação costuma gerar conflito, overhead e comportamento imprevisível.


Antes de começar: tenant e token

Para obter o tenantId e o apiToken, acesse:

Esse é o único ponto externo que o cliente precisa consultar antes do primeiro deploy da stack.

Essas credenciais alimentam automaticamente:

  • Prometheus remoteWrite

  • elven-otel-collector

  • Grafana Alloy

  • collector-fe

Ou seja: o cliente cria uma secret central e a stack reaproveita isso em todos os componentes.


Quick start

Se você quer o caminho mais rápido:

Depois valide:


Instalação passo a passo

1. Clonar o template

HTTPS:

SSH:

2. Criar o namespace monitoring

3. Criar a secret central

Busque o tenantId e o apiToken em monitoring.elven.works/setup e crie a secret:

4. Revisar opcionais antes do primeiro deploy

Na maioria dos ambientes, o cliente não precisa editar nada antes do primeiro helmfile apply.

Os pontos mais comuns de revisão são:

  • elven-prometheus/values-prometheus.yaml

  • elven-logs-collector/values-alloy.yaml

  • elven-collector-fe/values.yaml

  • elven-collector-fe/collector-fe-env-secret.yaml

  • elven-ebpf/values.yaml

5. Subir a stack

O que esse comando faz no template atual:

  1. instala ou atualiza os releases Helm

  2. renderiza o tenantId do Prometheus direto da secret central

  3. aplica o ClusterIssuer

  4. aplica a kustomization.yaml da raiz

  5. sobe ou atualiza o elven-otel-collector

  6. sobe ou atualiza o elven-instrumentation-operator

  7. espera a CRD instrumentations.opentelemetry.io

  8. aplica o Instrumentation automaticamente nos namespaces elegíveis

  9. reinicia os componentes locais que dependem de secret/config para garantir convergência

Você não precisa aplicar o Instrumentation manualmente no fluxo padrão. O helmfile apply já faz isso na ordem correta.

6. Restringir namespaces, se necessário

Por padrão, a stack cria o objeto Instrumentation em todos os namespaces elegíveis, ignorando namespaces operacionais.

Se você quiser limitar explicitamente:


O que pode ser customizado

Prometheus

Arquivo:

  • elven-prometheus/values-prometheus.yaml

Uso:

  • ajuste fino de scrape de infra

  • retenção

  • política de remote write

  • filtros de cardinalidade de métricas de infraestrutura

Importante:

  • o tenantId do remoteWrite é resolvido automaticamente a partir da secret central

  • não é mais necessário editar X-Scope-OrgID manualmente no values

Logs com Alloy

Arquivo:

  • elven-logs-collector/values-alloy.yaml

Uso:

  • pipelines de logs

  • labels extras

  • comportamento de parsing

collector-fe

Arquivos:

  • elven-collector-fe/values.yaml

  • elven-collector-fe/collector-fe-env-secret.yaml

Uso:

  • customizar SECRET_KEY

  • customizar LOKI_URL

  • customizar ALLOW_ORIGINS

  • customizar JWT_ISSUER

Se o cliente não usa telemetria frontend agora, normalmente dá para deixar esse release como está e tratar depois.

Beyla

Arquivo:

  • elven-ebpf/values.yaml

Status:

  • opcional

  • desligado por padrão no helmfile.yaml

Só habilite se o cliente realmente precisar de observabilidade via eBPF.


Como a instrumentação funciona

Instalar a stack não injeta agentes em toda aplicação automaticamente. O helmfile apply cria o Instrumentation em cada namespace elegível, mas a injeção continua sendo opt-in por annotation.

Você pode anotar:

  • o namespace

  • ou o workload (Deployment, StatefulSet, DaemonSet, Job)

Exemplo por namespace

Node.js

Python

Java

Exemplo por workload

Annotations suportadas

Runtime
Annotation

Java

instrumentation.opentelemetry.io/inject-java

Node.js

instrumentation.opentelemetry.io/inject-nodejs

Python

instrumentation.opentelemetry.io/inject-python

.NET

instrumentation.opentelemetry.io/inject-dotnet

Go

instrumentation.opentelemetry.io/inject-go

Apache HTTPD

instrumentation.opentelemetry.io/inject-apache-httpd

Nginx

instrumentation.opentelemetry.io/inject-nginx

SDK only

instrumentation.opentelemetry.io/inject-sdk

Casos especiais

Go

Para Go auto-instrumentado, o binário-alvo precisa ser informado por workload:

Python em musl

.NET em musl

Ruby e Rust

Para Ruby e Rust, use inject-sdk quando a aplicação já tiver SDK OTel embutido:


Métricas Prometheus de aplicação

Além de OTLP, o collector também pode fazer scrape genérico de apps anotadas com prometheus.io/*.

Use estas annotations quando a aplicação expõe endpoint Prometheus:

Esse scrape genérico continua no collector. O baseline não inclui scrapes específicos de cliente.


Logs das aplicações

Logs seguem o caminho:

Na prática:

  • se a aplicação escreve logs em stdout ou stderr, o Alloy já coleta

  • você não precisa configurar pipeline de logs no OpenTelemetry Collector

  • o baseline atual usa Alloy, não Promtail

Para aplicações JSON estruturadas, o Loki continua recebendo a linha completa, sem truncar apenas em message.


Validação após a instalação

Comandos principais:

O que você deve esperar:

  • pods de monitoring em Running

  • elven-otel-collector saudável

  • elven-instrumentation-operator-controller-manager saudável

  • pelo menos um Instrumentation criado nos namespaces elegíveis

  • endpoint do Instrumentation apontando para http://elven-otel-collector.monitoring.svc.cluster.local:4318

Validação do Instrumentation:

Validação rápida do collector:

Validação de logs:


Atualização da stack

Quando houver atualização do template:

O fluxo padrão reaplica:

  • releases Helm

  • manifests locais

  • Instrumentation

Sem necessidade de reaplicar tudo manualmente por fora.


Remoção da stack

Para desmontar a stack:

Esse fluxo remove:

  • releases Helm da stack

  • ClusterIssuer

  • manifests locais do collector e do operator

  • Instrumentation aplicado pela stack

  • secret de config do collector

  • secret de env do collector-fe

Esse fluxo não remove:

  • namespace monitoring

  • secret central elven-observability-credentials

Isso é intencional, para não apagar recursos adicionais do cliente por acidente.


Troubleshooting

helmfile apply falhou porque não encontrou tenantId ou apiToken

Confira se a secret existe:

O Operator subiu, mas a aplicação não foi instrumentada

Confira:

  1. se existe Instrumentation no namespace

  2. se o namespace ou workload recebeu a annotation correta

  3. se a aplicação não já usa outro agente legado em paralelo

O namespace não recebeu Instrumentation

Se você usou INSTRUMENTATION_TARGET_NAMESPACES, confira se o namespace está na lista.

A aplicação não envia métricas Prometheus para o collector

Confira as annotations:

A aplicação escreve logs em arquivo e não aparece no Loki

O baseline coleta stdout e stderr. Se a aplicação escreve apenas em arquivo local dentro do container, ajuste a estratégia de logging da app.


Checklist final


Veja também

Last updated

Was this helpful?