Телеметрия

Обзор

Meridian предоставляет встроенную телеметрию и мониторинг через сбор метрик Prometheus. Система телеметрии отслеживает производительность на уровне HTTP и взаимодействие с upstream-провайдерами, давая полную видимость производительности и паттернов использования AI-шлюза.

Ключевые возможности:

• Интеграция с Prometheus — нативный сбор метрик на эндпоинте /metrics;
• Полное покрытие — успехи и ошибки, использование токенов, расходы и эффективность кэша;
• Кастомные метки — настраиваемые измерения для детального анализа;
• Динамические заголовки — внедрение значений меток в рантайме через заголовки x-bf-prom-*;
• Контроль расходов — отслеживание стоимости в USD по AI-провайдерам в реальном времени;
• Аналитика кэша — учёт прямых и семантических hit'ов кэша;
• Асинхронный сбор — нулевое влияние на обработку запроса;
• Многоуровневый учёт — метрики HTTP-транспорта + метрики upstream-провайдеров.

Плагин телеметрии работает асинхронно, поэтому сбор метрик не влияет на латентность запросов и пропускную способность соединения.

Метрики по умолчанию

HTTP-метрики транспорта

Эти метрики отслеживают все входящие HTTP-запросы к Meridian:

Метки:

• path — путь HTTP-эндпоинта;
• method — HTTP-метод (GET, POST, PUT, DELETE);
• status — HTTP-код ответа;
• кастомные метки — настроенные в конфигурации Meridian.

Метрики upstream-провайдеров

Эти метрики отслеживают запросы, перенаправляемые AI-провайдерам:

Базовые метки:

• provider — имя AI-провайдера (openai, anthropic, azure и т. д.);
• model — имя модели (gpt-4o-mini, claude-3-sonnet и т. д.);
• method — тип запроса (chat, text, embedding, speech, transcription);
• virtual_key_id — ID виртуального ключа;
• virtual_key_name — имя виртуального ключа;
• routing_engines_used — список движков маршрутизации, через запятую (routing-rule, governance, loadbalancing);
• routing_rule_id — ID правила маршрутизации, сматчившего запрос;
• routing_rule_name — имя правила маршрутизации, сматчившего запрос;
• selected_key_id — ID выбранного ключа;
• selected_key_name — имя выбранного ключа;
• number_of_retries — число повторов;
• fallback_index — индекс fallback (0 — основная попытка, 1 — вторая и т. д.);
• кастомные метки — настроенные в конфигурации Meridian.

Streaming-метрики

Эти метрики фиксируют латентность, специфичную для потоковых ответов:

Примеры мониторинга

Мониторинг success rate

Отслеживание доли успехов по разным провайдерам:

# Доля успехов по провайдерам
rate(meridian_success_requests_total[5m]) /
rate(meridian_upstream_requests_total[5m]) * 100

Анализ использования токенов

Мониторинг расхода токенов по моделям:

# Input-токены в минуту по моделям
increase(meridian_input_tokens_total[1m])

# Output-токены в минуту по моделям
increase(meridian_output_tokens_total[1m])

# Эффективность токенов (output/input)
rate(meridian_output_tokens_total[5m]) /
rate(meridian_input_tokens_total[5m])

Учёт расходов

Мониторинг расходов по провайдерам и моделям:

# Стоимость в секунду по провайдерам
sum by (provider) (rate(meridian_cost_total[1m]))

# Оценка дневных расходов
sum by (provider) (increase(meridian_cost_total[1d]))

# Стоимость на запрос по провайдеру и модели
sum by (provider, model) (rate(meridian_cost_total[5m])) /
sum by (provider, model) (rate(meridian_upstream_requests_total[5m]))

Эффективность кэша

Контроль эффективности кэша:

# Hit rate кэша по типам
rate(meridian_cache_hits_total[5m]) /
rate(meridian_upstream_requests_total[5m]) * 100

# Прямые против семантических hit'ов
sum by (cache_type) (rate(meridian_cache_hits_total[5m]))

Анализ ошибок

Мониторинг паттернов ошибок:

# Доля ошибок по провайдерам
rate(meridian_error_requests_total[5m]) /
rate(meridian_upstream_requests_total[5m]) * 100

# Ошибки по моделям
sum by (model) (rate(meridian_error_requests_total[5m]))

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

Настройте кастомные метки Prometheus, чтобы добавить измерения для фильтрации и анализа:

Веб-интерфейсAPIconfig.json

1. Перейдите в конфигурацию:

   • откройте UI Meridian по адресу http://localhost:8080;
   • перейдите на вкладку Config.

2. Метки Prometheus:

   Custom Labels: team, environment, organization, project

# Обновить метки Prometheus через API
curl -X PATCH http://localhost:8080/config \
  -H "Content-Type: application/json" \
  -d '{
    "client": {
      "prometheus_labels": ["team", "environment", "organization", "project"]
    }
  }'

{
  "client": {
    "prometheus_labels": ["team", "environment", "organization", "project"],
    "drop_excess_requests": false,
    "initial_pool_size": 300
  }
}

Динамическое внедрение меток

Добавляйте значения кастомных меток в рантайме через заголовки x-bf-prom-*:

# Добавить кастомные метки к конкретному запросу
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bf-prom-team: engineering" \
  -H "x-bf-prom-environment: production" \
  -H "x-bf-prom-organization: my-org" \
  -H "x-bf-prom-project: my-project" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Формат заголовка:

• Префикс — x-bf-prom-;
• Имя метки — любая строка после префикса;
• Значение — строковое значение метки.

Настройка инфраструктуры

Разработка и тестирование

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

# Запустить Prometheus и Grafana
docker-compose up -d

# Доступные эндпоинты:
# Prometheus: http://localhost:9090
# Grafana:    http://localhost:3000 (admin/admin)
# Метрики Meridian: http://localhost:8080/metrics

Production-развёртывание

Для production-окружений:

1. Разверните Prometheus с правильным persistence, retention и безопасностью.
2. Настройте scrape на ваши инстансы Meridian, путь — /metrics.
3. Поднимите Grafana с аутентификацией и дашбордами.
4. Настройте алерты под ваши SLA.

Пример конфигурации scrape Prometheus:

scrape_configs:
  - job_name: "meridian-gateway"
    static_configs:
      - targets: ["meridian-instance-1:8080", "meridian-instance-2:8080"]
    scrape_interval: 30s
    metrics_path: /metrics
    # Если у Meridian включена аутентификация, добавьте:
    # basic_auth:
    #   username: '<admin_username>'
    #   password: '<admin_password>'

Примеры production-алертов

Настройте алерты для критичных сценариев на основе метрик:

Алерт на высокую долю ошибок:

- alert: MeridianHighErrorRate
  expr: sum by (provider) (rate(meridian_error_requests_total[5m])) / sum by (provider) (rate(meridian_upstream_requests_total[5m])) > 0.05
  for: 2m
  labels:
    severity: warning
  annotations:
    summary: "High error rate detected for provider {{ $labels.provider }} ({{ $value | humanizePercentage }})"

Алерт на высокие расходы:

- alert: MeridianHighCosts
  expr: sum by (provider) (increase(meridian_cost_total[1d])) > 100  # порог $100/день
  for: 10m
  labels:
    severity: warning
  annotations:
    summary: "Daily cost for provider {{ $labels.provider }} exceeds $100 ({{ $value | printf \"%.2f\" }})"

Алерт на низкую эффективность кэша:

- alert: MeridianLowCacheHitRate
  expr: sum by (provider) (rate(meridian_cache_hits_total[15m])) / sum by (provider) (rate(meridian_upstream_requests_total[15m])) < 0.1
  for: 5m
  labels:
    severity: info
  annotations:
    summary: "Cache hit rate for provider {{ $labels.provider }} below 10% ({{ $value | humanizePercentage }})"