Привет! Я Никита, Staff-инженер в крупном финтехе. В этой статье я хочу поделиться нашим опытом построения системы observability. Мы прошли путь от простых логов до сквозной трассировки, и я покажу, как это работает на фронтенде.

TL;DR: В статье разбираем опыт внедрения OpenTelemetry в крупном финтех-проекте.
Проблема: Логи без контекста не позволяют быстро найти причину 500-й ошибки в распределенной системе.
Решение: Сквозная трассировка (Distributed Tracing) от фронтенда до бэкенда.
Что внутри: Реализация CompositeLogger на TypeScript, патчинг fetch для сохранения контекста и примеры того, как превратить технические трейсы в карту бизнес-процесса. А именно - frontend реализация и практические детали интеграции.

Что мы хотели

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

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

Нам была нужна сквозная трассировка бизнес-процессов. Рассмотрим пример процесса на этой схеме:

Веб-модуль содержит форму для перевода денег. Форма может быть запущена несколько раз за время жизни веб-модуля. На форме есть шаги, и внутри этих шагов выполняются различные запросы к бекенду.

Мы хотим, чтобы весь процесс перевода денег, а по-хорошему - вся сессия внутри веб-модуля money-transfer-ui, логировалась. Тогда можно посмотреть логи, отфильтровать их,
и понять что происходило внутри.

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

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

Что такое OpenTelemetry

OpenTelemetry - это, в первую очередь, протокол, который регламентирует формат сообщений. Кроме того, это реализация API, SDK и collector сервера, который уже может пересылать логи в конкретные системы типа jaeger, prometeus, kibana, grafana etc.

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

Основные понятия в нашем контексте это trace, span, event, attribute.

• Trace. Корневая структура, внутри которой лежат дочерние элементы - span-ы. По своей сути trace это просто traceId, нужный для того чтобы объединять спаны в группы.

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

• Event. Событие, точка во времени. Есть время события, а так же атрибуты события и ссылка на span в рамках которого произошло событие.

• Attribute. Произвольная пара key-value. Сюда можно писать ваши данные, по которым можно будет фильтровать и производить поиск.

Архитектурное решение и типы

Архитектура системы

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

• Фронтенд SPA взаимодействует с продуктовыми бэкенд‑сервисами через HTTP API.

• Платформенный бэкенд недоступен для фронтенда и работает только как продюсер/консьюмер сообщений в Kafka и для обмена данными с другими бэкенд‑сервисами (эти другие бекенд сервисы у нас называются продуктовыми бекендами, у вас это может быть BFF).

• Для observability фронтенд отправляет трейсы через Audit Microservice, который проксирует их в OpenTelemetry Collector. Audit Microservice у нас используется для логирования, а теперь и трейсинга, чтобы не светить URL коллектора наружу.

• Все бэкенд‑сервисы также отдают трейсы, метрики и логи в Collector.

• Collector агрегирует данные и передаёт их в Jaeger (трейсы), Prometheus (метрики) и Kibana (логи), а Grafana используется для визуализации метрик и трейсов.

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

Архитектура frontend решения

Эту секцию можно пропустить если вас не интересует конкретика реализации решения на фронтенде.

Начнём с объявления абстракций. Главная абстракция в нашем решении - это интерфейс Logger. Данный интерфейс позволит создавать различные реализации логгера, в том числе наш OpenTelemetry logger.

/**
 * Интерфейс для логгера, который поддерживает логирование ошибок и сообщений,
 * а также может быть инициализирован с дополнительными опциями.
 */
export interface Logger {
  /**
   * Имя логгера
   */
  readonly name: string;
  /**
   * Инициализация логгера с переданными опциями.
   * Может быть использовано для настройки внешнего сервиса логирования.
   *
   * @param options - Необязательные параметры инициализации. Тип зависит от реализации.
   */
  init?(
    options?: CompositeInitOptions | SentryInitOptions | AuditInitOptions
  ): void;

  /**
   * Логирует ошибку с необязательным контекстом.
   *
   * @param error - Ошибка, которую необходимо залогировать.
   * @param context - Дополнительная информация о контексте, в котором произошла ошибка.
   */
  logError(error: Error, context?: ErrorContextType | ErrorContextType[]): void;

  /**
   * Логирует произвольное сообщение с необязательным контекстом.
   *
   * @param message - Сообщение для логирования.
   * @param context - Дополнительная контекстная информация.
   */
  logMessage?(message: string, context?: Record<string, unknown>): void;
}

CompositeLogger реализует паттерн Компоновщик.

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

Мы выбрали реализовать именно через CompositeLogger потому что такая реализация имеет ряд преимуществ. А именно:

• он позволяет скрыть реализацию от разработчиков, которые используют наше решение,

• даёт гибкость и возможность расширять набор систем логирования,

• не требует участия продуктовых команд при добавлении новой системы.

Если появляется новая система логирования - мы просто пишем ещё одну реализацию интерфейса Logger и добавляем её в CompositeLogger.

Можно не писать такой компоновщик вообще, но тогда придётся ходить по командам разработки и добавлять вызовы вручную. У нас слишком большой проект, поэтому мы решили добавить слой абстракции. Зато добавление новой системы логирования теперь происходит без участия продуктовых команд - им достаточно обновить npm-пакет.

Ниже приведён листинг CompositeLogger.
Полная реализация включает управление шагами, ошибками и sampling - здесь оставим только самые важные части.

export class CompositeLogger implements Logger {
  public readonly name = "composite";

  constructor(private readonly loggers: Logger[]) {}

  init(options?: CompositeInitOptions): void {
    this.loggers.forEach((logger) => {
      logger.init?.(options?.[logger.name as keyof CompositeInitOptions]);
    });
  }

  logError(error: Error, context?: ErrorContextType[]): void {
    this.loggers.forEach((logger) => {
      logger.logError(error, context);
    });
  }

  logMessage(message: string, context?: Record<string, unknown>): void {
    this.loggers.forEach((logger) => {
      logger.logMessage?.(message, context);
    });
  }

  startBusinessProcess(name: string, attributes?: Attributes): void {
    this.loggers.forEach((logger) => {
      if (logger.name === "otlp") {
        (logger as OtlpLogger).startBusinessProcess(name, attributes);
      }
    });
  }

  addEvent(name: string, attributes?: Attributes): void {
    this.loggers.forEach((logger) => {
      if (logger.name === "otlp") {
        (logger as OtlpLogger).addEvent(name, attributes);
      }
    });
  }
}

Код ниже предоставляет контекст, провайдер и хук для удобного использования логгера по всему приложению. Он не относится напрямую к нашей теме, скорее демонстрирует, как при помощи базовых инструментов react можно предоставить всему приложению доступ к системе логгирования.

import React, { createContext, useContext } from "react";
import { CompositeLogger } from "./composite-logger";

/**
 * Контекст для предоставления реализации логгера по всему дереву компонентов React.
 */
const LoggerContext = createContext<CompositeLogger | null>(null);

/**
 * Провайдер для внедрения логгера в дерево React-компонентов через контекст.
 *
 * @param props.logger - Реализация интерфейса `Logger`, предоставляемая потомкам.
 * @param props.children - Дочерние компоненты, которым будет доступен логгер через `useLogger`.
 */
export const LoggerProvider: React.FC<{
  logger: CompositeLogger;
  children: React.ReactNode;
}> = ({ logger, children }) => (
  <LoggerContext.Provider value={logger}>{children}</LoggerContext.Provider>
);

/**
 * Хук для получения логгера из контекста.
 * Бросает ошибку, если `LoggerProvider` не оборачивает вызывающий компонент.
 *
 * @throws {Error} Если `LoggerContext` не содержит логгер.
 * @returns {Logger} Экземпляр логгера из контекста.
 */
export const useLogger = (): CompositeLogger => {
  const logger = useContext(LoggerContext);

  if (!logger) {
    throw new Error("Logger not found in context");
  }

  return logger;
};

Класс логгера OpenTelemetry

Для OpenTelemetry логгера написана конкретная реализация интерфейса Logger.

Этот класс инициализирует SDK OpenTelemetry, патчит fetch (для наших целей это было обязательно), позволяет создавать бизнес-процессы и шаги, записывает события и ошибки. Словом - даёт возможность наполнять контекст полезной информацией.

Почему нам вообще понадобился патч fetch? Нам важно, чтобы запросы на бекенд выполнялись в рамках текущего активного спана. По умолчанию же на каждый HTTP-вызов Open Telemetry SDK создает отдельный trace.

В браузере сложно сохранять иерархию спанов, особенно при асинхронных вызовах. Для решения этой проблемы мы используем StackContextManager. Он хорошо работает на client side и довольно компактный с точки зрения влияния на размер сборки. Также StackContextManager позволяет приклеивать дочерние спаны (например, fetch) к текущему бизнес-процессу без передачи контекста в каждый метод руками.

export class OtlpLogger implements Logger {
  public readonly name = "otlp";

  private tracer?: Tracer;
  private provider?: WebTracerProvider;
  private activeSpan?: Span;

  async init(options?: OtlpInitOptions): Promise<void> {
    const provider = new WebTracerProvider({
      sampler: new TraceIdRatioBasedSampler(options?.sampleRatio ?? 1),
    });

    provider.addSpanProcessor(
      new BatchSpanProcessor(
        new OTLPTraceExporter({ url: options?.otlpUrl })
      )
    );

    provider.register({
      contextManager: new StackContextManager(),
      propagator: new B3Propagator(),
    });

    this.tracer = trace.getTracer(options?.serviceName || "frontend");
    this.provider = provider;

    this.patchFetch();
  }

  startBusinessProcess(name: string, attributes?: Attributes) {
    if (!this.tracer) return;

    this.activeSpan = this.tracer.startSpan(name, { attributes });
  }

  addEvent(name: string, attributes?: Attributes) {
    this.activeSpan?.addEvent(name, attributes);
  }

  logError(error: Error) {
    this.activeSpan?.recordException(error);
  }

  private patchFetch() {
    const originalFetch = window.fetch;

    window.fetch = async (...args) => {
      return context.with(context.active(), () =>
        originalFetch(...args)
      );
    };
  }
}

Самое главное здесь - это патчинг fetch. По умолчанию каждый HTTP-запрос создаёт новый trace. Нам же важно, чтобы запрос был частью текущего бизнес-процесса, для этого мы оборачиваем fetch в текущий контекст через context.with.

Пример использования в приложении

В нашем случае важно было разметить процесс оформления банковского перевода внутри приложения. Как можно увидеть из кода, модуль money-transfer-ui - это небольшое приложение со страницами /, /step-1, /step-2, /step-3. Каждая страница - шаг процесса перевода (* Интересный факт: по юридическим причинам вы не можете сделать все в один шаг, по крайней мере в России).

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

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

// Base dependencies
import { useEffect } from "react";
import { Routes, Route, useLocation } from "react-router-dom";

// Import pages
import { TransferPage } from "client/view/transefer-page";
import { FinalPage } from "client/view/final-page";
import { ContactPage } from "client/view/contact-page";

// Our logger package
import { useLogger } from "@my-org/logger";

// Constants moved to separate file
import { OTLP_BUISENESS_PROCESS_STEP_NAMES } from "client/system/otlp-logger-utils/constants";

export const AppRoutes = () => {
  const logger = useLogger();
  const location = useLocation();

  useEffect(() => {
    switch (location.pathname) {
      case "/":

      case "/step-1":
        logger.startBusinessProcessStep(
          OTLP_BUISENESS_PROCESS_STEP_NAMES.CHOOSING_A_PAYEE
        );
        break;

      case "/step-2":
        logger.startBusinessProcessStep(
          OTLP_BUISENESS_PROCESS_STEP_NAMES.SETTING_UP_A_PAYMENT
        );
        break;

      case "/step-3":
        logger.startBusinessProcessStep(
          OTLP_BUISENESS_PROCESS_STEP_NAMES.PAYMENT_COMPLETION
        );
        break;

      default:
        break;
    }

    return () => {
      if (location.pathname === "/step-3") {
        logger.endBusinessProcess();
      }

      logger.endBusinessProcessStep();
    };
  }, [location]);

  return (
    <Routes>
      <Route path="/" element={<ContactPage />} />
      <Route path="/step-1" element={<ContactPage />} />
      <Route path="/step-2" element={<TransferPage />} />
      <Route path="/step-3" element={<FinalPage />} />
    </Routes>
  );
};

Примеры трейсов, записанных при помощи нашего SDK

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

В результате, после разметки процесса можно получить полноценный таймлайн. На скриншоте видно, что в рамках Payment пользователь прошел шаги choosing a payee, setting up a recipient, setting up a payment, payment completed. Сразу видно, что на втором шаге в логику формы закралась ошибка. Если бекенд ответил ошибкой - пользователя нельзя пускать на следующие шаги, а здесь он был пропущен дальше.

Но прелесть OpenTelemetry в том, что далее мы можем посмотреть, что стало причиной ошибки:

Система сквозных идентификаторов (traceId) позволяет сопоставить ошибку на фронте и увидеть, что бек ответил с ошибкой по причине таймаута интеграции.

Этот пример простой, но бекенды могут пробрасывать сквозные идентификаторы (traceId и spanId) дальше и в интеграцию, и в kafka, и между собой. OpenTelemetry SDK предоставляет для этого инструментарий. В этом случае мы увидим еще большую детализацию в глубину.

Известные ограничения

Несмотря на то что OpenTelemetry - уже устоявшийся стандарт для работы с трейсами, все еще есть различные ограничения.

• OpenTelemetry писался для бекенда, поэтому на стороне фронта его больно использовать, особенно за рамками стандартных задач, описанных в документации.

• Сам SDK достаточно тяжелый. Если вам важен каждый байт, то вам придется разбираться с асинхронной загрузкой чанков телеметрии и проставить им приоритеты. Однако после всех улучшений станет значительно быстрее, чем из коробки.

• Если хочется спаном считать сессию (как в нашем примере), то вам придется писать костыли, просто потому что невозможно отследить событие завершения сессии (в нашем случае - уничтожение web-view). Да, на десктопе вы можете подписаться на onbeforeunload и использовать sendBeacon, но все это не железные 100% рабочие методы.

Заключение

OpenTelemetry часто сравнивают с Sentry, но я не буду комментировать это сравнение тут. Дело в том что sentry в нашем проекте тоже используется, в основном для снятия технических фронтовых метрик (web-vitals, метрики кеширования, ошибки технического характера). OpenTelemetry же у нас используется для разметки бизнес процессов, а так же для того, чтобы получить срез процесса по всей инфраструктуре, которая в нем участвует. Если тема сравнения OpenTelemetry и Sentry будет актуальна, я напишу отдельный пост.

Нужно ли всем заносить OpenTelemetry? Однозначно нет. Если у вас простая система, пара десятков сервисов, вам скорее всего хватит обычных логов. Если же у вас зоопарк из сервисов, они появляются быстрее, чем вы можете это контролировать и вам нужно надежное решение для обвязки ключевых процессов мониторингом - имеет смысл посмотреть в сторону OpenTelemetry.

Как вы решаете проблему сквозной аналитики в больших проектах? Пишите комментарии, будет интересно узнать ваши сетапы.