K3S/docs/observability.md

# Observability

Стек мониторинга, логирования и трассировки: Prometheus + Grafana + Alertmanager, Loki, Promtail, Tempo, Pushgateway.

## Быстрый старт — полный observability стек

```yaml
# group_vars/all/addons.yml
addon_prometheus_stack: true   # Prometheus + Grafana + Alertmanager
addon_loki: true               # Агрегация логов
addon_promtail: true           # Агент сбора логов (DaemonSet)
addon_tempo: false             # Distributed tracing (опционально)
addon_pushgateway: false       # Batch метрики (опционально)
```

```bash
make addon-prometheus-stack
make addon-loki
make addon-promtail
```

---

## Prometheus + Grafana + Alertmanager

### Параметры

| Переменная | Умолч. | Описание |
|---|---|---|
| `prometheus_retention_days` | `7` | Срок хранения метрик |
| `prometheus_storage_size` | `10Gi` | PVC Prometheus |
| `grafana_storage_size` | `5Gi` | PVC Grafana |
| `prometheus_alertmanager_enabled` | `true` | Alertmanager |
| `prometheus_grafana_ingress_enabled` | `false` | Grafana через Ingress |
| `prometheus_grafana_ingress_host` | `grafana.local` | Hostname Grafana |

### Доступ к Grafana

По умолчанию — NodePort 32000:
```
http://192.168.1.10:32000
```

Через Ingress:
```yaml
prometheus_grafana_ingress_enabled: true
prometheus_grafana_ingress_host: "grafana.example.com"
prometheus_grafana_ingress_tls: true
```

### ServiceMonitor — добавить своё приложение

```yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: my-app
  namespace: my-app
  labels:
    release: prom    # совпадает с prometheus_stack_release_name
spec:
  selector:
    matchLabels:
      app: my-app
  endpoints:
    - port: metrics
      interval: 30s
      path: /metrics
```

### Grafana дашборд через ConfigMap

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: my-dashboard
  namespace: monitoring
  labels:
    grafana_dashboard: "1"
data:
  my-dashboard.json: |
    { "title": "My App", "panels": [...] }
```

### PrometheusRule — алерты

```yaml
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: my-app-alerts
  namespace: my-app
  labels:
    release: prom
spec:
  groups:
    - name: my-app
      rules:
        - alert: MyAppDown
          expr: up{job="my-app"} == 0
          for: 5m
          labels:
            severity: critical
          annotations:
            summary: "{{ $labels.instance }} is down"
```

### PromQL примеры

```promql
# CPU usage нод
100 - (avg by(node) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

# Memory usage
(1 - node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes) * 100

# HTTP error rate ingress
sum(rate(nginx_ingress_controller_requests{status=~"5.."}[5m])) by (ingress)

# Pod restarts за час
increase(kube_pod_container_status_restarts_total[1h]) > 0

# Свободное место на PVC
kubelet_volume_stats_available_bytes / kubelet_volume_stats_capacity_bytes * 100 < 20
```

### Автоматические ServiceMonitor

Все включённые аддоны автоматически создают ServiceMonitor при `addon_prometheus_stack: true`:
ingress-nginx, cert-manager, ArgoCD, Gitea, Harbor, Jenkins, PostgreSQL, MySQL, MinIO, Loki, Tempo, Pushgateway, Longhorn, Velero, CrowdSec, Vaultwarden и другие.

---

## Loki — логи

```yaml
addon_loki: true
addon_promtail: true

# Опционально — S3 backend (автоматически при addon_minio: true):
# addon_minio: true
```

### Параметры

| Переменная | Умолч. | Описание |
|---|---|---|
| `loki_storage_type` | авто | filesystem \| s3 |
| `loki_storage_size` | `10Gi` | PVC |
| `loki_retention_period` | `720h` | Срок хранения (30 дней) |

### LogQL запросы в Grafana

```logql
# Все логи из namespace
{namespace="my-app"}

# Фильтр по тексту
{namespace="ingress-nginx"} |= "error"

# Парсинг JSON логов
{namespace="my-app"} | json | level="error"

# Rate ошибок
rate({namespace="my-app"} |= "error" [5m])
```

---

## Tempo — distributed tracing

```yaml
addon_tempo: true
```

### Протоколы приёма трейсов

| Протокол | Адрес | Порт |
|---|---|---|
| OTLP gRPC | `tempo.tempo.svc.cluster.local` | 4317 |
| OTLP HTTP | `tempo.tempo.svc.cluster.local` | 4318 |
| Jaeger HTTP | `tempo.tempo.svc.cluster.local` | 14268 |
| Jaeger gRPC | `tempo.tempo.svc.cluster.local` | 14250 |

### Инструментирование через env vars (авто)

```yaml
env:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: "http://tempo.tempo.svc.cluster.local:4318"
  - name: OTEL_SERVICE_NAME
    value: "my-service"
  - name: OTEL_TRACES_SAMPLER_ARG
    value: "0.1"   # 10% трейсов
```

---

## Pushgateway — batch метрики

```yaml
addon_pushgateway: true
```

Endpoint: `http://prometheus-pushgateway.monitoring.svc.cluster.local:9091`

```bash
# Отправить метрику
cat <<EOF | curl --data-binary @- \
  http://prometheus-pushgateway.monitoring.svc.cluster.local:9091/metrics/job/my-job
job_last_success_timestamp $(date +%s)
EOF
```

---

## Grafana datasources

При полном стеке Grafana автоматически получает datasources:
- **Prometheus** — метрики
- **Loki** — логи (при `addon_loki: true`)
- **Tempo** — трейсы (при `addon_tempo: true`)

Корреляция: в Grafana → Explore → Loki → кликни на Trace ID → автоматически переходит в Tempo.