Respan Dataset Explorer

"Нажимаем на один из спанов. Выбранный спан отвечает за поход в сервис."

При нажатии на один из спанов, выделяется спан, который отвечает за взаимодействие с сервисом.

"Справа представлена метаинформация спана. Справа внизу есть лейблы — начинаем их анализировать. Напротив **http.status_code** стоит 400 — скорее всего, в определённые промежутки времени user-info-сервис некорректно обращается к location-сервису. В **http.url** в параметре **ip_address** пустое значение. Получается, что иногда приходит пустота, поэтому возвращается четырёхсотка.

Дальше исправляем это в коде и перевыкатываем приложение. Однако ошибки сохраняются."

Справа отображается метаинформация спана. В правой нижней части расположены лейблы, с которых начинается анализ. Напротив **http.status_code** указано значение 400, что может указывать на то, что в определённые моменты времени `user-info-сервис` неверно взаимодействует с `location-сервисом`. В параметре **ip_address** для **http.url** указано пустое значение, что может означать, что иногда передаётся пустое значение, из-за чего возвращается ошибка 400.

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

"Снова заходим в интерфейс трейсинга в Monitoring UI, по поиску находим ошибочный трейс и анализируем его. Видно, что операция, связанная с HTTP-походом в location-сервис завершилась успешно. Значит, есть какая-то ещё причина ошибки."

Снова открыв интерфейс трейсинга в Monitoring UI, выполняется поиск для нахождения ошибочного трейса и его анализа. Из анализа видно, что операция, связанная с HTTP-запросом к `location-сервису`, завершилась успешно. Это говорит о том, что причина ошибки кроется где-то ещё.

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

Анализ показывает, что начальная часть трейса корректно трассируется и включает несколько спанов, однако значительная часть трейса остаётся скрытой. В таких случаях применяется ручное инструментирование: внося изменения в код приложения, создаются дополнительные спаны в ключевых местах, где это требуется для полного охвата трассировки.

перепиши для документации, как технический писатель. пиши от третьего лица "В данном случае создаём спан, который обозначает поход в базу данных Redis. Добавляем дополнительные атрибуты, которые, возможно, потребуются в дебаге. Устанавливаем **SetStatus** в качестве **Error** в случае, если операция похода в базу данных зафейлится (на скрине выделено синим).

Благодаря этому интерфейс Monitoring UI в трейсинге сразу подскажет, что произошла ошибка.

Затем снова идём в поиск, в интерфейс трейсинга, и видим, что теперь есть контекст — большую часть времени трейса занимал поход в базу данных, и он зафейлился."

В данном случае инженеры создают спан, который обозначает взаимодействие с базой данных Redis. Они добавляют дополнительные атрибуты, которые могут потребоваться при отладке. Если операция обращения к базе данных завершится неудачей, статус **SetStatus** устанавливается как **Error** (на скриншоте выделено синим).

Это позволяет интерфейсу Monitoring UI в трейсинге сразу указать на возникновение ошибки.

Затем в интерфейсе трейсинга через поиск устанавливается, что теперь доступен дополнительный контекст — основную часть времени трейса заняло обращение к базе данных, и оно завершилось неудачей.

"Переходим в код, исправляем проблему, перевыкатываем приложение и проверяем — фон ошибок ушёл."

Инженеры переходят к коду, исправляют выявленную проблему, развёртывают обновлённое приложение и проводят проверку — фоновые ошибки исчезают.

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

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

"
[Исходный код примера] можно взять за основу, чтобы проинструментировать другие сервисы. Инструментировать можно поэтапно: сначала воспользоваться автоинструментированием, например чтобы проинструментировать GRPC-походы в микросервисы, HTTP, затем посмотреть на получившиеся трейсы. Во фреймворке OpenTelemetry многое уже написано: можно использовать автоматическое инструментирование для Redis, Kafka, PostrgreSQL и других баз данных. Если контекста достаточно, то уже после этого можно отладить запрос.

А если где-то требуется больше детализации или контекста, то можно дополнительно проинструментировать код трейсингом и создать необходимые спаны. Логика проставления схожа с логами: мы пишем логи в значимых местах приложения, чтобы потом по ним можно было отладить и посмотреть, как происходили те или иные события. Так же и спаны пишутся в значимых частях приложения, где интересно смотреть на те или иные операции."

[Исходный код примера] может служить основой для инструментирования других сервисов. Инструментирование рекомендуется проводить поэтапно: сначала использовать автоинструментирование, например, для GRPC-вызовов в микросервисы или HTTP-запросов, затем проанализировать полученные трейсы. В фреймворке OpenTelemetry уже предусмотрено автоматическое инструментирование для таких систем, как Redis, Kafka, PostgreSQL и другие базы данных. Если предоставленного контекста достаточно, можно начинать отладку запросов.

Если требуется больше детализации или контекста, код может быть дополнительно инструментирован трейсингом с созданием необходимых спанов. Логика задания схожа с логированием: логи добавляются в ключевых местах приложения, чтобы позже можно было отладить и проанализировать происходящие события. Аналогично, спаны создаются в значимых частях приложения для отслеживания выполнения тех или иных операций.

"# Спан

## **Из чего состоят спаны**

**Название** — помогает понять, какая операция выполнялась в рамках того или иного микросервиса. В качестве названия следует выбирать короткое имя низкой кардинальности, которое хорошо характеризует выполняемую операцию.

**Статус** — в OpenTelemetry спан может находиться в трёх статусах: **UNSET**, **OK, ERROR**. Первые два нас не интересуют — в интерфейсе трейсинга в Monitoring UI они неотличимы."

# Спан

## **Компоненты спанов**

**Название** — предназначено для идентификации операции, выполняемой в конкретном микросервисе. Выбор названия должен учитывать короткое имя с низкой кардинальностью, которое точно характеризует выполняемую операцию.

**Статус** — в OpenTelemetry спан может принимать три различных статуса: **UNSET**, **OK**, **ERROR**. Наибольший интерес представляет статус **ERROR**, так как первые два не имеют отличий в интерфейсе трейсинга в Monitoring UI.

"Для нас важен статус **ERROR**, который показывает, что в каком-то спане произошла ошибка. В будущем, когда мы будем анализировать трейсы, это поможет локализовать ошибку."

Статус **ERROR** играет важную роль, поскольку он указывает на наличие ошибки в конкретном спане. В будущем при анализе трейсов этот статус поможет быстро локализовать и идентифицировать возникшую проблему.