Guia Completo de Instrumentação e Monitoramento no Kubernetes

Por /

Este guia foi criado para ajudá-lo a configurar facilmente uma stack de monitoramento e instrumentação utilizando ferramentas modernas como Prometheus, Promtail e OpenTelemetry. 🚀

Você utilizará o Grafana da Elven Observability para visualizar suas métricas, logs e dashboards no seguinte endereço:

🌐 https://grafana.elvenobservability.com

🧰 Conteúdo do Repositório

stack-observability/
├── opentelemetry-operator/
│   ├── instrumentation.yaml
│   ├── values.yaml
│   ├── README.md
├── otel-collector/
│   ├── collector-config.yaml
│   ├── collector-deploy.yaml
│   ├── collector-service.yaml
│   ├── kustomization.yaml
│   ├── secrets.env
│   ├── README.md
├── prometheus/
│   ├── values-prometheus.yaml
├── promtail/
│   ├── values-promtail.yaml
├── helmfile.yaml
└── README.md

⚙️ Pré-requisitos

Certifique-se de ter o seguinte configurado no seu ambiente:

  • Kubernetes: Cluster funcional e configurado 🛠️
  • kubectl: Para gerenciar recursos no Kubernetes ⚡
  • Helm: Para instalar os charts 🎛️
  • Helmfile: Para instalar múltiplos charts com facilidade

Instale o Helmfile:

curl -sL <https://github.com/helmfile/helmfile/releases/download/v1.0.0-rc.7/helmfile_1.0.0-rc.7_linux_amd64.tar.gz> | sudo tar -xz -C /usr/local/bin

🚀 Instalação: Passo a Passo

1️⃣ Clone o Repositório

Via SSH:

git clone git@github.com:elven-observability/stack-observability-k8s.git

Via HTTPS:

git clone <https://github.com/elven-observability/stack-observability-k8s.git>

2️⃣ Configurar Namespace e Credenciais

Crie o namespace de monitoramento:

kubectl create ns monitoring

Em seguida, configure uma Secret para armazenar as credenciais da Elven Observability. Essas credenciais podem ter sido fornecidas diretamente pelo nosso time, ou geradas automaticamente caso você tenha feito o cadastro pelo site: http://elvenobservability.com/. Caso ainda não tenha recebido, entre em contato com o suporte:

kubectl create secret generic elven-observability-credentials \
  -n monitoring \
  --from-literal=tenantId="<SEU_TENANT_ID>" \
  --from-literal=apiToken="<SEU_API_TOKEN>"

⚠️ Importante: Substitua <SEU_TENANT_ID> e <SEU_API_TOKEN> pelos valores corretos recebidos no onboarding ou via cadastro.

3️⃣ Configurar o Prometheus

Edite o arquivo prometheus/values-prometheus.yaml:

remoteWrite:
  - url: <https://mimir.elvenobservability.com/api/v1/push>
    authorization:
      type: Bearer
      credentials:
        key: apiToken
        name: elven-observability-credentials
    headers:
      X-Scope-OrgID: <SEU_TENANT_ID>
    relabelConfigs:
      - sourceLabels: [__name__]
        regex: "^(prometheus|go|promhttp|scrape).*"
        action: drop

4️⃣ Configuração do Promtail: Filtros por Namespace ou Annotation

No promtail/values-promtail.yaml, edite:

config:
  snippets:
    common:
      # Filtro por annotation
      # - action: keep
      #   source_labels: [__meta_kubernetes_pod_annotation_promtail_logs]
      #   regex: "true"

      # Filtro por namespace
      - action: keep
        source_labels: [__meta_kubernetes_namespace]
        regex: "^(default|monitoring|namespace1|namespace2)$"

Como Usar:

  • Por Namespace: coleta todos os logs dos pods nos namespaces definidos.
  • Por Annotation: coleta somente de pods com a annotation promtail_logs: "true":
metadata:
  annotations:
    promtail_logs: "true"

5️⃣ Configurar o OpenTelemetry Operator

Edite opentelemetry-operator/instrumentation.yaml:

apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: instrumentation
  namespace: default
spec:
  nodejs:
    env:
      - name: OTEL_NODE_DISABLED_INSTRUMENTATIONS
        value: fs
      - name: OTEL_NODE_RESOURCE_DETECTORS
        value: all
  exporter:
    endpoint: "<http://opentelemetrycollector.monitoring.svc.cluster.local:4318>"
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "1"

Aplique no cluster:

kubectl apply -f opentelemetry-operator/instrumentation.yaml

📚 Consulte o README.md da pasta opentelemetry-operator para mais exemplos de instrumentação.

6️⃣ Instalar os Componentes com Helmfile

helmfile sync

🌐 Acesso ao Grafana

Acesse: https://grafana.elvenobservability.com

Use as credenciais fornecidas via suporte ou após cadastro no site para visualizar dashboards de métricas, logs e traces.

📊 Recursos Instalados

  • Prometheus: Coleta de métricas e alertas
  • Promtail: Coleta de logs
  • OpenTelemetry Operator: Instrumentação automática
  • OpenTelemetry Collector: Centralização de métricas e traces

📚 Exemplos e Boas Práticas

  • Exemplos prontos na pasta opentelemetry-operator/
  • Sempre que possível, use annotation ao invés de capturar logs de todo o namespace
  • Ajuste o sampling de traces conforme a criticidade da aplicação
  • Organize os dashboards no Grafana por aplicação ou domínio de negócio

💡 Dicas e Otimizações

  • Use relabelConfigs para evitar ingestão excessiva de dados
  • Utilize atributos personalizados (resource_attributes) para enriquecer os dados dos traces e métricas
  • Explore dashboards públicos no Grafana para se inspirar
  • Adicione alertas com base em métricas críticas (ex: erro 5xx, alta latência, ausência de eventos)

🧯 Solução de Problemas (Troubleshooting)

ProblemaCausa ComumSolução
Dados não aparecem no GrafanaSecret mal configurada ou token inválidoVerifique a Secret e confirme as credenciais
Logs não chegam no LokiFiltros no Promtail ou falta de annotationRevise as regras de filtragem e annotations
Traces ausentesEndpoint do collector incorretoVerifique a URL no instrumentation.yaml

🔗 Documentações Oficiais

🛠️ Suporte

Se tiver dúvidas, dificuldades ou sugestões:

  • Abra uma issue neste repositório
  • Contribua com um Pull Request
  • Fale com o time Elven 🚀
Nesta página
Rolar para cima