# 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](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 git@github.com: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](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](https://opentelemetry.io/docs/)
* [Prometheus](https://prometheus.io/docs/introduction/overview/)
* [Loki](https://grafana.com/docs/loki/)
* [Grafana](https://grafana.com/docs/grafana/latest/)

## 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.