Index

Централизованная система сбора и хранения логов Kubernetes-кластера с использованием Loki и Fluent Bit.

Описание

Loki - система агрегации логов от Grafana, оптимизированная для хранения и запросов логов Kubernetes.

Fluent Bit - легковесный и производительный сборщик логов, работающий как DaemonSet на каждой ноде кластера.

Возможности

✅ Централизованный сбор логов (opt-in: только с подов с annotation logging: "true")
✅ Хранение логов в S3 (MinIO) с TSDB schema (v13)
✅ Автоматическая ротация и удаление старых логов (30 дней)
✅ Kubernetes metadata enrichment (namespace, pod, container, node)
✅ Низкая кардинальность labels для эффективных запросов
✅ Поддержка multiline логов (Java, Python, Go stacktraces)
✅ Compactor для очистки и оптимизации хранилища
✅ Single Binary режим Loki (простота развертывания)

Текущая конфигурация

Namespace: tech-logging
Loki mode: Single Binary (все компоненты в одном процессе)
Storage: MinIO S3 (s3-public tenant)
Schema: TSDB v13
Retention: 30 дней
Fluent Bit: DaemonSet на всех нодах (включая master)
Placement: Может размещаться на любых нодах (masters + workers)

Архитектура

┌─────────────────────────────────────────────────────────────┐
│  Kubernetes Cluster                                         │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Node 1                                             │   │
│  │  ├── Pod 1 → /var/log/containers/*.log              │   │
│  │  ├── Pod 2 → /var/log/containers/*.log              │   │
│  │  └── Fluent Bit DaemonSet ──────────────┐           │   │
│  └─────────────────────────────────────────│───────────┘   │
│                                             │               │
│  ┌─────────────────────────────────────────│───────────┐   │
│  │  Node 2                                 │           │   │
│  │  ├── Pod 3 → /var/log/containers/*.log  │           │   │
│  │  └── Fluent Bit DaemonSet ──────────────┤           │   │
│  └─────────────────────────────────────────│───────────┘   │
│                                             │               │
│  ┌─────────────────────────────────────────▼───────────┐   │
│  │  tech-logging namespace                             │   │
│  │                                                      │   │
│  │  ┌────────────────────────────────────────────┐     │   │
│  │  │  Loki (Single Binary)                      │     │   │
│  │  │  ├── Ingester                              │     │   │
│  │  │  ├── Querier                               │     │   │
│  │  │  ├── Query Frontend                        │     │   │
│  │  │  ├── Compactor (retention & cleanup)       │     │   │
│  │  │  └── Distributor                           │     │   │
│  │  └────────────────┬───────────────────────────┘     │   │
│  │                   │                                  │   │
│  │  ┌────────────────▼───────────────────────────┐     │   │
│  │  │  Loki Gateway (nginx)                      │     │   │
│  │  │  └── Service: loki-gateway (ClusterIP)      │     │   │
│  │  └────────────────────────────────────────────┘     │   │
│  └──────────────────────────────────────────────────────┘   │
│                      │                                      │
│                      ▼                                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  tech-minio-tenants namespace                        │  │
│  │  MinIO S3 (s3-public tenant)                         │  │
│  │  ├── Bucket: loki-chunks (95 GB quota, log data)     │  │
│  │  ├── Bucket: loki-ruler (4 GB quota, alerting rules)│  │
│  │  └── Bucket: loki-admin (1 GB quota, admin data)     │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Поток данных

Сбор логов: Fluent Bit читает логи из /var/log/containers/*.log на каждой ноде
Обогащение: Fluent Bit добавляет Kubernetes metadata (namespace, pod, container, node)
Фильтрация: Удаляются high-cardinality поля (pod_id, container_id, etc.)
Отправка: Логи отправляются в Loki через HTTP API
Индексация: Loki индексирует логи по labels с низкой кардинальностью
Хранение: Chunks и индексы сохраняются в MinIO S3
Compaction: Compactor периодически оптимизирует и удаляет старые данные
Запросы: LogQL запросы через Loki Gateway

Быстрый старт

Предварительные требования

Longhorn (для persistent storage)
MinIO S3 (для хранения логов)
Подготовленные ноды (labels и taints)

1. Подготовка инфраструктуры

# Установка Longhorn (если еще не установлен)
cd infra/k8s
make longhorn-install-all

# Установка MinIO (если еще не установлен)
make minio-install-all

# Подготовка нод
cd ../.. && make k8s-prepare-nodes

2. Создание S3 buckets

Создайте три bucket в MinIO для Loki:

Через MinIO Console (рекомендуется)

cd infra/k8s
make logging-create-buckets

Команда выведет пошаговую инструкцию. Или выполните вручную:

Откройте MinIO Console: https://s3.internal.ai-ops.tech
Войдите с MinIO credentials
Перейдите в раздел "Buckets"
Создайте три bucket:
loki-chunks
loki-ruler
loki-admin

Настройка квот (рекомендуется)

После создания buckets установите квоты для контроля использования хранилища:

Общий объем: 100 GB для всех buckets

loki-chunks: 95 GB
Основной storage для log chunks (сжатые данные)
Занимает ~95% от общего объема
loki-ruler: 4 GB
Alerting rules (небольшие файлы)
Защита от случайного роста
loki-admin: 1 GB
Admin data (минимальный объем)
Защита от случайного роста

Как установить квоту в MinIO Console:

Выберите bucket (например, loki-chunks)
Перейдите на вкладку "Summary"
Нажмите "Set Quota"
Выберите тип "Size"
Введите значение (например, 95GB для loki-chunks)
Нажмите "Set"
Повторите для остальных buckets

3. Создание S3 credentials secret

cd infra/k8s
make logging-create-s3-secret

Введите MinIO Access Key ID и Secret Access Key когда будет запрошено.

Или создайте секрет вручную:

kubectl -n tech-logging create secret generic loki-s3-secret \
  --from-literal=accessKeyId=YOUR_ACCESS_KEY \
  --from-literal=secretAccessKey=YOUR_SECRET_KEY

4. Установка Loki

1	`make logging-install-loki`

Это установит: - Namespace tech-logging - LimitRange и ResourceQuota - NetworkPolicy - StorageClass longhorn-logging - Loki Single Binary через Helm - Loki Gateway (nginx)

5. Установка Fluent Bit

1	`make logging-install-fluent`

Это установит Fluent Bit DaemonSet на всех нодах кластера.

6. Проверка статуса

1	`make logging-status`

Ожидаемый результат: - Loki pod в состоянии Running - Fluent Bit pods на каждой ноде в состоянии Running - PVC для Loki в состоянии Bound

7. Тестирование

# Проверка API
make logging-test-query

# Просмотр логов Loki
make logging-logs-loki

# Просмотр логов Fluent Bit
make logging-logs-fluent

8. Проверка сбора логов и записи в S3

Для полной проверки работы системы логирования используйте команду:

1	`make logging-verify-collection`

Эта команда выполнит комплексную проверку:

Статус компонентов - проверит, что Fluent Bit и Loki работают
Метрики Fluent Bit - покажет, сколько логов собрано (fluentbit_input_bytes_total, fluentbit_output_proc_records_total)
Метрики Loki - покажет, сколько логов получено (loki_distributor_lines_received_total, loki_ingester_chunks_created_total)
Метрики S3 storage - покажет операции записи в S3 (loki_compactor_compaction_operations_total)
Тестовый запрос - проверит доступность логов через Loki API
Инструкции по проверке S3 - как проверить buckets в MinIO

Ручная проверка S3 buckets:

Откройте MinIO Console:
1
make minio-console
Перейдите в раздел "Buckets" → выберите loki-chunks
Проверьте наличие файлов:
Должны быть папки с датами (например, index/2025/12/22/)
Внутри должны быть файлы chunks (.gz файлы)
Файлы должны появляться по мере сбора логов
Проверьте размер bucket:
Размер должен расти по мере сбора логов
Не должен превышать квоту (95 GB для loki-chunks)

Что означают метрики:

fluentbit_input_bytes_total > 0 - логи собираются с нод
loki_distributor_lines_received_total > 0 - логи попадают в Loki
loki_ingester_chunks_created_total > 0 - Loki создает chunks
loki_compactor_compaction_operations_total > 0 - chunks записываются в S3 (может быть 0 сразу после установки, compactor работает периодически)

Если логи не собираются:

Проверьте, что у подов есть annotation logging: "true":

kubectl get pods --all-namespaces -o jsonpath='{range .items[*]}{.metadata.namespace}{"\t"}{.metadata.name}{"\t"}{.metadata.annotations.logging}{"\n"}{end}' | grep -v "^$"

Проверьте логи Fluent Bit:
1
make logging-logs-fluent
Проверьте логи Loki:
1
make logging-logs-loki

Команды

Установка и обновление

make logging-install-all      # Установка полного стека (Loki + Fluent Bit)
make logging-install-loki     # Установка только Loki
make logging-install-fluent   # Установка только Fluent Bit
make logging-update-loki      # Обновление конфигурации Loki
make logging-update-fluent    # Обновление конфигурации Fluent Bit

Управление секретами и buckets

make logging-create-s3-secret  # Создание S3 credentials secret
make logging-create-buckets    # Создание S3 buckets в MinIO

Мониторинг и отладка

make logging-status           # Статус всего стека
make logging-verify-collection # Проверка сбора логов и записи в S3
make logging-logs-loki        # Логи Loki
make logging-logs-fluent      # Логи Fluent Bit
make logging-port-forward     # Port-forward Loki (localhost:3100)
make logging-test-query       # Тест Loki API

Удаление

make logging-uninstall        # Удаление стека (УДАЛЯЕТ ДАННЫЕ!)

Справка

make logging-help             # Справка по командам

Конфигурация

Loki

Конфигурация в charts/loki/values.yaml:

Storage (S3 + TSDB) - Schema: TSDB v13 (оптимизирован для Kubernetes) - Object Store: MinIO S3 (s3-public-hl.tech-minio-tenants.svc.cluster.local:9000) - Buckets: loki-chunks, loki-ruler, loki-admin - Credentials: Secret loki-s3-secret - Recommended Quotas (total 100 GB): - loki-chunks: 95 GB (main log storage) - loki-ruler: 4 GB (alerting rules) - loki-admin: 1 GB (admin data)

Retention - Period: 720 часов (30 дней) - Compaction: Каждые 10 минут - Delete delay: 2 часа после пометки на удаление

Limits - Ingestion rate: 50 MB/s - Ingestion burst: 100 MB - Max streams: 10000 глобально - Max query series: 10000 - Query parallelism: 32

Resources - Requests: 500m CPU, 1Gi RAM - Limits: 2000m CPU, 4Gi RAM - Storage: 18Gi (backend) + 10Gi (write) = 28Gi (Longhorn)

Fluent Bit

Конфигурация в charts/fluent-bit/values.yaml:

Input - Source: /var/log/containers/*.log - Parser: docker, cri (multiline support) - Buffer: 5MB per file - Storage: Filesystem buffering для надежности

Filters - Kubernetes metadata: Автоматическое обогащение - Opt-in collection: Собираются логи только с подов, у которых есть annotation logging: "true" - Label extraction: Только low-cardinality labels - Kept labels: namespace, pod, container, node - Removed fields: pod_id, container_id, docker_id, container_hash

Output - Target: loki-gateway.tech-logging.svc.cluster.local:80 - Format: JSON - Labels: job=fluentbit, + Kubernetes labels - Retry: 3 attempts - Buffer limit: 10MB

Multiline Parsers - Java: Stacktraces с at, Caused by - Python: Stacktraces с Traceback, File, Error - Go: Panic messages с goroutine, created by

Resources - Requests: 100m CPU, 128Mi RAM - Limits: 500m CPU, 512Mi RAM

Использование

Включение сбора логов для подов (Opt-in)

По умолчанию логи не собираются. Для включения сбора логов добавьте annotation на под:

Через Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    metadata:
      annotations:
        logging: "true"  # Включить сбор логов
    spec:
      containers:
      - name: app
        image: my-app:latest

Через Pod:

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  annotations:
    logging: "true"  # Включить сбор логов
spec:
  containers:
  - name: app
    image: my-app:latest

Через kubectl:

kubectl annotate pod <pod-name> logging="true"
kubectl annotate deployment <deployment-name> logging="true"

Примечание: После добавления annotation поды автоматически начнут логироваться. Fluent Bit проверяет annotation каждые 10 секунд (Refresh_Interval).

Доступ к Loki

Через port-forward

make logging-port-forward
# Доступ: http://localhost:3100

Изнутри кластера (для Grafana и других сервисов)

1	`http://loki-gateway.tech-logging.svc.cluster.local`

LogQL запросы

Базовые запросы

# Все логи из namespace
{namespace="kube-system"}

# Логи конкретного пода
{namespace="tech-logging", pod="loki-0"}

# Логи конкретного контейнера
{namespace="tech-logging", container="loki"}

# Логи с конкретной ноды
{node="k8s-master-1"}

Фильтрация по содержимому

# Поиск по тексту
{namespace="kube-system"} |= "error"

# Регулярное выражение
{namespace="kube-system"} |~ "error|failed|exception"

# Исключение
{namespace="kube-system"} != "debug"

Агрегация

# Количество логов по namespace
sum(count_over_time({namespace="kube-system"}[5m])) by (namespace)

# Rate логов
rate({namespace="kube-system"}[5m])

# Топ подов по количеству логов
topk(10, sum(count_over_time({namespace="kube-system"}[1h])) by (pod))

Multiline логи

# Java stacktraces (автоматически объединяются Fluent Bit)
{namespace="default", container="java-app"} |= "Exception"

# Python stacktraces
{namespace="default", container="python-app"} |= "Traceback"

Примеры использования

1. Поиск ошибок в конкретном namespace

curl -G -s "http://localhost:3100/loki/api/v1/query_range" \
  --data-urlencode 'query={namespace="kube-system"} |= "error"' \
  --data-urlencode 'limit=100' | jq

2. Экспорт логов в файл

curl -G -s "http://localhost:3100/loki/api/v1/query_range" \
  --data-urlencode 'query={namespace="tech-logging"}' \
  --data-urlencode 'start=2024-01-01T00:00:00Z' \
  --data-urlencode 'end=2024-01-01T23:59:59Z' \
  --data-urlencode 'limit=5000' | jq -r '.data.result[].values[][1]' > logs.txt

3. Мониторинг в реальном времени

# Через kubectl (логи Fluent Bit)
kubectl -n tech-logging logs -l app=fluent-bit -f

# Через Loki API (tail)
curl -G -s "http://localhost:3100/loki/api/v1/tail" \
  --data-urlencode 'query={namespace="kube-system"}' \
  --data-urlencode 'limit=10'

Troubleshooting

Loki не запускается

Проблема: Pod в состоянии CrashLoopBackOff

Решение:

# Проверка логов
make logging-logs-loki

# Частые причины:
# 1. Отсутствует S3 secret
kubectl -n tech-logging get secret loki-s3-secret

# 2. Неверные S3 credentials
kubectl -n tech-logging describe secret loki-s3-secret

# 3. Недоступен MinIO
kubectl -n tech-minio-tenants get pods

# 4. Не созданы buckets
# Создайте через: make logging-create-buckets

Fluent Bit не отправляет логи

Проблема: Логи не появляются в Loki

Решение:

# Проверка статуса Fluent Bit
kubectl -n tech-logging get pods -l app=fluent-bit

# Проверка логов Fluent Bit
make logging-logs-fluent

# Частые причины:
# 1. Отсутствует annotation logging="true" на подах
#    Проверьте annotation:
kubectl get pods -A -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.logging}{"\n"}{end}'

#    Добавьте annotation если отсутствует:
kubectl annotate pod <pod-name> logging="true"
kubectl annotate deployment <deployment-name> logging="true"

# 2. Loki недоступен
kubectl -n tech-logging get svc loki-gateway

# 3. Network Policy блокирует трафик
kubectl -n tech-logging get networkpolicy

# 4. Проблемы с парсингом логов
# Проверьте логи Fluent Bit на ошибки парсинга

Высокая кардинальность labels

Проблема: Loki медленно работает или падает с ошибкой "too many streams"

Решение:

# Проверка количества streams
curl -s "http://localhost:3100/loki/api/v1/label" | jq

# Проверка кардинальности конкретного label
curl -s "http://localhost:3100/loki/api/v1/label/pod/values" | jq

# Если кардинальность высокая:
# 1. Не используйте в labels: pod_id, container_id, request_id, trace_id, user_id
# 2. Используйте только: namespace, pod, container, node, job
# 3. Динамические значения ищите в содержимом логов, а не в labels

Проблемы с S3 storage

Проблема: Ошибки записи в S3

Решение:

# Проверка доступности MinIO
kubectl -n tech-minio-tenants get pods

# Проверка buckets
mc ls s3-public | grep loki

# Проверка credentials
kubectl -n tech-logging get secret loki-s3-secret -o yaml

# Тест подключения из Loki pod
kubectl -n tech-logging exec -it deployment/loki -- sh
# В pod:
wget -O- http://s3-public-hl.tech-minio-tenants.svc.cluster.local:9000

Логи не удаляются (retention не работает)

Проблема: Старые логи не удаляются после 30 дней

Решение:

# Проверка конфигурации compactor
kubectl -n tech-logging get deployment loki -o yaml | grep -A 10 compactor

# Проверка логов compactor
kubectl -n tech-logging logs deployment/loki | grep compactor

# Убедитесь что:
# 1. retention_enabled: true
# 2. compaction_interval: 10m
# 3. retention_period: 720h (30 дней)

Multiline логи разбиваются на отдельные строки

Проблема: Java/Python stacktraces разбиваются на несколько записей

Решение:

Fluent Bit уже настроен с multiline парсерами для Java, Python и Go.

Проверьте конфигурацию:

kubectl -n tech-logging get configmap fluent-bit -o yaml | grep -A 20 MULTILINE_PARSER

Если проблема сохраняется, добавьте кастомный парсер в charts/fluent-bit/values.yaml:

customParsers: |
  [MULTILINE_PARSER]
      name          your-custom-parser
      type          regex
      flush_timeout 1000
      rule      "start_state"   "/^your-pattern/"  "cont"
      rule      "cont"           "/^your-continuation/"  "cont"

Best Practices

Opt-in подход

Система использует opt-in подход: логи собираются только с подов, у которых явно указана annotation logging: "true".

Преимущества: - ✅ Безопасность: не собираем лишние логи - ✅ Экономия ресурсов: меньше логов → меньше CPU/памяти/хранилища - ✅ Контроль: явно видно, что логируется - ✅ Низкая кардинальность: меньше streams в Loki

Рекомендации: - Добавляйте annotation на все важные production сервисы - Используйте для всех пользовательских приложений - Не добавляйте для системных подов (kube-system, etc.) - они обычно не нужны - Можно добавить через Helm values или Kustomize patches

Пример для Helm:

# values.yaml
podAnnotations:
  logging: "true"

Пример для Kustomize:

# kustomization.yaml
patches:
  - patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: my-app
      spec:
        template:
          metadata:
            annotations:
              logging: "true"
    target:
      kind: Deployment
      name: my-app

Labels

✅ DO: Используйте low-cardinality labels

1	`{namespace="production", container="api", node="worker-1"}`

❌ DON'T: Не используйте high-cardinality labels

# ПЛОХО: pod_id меняется при каждом рестарте
{pod_id="abc123"}

# ПЛОХО: request_id уникален для каждого запроса
{request_id="req-xyz"}

# ПЛОХО: user_id создает миллионы streams
{user_id="12345"}

Правило: Если значение label может иметь > 1000 уникальных значений, не используйте его как label.

Запросы

✅ DO: Фильтруйте по labels сначала

1	`{namespace="production"} \|= "error"`

❌ DON'T: Не сканируйте все логи

1	`{} \|= "error" # Очень медленно!`

✅ DO: Используйте разумные временные диапазоны

1	`{namespace="production"}[5m] # Последние 5 минут`

❌ DON'T: Не запрашивайте слишком большие диапазоны

1	`{namespace="production"}[30d] # Очень медленно!`

Хранение

✅ DO: Установите квоты на S3 buckets

Рекомендуемые квоты (общий объем 100 GB): - loki-chunks: 95 GB (основной storage для логов) - loki-ruler: 4 GB (alerting rules) - loki-admin: 1 GB (admin data)

Как установить квоту в MinIO Console: 1. Выберите bucket → "Summary" → "Set Quota" 2. Выберите тип "Size" 3. Введите значение (например, 95GB) 4. Нажмите "Set"

✅ DO: Регулярно проверяйте размер S3 buckets

# Через MinIO Console: Buckets → Select bucket → Summary
# Или через mc CLI (если доступен):
mc du s3-public/loki-chunks
mc du s3-public/loki-ruler
mc du s3-public/loki-admin

✅ DO: Мониторьте использование PVC

kubectl -n tech-logging get pvc
kubectl -n tech-logging exec deployment/loki -- df -h /var/loki

✅ DO: Настройте retention в соответствии с требованиями

Текущий retention: 30 дней. Для изменения отредактируйте charts/loki/values.yaml:

limits_config:
  retention_period: 720h  # 30 дней (измените при необходимости)

Примечание: При достижении квоты bucket Loki не сможет писать новые логи. Убедитесь, что retention настроен правильно для автоматической очистки старых данных.

Производительность

✅ DO: Используйте агрегацию для больших запросов

1	`sum(count_over_time({namespace="production"}[5m])) by (container)`

✅ DO: Используйте limit для ограничения результатов

1	`{namespace="production"} \| limit 1000`

✅ DO: Используйте кеширование результатов

Loki автоматически кеширует результаты запросов (настроено в query_range.cache_results).

Интеграция с Grafana

После установки Grafana, добавьте Loki как datasource:

URL: http://loki-gateway.tech-logging.svc.cluster.local
Type: Loki
Access: Server (default)

Или через provisioning:

apiVersion: 1
datasources:
  - name: Loki
    type: loki
    access: proxy
    url: http://loki-gateway.tech-logging.svc.cluster.local
    jsonData:
      maxLines: 1000

Примечание: Доступ к Loki возможен только изнутри кластера. Для внешнего доступа используйте Grafana UI или port-forward.

Дополнительные ресурсы

← Назад к главной документации

На странице

Оглавление Описание Возможности Текущая конфигурация Архитектура Поток данных Быстрый старт Предварительные требования 1. Подготовка инфраструктуры 2. Создание S3 buckets 3. Создание S3 credentials secret 4. Установка Loki 5. Установка Fluent Bit 6. Проверка статуса 7. Тестирование 8. Проверка сбора логов и записи в S3 Команды Установка и обновление Управление секретами и buckets Мониторинг и отладка Удаление Справка Конфигурация Loki Fluent Bit Использование Включение сбора логов для подов (Opt-in) Доступ к Loki LogQL запросы Примеры использования Troubleshooting Loki не запускается Fluent Bit не отправляет логи Высокая кардинальность labels Проблемы с S3 storage Логи не удаляются (retention не работает) Multiline логи разбиваются на отдельные строки Best Practices Opt-in подход Labels Запросы Хранение Производительность Интеграция с Grafana Дополнительные ресурсы