← Cloudflare Workers / workers / observability

Трассировки

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

• В чём причина долго выполняющегося запроса?
• Сколько времени занимают подзапросы моего Worker?
• Сколько времени занимают вызовы к моему пространству имён KV или бакету R2?

Cloudflare Workers обеспечивает инструментацию трассировки из коробки : изменения кода или SDK не требуются. Достаточно включить трассировку для вашего Worker, и Cloudflare автоматически начнёт собирать данные телеметрии для:

• Вызовы fetch : все исходящие HTTP запросы с фиксацией времени выполнения, кодов состояния и метаданных запроса. Это позволяет быстро понять, как внешние зависимости влияют на производительность приложения.
• Вызовы привязок : взаимодействия с различными привязками Worker, такими как чтение и запись KV, операции с объектным хранилищем R2 и вызовы Durable Object.
• Вызовы обработчика : полный жизненный цикл каждого вызова Worker, включая такие триггеры, как обработчики fetch, обработчики запланированных событий, а также обработчики очередей.

Полный список инструментируемых операций см. в документация по spans и attributes.

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

Подробнее см. в Пользовательские спаны.

Трассировку можно настроить, задав observability.traces.enabled = true в вашем конфигурационный файл Wrangler.

{
	"observability": {
		"traces": {
			"enabled": true,
			// optional sampling rate (recommended for high-traffic workloads)
			"head_sampling_rate": 0.05
		}
	}
}

[observability.traces]
enabled = true
head_sampling_rate = 0.05

Трассировка Workers следует Стандарты OpenTelemetry (OTel) ↗. Благодаря этому она совместима с популярными платформами наблюдаемости, такими как Honeycomb, Grafana Cloud, и Axiom, не требуя от вас никаких усилий по разработке. Если у вашего провайдера observability есть доступная конечная точка OpenTelemetry, вы можете экспортировать трассировки (и логи)!

Также можно задать persist: false чтобы экспортировать трассировки в нужное место назначения без их сохранения в панели управления Cloudflare. Это позволяет использовать стороннего провайдера наблюдаемости как единственное место назначения для трассировок.

Подробнее об экспорте данных OpenTelemetry из Workers здесь.

С помощью sampling можно трассировать определенный процент входящих запросов в Cloudflare Worker. Это позволяет управлять объемом данных и расходами, при этом сохраняя полезную информацию о работе приложения.

Допустимый диапазон выборки: от 0 к 1, где 0 означает, что не будет трассирован ни один вызов из ста, а 1 означает, что будут трассироваться все запросы, а число вроде 0.05 означает, что будут трассироваться пять запросов из ста.

Если частота сэмплирования не указана, по умолчанию используется значение 1, то есть будет трассироваться 100% запросов.

{
	"observability": {
		"traces": {
			"enabled": true,
			// set tracing sampling rate to 5%
			"head_sampling_rate": 0.05
		},
		"logs": {
			"enabled": true,
			// set logging sampling rate to 60%
			"head_sampling_rate": 0.6
		}
	}
}

[observability.traces]
enabled = true
head_sampling_rate = 0.05

[observability.logs]
enabled = true
head_sampling_rate = 0.6

Если у вас есть head_sampling_rate настроена для логов, вы также можете создать отдельную частоту для трассировок.

Выборка на основе head ↗, то есть запросы без трассировки не несут дополнительных накладных расходов на трассировку.

Трассировка Workers в настоящее время бесплатно в течение первоначального бета периода. Сюда входит вся функциональность трассировки: сбор трасс, их хранение и просмотр в Cloudflare dashboard.

Начиная с 1 октября 2026 года трассировка будет включена в тарификацию использования на тарифных планах Workers Free, Paid и Enterprise. Каждый span трассировки соответствует одному событию наблюдаемости и учитывается в рамках той же ежемесячной квоты и тарификации, что и логи Workers: