* @copyright 2026 Nowo.tech */ class PerformanceMetricsService { /** * Attempts of one metrics write unit (the first one and up to two replays after a unique violation or a lock * conflict). */ public const MAX_WRITE_ATTEMPTS = 3; /** * The entity manager for the configured connection. */ private readonly EntityManagerInterface $entityManager; /** * The repository for RouteData entities. */ private readonly RouteDataRepository $repository; /** * The repository for RouteDataRecord entities. */ private readonly RouteDataRecordRepository $recordRepository; /** * Cache service for performance metrics (optional). */ private ?PerformanceCacheService $cacheService = null; /** * Event dispatcher (optional). */ private ?EventDispatcherInterface $eventDispatcher = null; /** * Message bus for async processing (optional). */ private ?MessageBusInterface $messageBus = null; /** * Private entity manager of the write path (created on first write, dropped after an error). */ private ?EntityManagerInterface $writeEntityManager = null; /** * Creates a new instance. * * @param ManagerRegistry $registry The Doctrine registry * @param string $connectionName The name of the Doctrine connection to use * @param bool $async Whether to use async mode * @param MetricsEntityManagerFactory|null $writeEntityManagerFactory Creates the private write entity manager */ public function __construct( private readonly ManagerRegistry $registry, #[Autowire('%nowo_performance.connection%')] private readonly string $connectionName, #[Autowire('%nowo_performance.async%')] private readonly bool $async = false, /** * Whether access records are enabled. */ #[Autowire('%nowo_performance.enable_access_records%')] private readonly bool $enableAccessRecords = false, /** * Whether logging is enabled. */ #[Autowire('%nowo_performance.enable_logging%')] private readonly bool $enableLogging = true, private readonly ?LoggerInterface $logger = null, private readonly ClockInterface $clock = new NativeClock(), private readonly ?MetricsEntityManagerFactory $writeEntityManagerFactory = null, ) { $manager = $this->registry->getManager($this->connectionName); if (!$manager instanceof EntityManagerInterface) { throw new LogicException('Expected EntityManagerInterface from registry.'); } $this->entityManager = $manager; $repository = $this->entityManager->getRepository(RouteData::class); if (!$repository instanceof RouteDataRepository) { throw new LogicException('Expected RouteDataRepository.'); } $this->repository = $repository; $recordRepo = $this->entityManager->getRepository(RouteDataRecord::class); if (!$recordRepo instanceof RouteDataRecordRepository) { throw new LogicException('Expected RouteDataRecordRepository.'); } $this->recordRepository = $recordRepo; } /** * Get the DBAL connection used by the metrics service. */ public function getConnection(): Connection { return $this->entityManager->getConnection(); } /** * Get the entity manager of the configured connection (reads, dashboard actions). * * Metrics recorded by recordMetrics() / recordMetricsSync() are written through a private entity manager on the * same connection instead, so they never flush this manager's pending changes. */ public function getEntityManager(): EntityManagerInterface { return $this->entityManager; } /** * Set the cache service (optional, for cache invalidation). * * @param PerformanceCacheService|null $cacheService The cache service */ #[Required] public function setCacheService(?PerformanceCacheService $cacheService): void { // @igor-ignore - Service coordinates I/O or request-scoped work; not unsafe worker singleton state. $this->cacheService = $cacheService; } /** * Set the event dispatcher (optional, for event dispatching). * * @param EventDispatcherInterface|null $eventDispatcher The event dispatcher */ #[Required] public function setEventDispatcher(?EventDispatcherInterface $eventDispatcher): void { // @igor-ignore - Service coordinates I/O or request-scoped work; not unsafe worker singleton state. $this->eventDispatcher = $eventDispatcher; } /** * Set the message bus (optional, for async processing). * * This method is called automatically by Symfony's dependency injection * only if Messenger is installed. If Messenger is not available, this * method will not be called and $messageBus will remain null. * * @param MessageBusInterface|null $messageBus The message bus (e.g. Symfony Messenger) */ public function setMessageBus(?MessageBusInterface $messageBus): void { // @igor-ignore - Service coordinates I/O or request-scoped work; not unsafe worker singleton state. $this->messageBus = $messageBus; } /** * Record or update route performance metrics. * * @param string $routeName The route name * @param string $env The environment (dev, test, prod) * @param float|null $requestTime Request execution time in seconds * @param int|null $totalQueries Total number of database queries * @param float|null $queryTime Total query execution time in seconds * @param array|null $params Route parameters * @param int|null $memoryUsage Peak memory usage in bytes * @param string|null $httpMethod HTTP method (GET, POST, PUT, DELETE, etc.) * @param int|null $statusCode HTTP status code (200, 404, 500, etc.) * @param array $trackStatusCodes List of status codes to track * @param string|null $requestId Unique request ID to avoid duplicate access records for the same request * @param string|null $referer HTTP Referer header (page that linked to this request) * @param string|null $userIdentifier Logged-in user identifier (e.g. username, email) * @param string|null $userId Logged-in user ID (stringified, if available) * @param string|null $routePath Request path including query string (e.g. /user/123?page=2) for access records * * @return array{is_new: bool, was_updated: bool} Information about the operation */ public function recordMetrics( string $routeName, string $env, ?float $requestTime = null, ?int $totalQueries = null, ?float $queryTime = null, ?array $params = null, ?int $memoryUsage = null, ?string $httpMethod = null, ?int $statusCode = null, array $trackStatusCodes = [], ?string $requestId = null, ?string $referer = null, ?string $userIdentifier = null, ?string $userId = null, ?string $routePath = null, ): array { $this->bundleLog( 'debug', '[PerformanceBundle] recordMetrics: START - route=%s, env=%s, async=%s, requestTime=%s, totalQueries=%s', $routeName, $env, $this->async ? 'true' : 'false', $requestTime !== null ? (string) $requestTime : 'null', $totalQueries !== null ? (string) $totalQueries : 'null', ); // Dispatch before event to allow modification of metrics if ($this->eventDispatcher instanceof EventDispatcherInterface) { $beforeEvent = new BeforeMetricsRecordedEvent( $routeName, $env, $requestTime, $totalQueries, $queryTime, $params, $memoryUsage, ); $this->eventDispatcher->dispatch($beforeEvent); // Use modified values from event $requestTime = $beforeEvent->getRequestTime(); $totalQueries = $beforeEvent->getTotalQueries(); $queryTime = $beforeEvent->getQueryTime(); $params = $beforeEvent->getParams(); $memoryUsage = $beforeEvent->getMemoryUsage(); // Note: httpMethod is not modifiable via event, use original value } // If async mode is enabled and message bus is available, dispatch message $messageBus = $this->messageBus; if ($this->async && $messageBus instanceof MessageBusInterface) { $this->bundleLog('debug', '[PerformanceBundle] recordMetrics: Dispatching async message'); $message = new RecordMetricsMessage( $routeName, $env, $requestTime, $totalQueries, $queryTime, $params, $memoryUsage, $httpMethod, $statusCode, $requestId, $referer, $userIdentifier, $userId, $routePath, ); $messageBus->dispatch($message); // In async mode, we can't know if it was new or updated until the message is processed return ['is_new' => false, 'was_updated' => false]; } // Otherwise, record synchronously $this->bundleLog('debug', '[PerformanceBundle] recordMetrics: Recording synchronously'); return $this->recordMetricsSync($routeName, $env, $requestTime, $totalQueries, $queryTime, $params, $memoryUsage, $httpMethod, $statusCode, $requestId, $referer, $userIdentifier, $userId, $routePath); } /** * Record metrics synchronously (used by sync mode and async message handler). * * @param string $routeName The route name * @param string $env The environment * @param float|null $requestTime Request execution time in seconds * @param int|null $totalQueries Total number of database queries * @param float|null $queryTime Total query execution time in seconds * @param array|null $params Route parameters * @param int|null $memoryUsage Peak memory usage in bytes * @param string|null $httpMethod HTTP method (GET, POST, PUT, DELETE, etc.) * @param int|null $statusCode HTTP status code (200, 404, 500, etc.) * @param string|null $requestId Unique request ID to avoid duplicate access records for the same request * @param string|null $referer HTTP Referer header * @param string|null $userIdentifier Logged-in user identifier (e.g. username, email) * @param string|null $userId Logged-in user ID (stringified, if available) * @param string|null $routePath Request path including query string (e.g. /user/123?page=2) for access records * * @return array{is_new: bool, was_updated: bool} Information about the operation */ public function recordMetricsSync( string $routeName, string $env, ?float $requestTime = null, ?int $totalQueries = null, ?float $queryTime = null, ?array $params = null, ?int $memoryUsage = null, ?string $httpMethod = null, ?int $statusCode = null, ?string $requestId = null, ?string $referer = null, ?string $userIdentifier = null, ?string $userId = null, ?string $routePath = null, ): array { $this->bundleLog( 'debug', '[PerformanceBundle] recordMetricsSync: Looking for existing record - route=%s, env=%s', $routeName, $env, ); // One write unit (REQ-RUNTIME-003): the RouteData (found or inserted) and the access record are committed in // one transaction of the private entity manager. A unique violation means another worker inserted the same // route (uniq_route_env_name) or saved the same request id (uniq_record_request_id) first: the unit is run // again and re-reads what the other worker committed. A lock conflict (deadlock, lock wait timeout) is // replayed too. Only the outermost transaction may replay (a host transaction may already be rolled back). $uniqueConflicts = 0; for ($attempt = 1;; ++$attempt) { // A private entity manager on the configured connection: its unit of work only holds the bundle's // entities, so its flush never commits a change the host left pending, and the host's manager is never // flushed, cleared or reset by the bundle. $entityManager = $this->writeEntityManager(); $replayable = $entityManager->getConnection()->getTransactionNestingLevel() === 0; try { /** @var array{0: RouteData, 1: bool, 2: bool} $written */ $written = DoctrineTransactionRunner::forEntityManager($entityManager)->run( fn (): array => $this->writeMetrics( $entityManager, $routeName, $env, $requestTime, $totalQueries, $queryTime, $params, $memoryUsage, $httpMethod, $statusCode, $requestId, $referer, $userIdentifier, $userId, $routePath, $uniqueConflicts, ), ); } catch (Throwable $e) { // Drop the private manager after an error (it may be closed or hold half-written entities); the next // attempt or recording creates a fresh one. The host's entity manager is never reset by the bundle. // @igor-ignore - Private unit of work of the write path, cleared after every recording and dropped on error. $this->writeEntityManager = null; $unique = $this->isUniqueViolation($e); if (!$replayable || $attempt >= self::MAX_WRITE_ATTEMPTS || (!$unique && !$e instanceof TransientStorageFailure)) { $this->bundleLog( 'debug', '[PerformanceBundle] recordMetricsSync: ERROR - route=%s, env=%s, attempt=%d, exception=%s, message=%s', $routeName, $env, $attempt, $e::class, $e->getMessage(), ); // Re-throw: the subscriber logs it at warning level, Messenger retries the message. throw $e; } $this->logger?->notice('[PerformanceBundle] Concurrent metrics write; running the write unit again.', [ 'bundle' => 'performance', 'route' => $routeName, 'env' => $env, 'attempt' => $attempt, 'exception' => $e::class, ]); if ($unique) { ++$uniqueConflicts; } else { $this->pauseBeforeReplay($attempt); } continue; } break; } [$routeData, $isNew, $accessRecordSkippedByRace] = $written; if ($accessRecordSkippedByRace) { // Not silent (rule 8): the route's metrics were saved, the access record of this request was not. $this->logger?->warning('[PerformanceBundle] The access record of a request was not saved: a concurrent write used the same request id.', [ 'bundle' => 'performance', 'route' => $routeName, 'env' => $env, ]); } $this->bundleLog( 'debug', '[PerformanceBundle] After flush SUCCESS: route=%s, env=%s, isNew=%s', $routeName, $env, $isNew ? 'true' : 'false', ); // Side effects after the commit only (rule 1). if ($this->cacheService instanceof PerformanceCacheService) { $this->cacheService->invalidateStatistics($env); } if ($this->eventDispatcher instanceof EventDispatcherInterface) { $afterEvent = new AfterMetricsRecordedEvent($routeData, $isNew, $requestTime, $totalQueries, $memoryUsage); $this->eventDispatcher->dispatch($afterEvent); } // The private manager only holds the bundle's entities: clearing it keeps a long-running worker from // accumulating one record per request or serving a stale RouteData changed by another worker. $entityManager->clear(); $this->bundleLog( 'debug', '[PerformanceBundle] recordMetricsSync: SUCCESS - route=%s, env=%s, isNew=%s, wasUpdated=%s', $routeName, $env, $isNew ? 'true' : 'false', $isNew ? 'false' : 'true', ); return ['is_new' => $isNew, 'was_updated' => !$isNew]; } /** * Get route data by name and environment. * * @param string $routeName The route name * @param string $env The environment (dev, test, prod) * * @return RouteData|null The route data or null if not found */ public function getRouteData(string $routeName, string $env): ?RouteData { return $this->repository->findByRouteAndEnv($routeName, $env); } /** * Get all routes for an environment. * * @return RouteData[] */ public function getRoutesByEnvironment(string $env): array { return $this->repository->findByEnvironment($env); } /** * Get routes for an environment with aggregates from RouteDataRecord (for dashboard/listings). * * Returns RouteDataWithAggregates[] sorted by request_time descending (worst first). * * @return RouteDataWithAggregates[] */ public function getRoutesWithAggregates(string $env): array { $routes = $this->repository->findByEnvironment($env); if ($routes === []) { return []; } $ids = array_values(array_filter( array_map(static fn (RouteData $r): ?int => $r->getId(), $routes), static fn (?int $id): bool => $id !== null, )); if ($ids === []) { return []; } $aggregates = $this->recordRepository->getAggregatesForRouteDataIds($ids); $withAggregates = []; foreach ($routes as $route) { $id = $route->getId(); if ($id === null) { continue; } $agg = $aggregates[$id] ?? [ 'request_time' => null, 'total_queries' => null, 'query_time' => null, 'memory_usage' => null, 'access_count' => 0, 'status_codes' => [], ]; $withAggregates[] = new RouteDataWithAggregates($route, $agg); } usort($withAggregates, static function (RouteDataWithAggregates $a, RouteDataWithAggregates $b): int { $at = $a->getRequestTime() ?? 0.0; $bt = $b->getRequestTime() ?? 0.0; return $bt <=> $at; }); return $withAggregates; } /** * Get routes with aggregates and optional filters/sort (for dashboard, export). * * Metric sort (requestTime, totalQueries, etc.) is applied in PHP from aggregates. * * @param array $filters Filters (route_names, route_name_pattern, date_from, date_to) * * @return RouteDataWithAggregates[] */ public function getRoutesWithAggregatesFiltered( string $env, array $filters = [], string $sortBy = 'requestTime', string $order = 'DESC', ?int $limit = null, ): array { $entitySortFields = ['name', 'createdAt', 'lastAccessedAt']; $sortByEntity = in_array($sortBy, $entitySortFields, true) ? $sortBy : 'lastAccessedAt'; $routes = $this->repository->findWithFilters($env, $filters, $sortByEntity, $order, $limit); if ($routes === []) { return []; } $ids = array_values(array_filter( array_map(static fn (RouteData $r): ?int => $r->getId(), $routes), static fn (?int $id): bool => $id !== null, )); if ($ids === []) { return []; } $aggregates = $this->recordRepository->getAggregatesForRouteDataIds($ids); $withAggregates = []; foreach ($routes as $route) { $id = $route->getId(); if ($id === null) { continue; } $agg = $aggregates[$id] ?? [ 'request_time' => null, 'total_queries' => null, 'query_time' => null, 'memory_usage' => null, 'access_count' => 0, 'status_codes' => [], ]; $withAggregates[] = new RouteDataWithAggregates($route, $agg); } if (!in_array($sortBy, $entitySortFields, true)) { $desc = strtoupper($order) === 'DESC'; usort($withAggregates, static function (RouteDataWithAggregates $a, RouteDataWithAggregates $b) use ($sortBy, $desc): int { $av = match ($sortBy) { 'requestTime' => $a->getRequestTime() ?? 0.0, 'totalQueries' => $a->getTotalQueries() ?? 0, 'queryTime' => $a->getQueryTime() ?? 0.0, 'accessCount' => $a->getAccessCount(), 'memoryUsage' => $a->getMemoryUsage() ?? 0, default => 0, }; $bv = match ($sortBy) { 'requestTime' => $b->getRequestTime() ?? 0.0, 'totalQueries' => $b->getTotalQueries() ?? 0, 'queryTime' => $b->getQueryTime() ?? 0.0, 'accessCount' => $b->getAccessCount(), 'memoryUsage' => $b->getMemoryUsage() ?? 0, default => 0, }; return $desc ? $bv <=> $av : $av <=> $bv; }); } return $withAggregates; } /** * Get worst performing routes for an environment. * * Returns routes ordered by request time descending (worst first). * * @param string $env The environment (dev, test, prod) * @param int $limit Maximum number of results to return (default: 10) * * @return RouteData[] Array of route data entities */ public function getWorstPerformingRoutes(string $env, int $limit = 10): array { return $this->repository->findWorstPerforming($env, $limit); } /** * Get the repository instance. * * @return RouteDataRepository The repository */ public function getRepository(): RouteDataRepository { return $this->repository; } /** * One attempt of the metrics write unit, run inside the private manager's transaction (flushed by the runner). * * @param array|null $params Route parameters * @param int $uniqueConflicts Unique violations met by the earlier attempts of this recording * * @return array{0: RouteData, 1: bool, 2: bool} The route, whether it was inserted, and whether the access record * was skipped because a concurrent write saved the same request id */ private function writeMetrics( EntityManagerInterface $entityManager, string $routeName, string $env, ?float $requestTime, ?int $totalQueries, ?float $queryTime, ?array $params, ?int $memoryUsage, ?string $httpMethod, ?int $statusCode, ?string $requestId, ?string $referer, ?string $userIdentifier, ?string $userId, ?string $routePath, int $uniqueConflicts, ): array { $isNew = false; $routeData = $this->findRouteDataForWrite($entityManager, $routeName, $env); if (!$routeData instanceof RouteData) { $this->bundleLog( 'debug', '[PerformanceBundle] recordMetricsSync: No existing record found, creating new - route=%s, env=%s', $routeName, $env, ); // Create new RouteData (identity + lastAccessedAt only; metrics live in RouteDataRecord). A concurrent // insert of the same (env, name) fails on uniq_route_env_name and the unit re-reads the committed row. $routeData = new RouteData(); $routeData->setName($routeName); $routeData->setEnv($env); $routeData->setHttpMethod($httpMethod); $routeData->setParams($params !== null ? SensitiveDataRedactor::redactParams($params) : null); $routeData->setLastAccessedAt($this->clock->now()); $entityManager->persist($routeData); $isNew = true; } else { $this->bundleLog( 'debug', '[PerformanceBundle] recordMetricsSync: Existing record found - route=%s, env=%s', $routeName, $env, ); $routeData->setLastAccessedAt($this->clock->now()); } // Create access record if enabled (one per request when requestId is set), unless this route has // "save access records" disabled. $skippedByRace = false; if ($this->enableAccessRecords && $routeData->getSaveAccessRecords()) { $hasRequestId = $requestId !== null && $requestId !== ''; if ($uniqueConflicts >= self::MAX_WRITE_ATTEMPTS - 1) { // Unique conflicts on every earlier attempt: save the route's metrics without the access record // rather than lose both. $skippedByRace = true; } elseif ($hasRequestId && $this->accessRecordExistsForWrite($entityManager, $requestId)) { // Already saved for this request id: by an earlier TERMINATE of the same request, or (after a unique // violation) by a concurrent write that won the race on uniq_record_request_id. $skippedByRace = $uniqueConflicts > 0; } else { $entityManager->persist($this->newAccessRecord( $routeData, $requestTime, $totalQueries, $queryTime, $params, $memoryUsage, $statusCode, $requestId, $referer, $userIdentifier, $userId, $routePath, )); } } $this->bundleLog( 'debug', '[PerformanceBundle] Before flush: route=%s, env=%s, isNew=%s, entityManagerOpen=%s', $routeName, $env, $isNew ? 'true' : 'false', $entityManager->isOpen() ? 'true' : 'false', ); return [$routeData, $isNew, $skippedByRace]; } /** * Builds the access record of one request (redacted referer, parameters and path). * * @param array|null $params Route parameters */ private function newAccessRecord( RouteData $routeData, ?float $requestTime, ?int $totalQueries, ?float $queryTime, ?array $params, ?int $memoryUsage, ?int $statusCode, ?string $requestId, ?string $referer, ?string $userIdentifier, ?string $userId, ?string $routePath, ): RouteDataRecord { $accessRecord = new RouteDataRecord(); $accessRecord->setRouteData($routeData); $accessRecord->setAccessedAt($this->clock->now()); $accessRecord->setStatusCode($statusCode); // responseTime in RouteDataRecord is the per-request duration, stored raw for temporal analysis. $accessRecord->setResponseTime($requestTime); $accessRecord->setTotalQueries($totalQueries); $accessRecord->setQueryTime($queryTime); $accessRecord->setMemoryUsage($memoryUsage); if ($requestId !== null && $requestId !== '') { $accessRecord->setRequestId($requestId); } if ($referer !== null && $referer !== '') { $accessRecord->setReferer(SensitiveDataRedactor::redactUrl($referer)); } if ($userIdentifier !== null && $userIdentifier !== '') { $accessRecord->setUserIdentifier($userIdentifier); } if ($userId !== null && $userId !== '') { $accessRecord->setUserId($userId); } if ($params !== null && $params !== []) { $accessRecord->setRouteParams(SensitiveDataRedactor::redactParams($params)); } if ($routePath !== null && $routePath !== '') { $accessRecord->setRoutePath(SensitiveDataRedactor::redactUrl($routePath)); } return $accessRecord; } /** * Whether the failure (or anything in its previous chain) is a unique-constraint violation. */ private function isUniqueViolation(Throwable $failure): bool { for ($current = $failure; $current instanceof Throwable; $current = $current->getPrevious()) { if ($current instanceof UniqueConstraintViolationException) { return true; } } return false; } /** * Short full-jitter pause before replaying a write unit after a lock conflict (20 ms to 50 ms × attempt). * * Runs on kernel.terminate (after the response was sent) or in a Messenger worker, never before the answer. */ protected function pauseBeforeReplay(int $attempt): void { usleep(random_int(20_000, 50_000 * $attempt)); } /** * Returns the open private entity manager metrics are written with, creating it when needed. */ private function writeEntityManager(): EntityManagerInterface { if ($this->writeEntityManager instanceof EntityManagerInterface && $this->writeEntityManager->isOpen()) { return $this->writeEntityManager; } $factory = $this->writeEntityManagerFactory ?? new MetricsEntityManagerFactory(); // @igor-ignore - Private unit of work of the write path, cleared after every recording and dropped on error. $this->writeEntityManager = $factory->create($this->entityManager); return $this->writeEntityManager; } /** * Loads the RouteData of a route and environment through the private write manager. */ private function findRouteDataForWrite(EntityManagerInterface $entityManager, string $routeName, string $env): ?RouteData { $routeData = $entityManager->createQueryBuilder() ->select('r') ->from(RouteData::class, 'r') ->where('r.name = :name') ->andWhere('r.env = :env') ->setParameter('name', $routeName) ->setParameter('env', $env) ->setMaxResults(1) ->getQuery() ->getOneOrNullResult(); return $routeData instanceof RouteData ? $routeData : null; } /** * Tells whether an access record already exists for the request id (private write manager). */ private function accessRecordExistsForWrite(EntityManagerInterface $entityManager, string $requestId): bool { $count = $entityManager->createQueryBuilder() ->select('COUNT(rec.id)') ->from(RouteDataRecord::class, 'rec') ->where('rec.requestId = :requestId') ->setParameter('requestId', $requestId) ->getQuery() ->getSingleScalarResult(); return (int) $count > 0; } /** * Logs through the injected PSR-3 logger when bundle logging is enabled (REQ-OBS-001 / REQ-DI-001). * * @param string $level PSR-3 level * @param string $format sprintf() format (used verbatim when no arguments are given) * @param mixed ...$args sprintf() arguments */ private function bundleLog(string $level, string $format, mixed ...$args): void { if (!$this->enableLogging) { return; } $this->logger?->log($level, $args === [] ? $format : sprintf($format, ...$args), ['bundle' => 'performance']); } }