food-market/docs/observability.md

Observability (Prometheus / Grafana)

food-market.api экспортирует метрики Prometheus на /metrics (text exposition format, без авторизации). На prod закрываем nginx-уровнем (allow private network, deny all) или basic-auth.

Базовые метрики (от prometheus-net)

Метрика	Тип	Лейблы	Что показывает
http_requests_received_total	counter	code, method, controller, action	Сколько HTTP-запросов прошло — split per controller+action+status.
http_request_duration_seconds	histogram	code, method, controller, action	Длительность HTTP, гистограмма для p50/p95/p99 SLO.
process_cpu_seconds_total	counter	—	CPU time.
process_resident_memory_bytes	gauge	—	RSS.
dotnet_total_memory_bytes	gauge	—	Managed heap.
dotnet_collection_count_total	counter	generation	GC count по поколениям.

Кастомные метрики

Метрика	Тип	Лейблы	Семантика
food_market_documents_posted_total	counter	type	Проведено документов (retail-sale, supply, enter, loss, transfer, inventory, supplier-return, customer-return).
food_market_sales_posted_total	counter	—	Alias для documents_posted{type="retail-sale"} (явно перечислен в SLO).
food_market_supplies_posted_total	counter	—	Alias для documents_posted{type="supply"}.
food_market_documents_error_total	counter	type, reason	Ошибки проведения: reason serialization (40001), insufficient_stock, number_conflict, validation, other.
food_market_db_query_duration_seconds	histogram	kind	Длительность SQL-запросов EF Core. kind=query (SELECT), kind=command (INSERT/UPDATE/DELETE/SCALAR).

Tenant-меток в кастомных метриках НЕТ сознательно: на multi-tenant хосте они бы раздули cardinality. Per-org разрез — через /api/reports/* (там authz-фильтр уже работает).

Scrape-конфиг (prometheus.yml)

scrape_configs:
  - job_name: food-market-api
    metrics_path: /metrics
    scrape_interval: 15s
    static_configs:
      - targets: ['food-market-api:8080']

Готовый Grafana dashboard

В репо лежит JSON-дашборд, готовый к импорту: deploy/grafana/dashboards/food-market.json. Содержит 9 панелей:

1. HTTP — RPS по статус-коду (stacked).
2. HTTP — latency p50/p95/p99 (5-минутный rolling).
3. Бизнес — документы посчитаны (Post), per-type RPS.
4. Бизнес — ошибки проведения per-type/reason.
5. DB — длительность EF-запросов (heatmap).
6. HTTP — % 5xx за 5 мин (stat-панель с порогами).
7. HTTP — % 4xx за 5 мин.
8. Процесс — память (RSS + managed heap).
9. GC — сборки в секунду по поколениям.

Импорт в Grafana

Через UI:

1. Grafana → Dashboards → New → Import.
2. Upload JSON file → выбрать deploy/grafana/dashboards/food-market.json.
3. Datasource — выбрать Prometheus (по дефолту в шаблонной переменной ${DS_PROMETHEUS} написано «Prometheus»).
4. Import.

Через CLI (curl к Grafana API, требует Bearer-токен от service-account c ролью Editor):

GRAFANA_URL=http://grafana.local:3000
GRAFANA_TOKEN=<your-sa-token>
DS_UID=$(curl -s -H "Authorization: Bearer $GRAFANA_TOKEN" \
    "$GRAFANA_URL/api/datasources/name/Prometheus" | jq -r .uid)
jq --arg uid "$DS_UID" '
    .dashboard = .;
    .dashboard.id = null;
    .overwrite = true;
    .inputs = [{"name":"DS_PROMETHEUS","type":"datasource","pluginId":"prometheus","value":$uid}];
    {dashboard: .dashboard, overwrite: true, inputs: .inputs, folderId: 0}
' deploy/grafana/dashboards/food-market.json \
| curl -s -X POST -H "Authorization: Bearer $GRAFANA_TOKEN" \
    -H "Content-Type: application/json" \
    -d @- "$GRAFANA_URL/api/dashboards/import"

Через provisioning (когда Grafana поднимается рядом):

# /etc/grafana/provisioning/dashboards/food-market.yaml
apiVersion: 1
providers:
  - name: food-market
    orgId: 1
    folder: 'food-market'
    type: file
    disableDeletion: false
    updateIntervalSeconds: 60
    options:
      path: /etc/grafana/dashboards/food-market

Положить food-market.json в /etc/grafana/dashboards/food-market/.

Альтернатива — минимальный набор панелей (если делать руками):

Health row

• Request rate — sum(rate(http_requests_received_total[5m])) by (code) → стек по 2xx/3xx/4xx/5xx.
• Error rate (5xx) — sum(rate(http_requests_received_total{code=~"5.."}[5m])) с alert > 0.1 req/s (5 минут) → Telegram.
• p95 latency — histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le)).

Business row

• Sales/hour — rate(food_market_sales_posted_total[1h]) * 3600.
• Supplies posted — increase(food_market_supplies_posted_total[1d]).
• Document errors — sum(rate(food_market_documents_error_total[5m])) by (type, reason). Alert serialization rate > 1 req/min: указывает на лок-контеншн Postgres.

Database row

• EF query rate — sum(rate(food_market_db_query_duration_seconds_count[5m])) by (kind).
• EF query p95 — histogram_quantile(0.95, sum(rate(food_market_db_query_duration_seconds_bucket[5m])) by (le, kind)).

Runtime row

• CPU — rate(process_cpu_seconds_total[1m]) * 100.
• Memory — process_resident_memory_bytes / 1024 / 1024.
• GC Gen2 collections — rate(dotnet_collection_count_total{generation="2"}[5m]).

Alerts (prometheus rules) — пример

groups:
  - name: food-market
    rules:
      - alert: HighErrorRate
        expr: sum(rate(http_requests_received_total{code=~"5.."}[5m])) > 0.1
        for: 5m
        labels: { severity: warning }
        annotations:
          summary: "food-market.api возвращает >0.1 5xx/s"
      - alert: DbSerializationContention
        expr: rate(food_market_documents_error_total{reason="serialization"}[5m]) > 0.016
        for: 10m
        labels: { severity: warning }
        annotations:
          summary: "Сериализационные конфликты EF >1/мин"
      - alert: NoSalesIn30Min
        expr: increase(food_market_sales_posted_total[30m]) == 0
        for: 30m
        labels: { severity: info }
        annotations:
          summary: "Нет продаж 30 минут — POS оффлайн или магазин закрыт"

Локальная отладка

# Чтобы посмотреть метрики из локального API:
curl http://localhost:5081/metrics | head -50

# Конкретная метрика:
curl -s http://localhost:5081/metrics | grep food_market_sales_posted_total

Поведение в тестовом окружении

В интеграционных тестах prometheus-метрики поднимаются как часть WebApplicationFactory; счётчики живут per-process (статические Metrics.Create...). Состояние accumulated между тестами в той же сборке — поэтому в MetricsEndpointTests мы проверяем «значение увеличилось», а не точное число.