Трассировка
Трейс показывает путь одного запроса через приложение и другие сервисы. Он состоит из спанов: каждый спан соответствует одной операции, например загрузке экрана или SQL-запросу, и хранит её длительность и атрибуты. Спаны вложены друг в друга, поэтому по трейсу видно, какая операция выполнялась дольше всего.
Трассировка в Jmix строится на Micrometer Observation и Micrometer Tracing, экспорт выполняется через OpenTelemetry. Jmix создаёт спаны для своих операций; Spring Boot — для входящих и исходящих HTTP-запросов.
Включение спанов Jmix
jmix.core.data-observation-enabled=true
jmix.ui.ui-observation-enabled=true
Первое свойство включает спаны доступа к данным, второе — спаны UI. По умолчанию оба имеют значение false. Эти же свойства включают метрики Jmix: одно наблюдение даёт и метрику, и спан.
Vaadin передаёт все действия пользователя запросами к одному адресу, и корневой спан каждого из них называется одинаково — http post /**. Какой экран открывался и какое действие выполнял пользователь, видно только по спанам Jmix view lifecycle, data loader lifecycle, fragment lifecycle и execute action и их атрибутам.
Экспорт через OpenTelemetry
Добавьте стартер OpenTelemetry. Начиная со Spring Boot 4 это рекомендуемый способ подключения: стартер содержит мост Micrometer Tracing и экспортёр OTLP.
implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'org.springframework.boot:spring-boot-starter-opentelemetry'
Укажите адрес сборщика трейсов, например OpenTelemetry Collector или Grafana Tempo:
management.opentelemetry.tracing.export.otlp.endpoint=http://localhost:4318/v1/traces
Доля сохраняемых трейсов
Свойство management.tracing.sampling.probability задаёт долю запросов, для которых трейс отправляется в систему хранения. Значение по умолчанию 0.1: сохраняется один трейс из десяти.
management.tracing.sampling.probability=1.0
Значение 1.0 удобно при разработке и отладке. В промышленной эксплуатации оно увеличивает нагрузку на приложение и объём хранимых данных, поэтому там задают значение от 0.01 до 0.1.
Спаны Jmix
Имя спана в системе трассировки отличается от имени наблюдения: например, наблюдение jmix.ui.views даёт спаны с именем view lifecycle.
| Наблюдение | Имя спана | Атрибуты |
|---|---|---|
|
|
|
|
||
|
||
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Значения тегов, общих с метриками, описаны на странице Метрики. Атрибуты, которых нет в метриках:
| Атрибут | Значение |
|---|---|
|
Текст JPQL-запроса |
|
Параметры запроса с их значениями. Добавляется, если у запроса есть параметры |
|
Список свойств загружаемых значений |
|
Количество сохраняемых и удаляемых сущностей каждого типа, например |
|
Исходный идентификатор загрузчика, если в |
Подсчёт значений через DataManager.getCount(ValueLoadContext) записывается спаном с именем load values и атрибутом method=getCount.
Например, в трейсе открытия списка визитов в портале спан data loader lifecycle загрузчика экрана содержит загрузку через REST DataStore и обработку запроса во втором приложении:
view lifecycle (beforeShow) jmix-petclinic-portal
└── data loader lifecycle (load, visitsDl) jmix-petclinic-portal
└── load list of entities jmix-petclinic-portal
└── http post jmix-petclinic-portal
└── http post /rest/entities/{entityName}/search jmix-petclinic
└── secured request jmix-petclinic
└── load list of entities jmix-petclinic
У спана load list of entities во втором приложении есть атрибуты Jmix: entity.name (petclinic_Visit), jpql.query с текстом JPQL-запроса, method с операцией и jmix.user.username с пользователем, от имени которого выполнен запрос.
Как по спанам загрузки данных находить лишние и медленные запросы к базе данных, описано в разделе Доступ к данным.
Атрибуты пользователя и арендатора
При включённом свойстве jmix.core.use-user-info-for-observation (значение по умолчанию) ко всем спанам добавляются атрибуты:
-
jmix.user.username— имя текущего пользователя; -
jmix.user.tenantId— идентификатор арендатора в приложениях с мультиарендностью.
По jmix.user.username в системе трассировки находят запросы конкретного пользователя. Если имена пользователей не должны попадать в систему трассировки, задайте свойству значение false.
Атрибут jpql.parameters содержит значения параметров запросов, в том числе персональные данные из условий поиска. Учитывайте это при настройке доступа к системе хранения трейсов.
Передача контекста между сервисами
Чтобы трейс продолжался в другом сервисе, исходящий HTTP-запрос должен нести заголовки трассировки. Spring Boot добавляет их автоматически, если клиент создан из автоматически настроенного RestClient.Builder или RestTemplateBuilder. Клиент, созданный через RestClient.create() или new RestTemplate(), заголовки не передаёт, и трейс обрывается на границе сервиса.
Просмотр трейсов в Grafana
Трейсы хранятся в системе трассировки, например Grafana Tempo, и просматриваются в Grafana через Explore с источником данных Tempo. Трейс отображается как дерево спанов на шкале времени: длина полосы — длительность операции, вложенность — какая операция какую вызвала. По этой шкале видно, какой спан занял большую часть времени запроса.
Трейсы ищут запросом на языке TraceQL. Атрибуты спана указываются с префиксом span.. Загрузки списка сущностей дольше 500 мс:
{ name = "load list of entities" && duration > 500ms }
Все спаны жизненного цикла экрана User.list, открытого пользователем admin:
{ name = "view lifecycle" && span.view.id = "User.list" && span.jmix.user.username = "admin" }
Без написания запросов трейсы просматриваются в Drilldown → Traces: Grafana показывает частоту запросов, ошибки и длительность по сервисам и спанам и позволяет перейти от выбросов на графике к конкретным трейсам.
В верхней части страницы — частота всех спанов, ошибки и распределение длительности; в нижней — те же данные по именам спанов. В примере Petclinic больше всего спанов создаёт цепочка фильтров Spring Security (authorize request, secured request, security filterchain): их больше, чем спанов Jmix view lifecycle. Если такие спаны не нужны, их отключают, см. Настройка для промышленной эксплуатации.
Поиск и просмотр трейсов встроены в Grafana. Медленные запросы, этапы экранов и загрузки DataManager собраны в разделе Traces панели мониторинга «Jmix 3 Full Observability», см. Готовые панели мониторинга. Переход к трейсу возможен и из других сигналов: из строки лога по идентификатору трейса, см. Идентификаторы трейсов в логах, и из точки exemplar на графике метрики, см. Exemplars. Из корневого спана запроса открывается профиль процессора или выделения памяти за время этого спана, см. Связь профилей со спанами. Переход от строки лога к трейсу показан в руководстве Observability: Distributed Tracing.
Спаны бизнес-операций
Бизнес-операцию, которая включает несколько вызовов фреймворка, можно объединить в один спан через Observation API Micrometer. Наблюдение создаётся через бин ObservationRegistry:
@Autowired
private ObservationRegistry observationRegistry;
public void confirmOrder(Order order) {
Observation.createNotStarted("sales.order.confirm", observationRegistry)
.contextualName("confirm order")
.lowCardinalityKeyValue("order.channel", order.getChannel().getId())
.observe(() -> orderProcessor.process(order)); (1)
}
| 1 | Обработка заказа: вызовы DataManager и других сервисов внутри операции. |
Наблюдение даёт спан confirm order; спаны load entity, save entities и исходящих HTTP-запросов, созданные внутри операции, становятся его дочерними спанами. Одновременно появляется таймер sales.order.confirm с тегом order.channel. Если операция завершилась исключением, observe() записывает его в спан и в тег error таймера.
Теги lowCardinalityKeyValue попадают и в метрику, и в спан, поэтому для них подходят только значения из небольшого набора. Идентификаторы и другие уникальные значения добавляются через highCardinalityKeyValue: они записываются только в спан.
Полный пример со спаном регистрации пользователя приведён в руководстве Observability: Distributed Tracing.
Настройка для промышленной эксплуатации
-
Сохраняется доля трейсов, обычно от 1 до 10%, см. Доля сохраняемых трейсов.
-
Чтобы сохранять все трейсы с ошибками и медленные запросы, решение принимают после завершения трейса в OpenTelemetry Collector с процессором tail_sampling. В этом случае приложение отправляет в Collector все трейсы (
management.tracing.sampling.probability=1.0), а отбор выполняет Collector. -
Ненужные наблюдения отключаются свойством
management.observations.enableпо префиксу имени, вместе с их спанами и метриками. Например, Spring Security добавляет к каждому запросу несколько спанов цепочки фильтров; их отключаетmanagement.observations.enable.spring.security=false. -
Спаны содержат персональные данные (
jpql.parameters,jmix.user.username), см. Атрибуты пользователя и арендатора; от этого зависят выбор системы хранения трейсов и права доступа к ней. -
Срок хранения трейсов в Tempo задаётся параметром
compactor.compaction.block_retention.
См. также
-
Observability: Distributed Tracing — пример из двух приложений с Grafana Tempo