Span — Buglapse Docs

Событие span — одна замеренная операция — запрос, отрисовка, обращение к базе — внутри трейса. Спаны указывают на родительский спан, из этого и строится водопад трейса. Спаны же переносят метрики: отдельного события для метрик нет, как нет и отдельного события для трейса.

Откуда берётся

span(name, fn) / asyncSpan(name, fn) — отправляется, когда fn возвращает значение, бросает исключение или её промис завершается.
startInactiveSpan(name) — отправляется при вызове end().
Интеграции, которые замеряют что-то автоматически (например, исходящие HTTP-запросы).

См. Трейсинг и Метрики.

Payload

json

{
    "type": "span",
    "timestamp": "2026-09-24T10:15:02.913Z",
    "tags": {},
    "contexts": { "environment": "production", "http.method": "GET", "http.status_code": 200 },
    "payload": {
        "uuid": "00f067aa0ba902b7",
        "name": "GET /api/cart",
        "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
        "parentId": "53995c3f42cd8ad8",
        "startTime": "2026-09-24T10:15:02.481Z",
        "endTime": "2026-09-24T10:15:02.913Z",
        "duration": 432,
        "op": "http.client",
        "status": "ok",
        "metrics": { "cart.items": 3, "response.bytes": 5120 }
    }
}

Поле	Тип	Описание
`uuid`	string	Id этого спана: 16 шестнадцатеричных символов в нижнем регистре.
`name`	string	Что замерялось — первый аргумент `span()`.
`traceId`	string	Трейс, к которому относится спан: 32 шестнадцатеричных символа в нижнем регистре.
`parentId`	string, необязательно	Id объемлющего спана — возможно, спана другого сервиса, который вызвал этот. Нет у корневого спана трейса.
`startTime`	string	Время начала в ISO 8601.
`endTime`	string	Время окончания в ISO 8601.
`duration`	number	Длительность в миллисекундах.
`op`	string, необязательно	Категория операции (`http.client`, `db`, `ui.render`, …) из `{ op }` в опциях спана.
`status`	`ok` \| `error` \| `cancelled`	`error`, если колбэк бросил исключение или его промис отклонён, иначе `ok`, если не изменён через `span.setStatus()`.
`metrics`	object	Значения `имя → число`, записанные через `span.metric(name, value)`.

Id те же, что в W3C Trace Context, OpenTelemetry и Sentry, так что между сервисами они передаются в заголовке traceparent как есть. Читаются они снисходительно — верхний регистр и дефисы нормализуются, слишком длинный id спана обрезается до первых 16 цифр, — а id, который не шестнадцатеричный или весь из нулей, id не считается: спан без пригодного traceId (или с непригодным uuid) отклоняется как некорректный, непригодный parentId отбрасывается. То же для trace.id / span.id / previous_trace.id в contexts любого события: непригодный удаляется, а событие сохраняется.

Значения из span.setData(key, value) не входят в payload — они вливаются в contexts события.

Трейсы

Трейс — не отдельное событие, а traceId, общий для его спанов. Первый спан с новым traceId создаёт трейс в разделе Трейсы проекта, а каждый следующий спан с тем же id присоединяется к нему.

Окружение, пользователь, теги и контексты трейса берутся из его корневых спанов (без parentId), а пока такой не пришёл — из самого раннего полученного спана. В браузере у трейса одной страницы может быть несколько корней (клик, который отправил запрос после окончания спана pageload); каждый вливает свои теги и контексты в трейс, а не заменяет их.

Трейс может проходить через несколько проектов: страница, отправляющая в один проект, и бэкенд, отправляющий в другой, разделяют traceId, когда SDK передают его. Каждый проект хранит, сэмплирует, тарифицирует и держит свои спаны сам; страница трейса склеивает проекты одной организации в один водопад, а список Трейсов каждого проекта показывает свою часть (верхний спан продолженного запроса считается корнем этого проекта).

Контексты уровня трейса передаются в корневом спане. browserTracingIntegration кладёт previous_trace.id — трейс страницы, с которой пришёл пользователь, — в спан pageload/navigation, и панель связывает через него трейсы страниц одного визита (см. Путь по визиту).

Метрики

Каждый вызов span.metric(name, value) внутри спана попадает в его словарь metrics. Два вызова с одним именем оставляют только последнее значение. Метрики показываются графиками на странице трейса и всегда привязаны к спану (и трейсу), в котором записаны.

Сэмплирование

Действуют две доли, обе решаются на traceId, а не на спан: все спаны трейса сохраняются или отбрасываются вместе, так что наполовину сэмплированного водопада не бывает.

tracesSampleRate в SDK (или traces_sample_rate в Sentry SDK) решает, что отправляется. Sentry SDK поддерживаются в обоих режимах жизненного цикла трейса: целые транзакции или потоковые спаны (traceLifecycle: 'stream' / trace_lifecycle="stream"). Ошибки и логи из несэмплированного трейса всё равно отправляются и несут его trace.id.
Доля трейсов проекта (Настройки → Фильтры → Сэмплирование) решает при приёме, что из отправленного сохранить, — для любого SDK, со следующей пачки. Решение зависит только от id трейса, так что трейс, продолженный другим проектом (браузер → API), остаётся целым в обоих, если оба его сохраняют.

Спан, отброшенный сэмплированием на сервере, не хранится и не тарифицируется и учитывается как Sampled в Статистика и использование. Каждый сохранённый трейс помнит общую долю, с которой сохранён (SDK × сервер), и число трейсов в обзоре и на главной экстраполируется по ней (1 / доля на трейс), так что оно оценивает реальный трафик. Список трейсов показывает сохранённые и сообщает об этом, если доля проекта ниже 100 %. Ссылка ошибки на трейс может вести на несохранённый трейс.

Квота

Учитывается как одно событие в месячном лимите спанов — единственном, по которому тарифицируется трейсинг, ведь трейс не отдельное событие. Значения в metrics отдельно ничего не стоят.

Откуда берётся ​

Payload ​

Трейсы ​

Метрики ​

Сэмплирование ​