Оптимизация SentryTarget класса

Ваш класс SentryTarget выглядит достаточно продуманным и функциональным. Однако всегда есть возможности для улучшения кода с точки зрения читаемости, производительности и поддержки. Ниже приведены рекомендации, которые помогут оптимизировать и улучшить ваш код:

1. Улучшение читаемости и поддерживаемости кода

• Использование констант для уровней логирования и тегов:

  Вместо жестко закодированных строк используйте константы. Это уменьшит вероятность ошибок и упростит изменение значений в будущем.

  php
  class SentryTarget extends BaseSentryTarget
  {
      private const LEVEL_ERROR = Logger::LEVEL_ERROR;
      private const LEVEL_WARNING = Logger::LEVEL_WARNING;
  
      private const TAG_ROUTE = 'route';
      private const TAG_APP_ID = 'app-id';
      private const TAG_TRACE_ID = 'trace-id';
      
      // Остальной код...
  }

• Централизация тегов:

  Создайте метод для генерации общих тегов, чтобы избежать дублирования кода.

  php
  private function getCommonTags(string $operationName, string $traceId): array
  {
      return [
          self::TAG_ROUTE => $operationName,
          self::TAG_APP_ID => Yii::$app->id,
          self::TAG_TRACE_ID => $traceId,
      ];
  }

2. Оптимизация вызовов Sentry SDK

• Сокращение повторных вызовов SentrySdk::getCurrentHub():

  Сохраните ссылку на хаб Sentry в переменную, чтобы избежать многократных вызовов статического метода.

  php
  public function export()
  {
      if (empty($this->messages)) {
          return;
      }
  
      $hub = SentrySdk::getCurrentHub();
  
      // Остальной код с использованием $hub вместо повторных вызовов
  }

3. Улучшение обработки сообщений

• Проверка структуры сообщения:

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

  php
  foreach ($this->messages as $message) {
      if (count($message) < 6) {
          // Логирование или пропуск некорректных сообщений
          continue;
      }
  
      [$text, $level, $action, $timestamp, $stackTrace, $memory] = $message;
  
      // Остальной код...
  }

• Использование строгой типизации:

  Добавьте типы параметров и возвращаемых значений для методов, что повысит безопасность и читаемость кода.

  php
  private function determineOperationName(): string
  {
      // Код метода...
  }
  
  private function buildSpanData(array $message): array
  {
      // Код метода...
  }

4. Улучшение обработки исключений

• Более детальная обработка ошибок:

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

  php
  catch (Throwable $exception) {
      // Логирование исключения в Yii лог
      Yii::error('Error exporting to Sentry: ' . $exception->getMessage(), __METHOD__);
      
      // Также отправка исключения в Sentry
      $hub->captureException($exception);
  }

5. Оптимизация формирования стектрейса

• Использование встроенных возможностей Sentry для захвата стека:

  Вместо ручного создания фреймов стека можно использовать встроенные возможности Sentry для автоматического захвата стека вызовов.

  php
  if (is_array($stackTrace) && !empty($stackTrace)) {
      $event->setStacktrace(StacktraceBuilder::fromBacktrace($stackTrace));
  }

6. Улучшение метода determineOperationName

• Использование вспомогательных методов для формирования названия операции:

  Это повысит читаемость и облегчит тестирование.

  php
  private function determineOperationName(): string
  {
      if (Yii::$app instanceof ConsoleApplication) {
          return $this->getConsoleOperationName();
      } elseif (Yii::$app instanceof WebApplication) {
          return $this->getWebOperationName();
      }
  
      return 'application';
  }
  
  private function getConsoleOperationName(): string
  {
      $controller = Yii::$app->controller;
      if ($controller instanceof ConsoleController) {
          $commandName = Yii::$app->requestedRoute;
          $args = implode(' ', Yii::$app->request->getArgs());
          return "console.{$commandName} {$args}";
      }
      return 'console';
  }
  
  private function getWebOperationName(): string
  {
      $controller = Yii::$app->controller;
      if ($controller instanceof WebController) {
          $module = $controller->module->id ?? 'app';
          $controllerId = $controller->id;
          $actionId = $controller->action->id ?? 'index';
          return "web.{$module}.{$controllerId}.{$actionId}";
      }
      return 'web';
  }

7. Безопасность и обработка данных

• Избегайте использования var_export для данных, содержащих потенциально чувствительную информацию:

  Если text может содержать конфиденциальные данные, рассмотрите возможность их фильтрации или маскировки перед отправкой в Sentry.

  php
  private function exportText($text): string
  {
      if (is_array($text)) {
          // Фильтрация или маскировка чувствительных данных
          return json_encode($text, JSON_UNESCAPED_UNICODE);
      }
  
      return (string)$text;
  }

  Затем используйте этот метод при формировании сообщений:

  php
  $textExport = $this->exportText($text);

8. Документирование кода

• Добавление PHPDoc комментариев:

  Это поможет другим разработчикам (и вам в будущем) лучше понимать назначение методов и их параметры.

  php
  /**
   * Экспортирует накопленные сообщения в Sentry.
   *
   * @return void
   */
  public function export(): void
  {
      // Код метода...
  }
  
  /**
   * Определяет название операции для транзакции на основе типа приложения и контекста запроса.
   *
   * @return string Название операции.
   */
  private function determineOperationName(): string
  {
      // Код метода...
  }
  
  /**
   * Строит данные для спана на основе сообщения.
   *
   * @param array $message Сообщение логирования.
   * @return array Данные для спана.
   */
  private function buildSpanData(array $message): array
  {
      // Код метода...
  }

9. Соответствие стандартам кодирования

• Следование PSR-12:

  Убедитесь, что ваш код соответствует стандарту PSR-12 для PHP, что повысит его читаемость и облегчит интеграцию с другими проектами.

10. Тестирование и покрытие кода

• Написание юнит-тестов:

  Добавьте тесты для вашего класса, чтобы гарантировать корректность его работы и облегчить будущие изменения.

11. Использование современных возможностей PHP

• Использование match вместо if-elseif:

  Если вы используете PHP 8.0 или выше, можно использовать конструкцию match для определения типа приложения.

  php
  private function determineOperationName(): string
  {
      return match (true) {
          Yii::$app instanceof ConsoleApplication => $this->getConsoleOperationName(),
          Yii::$app instanceof WebApplication => $this->getWebOperationName(),
          default => 'application',
      };
  }

12. Управление транзакциями и спанами

• Проверка, активна ли транзакция перед завершением:

  Это поможет избежать потенциальных ошибок при завершении транзакции.

  php
  if ($transaction->isActive()) {
      $transaction->finish($finalTimestamp);
  }

Итоговый пример улучшенного кода

Ниже приведен обновленный пример класса с учетом некоторых из вышеупомянутых рекомендаций:

php
<?php

namespace common\components\log;

use notamedia\sentry\SentryTarget as BaseSentryTarget;
use Sentry\Event;
use Sentry\EventHint;
use Sentry\Frame;
use Sentry\SentrySdk;
use Sentry\Severity;
use Sentry\Stacktrace;
use Sentry\Tracing\SpanContext;
use Sentry\Tracing\TraceId;
use Sentry\Tracing\TransactionContext;
use Yii;
use yii\console\Application as ConsoleApplication;
use yii\console\Controller as ConsoleController;
use yii\web\Application as WebApplication;
use yii\web\Controller as WebController;
use yii\log\Logger;
use Throwable;

class SentryTarget extends BaseSentryTarget
{
    private const LEVEL_ERROR = Logger::LEVEL_ERROR;
    private const LEVEL_WARNING = Logger::LEVEL_WARNING;

    private const TAG_ROUTE = 'route';
    private const TAG_APP_ID = 'app-id';
    private const TAG_TRACE_ID = 'trace-id';

    /**
     * Экспортирует накопленные сообщения в Sentry.
     *
     * @return void
     */
    public function export(): void
    {
        if (empty($this->messages)) {
            return;
        }

        $hub = SentrySdk::getCurrentHub();
        $applicationRunId = preg_replace("/-/", '', Yii::$app->getRequest()->applicationRunId);
        $operationName = $this->determineOperationName();
        $commonTags = $this->getCommonTags($operationName, $applicationRunId);

        // Используем timestamp первого сообщения как старт транзакции
        $firstMessage = reset($this->messages);
        $startTimestamp = $firstMessage[3] ?? microtime(true);

        $transactionContext = new TransactionContext();
        $transactionContext->setName($operationName);
        $transactionContext->setOp(Yii::$app->id);
        $transactionContext->setDescription($operationName);
        $transactionContext->setTraceId(new TraceId($applicationRunId));
        $transactionContext->setStartTimestamp($startTimestamp);
        $transactionContext->setTags($commonTags);
        $transactionContext->setSampled(true);

        $transaction = $hub->startTransaction($transactionContext);
        $hub->setSpan($transaction);

        foreach ($this->messages as $message) {
            if (count($message) < 6) {
                Yii::warning('Некорректное сообщение для Sentry', __METHOD__);
                continue;
            }

            [$text, $level, $action, $timestamp, $stackTrace, $memory] = $message;
            $textExport = $this->exportText($text);

            $spanContext = new SpanContext();
            $spanContext->setOp($action);
            $spanContext->setTags($commonTags + ['action' => $action]);
            $spanContext->setDescription($textExport);
            $spanContext->setStartTimestamp($startTimestamp);
            $spanContext->setSampled(true);
            $spanContext->setData($this->buildSpanData($message));

            $span = $transaction->startChild($spanContext);

            if (in_array($level, [self::LEVEL_ERROR, self::LEVEL_WARNING], true)) {
                if ($text instanceof Throwable) {
                    $hub->captureException($text);
                } else {
                    $event = $this->createSentryEvent($textExport, $level, $action, $commonTags, $stackTrace, $startTimestamp);
                    $hub->captureEvent($event, $this->getExceptionHint($text));
                }
            }

            $span->finish($timestamp);
            $startTimestamp = $timestamp;
        }

        $lastMessage = end($this->messages);
        $finalTimestamp = $lastMessage[3] ?? microtime(true);
        if ($transaction->isActive()) {
            $transaction->finish($finalTimestamp);
        }
    }

    /**
     * Определяет название операции для транзакции на основе типа приложения и контекста запроса.
     *
     * @return string Название операции.
     */
    private function determineOperationName(): string
    {
        return match (true) {
            Yii::$app instanceof ConsoleApplication => $this->getConsoleOperationName(),
            Yii::$app instanceof WebApplication => $this->getWebOperationName(),
            default => 'application',
        };
    }

    private function getConsoleOperationName(): string
    {
        $controller = Yii::$app->controller;
        if ($controller instanceof ConsoleController) {
            $commandName = Yii::$app->requestedRoute;
            $args = implode(' ', Yii::$app->request->getArgs());
            return "console.{$commandName} {$args}";
        }
        return 'console';
    }

    private function getWebOperationName(): string
    {
        $controller = Yii::$app->controller;
        if ($controller instanceof WebController) {
            $module = $controller->module->id ?? 'app';
            $controllerId = $controller->id;
            $actionId = $controller->action->id ?? 'index';
            return "web.{$module}.{$controllerId}.{$actionId}";
        }
        return 'web';
    }

    private function getCommonTags(string $operationName, string $traceId): array
    {
        return [
            self::TAG_ROUTE => $operationName,
            self::TAG_APP_ID => Yii::$app->id,
            self::TAG_TRACE_ID => $traceId,
        ];
    }

    /**
     * Формирует данные для спана на основе сообщения.
     *
     * @param array $message Сообщение логирования.
     * @return array Данные для спана.
     */
    private function buildSpanData(array $message): array
    {
        [$text, $level, $action, $timestamp, $stackTrace, $memoryUsages] = $message;
        $user = Yii::$app->user ?? null;

        return [
            'level'     => Logger::getLevelName($level),
            'action'    => $action,
            'timestamp' => $timestamp,
            'user'      => $user ? $user->getId() : 'CLI',
            'memory'    => $memoryUsages,
            'trace'     => $stackTrace,
            'message'   => $this->exportText($text),
        ];
    }

    /**
     * Создает Sentry Event на основе предоставленных данных.
     *
     * @param string $message Сообщение.
     * @param string $level Уровень логирования.
     * @param string $action Действие.
     * @param array $tags Теги.
     * @param array|null $stackTrace Стектрейс.
     * @param float $timestamp Временная метка.
     * @return Event
     */
    private function createSentryEvent(string $message, string $level, string $action, array $tags, ?array $stackTrace, float $timestamp): Event
    {
        $event = Event::createEvent();
        $event->setFingerprint([$level, $action, $tags[self::TAG_ROUTE], $tags[self::TAG_APP_ID]]);
        $event->setTags($tags);
        $event->setMessage($message);

        $severity = $level === self::LEVEL_WARNING ? Severity::warning() : Severity::error();
        $event->setLevel($severity);
        $event->setStartTimestamp($timestamp);

        if (is_array($stackTrace) && !empty($stackTrace)) {
            $frames = array_map(fn($frameData) => new Frame(
                $frameData['file'] ?? null,
                $frameData['line'] ?? null,
                $frameData['function'] ?? null,
                $frameData['class'] ?? null
            ), $stackTrace);

            if (!empty($frames)) {
                $event->setStacktrace(new Stacktrace($frames));
            }
        }

        return $event;
    }

    /**
     * Получает подсказку для события на основе текста сообщения.
     *
     * @param mixed $text Текст сообщения.
     * @return EventHint|null
     */
    private function getExceptionHint($text): ?EventHint
    {
        if (is_array($text) && isset($text['exception']) && $text['exception'] instanceof Throwable) {
            return EventHint::fromArray(['exception' => $text['exception']]);
        }

        return null;
    }

    /**
     * Форматирует текст сообщения для отправки в Sentry.
     *
     * @param mixed $text Текст сообщения.
     * @return string
     */
    private function exportText($text): string
    {
        if (is_array($text)) {
            return json_encode($text, JSON_UNESCAPED_UNICODE);
        }

        return (string)$text;
    }
}

Дополнительные рекомендации

• Логирование внутри класса SentryTarget:

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

• Конфигурация Sentry SDK:

  Убедитесь, что все необходимые настройки Sentry (DSN, уровни логирования, теги по умолчанию и т.д.) правильно сконфигурированы, возможно, через конфигурационные файлы Yii.

• Мониторинг производительности:

  Если объем логов большой, отслеживайте влияние экспорта в Sentry на производительность приложения и при необходимости оптимизируйте этот процесс (например, используя очереди или асинхронные задачи).

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

Понял, вы хотите получить рекомендации по улучшению функции export, которая экспортирует накопленные сообщения в Sentry. Рассмотрим текущую реализацию функции и предложим возможные улучшения для повышения эффективности, читаемости и надежности.

Текущая реализация функции export

Для удобства, приведу кратко основную структуру функции export из вашего класса SentryTarget:

php
public function export()
{
    if (empty($this->messages)) {
        return;
    }

    $applicationRunId = preg_replace("/-/", '', Yii::$app->getRequest()->applicationRunId);
    $operationName = $this->determineOperationName();

    // Используем timestamp первого сообщения как старт транзакции
    $firstMessage = reset($this->messages);
    $startTimestamp = $firstMessage[3] ?? microtime(true);

    $transactionContext = new TransactionContext();
    // Настройка контекста транзакции...
    $transaction = SentrySdk::getCurrentHub()->startTransaction($transactionContext);
    SentrySdk::getCurrentHub()->setSpan($transaction);

    foreach ($this->messages as $message) {
        try {
            [$text, $level, $action, $timestamp, $stackTrace, $memory] = $message;
            $textExport = is_array($text) ? var_export($text, true) : (string)$text;

            // Создание и настройка спана
            $spanContext = new SpanContext();
            // Настройка контекста спана...
            $span = $transaction->startChild($spanContext);

            // Обработка ошибок и предупреждений
            if (in_array($level, [Logger::LEVEL_ERROR, Logger::LEVEL_WARNING], true)) {
                if ($text instanceof Throwable) {
                    SentrySdk::getCurrentHub()->captureException($text);
                } else {
                    // Создание и настройка события
                    $event = Event::createEvent();
                    // Настройка события...
                    SentrySdk::getCurrentHub()->captureEvent(
                        $event,
                        EventHint::fromArray(array_filter((array)$exceptionHint))
                    );
                }
            }

            // Завершение спана
            $span->finish($timestamp);
            $startTimestamp = $timestamp;
        } catch (Throwable $exception) {
            SentrySdk::getCurrentHub()->captureException($exception);
        }
    }

    // Завершение транзакции
    $lastMessage = end($this->messages);
    $finalTimestamp = $lastMessage[3] ?? microtime(true);
    $transaction->finish($finalTimestamp);
}

Рекомендации по улучшению функции export

1. Оптимизация доступа к Sentry Hub:

   Вместо многократных вызовов SentrySdk::getCurrentHub(), лучше сохранить ссылку на хаб в переменную. Это улучшит читаемость и потенциально повысит производительность.

   php
   $hub = SentrySdk::getCurrentHub();

2. Использование транзакций и спанов с проверкой на активность:

   Перед завершением транзакции убедитесь, что она все еще активна. Это предотвратит возможные ошибки в случае непредвиденных ситуаций.

   php
   if ($transaction->isActive()) {
       $transaction->finish($finalTimestamp);
   }

3. Улучшение обработки сообщений:

   • Проверка структуры сообщений:

     Перед разбором сообщения убедитесь, что оно содержит ожидаемое количество элементов. Это предотвратит ошибки деструктуризации.

     php
     if (count($message) < 6) {
         Yii::warning('Некорректное сообщение для Sentry', __METHOD__);
         continue;
     }

   • Использование строгой типизации:

     Убедитесь, что все используемые переменные имеют ожидаемые типы данных.

4. Централизация тегов и использование констант:

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

   php
   private const LEVEL_ERROR = Logger::LEVEL_ERROR;
   private const LEVEL_WARNING = Logger::LEVEL_WARNING;
   
   private const TAG_ROUTE = 'route';
   private const TAG_APP_ID = 'app-id';
   private const TAG_TRACE_ID = 'trace-id';

   И использование метода для получения общих тегов:

   php
   private function getCommonTags(string $operationName, string $traceId): array
   {
       return [
           self::TAG_ROUTE => $operationName,
           self::TAG_APP_ID => Yii::$app->id,
           self::TAG_TRACE_ID => $traceId,
       ];
   }

5. Улучшение формирования стектрейса:

   Вместо ручного создания фреймов стека, можно использовать встроенные методы Sentry для построения стектрейса.

   php
   if (is_array($stackTrace) && !empty($stackTrace)) {
       $event->setStacktrace(StacktraceBuilder::fromBacktrace($stackTrace));
   }

6. Асинхронная отправка данных:

   Если объем логов велик, рассмотрите возможность отправки данных в Sentry асинхронно, чтобы не блокировать основной поток выполнения приложения. Это можно реализовать с помощью очередей (например, RabbitMQ, Redis) или фоновых задач.

7. Фильтрация чувствительных данных:

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

   php
   private function exportText($text): string
   {
       if (is_array($text)) {
           // Фильтрация или маскировка чувствительных данных
           return json_encode($text, JSON_UNESCAPED_UNICODE);
       }
   
       return (string)$text;
   }

8. Добавление логирования внутри класса:

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

   php
   catch (Throwable $exception) {
       Yii::error('Error exporting to Sentry: ' . $exception->getMessage(), __METHOD__);
       $hub->captureException($exception);
   }

9. Использование типов и строгой типизации:

   Добавьте типы параметров и возвращаемых значений для методов, что повысит безопасность и читаемость кода.

   php
   /**
    * Экспортирует накопленные сообщения в Sentry.
    *
    * @return void
    */
   public function export(): void
   {
       // Код метода...
   }

10. Разделение логики на небольшие методы:

    Разделите сложные блоки кода на отдельные методы для повышения читаемости и упрощения тестирования.

    php
    private function createSentryEvent(string $message, string $level, string $action, array $tags, ?array $stackTrace, float $timestamp): Event
    {
        // Создание и настройка события...
    }
    
    private function getExceptionHint($text): ?EventHint
    {
        // Получение подсказки для события...
    }

11. Использование современных возможностей PHP:

    Если вы используете PHP 8.0 или выше, можно использовать конструкцию match для более читаемого определения типа приложения.

    php
    private function determineOperationName(): string
    {
        return match (true) {
            Yii::$app instanceof ConsoleApplication => $this->getConsoleOperationName(),
            Yii::$app instanceof WebApplication => $this->getWebOperationName(),
            default => 'application',
        };
    }

12. Документирование кода:

    Добавьте PHPDoc комментарии к методам для улучшения понимания кода другими разработчиками и инструментами анализа.

    php
    /**
     * Экспортирует накопленные сообщения в Sentry.
     *
     * @return void
     */
    public function export(): void
    {
        // Код метода...
    }

Пример улучшенной функции export

Ниже приведен обновленный пример функции export с учетом вышеуказанных рекомендаций:

php
public function export(): void
{
    if (empty($this->messages)) {
        return;
    }

    $hub = SentrySdk::getCurrentHub();
    $applicationRunId = preg_replace("/-/", '', Yii::$app->getRequest()->applicationRunId);
    $operationName = $this->determineOperationName();
    $commonTags = $this->getCommonTags($operationName, $applicationRunId);

    // Используем timestamp первого сообщения как старт транзакции
    $firstMessage = reset($this->messages);
    $startTimestamp = $firstMessage[3] ?? microtime(true);

    $transactionContext = new TransactionContext();
    $transactionContext->setName($operationName);
    $transactionContext->setOp(Yii::$app->id);
    $transactionContext->setDescription($operationName);
    $transactionContext->setTraceId(new TraceId($applicationRunId));
    $transactionContext->setStartTimestamp($startTimestamp);
    $transactionContext->setTags($commonTags);
    $transactionContext->setSampled(true);

    $transaction = $hub->startTransaction($transactionContext);
    $hub->setSpan($transaction);

    foreach ($this->messages as $message) {
        if (count($message) < 6) {
            Yii::warning('Некорректное сообщение для Sentry', __METHOD__);
            continue;
        }

        [$text, $level, $action, $timestamp, $stackTrace, $memory] = $message;
        $textExport = $this->exportText($text);

        $spanContext = new SpanContext();
        $spanContext->setOp($action);
        $spanContext->setTags($commonTags + ['action' => $action]);
        $spanContext->setDescription($textExport);
        $spanContext->setStartTimestamp($startTimestamp);
        $spanContext->setSampled(true);
        $spanContext->setData($this->buildSpanData($message));

        $span = $transaction->startChild($spanContext);

        if (in_array($level, [self::LEVEL_ERROR, self::LEVEL_WARNING], true)) {
            if ($text instanceof Throwable) {
                $hub->captureException($text);
            } else {
                $event = $this->createSentryEvent($textExport, $level, $action, $commonTags, $stackTrace, $startTimestamp);
                $hub->captureEvent($event, $this->getExceptionHint($text));
            }
        }

        $span->finish($timestamp);
        $startTimestamp = $timestamp;
    }

    $lastMessage = end($this->messages);
    $finalTimestamp = $lastMessage[3] ?? microtime(true);
    if ($transaction->isActive()) {
        $transaction->finish($finalTimestamp);
    }
}

Дополнительные рекомендации

1. Тестирование:

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

2. Мониторинг производительности:

   Если объем логов большой, отслеживайте влияние экспорта в Sentry на производительность приложения. Рассмотрите возможность использования очередей или фоновых задач для обработки логов.

3. Конфигурация Sentry SDK:

   Убедитесь, что все необходимые настройки Sentry (например, DSN, уровни логирования, теги по умолчанию) правильно сконфигурированы, возможно, через конфигурационные файлы Yii.

4. Обработка специфичных случаев:

   Рассмотрите возможность обработки других уровней логирования или типов сообщений, если это необходимо для вашего приложения.

5. Документация:

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

Следуя этим рекомендациям, вы сможете сделать функцию export более эффективной, надежной и удобной для поддержки. Если у вас есть конкретные вопросы или требуется помощь с определенными аспектами функции, пожалуйста, уточните, и я с радостью помогу!

Конечно! Давайте подробно разберем, как функция export из вашего класса SentryTarget экспортирует накопленные сообщения в Sentry. Мы рассмотрим процесс пошагово, начиная от получения запроса (через консоль или веб) до отправки данных в Sentry.

Общая картина

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

Пошаговое объяснение функции export

1. Проверка наличия сообщений для экспорта

   php
   if (empty($this->messages)) {
       return;
   }

   • Что происходит: Функция проверяет, есть ли накопленные сообщения для отправки. Если сообщений нет ($this->messages пустой), функция завершает работу.
   • Зачем: Избегает ненужных вызовов к Sentry, если нет данных для отправки, что повышает производительность.

2. Подготовка идентификатора выполнения приложения и определения названия операции

   php
   $applicationRunId = preg_replace("/-/", '', Yii::$app->getRequest()->applicationRunId);
   $operationName = $this->determineOperationName();

   • Что происходит:
     • applicationRunId: Получает уникальный идентификатор выполнения приложения, удаляя все дефисы. Этот идентификатор используется для отслеживания транзакций.
     • operationName: Вызывает метод determineOperationName(), который определяет название текущей операции на основе типа приложения (консольное или веб).
   • Зачем: Эти данные будут использоваться для создания контекста транзакции в Sentry, что поможет лучше понять, где и как происходят ошибки или замедления.

3. Инициализация Sentry Hub и создание транзакции

   php
   $hub = SentrySdk::getCurrentHub();
   
   // Используем timestamp первого сообщения как старт транзакции
   $firstMessage = reset($this->messages);
   $startTimestamp = $firstMessage[3] ?? microtime(true);
   
   $transactionContext = new TransactionContext();
   $transactionContext->setName($operationName);
   $transactionContext->setOp(Yii::$app->id);
   $transactionContext->setDescription($operationName);
   $transactionContext->setTraceId(new TraceId($applicationRunId));
   $transactionContext->setStartTimestamp($startTimestamp);
   $transactionContext->setTags([
       'route' => $operationName,
       'app-id' => Yii::$app->id,
       'trace-id' => $applicationRunId
   ]);
   $transactionContext->setSampled(true);
   
   $transaction = $hub->startTransaction($transactionContext);
   $hub->setSpan($transaction);

   • Что происходит:
     • Sentry Hub: Получает текущий Sentry Hub, который управляет отправкой данных в Sentry.
     • Начальный таймштамп: Использует временную метку первого сообщения как начало транзакции.
     • TransactionContext: Создает контекст транзакции с информацией о текущей операции, приложении, идентификаторе трассировки и тегах.
     • Создание транзакции: Начинает транзакцию с заданным контекстом и устанавливает её как текущую активную спан.
   • Зачем:
     • Транзакции и спаны: Позволяют отслеживать производительность и время выполнения различных частей приложения. Транзакция представляет собой высокоуровневую операцию (например, обработка HTTP-запроса), а спаны — её подзадачи.
     • Теги и контекст: Обеспечивают дополнительную информацию для анализа в Sentry.

4. Обработка каждого сообщения лога

   php
   foreach ($this->messages as $message) {
       try {
           [$text, $level, $action, $timestamp, $stackTrace, $memory] = $message;
           $textExport = is_array($text) ? var_export($text, true) : (string)$text;
   
           // Параметры для спанов
           $spanContext = new SpanContext();
           $spanContext->setOp($action);
           $spanContext->setTags([
               'action' => $action,
               'route' => $operationName,
               'app-id' => Yii::$app->id,
               'trace-id' => $applicationRunId
           ]);
           $spanContext->setDescription($textExport);
           $spanContext->setStartTimestamp($startTimestamp);
           $spanContext->setSampled(true);
           $spanContext->setData($this->buildSpanData($message));
   
           // Старт спана
           $span = $transaction->startChild($spanContext);
   
           // Обработка ошибки или предупреждения
           if (in_array($level, [Logger::LEVEL_ERROR, Logger::LEVEL_WARNING], true)) {
               if ($text instanceof Throwable) {
                   // Если это реальный Throwable, отправим как исключение
                   $hub->captureException($text);
               } else {
                   // В остальных случаях создаем ивент вручную
                   $event = Event::createEvent();
                   $event->setFingerprint([$level, $action, $operationName, Yii::$app->id]);
                   $event->setTags([
                       'action' => $action,
                       'route' => $operationName,
                       'app-id' => Yii::$app->id,
                       'trace-id' => $applicationRunId
                   ]);
                   $event->setMessage($textExport);
   
                   // Установка уровня серьёзности
                   $severity = $level === Logger::LEVEL_WARNING ? Severity::warning() : Severity::error();
                   $event->setLevel($severity);
                   $event->setStartTimestamp($startTimestamp);
   
                   // Формирование стектрейса, если доступен
                   if (is_array($stackTrace) && !empty($stackTrace)) {
                       $frames = [];
                       foreach ($stackTrace as $frameData) {
                           $frames[] = new Frame(
                               $frameData['file'] ?? null,
                               $frameData['line'] ?? null,
                               $frameData['function'] ?? null,
                               $frameData['class'] ?? null
                           );
                       }
                       if (!empty($frames)) {
                           $event->setStacktrace(new Stacktrace($frames));
                       }
                   }
   
                   // Если есть информация об исключении в тексте
                   $exceptionHint = null;
                   if (is_array($text) && isset($text['exception']) && $text['exception'] instanceof Throwable) {
                       $exceptionHint = ['exception' => $text['exception']];
                   }
   
                   $hub->captureEvent(
                       $event,
                       EventHint::fromArray(array_filter((array)$exceptionHint))
                   );
               }
           }
   
           // Завершение спана
           $span->finish($timestamp);
           $startTimestamp = $timestamp;
       } catch (Throwable $exception) {
           $hub->captureException($exception);
       }
   }

   • Что происходит:

     1. Итерация по сообщениям:
        • Перебирает каждое сообщение лога из $this->messages.
     2. Разбор сообщения:
        • Распаковывает сообщение на составляющие: текст ($text), уровень ($level), действие ($action), временная метка ($timestamp), стек-трейс ($stackTrace), использование памяти ($memory).
        • Преобразует текст в строку, если он является массивом.
     3. Создание контекста спана:
        • Создает SpanContext с информацией о текущем действии, тегах, описании и временной метке.
        • Добавляет дополнительные данные через метод buildSpanData($message).
     4. Старт спана:
        • Создает дочерний спан для текущей транзакции.
     5. Обработка ошибок и предупреждений:
        • Если уровень лога соответствует ошибке (LEVEL_ERROR) или предупреждению (LEVEL_WARNING):
          • Если текст является экземпляром Throwable: Отправляет исключение напрямую в Sentry через captureException.
          • Иначе: Создает вручную событие (Event), устанавливает его свойства (сообщение, уровень, теги, стек-трейс) и отправляет через captureEvent.
     6. Завершение спана:
        • Завершает спан с текущей временной меткой.
        • Обновляет startTimestamp для следующего спана.
     7. Обработка исключений внутри цикла:
        • Любые исключения, возникающие в процессе обработки сообщений, отправляются в Sentry для дальнейшего анализа.

   • Зачем:

     • Спаны: Позволяют детализировать действия внутри транзакции, предоставляя информацию о времени выполнения каждой подзадачи.
     • Ошибки и предупреждения: Отправка в Sentry позволяет отслеживать и анализировать проблемы в приложении.
     • Стек-трейс: Помогает в диагностике проблем, показывая, где именно произошла ошибка.

5. Завершение транзакции

   php
   $lastMessage = end($this->messages);
   $finalTimestamp = $lastMessage[3] ?? microtime(true);
   $transaction->finish($finalTimestamp);

   • Что происходит:
     • Получает временную метку последнего сообщения.
     • Завершает транзакцию с этой временной меткой.
   • Зачем:
     • Завершение транзакции позволяет Sentry вычислить общее время выполнения операции и собрать все связанные спаны.

Работа в контексте консольных и веб-запросов

Функция export учитывает, откуда пришел запрос — из консоли или из веб. Это влияет на определение названия операции (operationName), что, в свою очередь, отражается в транзакциях и спанах.

Определение названия операции

Метод determineOperationName() отвечает за определение контекста операции:

php
private function determineOperationName(): string
{
    if (Yii::$app instanceof ConsoleApplication) {
        // Для консольных приложений используем имя команды и аргументы
        $controller = Yii::$app->controller;
        if ($controller instanceof ConsoleController) {
            $commandName = Yii::$app->requestedRoute;
            $args = implode(' ', Yii::$app->request->getArgs());
            return "console.{$commandName} {$args}";
        }
        return 'console';
    } elseif (Yii::$app instanceof WebApplication) {
        // Для веб-приложений используем модуль, контроллер и действие
        $controller = Yii::$app->controller;
        if ($controller instanceof WebController) {
            $module = Yii::$app->controller->module->id ?? 'app';
            $controllerId = Yii::$app->controller->id;
            $actionId = Yii::$app->controller->action->id ?? 'index';
            return "web.{$module}.{$controllerId}.{$actionId}";
        }
        return 'web';
    }

    // По умолчанию
    return 'application';
}

• Консольные запросы:

  • Формируют название операции на основе имени команды и ее аргументов, например: console.migrate --migrationPath=@app/migrations.
  • Это позволяет отслеживать, какие команды выполнялись и с какими параметрами.

• Веб-запросы:

  • Формируют название операции на основе модуля, контроллера и действия, например: web.site.index.
  • Это позволяет отслеживать, какие маршруты обрабатывались и какие действия выполнялись.

• По умолчанию:

  • Если приложение не является ни консольным, ни веб-приложением, название операции устанавливается как application.

Создание и использование спанов и транзакций

• Транзакция (Transaction):

  • Представляет собой высокоуровневую операцию, такую как обработка HTTP-запроса или выполнение консольной команды.
  • Содержит информацию о времени начала и окончания операции, а также связанные спаны.

• Спан (Span):

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

• Зачем использовать транзакции и спаны:

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

Отправка данных в Sentry

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

Особенности работы под капотом

1. Sentry SDK:

   • Ваш класс использует Sentry SDK для PHP, который обрабатывает взаимодействие с сервисом Sentry.
   • SDK управляет хабами, транзакциями и спанами, обеспечивает отправку данных и обработку ошибок.

2. Контекст приложения:

   • Информация о приложении (например, идентификатор, модуль, контроллер) добавляется как теги, что упрощает фильтрацию и поиск в Sentry.

3. Управление исключениями:

   • Исключения (Throwable) автоматически отправляются в Sentry через captureException.
   • Это позволяет отслеживать не только логи, но и реальные ошибки, которые могут привести к сбоям.

4. Стек-трейсы:

   • При отправке событий с ошибками и предупреждениями включается стек-трейс, что облегчает диагностику и исправление проблем.

5. Таймштампы:

   • Используются для определения времени начала и окончания транзакций и спанов, что позволяет оценивать производительность.

Пример рабочего процесса

Давайте рассмотрим, как функция export обрабатывает запрос шаг за шагом:

1. Получение запроса:

   • Консольный запрос: Пользователь запускает команду, например, yii migrate.
   • Веб-запрос: Пользователь обращается к URL, например, https://example.com/site/index.

2. Логирование:

   • В процессе обработки запроса приложение генерирует сообщения логов (например, информационные, предупреждения, ошибки).

3. Накопление сообщений:

   • Эти сообщения накапливаются в массиве $this->messages внутри класса SentryTarget.

4. Вызов функции export:

   • Когда приложение завершает обработку запроса, вызывается функция export, которая отправляет накопленные сообщения в Sentry.

5. Создание транзакции:

   • Функция определяет тип запроса (консольный или веб) и формирует название операции.
   • Создает транзакцию в Sentry с соответствующим контекстом.

6. Обработка сообщений:

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

7. Завершение транзакции:

   • После обработки всех сообщений транзакция завершается, и все данные отправляются в Sentry.

8. Анализ в Sentry:

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

Преимущества такого подхода

• Централизованное логирование и мониторинг:

  • Все важные события и ошибки собираются в одном месте, что облегчает их отслеживание и анализ.

• Мониторинг производительности:

  • Транзакции и спаны позволяют анализировать производительность приложения и выявлять узкие места.

• Диагностика ошибок:

  • Стек-трейсы и контекст событий помогают быстро находить и устранять ошибки.

• Различие между типами запросов:

  • Отдельное определение названий операций для консольных и веб-запросов обеспечивает более точный мониторинг.

Заключение

Функция export эффективно интегрирует ваш PHP-приложение с Sentry, обеспечивая подробное логирование, мониторинг ошибок и анализ производительности. Она учитывает специфику различных типов запросов (консольных и веб), создавая транзакции и спаны, которые позволяют получить глубокое понимание работы приложения.

Рекомендации для дальнейшего улучшения:

1. Асинхронная отправка логов:

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

2. Фильтрация чувствительных данных:

   • Убедитесь, что в логи не попадают конфиденциальные данные, или используйте механизмы маскировки перед отправкой в Sentry.

3. Управление уровнем логирования:

   • Настройте уровни логирования таким образом, чтобы отправлять только важные события в Sentry, что поможет избежать избыточной нагрузки и повышенной стоимости.

4. Тестирование:

   • Пишите юнит-тесты для класса SentryTarget, чтобы гарантировать корректность его работы и облегчить будущие изменения.

5. Документация:

   • Документируйте особенности и настройки интеграции с Sentry, что облегчит поддержку и развитие приложения в будущем.

Если у вас возникнут дополнительные вопросы или потребуется помощь с конкретными аспектами интеграции, не стесняйтесь обращаться!

Конечно! Ниже представлен улучшенный и оптимизированный вариант класса SentryTarget для интеграции с Sentry в вашем Yii-приложении. Этот класс учитывает все рекомендации по улучшению, включая повышение читаемости, производительности, безопасности и поддержки.

php
<?php

namespace common\components\log;

use notamedia\sentry\SentryTarget as BaseSentryTarget;
use Sentry\Event;
use Sentry\EventHint;
use Sentry\Frame;
use Sentry\SentrySdk;
use Sentry\Severity;
use Sentry\Stacktrace;
use Sentry\Tracing\SpanContext;
use Sentry\Tracing\TraceId;
use Sentry\Tracing\TransactionContext;
use Sentry\StacktraceBuilder;
use Yii;
use yii\console\Application as ConsoleApplication;
use yii\console\Controller as ConsoleController;
use yii\web\Application as WebApplication;
use yii\web\Controller as WebController;
use yii\log\Logger;
use Throwable;

/**
 * Класс SentryTarget отвечает за экспорт логов в Sentry с поддержкой транзакций и спанов для мониторинга производительности.
 */
class SentryTarget extends BaseSentryTarget
{
    // Константы уровней логирования
    private const LEVEL_ERROR = Logger::LEVEL_ERROR;
    private const LEVEL_WARNING = Logger::LEVEL_WARNING;

    // Константы тегов
    private const TAG_ROUTE = 'route';
    private const TAG_APP_ID = 'app-id';
    private const TAG_TRACE_ID = 'trace-id';
    private const TAG_ACTION = 'action';

    /**
     * Экспортирует накопленные сообщения в Sentry.
     *
     * @return void
     */
    public function export(): void
    {
        if (empty($this->messages)) {
            return;
        }

        $hub = SentrySdk::getCurrentHub();
        $applicationRunId = $this->getApplicationRunId();
        $operationName = $this->determineOperationName();
        $commonTags = $this->getCommonTags($operationName, $applicationRunId);

        // Используем timestamp первого сообщения как старт транзакции
        $firstMessage = reset($this->messages);
        $startTimestamp = $firstMessage[3] ?? microtime(true);

        $transactionContext = new TransactionContext();
        $transactionContext->setName($operationName);
        $transactionContext->setOp(Yii::$app->id);
        $transactionContext->setDescription($operationName);
        $transactionContext->setTraceId(new TraceId($applicationRunId));
        $transactionContext->setStartTimestamp($startTimestamp);
        $transactionContext->setTags($commonTags);
        $transactionContext->setSampled(true);

        $transaction = $hub->startTransaction($transactionContext);
        $hub->setSpan($transaction);

        foreach ($this->messages as $message) {
            if (!$this->isValidMessage($message)) {
                Yii::warning('Некорректное сообщение для Sentry', __METHOD__);
                continue;
            }

            [$text, $level, $action, $timestamp, $stackTrace, $memory] = $message;
            $textExport = $this->exportText($text);

            $spanContext = new SpanContext();
            $spanContext->setOp($action);
            $spanContext->setTags(array_merge($commonTags, [self::TAG_ACTION => $action]));
            $spanContext->setDescription($textExport);
            $spanContext->setStartTimestamp($startTimestamp);
            $spanContext->setSampled(true);
            $spanContext->setData($this->buildSpanData($message));

            $span = $transaction->startChild($spanContext);

            if (in_array($level, [self::LEVEL_ERROR, self::LEVEL_WARNING], true)) {
                if ($text instanceof Throwable) {
                    $hub->captureException($text);
                } else {
                    $event = $this->createSentryEvent($textExport, $level, $action, $commonTags, $stackTrace, $startTimestamp);
                    $hub->captureEvent($event, $this->getExceptionHint($text));
                }
            }

            $span->finish($timestamp);
            $startTimestamp = $timestamp;
        }

        $lastMessage = end($this->messages);
        $finalTimestamp = $lastMessage[3] ?? microtime(true);
        if ($transaction->isActive()) {
            $transaction->finish($finalTimestamp);
        }
    }

    /**
     * Получает уникальный идентификатор выполнения приложения без дефисов.
     *
     * @return string
     */
    private function getApplicationRunId(): string
    {
        return preg_replace("/-/", '', Yii::$app->getRequest()->applicationRunId);
    }

    /**
     * Определяет название операции для транзакции на основе типа приложения и контекста запроса.
     *
     * @return string Название операции.
     */
    private function determineOperationName(): string
    {
        return match (true) {
            Yii::$app instanceof ConsoleApplication => $this->getConsoleOperationName(),
            Yii::$app instanceof WebApplication => $this->getWebOperationName(),
            default => 'application',
        };
    }

    /**
     * Получает название операции для консольного приложения.
     *
     * @return string Название операции.
     */
    private function getConsoleOperationName(): string
    {
        $controller = Yii::$app->controller;
        if ($controller instanceof ConsoleController) {
            $commandName = Yii::$app->requestedRoute;
            $args = implode(' ', Yii::$app->request->getArgs());
            return "console.{$commandName} {$args}";
        }
        return 'console';
    }

    /**
     * Получает название операции для веб-приложения.
     *
     * @return string Название операции.
     */
    private function getWebOperationName(): string
    {
        $controller = Yii::$app->controller;
        if ($controller instanceof WebController) {
            $module = $controller->module->id ?? 'app';
            $controllerId = $controller->id;
            $actionId = $controller->action->id ?? 'index';
            return "web.{$module}.{$controllerId}.{$actionId}";
        }
        return 'web';
    }

    /**
     * Генерирует общие теги для Sentry событий.
     *
     * @param string $operationName Название операции.
     * @param string $traceId Идентификатор трассировки.
     * @return array Массив тегов.
     */
    private function getCommonTags(string $operationName, string $traceId): array
    {
        return [
            self::TAG_ROUTE => $operationName,
            self::TAG_APP_ID => Yii::$app->id,
            self::TAG_TRACE_ID => $traceId,
        ];
    }

    /**
     * Проверяет корректность структуры сообщения.
     *
     * @param array $message Сообщение лога.
     * @return bool Истина, если сообщение корректно, иначе ложь.
     */
    private function isValidMessage(array $message): bool
    {
        return count($message) >= 6;
    }

    /**
     * Формирует данные для спана на основе сообщения.
     *
     * @param array $message Сообщение логирования.
     * @return array Данные для спана.
     */
    private function buildSpanData(array $message): array
    {
        [$text, $level, $action, $timestamp, $stackTrace, $memoryUsages] = $message;
        $user = Yii::$app->user ?? null;

        return [
            'level'     => Logger::getLevelName($level),
            'action'    => $action,
            'timestamp' => $timestamp,
            'user'      => $user ? $user->getId() : 'CLI',
            'memory'    => $memoryUsages,
            'trace'     => $stackTrace,
            'message'   => $this->exportText($text),
        ];
    }

    /**
     * Создает Sentry Event на основе предоставленных данных.
     *
     * @param string $message Сообщение.
     * @param string $level Уровень логирования.
     * @param string $action Действие.
     * @param array $tags Теги.
     * @param array|null $stackTrace Стектрейс.
     * @param float $timestamp Временная метка.
     * @return Event
     */
    private function createSentryEvent(string $message, string $level, string $action, array $tags, ?array $stackTrace, float $timestamp): Event
    {
        $event = Event::createEvent();
        $event->setFingerprint([$level, $action, $tags[self::TAG_ROUTE], $tags[self::TAG_APP_ID]]);
        $event->setTags($tags);
        $event->setMessage($message);

        $severity = $level === self::LEVEL_WARNING ? Severity::warning() : Severity::error();
        $event->setLevel($severity);
        $event->setStartTimestamp($timestamp);

        if (is_array($stackTrace) && !empty($stackTrace)) {
            $frames = array_map(fn($frameData) => new Frame(
                $frameData['file'] ?? null,
                $frameData['line'] ?? null,
                $frameData['function'] ?? null,
                $frameData['class'] ?? null
            ), $stackTrace);

            if (!empty($frames)) {
                $event->setStacktrace(new Stacktrace($frames));
            }
        }

        return $event;
    }

    /**
     * Получает подсказку для события на основе текста сообщения.
     *
     * @param mixed $text Текст сообщения.
     * @return EventHint|null
     */
    private function getExceptionHint($text): ?EventHint
    {
        if (is_array($text) && isset($text['exception']) && $text['exception'] instanceof Throwable) {
            return EventHint::fromArray(['exception' => $text['exception']]);
        }

        return null;
    }

    /**
     * Форматирует текст сообщения для отправки в Sentry.
     *
     * @param mixed $text Текст сообщения.
     * @return string
     */
    private function exportText($text): string
    {
        if (is_array($text)) {
            return json_encode($text, JSON_UNESCAPED_UNICODE);
        }

        return (string)$text;
    }
}