Vercel CLI теперь ищет этапы выполнения запросов

Что делает команда

Команда vercel traces search позволяет искать trace spans проекта прямо из терминала. Каждый span — это отдельный шаг в обработке запроса; через CLI вы получаете доступ к этим шагам без необходимости открывать веб‑дашборд. Такой поиск пригодится при расследовании ошибок, выявлении узких мест по задержке и анализе поведения, связанного с безопасностью.

По умолчанию команда возвращает до 100 span’ов за последний час, отсортированных от новых к старым. Это значит, что искать можно «сверху» — без предварительного поиска конкретного request или trace ID: достаточно запустить команду и применить фильтры.

Как применять: фильтры и вывод

Возможные способы фильтрации включают среду (environment), сервис, имя span, статус, ID деплоя, ID запроса, trace ID и span ID. Временной диапазон точнее задают параметры --since и --until. Примеры из исходного описания демонстрируют типичные кейсы:

— найти error‑span’ы за последний час: vercel traces search --status error --since 1h. — посмотреть все span’ы конкретного trace: vercel traces search --trace-id <trace-id>. Эти варианты позволяют быстро отфильтровать нужные события.

Если требуемого фильтра нет как отдельной опции, используйте --query и поддерживаемую Vercel подмножество Kibana Query Language (KQL). В --query можно ссылаться на поля вроде duration и на атрибуты span или ресурса. Например: vercel traces search --query 'span.duration > 2000' возвращает span’ы, длившиеся более двух секунд.

Для машинной обработки добавьте флаг --json: команда выведет по одному JSON‑объекту на span. Это упрощает интеграцию с автоматизированными скриптами или агентами, которые могут парсить вывод и принимать решения или отправлять уведомления.

Практический контекст и последствия для работы

Доступ к span’ам из CLI меняет привычный поток расследования инцидентов: вместо переключения в веб‑интерфейс можно держать рабочий процесс в терминале и сразу применять фильтры. Для разработчика это сокращает время на локализацию ошибок и позволяет быстрее собрать контекст по задержкам или нештатным статусам.

Для сценариев с агентами и скриптами важен JSON‑вывод: агент может запрашивать недавние span’ы, фильтровать их по критериям (например, длительность или статус) и затем запускать следующие шаги — например, создавать тикет, отправлять подробный лог в систему оповещений или пробегать матрицу трассировки для поиска общей причины.

Возвращение максимум 100 span’ов из последнего часа по умолчанию упрощает быстрые проверки. Если нужен более точный охват, в команду можно добавить временные границы --since/--until или указать конкретные ID. Возможность искать по trace ID даёт полный набор шагов для одного запроса, а KQL‑запросы позволяют сложнее фильтровать по атрибутам, например по длительности.

Как начать и что проверить

Перед использованием обновите Vercel CLI: vercel upgrade. После обновления запускайте vercel traces search --help, чтобы увидеть все доступные опции в вашей версии. Документация по vercel traces содержит дополнительные детали и примеры, которые пригодятся при настройке запросов и автоматизации.

Включите --json, если планируете парсить вывод программно; используйте --query, когда нужна тонкая фильтрация по полям и атрибутам. Для быстрых ручных проверок достаточно параметров вроде --status, --trace-id и временных границ.

Ограничения и что помнить

По умолчанию команда возвращает не более 100 span’ов и охватывает последний час. Если требуется другой объём данных или более давние span’ы, нужно явно задавать временные границы или конкретные ID. Это влияет на случай, когда нужен полный исторический анализ без заранее известного trace ID.

KQL поддерживается в подмножестве, которое использует Vercel; не все синтаксические конструкции Kibana могут быть доступны. При написании сложных запросов проверяйте их работоспособность через --help или документацию vercel traces.

Вывод в JSON упрощает автоматизацию, но требует корректной обработки на стороне скриптов или агентов: учитывайте формат одного JSON‑объекта на span и возможное количество записей. Также команда ориентирована на поиск по span’ам, а не на редактирование или изменение настроек трассировки — для управления конфигурацией трассировки потребуется другой набор инструментов.