Guia Completo de Instrumentação e Monitoramento no Kubernetes

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

Clone o Repositório

Via SSH:

git clone [email protected]:elven-observability/stack-observability-k8s.git

Via HTTPS:

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

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.

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

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"

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.

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)

Problema	Causa Comum	Solução
Dados não aparecem no Grafana.	Secret mal configurada ou token inválido.	Verifique a Secret e confirme as credenciais.
Logs não chegam no Loki.	Filtros no Promtail ou falta de annotation.	Revise as regras de filtragem e annotations.
Traces ausentes.	Endpoint do collector incorreto.	Verifique a URL no instrumentation.yaml

Documentações Oficiais

• OpenTelemetry

• Prometheus

• Loki

• Grafana

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.