Ключи приёма

Каждый проект принимает телеметрию по DSN-ключу — публичной строке, которая одновременно называет проект и разрешает слать в него данные (см. Термины). У ключа есть тип: он ограничивает, какую телеметрию этим конкретным ключом можно прислать. Тип нужен потому, что не все ключи одинаково чувствительны: браузерный ключ публикуется намеренно — он лежит открытым текстом в коде страницы, который видит любой посетитель, — и раньше тот же самый ключ мог зарегистрировать хост или прислать деплой-маркер. Утёкший (а он и не «утекает» — он публикуется по замыслу) ключ браузера давал постороннему заполнить парк хостов проекта поддельными машинами вплоть до потолка в 1000 штук либо запостить фальшивый деплой.

Эта страница — единственное место, где расписан полный список допуска; остальные страницы документации на неё ссылаются.

Типы ключей

Новый проект получает сразу три ключа — по одному на класс источника, без общего «главного» ключа:

Тип ключа привязан к тому, откуда данные приходят технически, а не к тому, кто их шлёт: разница между server и agent — не «сервер или агент», а регистрирует ли источник хост. Ключ без указанного типа не даёт ничего — это защита от забытой инициализации, а не рабочий режим: такое значение не должно встречаться на живом ключе, только пустое поле по ошибке где-то в коде.

agent — это любой источник хостовых метрик

Тип agent называется по своей главной роли, но означает не «только собственный агент Gotcha», а источник хостовых метрик вообще. Ключом agent пользуются оба способа подключить хост со страницы «Хосты»:

• собственный агент gotcha-agent;
• сторонний otelcol-contrib с ресивером hostmetrics и процессором resourcedetection — конфиг с той же страницы «Хосты».

Оба шлют метрики с resource-атрибутом host.name, и именно поэтому оба регистрируют хост — граница проходит по наличию resourcedetection в конфиге, а не по тому, что это «коллектор» как таковой (у рецептов мониторинга сервисов тоже коллектор, но другой — см. ниже).

Почему рецептам сервисов нужен server, а не agent

Рецепты мониторинга (PostgreSQL, MariaDB, nginx, Redis, Docker) тоже подключаются через otelcol-contrib, но их сниппеты сознательно не ставят resourcedetection — рецепт следит за самим сервисом, а не за хостом, на котором он работает, и хост не регистрирует и никогда не регистрировал. DSN, подставленный в конфиг рецепта, — ключ типа server. Выдать рецепту agent-ключ значило бы дать источнику, которому регистрация хоста не нужна, право её делать — то, ради чего типы и заводятся.

Какой ключ куда

Подробности по каждому источнику — на его собственной странице: SDK и интеграции, Деплои, Профилирование, Логи, Хосты, Рецепты мониторинга.

Ключи без типа (legacy)

Ключи, выпущенные до появления типов, продолжают работать без изменений и без ограничения по времени — обновление ничего не ломает. В настройках проекта такой ключ помечен бейджем «Без типа» — это не авария, а описание факта: полный допуск сохраняется бессрочно, менять ключ не обязательно.

Развести источники по типам, не останавливая приём, можно так:

1. выпустите в настройках проекта новые типизированные ключи (browser/server/agent) — старый ключ при этом продолжает работать;
2. переключите каждый источник на ключ нужного ему типа (см. таблицу выше) — по одному, без общего окна простоя: пока не переключены все источники, старый ключ обслуживает оставшиеся;
3. когда все источники переехали, отзовите старый ключ без типа в настройках проекта.

Ключ без типа выпустить заново через интерфейс нельзя — форма создания ключа всегда требует выбрать один из трёх типов.

Тип ключа неизменяем

Сменить тип у существующего ключа нельзя. Единственный способ дать источнику другой набор допуска — выпустить новый ключ нужного типа и отозвать старый (шаги выше). Это осознанное ограничение: тип ключа кешируется вместе с самим ключом на 30 секунд, и невозможность смены типа снимает вопрос о том, что делать с уже закешированным правом доступа.

Что видно при отказе

Запрос ключом не того типа отклоняется с HTTP 403 (а не 401 — ключ опознан и принадлежит проекту, но не подходит по типу для этого конкретного эндпойнта). Если вы держите gotcha сами, это видно и в наблюдаемости — см. Мониторинг самого gotcha:

• gotcha_ingest_rejected_total{reason="key_scope",signal="…"} — отказ по типу ключа, с меткой сигнала (event, transaction, metric, log, profile, deploy);
• gotcha_ingest_key_rejections_total{reason="scope"} — тот же отказ на этапе аутентификации по ключу;
• gotcha_host_registrations_scope_skipped_total — отдельный случай: метрики с ключом не типа agent несут атрибуты host.name. Экспорт при этом ПРИНИМАЕТСЯ и точки записываются — пропускается только регистрация хоста;
• строка в логе с путём эндпойнта, на который пришёл запрос не тем ключом — для отказа по типу, как и для остальных отказов по ключу.

Отказы по ключу этого проекта — неверный/отозванный ключ, ключ чужого проекта, ключ не того типа — видны и на странице проекта: за последний час они показываются на пустом списке проблем и в чек-листе «Первые шаги», без похода в наблюдаемость.

Один запрос со смешанным содержимым (например, envelope браузерного SDK, куда SDK положил заодно и profile-элемент) отбраковывается поштучно: элемент, на который у ключа нет допуска, отбрасывается, а остальное содержимое запроса принимается как обычно.