← Cloudflare Workers / workers / observability

Query Builder

Query Builder помогает составлять структурированные запросы для анализа и визуализации данных телеметрии. Query Builder выполняет поиск по набору данных Workers Observability, который в настоящее время включает все логи, сохраненные Workers Logs.

Query Builder находится в Observability странице панели управления Cloudflare:

Query Builder доступен всем разработчикам и не требует включения. Запросы выполняют поиск по всем Workers Logs, сохраненным Cloudflare. Если вы еще не включили Workers Logs, сделать это можно, добавив следующую настройку в Файл Wrangler Worker и повторного развёртывания Worker.

{
	"observability": {
		"enabled": true,
		"logs": {
			"invocation_logs": true,
			"head_sampling_rate": 1 // optional. default = 1.
		}
	}
}

[observability]
enabled = true

  [observability.logs]
  invocation_logs = true
  head_sampling_rate = 1

1. На панели управления Cloudflare перейдите к разделу Workers & Pages страницу.

   Перейдите в Workers & Pages ↗

2. Выберите свой Worker.

3. Выберите Observability в левой панели навигации, а затем Обзор на вкладке.

4. Выберите Визуализация.

5. Необязательно: добавьте поля в Filter, Group By, Order By и Limit. Подробнее о том, что формирует запрос.

6. Необязательно: выберите подходящий временной диапазон.

7. Выберите Запуск. Запрос будет автоматически выполняться при каждом изменении.

Query Builder поддерживает множество операторов визуализации, включая:

В один запрос можно добавить несколько визуализаций. Каждая визуализация выводит график. Также возвращается единая сводная таблица с необработанными результатами запроса.

Все методы являются агрегатными функциями. Большинство методов работают с определённым полем в событии журнала. Count является исключением и представляет собой агрегирующую функцию, которая возвращает количество событий журнала, соответствующих условиям фильтра.

Фильтры позволяют получить столбцы, соответствующие заданным условиям. Фильтр состоит из трёх компонентов: ключа, оператора и значения.

В качестве ключа может выступать любое поле события журнала. Например, вы можете выбрать $workers.cpuTimeMs или $metadata.message.

Оператор представляет собой логическое условие, которое принимает значение true или false. Поддерживаемые условия перечислены в таблице ниже:

Значением числового поля является целое число. Значением строкового поля может быть любая строка.

Чтобы добавить фильтр:

Если выполнить запрос с указанным выше фильтром, будут показаны только те события журнала, где $workers.cpuTimeMs > 100 будет возвращён.

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

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

Group By объединяет строки с одинаковым значением в итоговые строки. Например, если запрос добавляет $workers.event.request.cf.country в качестве поля Group By, тогда сводная таблица будет группироваться по странам.

Order By влияет на то, как сортируются результаты в сводной таблице. Если asc выбран, результаты сортируются по возрастанию: от меньшего к большему. Если desc выбран, результаты сортируются по убыванию: от большего к меньшему.

Limit ограничивает количество возвращаемых результатов. В сочетании с Order By, его можно использовать для возврата «верхних» или «первых» N результатов.

Выбирая временной диапазон, вы задаёте интервал, в котором нужно искать подходящие события. Период хранения зависит от вашего тип тарифного плана.

Для запросов доступны три представления: Visualizations, Invocations и Events.

Визуализации вкладка отображает графики и сводную таблицу по запросу.

Вызовы вкладка отображает все журналы, сгруппированные по вызовам и отсортированные по времени. Возвращаются только вызовы, соответствующие критериям запроса.

События вкладка отображает все журналы, отсортированные по времени. Возвращаются только события, соответствующие критериям запроса. Вкладку Events можно настроить, добавив в представление дополнительные поля.

Рекомендуется сохранять запросы, которые могут пригодиться для будущих расследований. Чтобы сохранить запрос с именем, описанием и пользовательскими тегами, выберите Save Query. Запросы сохраняются на уровне аккаунта и доступны всем пользователям аккаунта.

Сохранённые запросы можно запустить повторно, выбрав нужный запрос в Запросы вкладка. Вы можете отредактировать запрос и сохранить изменения.

Пользователи могут отмечать запросы звёздочкой. Отмеченные запросы привязаны к конкретному пользователю, а не к учётной записи.

Сохранённые запросы можно удалить в Запросы вкладка. Если вы удалите запрос, он будет удален для всех пользователей аккаунта.

1. На панели управления Cloudflare перейдите к разделу Observability страницу.

   Перейдите в Observability ↗

2. Выберите Запросы на вкладке.

3. Справа выберите три точки, чтобы открыть дополнительные действия.

4. Выберите Удалить запрос и следуйте инструкциям.

Сохранённым запросам присваивается уникальный URL, и ими можно поделиться с любым пользователем аккаунта.

В этом примере мы составим запрос для поиска и отладки всех путей, которые отвечают ошибками 5xx. Сначала создадим базовый запрос. В этом базовом запросе визуализация будет выполняться по количеству необработанных событий. Мы можем добавить фильтр для $workers.event.response.status которое больше 500. Затем группируем по $workers.event.request.path и $workers.event.response.status чтобы определить количество запросов, затронутых этим поведением.

Результаты показывают, что /agents/chat/default пути возникали ошибки 404 и 500. Теперь можно применить фильтр для этого пути и разобраться в причине.

Теперь можно разобраться в ситуации, выбрав Вызовы вкладка. Видно, что эта ошибка была зафиксирована в двух вызовах.

Мы можем развернуть отдельный вызов, чтобы увидеть соответствующие логи, и продолжить отладку.