Метрики

Раздел «Метрики» хранит числовые временные ряды, которые ваше приложение отправляет по протоколу OTLP (OpenTelemetry Protocol). Это отдельный канал приёма — не ошибки и не транзакции: метрика — это число (например, длительность запроса, размер очереди, число заказов), измеренное в конкретный момент и, опционально, помеченное лейблами (окружение, регион, статус-код и т. п.).

Открывается по значку графика в левой рельсе («Метрики») или напрямую по /projects/{id}/metrics.

Как отправить метрику

Эндпойнт приёма

Gotcha принимает метрики через OTLP/HTTP по адресу:

POST /v1/metrics

на том же хосте, что и остальной приём событий (см. DSN проекта). Поддерживаются обе стандартные кодировки OTLP:

Аутентификация

Как и приём ошибок/транзакций, /v1/metrics авторизуется публичным ключом проекта — но не в URL, а в заголовке:

Authorization: Bearer <PUBLIC_KEY>

<PUBLIC_KEY> — это часть DSN проекта между https:// и @. Возьмите DSN на странице проекта «Подключение» (см. SDK и интеграции): для DSN вида

https://a1b2c3d4e5f6@gotcha.example.com/42

ключом будет a1b2c3d4e5f6, а хостом для метрик — gotcha.example.com. Проект определяется по ключу, поэтому в пути /v1/metrics номер проекта не указывается. Неверный или отсутствующий ключ — ответ 401.

Быстрая проверка curl

Самый простой способ отправить тестовую точку — OTLP/JSON без всякого SDK:

curl -X POST https://gotcha.example.com/v1/metrics \
  -H "Authorization: Bearer a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceMetrics": [{
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "my-php-app"}},
          {"key": "deployment.environment.name", "value": {"stringValue": "production"}}
        ]
      },
      "scopeMetrics": [{
        "metrics": [{
          "name": "http.server.duration",
          "unit": "ms",
          "gauge": {
            "dataPoints": [{
              "asDouble": 123.4,
              "timeUnixNano": "1700000000000000000",
              "attributes": [{"key": "route", "value": {"stringValue": "/checkout"}}]
            }]
          }
        }]
      }]
    }]
  }'

Если ключ верный и приём метрик включён на инстансе, ответ — пустой 200 OK. Через минуту-другую метрика http.server.duration появится в списке.

Настройка OTel-экспортёра переменными окружения

Для регулярной отправки удобнее не собирать JSON руками, а настроить OTel SDK/экспортёр вашего языка (Go, PHP, Node, Python — любой, поддерживающий стандартные переменные окружения OTLP):

OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://gotcha.example.com/v1/metrics
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_METRICS_HEADERS=Authorization=Bearer%20a1b2c3d4e5f6
OTEL_METRIC_EXPORT_INTERVAL=15000

Для PHP это, например, пакет open-telemetry/exporter-otlp поверх open-telemetry/sdk — он читает эти же переменные без дополнительного кода. Экспортёр сам собирает resourceMetrics/scopeMetrics и шлёт их пачками по таймеру (OTEL_METRIC_EXPORT_INTERVAL, миллисекунды).

Метрики не семплируются и не зависят от переключателя трейсинга — если приём метрик включён на инстансе, долетает каждая точка (в пределах квоты организации).

Какие типы метрик принимаются

ExponentialHistogram и Summary пока не поддерживаются — такие метрики молча пропускаются при разборе.

Значения NaN/±Inf в датапоинтах отбрасываются на приёме, а не сохраняются как есть.

Лейблы и окружение

• service.name из ресурсных атрибутов идёт в поле «сервис».
• deployment.environment.name (актуальная семконвенция OTel) или deployment.environment (старая) — в окружение, по нему фильтруется список и график.
• Остальные атрибуты датапоинта (например, route, status_code, region) становятся лейблами метрики — по ним можно фильтровать детальный график и переходить между срезами.

На одну точку принимается не более 64 лейблов (лишние отбрасываются детерминированно, по отсортированным ключам); в UI по каждому ключу лейбла показывается до 20 известных значений.

Окно приёма

Точка со временем старше 90 дней в прошлом или больше суток в будущем относительно момента приёма отбрасывается (та же защита партиций ClickHouse, что и у событий/трасс) — экспортёр с сильно рассинхронизированными часами будет терять точки.

Список метрик

/projects/{id}/metrics — таблица всех метрик проекта: имя, тип (gauge/sum/histogram), юнит. Сверху можно отфильтровать по окружению. Пока метрик нет, страница показывает подсказку с ссылкой на эту документацию.

Детальная страница метрики

Клик по имени метрики открывает /projects/{id}/metrics/{name} — график временного ряда с фильтрами:

• Период — 1h / 24h / 7d (шаг корзины подстраивается: минута / 10 минут / час);
• Агрегация — набор зависит от типа метрики (см. таблицу выше; для histogram по умолчанию перцентили, для остальных — avg/max/min/sum);
• Окружение — из известных окружений этой метрики, «все» по умолчанию.

График — SVG с подписанными осями (значения по Y отформатированы с учётом юнита метрики). Если на эту метрику с этой же агрегацией заведено включённое правило оповещения по метрике, его порог рисуется горизонтальной пунктирной линией с подписью условия (например, > 500) — так видно, насколько текущий график близок к алерту.

Ниже графика — список известных лейблов метрики; клик по значению лейбла переходит на тот же график с фильтром по этому лейблу (label_key/label_value в URL).

Настройки и квоты

Отдельной страницы настроек метрик на уровне проекта (в отличие, например, от ретенции спанов в «Производительности») пока нет — метрики хранятся по общей политике инстанса. Приём метрик считается в месячную квоту организации; лимит по умолчанию задаётся оператором через GOTCHA_DEFAULT_METRIC_QUOTA (см. Конфигурацию) и настраивается тонко в «Настройках организации → Использование и лимиты». При исчерпании квоты /v1/metrics отвечает 429, уже принятые точки не удаляются.

Оповещения по метрикам

На метрику можно повесить правило: порог по значению агрегации за окно времени, при пробитии которого открывается инцидент и уходит уведомление в каналы проекта. Подробный разбор с примером — в Оповещениях по метрикам; о самих каналах доставки — в Оповещениях.