Prometheus мониторинг для iobackup

Этот документ описывает, как подключить iobackup-agent к Prometheus, какие метрики доступны и как построить базовые алерты/дашборды.

1) Endpoint метрик

Агент экспортирует метрики на:

• GET /metrics

Пример проверки:

curl -sS http://127.0.0.1:8735/metrics

В ответе есть:

• runtime метрики Go (go_*);
• process метрики (process_*);
• бизнес-метрики iobackup_*.

2) Подключение Prometheus

Пример prometheus.yml:

scrape_configs:
  - job_name: iobackup-agent
    metrics_path: /metrics
    scrape_interval: 15s
    scrape_timeout: 10s
    static_configs:
      - targets:
          - 127.0.0.1:8735
        labels:
          service: iobackup
          env: dev

Если агент доступен не локально, замените target на адрес узла с агентом.

3) Модель метрик

Cardinality policy (0.17-fix.50)

Allowed labels (expected low-cardinality / safe):

• agent_id
• job_id
• task_id
• provider_type
• provider_kind
• status
• error_code
• stage

Forbidden / high-risk labels (do not add; may explode cardinality or leak sensitive info):

• run_id
• task_run_id
• artifact_id
• backup_id
• request_id
• correlation_id
• error_message
• object_key
• path
• webhook_url
• vault_path

Note: current metrics include job_id, task_id and webhook (webhook name) labels. Это допустимо только если имена webhook и job/task конфигов ограничены конфигом (не генерируются динамически на каждый run). Если потребуется более строгая политика — пересмотрим label set в 0.17-fix.60+.

3.1 API метрики

• iobackup_api_requests_total{method,route,status}
  • сколько HTTP-запросов обработано;
  • status — HTTP код ответа.
• iobackup_api_request_duration_seconds{method,route,status}
  • latency API;
  • тип: histogram (есть _bucket, _sum, _count).
• iobackup_api_inflight_requests{method,route}
  • текущие in-flight запросы.

3.2 Job / Run / Task lifecycle

• iobackup_jobs_submitted_total{status}
  • submit job: status=success|error.
• iobackup_jobs_stored_total
  • текущее число job в storage.
• iobackup_runs_started_total{job_id}
  • число стартов run.
• iobackup_runs_finished_total{job_id,status}
  • число завершенных run по итоговому статусу.
• iobackup_run_duration_seconds{job_id,status}
  • длительность run (histogram).
• iobackup_runs_in_progress
  • текущие run в статусе running.
• iobackup_run_task_count{job_id}
  • распределение количества tasks на run.
• iobackup_last_run_finished_timestamp_seconds{job_id}
• iobackup_last_run_success_timestamp_seconds{job_id}
• iobackup_last_run_failed_timestamp_seconds{job_id}
• iobackup_run_status_transitions_total{status}

Task-уровень:

• iobackup_tasks_started_total{job_id,task_id,source_type,destination_type}
• iobackup_tasks_finished_total{job_id,task_id,source_type,destination_type,status}
• iobackup_task_duration_seconds{job_id,task_id,source_type,destination_type,status}
• iobackup_tasks_in_progress{source_type,destination_type}

3.3 Provider operations

• iobackup_provider_operations_total{kind,provider,operation,status}
• iobackup_provider_operation_duration_seconds{kind,provider,operation,status}

Где:

• kind: source|destination|policy|notification;
• provider: например filesystem, s3, ssh, postgres, mysql, webhook;
• operation: например backup, put, get, put_manifest, apply, send.

3.4 Backup data и artifacts

• iobackup_backup_bytes_total{source_type,destination_type}
  • суммарный объем успешно сохраненных backup-данных.
• iobackup_artifacts_created_total{destination_type}
• iobackup_artifact_downloads_total{destination_type,status}
• iobackup_artifact_deletes_total{status}
• iobackup_retention_cleanup_total{status,destination_type}
  • действия retention cleanup (deleted, artifact_delete_failed, manifest_delete_failed).
• iobackup_verifications_total{destination_type,status}
  • количество verify-попыток (success|failed|error) по destination.
• iobackup_verification_duration_seconds{destination_type,status}
  • длительность verify (histogram).
• iobackup_verify_after_run_total{status}
  • статусы авто verify-after-run (started|error|skipped_disabled|skipped_no_success_tasks).

3.5 Webhook notifications

• iobackup_notifications_total{scope,event,webhook,status}
  • delivery-события webhook.
• iobackup_notification_attempts{scope,event,webhook,status}
  • число попыток отправки (histogram), полезно для контроля retry.

3.6 Runtime/build

• iobackup_build_info{version,agent_id,hostname}=1
• go_*, process_* — стандартные технические метрики процесса.

4) Примеры PromQL

4.1 Ошибки run/task

Run failed за 15 минут:

sum(increase(iobackup_runs_finished_total{status="failed"}[15m]))

Task failed по destination за 15 минут:

sum by (destination_type) (
  increase(iobackup_tasks_finished_total{status="failed"}[15m])
)

4.2 Успешность и SLI

Run success ratio за 1 час:

sum(increase(iobackup_runs_finished_total{status="success"}[1h]))
/
sum(increase(iobackup_runs_finished_total[1h]))

Webhook success ratio за 30 минут:

sum(increase(iobackup_notifications_total{status="success"}[30m]))
/
sum(increase(iobackup_notifications_total[30m]))

4.3 Длительность

P95 API latency (в секундах):

histogram_quantile(
  0.95,
  sum by (le, route, method) (
    rate(iobackup_api_request_duration_seconds_bucket[5m])
  )
)

P95 task duration по source/destination:

histogram_quantile(
  0.95,
  sum by (le, source_type, destination_type) (
    rate(iobackup_task_duration_seconds_bucket[15m])
  )
)

4.4 Throughput / объемы

Скорость записи backup-данных (bytes/sec) по destination:

sum by (destination_type) (
  rate(iobackup_backup_bytes_total[5m])
)

5) Пример alert rules

Файл iobackup-alerts.yml:

groups:
  - name: iobackup.rules
    rules:
      - alert: IobackupRunFailures
        expr: sum(increase(iobackup_runs_finished_total{status="failed"}[10m])) > 0
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Есть failed run в iobackup"
          description: "За последние 10m обнаружены неуспешные run."

      - alert: IobackupTaskFailuresHigh
        expr: sum(increase(iobackup_tasks_finished_total{status="failed"}[15m])) > 3
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Высокий уровень task failures"
          description: "Более 3 failed task за 15m."

      - alert: IobackupWebhookFailures
        expr: sum(increase(iobackup_notifications_total{status="failed"}[10m])) > 0
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "Webhook delivery errors"
          description: "Есть failed webhook notifications."

      - alert: IobackupAPILatencyP95High
        expr: |
          histogram_quantile(
            0.95,
            sum by (le) (rate(iobackup_api_request_duration_seconds_bucket[5m]))
          ) > 1
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Высокая latency API"
          description: "P95 API latency выше 1s в течение 10m."

6) Рекомендации по эксплуатации

• Используйте стабильные external labels (env, cluster, service) в Prometheus.
• Для cardinality-контроля:
  • избегайте избыточно динамических job_id/task_id naming-pattern;
  • не включайте user-generated значения в path API.
• Для продакшн-алертов начинайте с warning-порогов и калибруйте под вашу нагрузку 1-2 недели.
• Если метрик слишком много для удаленного хранилища, делайте relabel/drop для неиспользуемых series.

7) Быстрый чек-лист внедрения

1. Проверить curl http://<agent>/metrics.
2. Добавить scrape_config в Prometheus.
3. Проверить target в /targets Prometheus UI.
4. Убедиться, что появляются iobackup_runs_finished_total и iobackup_tasks_finished_total.
5. Подключить alert rules и протестировать тестовым failed run.