fix(flow-php/symfony-telemetry-bundle): stop calling Router::getRouteCollection() on every request (#2525)

fix(flow-php/symfony-telemetry-bundle): stop calling Router::getRouteCollection() on every request with route_naming: pat

- add RouteNamePathMap: ConfigCache-backed [route name => path] map,
warmed at cache:warmup (optional warmer) or lazily on first use
- HttpKernelSpanSubscriber takes ?RouteNamePathMap instead of
?RouterInterface; routeValue() is an O(1) lookup
- degrade to route-name naming (never touch the router at runtime) when
the map cannot be built

Author: norberttech

documentation/components/bridges/symfony-telemetry-bundle.md

@@ -1151,7 +1151,9 @@ The request (SERVER) span follows the OpenTelemetry HTTP semantic conventions fo
 controlled by `route_naming`:
 
 - `path` (default) — the route **path template**, e.g. `GET /orders/{id}` (low cardinality, semconv value
-  for `http.route`); resolved from the router.
+  for `http.route`); resolved from a `[route name => path]` map built once per deployment by an optional
+  cache warmer (`cache:warmup`) and rebuilt lazily when missing, so the router is never queried on the
+  request path.
 - `name` — the Symfony **route name**, e.g. `GET order_show`.
 - Sub-requests (`render(controller(...))`) have no route, so they are named after the **controller**
   (`GET App\Controller\NavigationController::top`); a request that matches no route at all uses the method

documentation/upgrading.md

@@ -294,6 +294,16 @@ implementation is `yield $this->get($key);`.
 
 Convert `DateTime`/`DateTimeImmutable` subclasses to `DateTime`/`DateTimeImmutable` before caching or serializing.
 
+### 21) `flow-php/symfony-telemetry-bundle` - `HttpKernelSpanSubscriber` takes a
+`RouteNamePathMap` instead of the router
+
+| Before                                                | After                                                               |
+|-------------------------------------------------------|---------------------------------------------------------------------|
+| `new HttpKernelSpanSubscriber(…, router: $router, …)` | `new HttpKernelSpanSubscriber(…, routePaths: $routeNamePathMap, …)` |
+| `?RouterInterface $router = null`                     | `?RouteNamePathMap $routePaths = null`                              |
+
+Applies only to direct construction; services wired by the bundle need no change.
+
 ---
 
 ## Upgrading from 0.40.x to 0.41.x

src/bridge/symfony/telemetry-bundle/src/Flow/Bridge/Symfony/TelemetryBundle/Instrumentation/HttpKernel/HttpKernelSpanSubscriber.php

@@ -30,7 +30,6 @@
 use Symfony\Component\HttpKernel\Event\ResponseEvent;
 use Symfony\Component\HttpKernel\Event\TerminateEvent;
 use Symfony\Component\HttpKernel\KernelEvents;
-use Symfony\Component\Routing\RouterInterface;
 
 use function array_key_exists;
 use function array_map;
@@ -59,7 +58,7 @@ public function __construct(
         private Propagator $propagator,
         private bool $contextPropagation = true,
         private bool $contextPropagationQuery = false,
-        private ?RouterInterface $router = null,
+        private ?RouteNamePathMap $routePaths = null,
         private RouteNaming $routeNaming = RouteNaming::Path,
     ) {
         $this->excludePathRules = array_map(
@@ -98,11 +97,11 @@ public function onController(ControllerEvent $event): void
 
     private function routeValue(string $routeName): string
     {
-        if ($this->routeNaming !== RouteNaming::Path || $this->router === null) {
+        if ($this->routeNaming !== RouteNaming::Path) {
             return $routeName;
         }
 
-        return $this->router->getRouteCollection()->get($routeName)?->getPath() ?? $routeName;
+        return $this->routePaths?->pathFor($routeName) ?? $routeName;
     }
 
     public function onException(ExceptionEvent $event): void

src/bridge/symfony/telemetry-bundle/src/Flow/Bridge/Symfony/TelemetryBundle/Instrumentation/HttpKernel/RouteNamePathMap.php

@@ -0,0 +1,114 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\Bridge\Symfony\TelemetryBundle\Instrumentation\HttpKernel;
+
+use Symfony\Component\Config\ConfigCache;
+use Symfony\Component\HttpKernel\CacheWarmer\CacheWarmerInterface;
+use Symfony\Component\Routing\RouterInterface;
+use Throwable;
+
+use function dirname;
+use function is_dir;
+use function is_writable;
+use function var_export;
+
+/**
+ * Deployment-static [route name => path template] map so request spans can carry the OTEL http.route
+ * path template without touching the router at runtime — Router::getRouteCollection() bypasses the
+ * compiled matcher and rebuilds the full route collection, which Symfony explicitly warns is too slow
+ * for the request path.
+ */
+final class RouteNamePathMap implements CacheWarmerInterface
+{
+    private ConfigCache $cache;
+
+    /** @var null|array<string, string> */
+    private ?array $paths = null;
+
+    private bool $unavailable = false;
+
+    public function __construct(
+        private readonly ?RouterInterface $router,
+        string $directory,
+        bool $debug,
+    ) {
+        $this->cache = new ConfigCache($directory . '/flow_telemetry_route_paths.php', $debug);
+    }
+
+    public function isOptional(): bool
+    {
+        return true;
+    }
+
+    public function pathFor(string $routeName): ?string
+    {
+        if ($this->paths === null && !$this->load()) {
+            return null;
+        }
+
+        return $this->paths[$routeName] ?? null;
+    }
+
+    public function warmUp(string $cacheDir, ?string $buildDir = null): array
+    {
+        if ($this->router === null) {
+            return [];
+        }
+
+        $collection = $this->router->getRouteCollection();
+        $paths = [];
+
+        foreach ($collection->all() as $name => $route) {
+            $paths[$name] = $route->getPath();
+        }
+
+        $this->cache->write('<?php return ' . var_export($paths, true) . ';', $collection->getResources());
+        $this->paths = $paths;
+
+        return [$this->cache->getPath()];
+    }
+
+    private function load(): bool
+    {
+        if ($this->unavailable) {
+            return false;
+        }
+
+        try {
+            if (!$this->cache->isFresh()) {
+                $directory = dirname($this->cache->getPath());
+
+                // Guard against the unwritable branch before touching the router: under PHP-FPM the
+                // failure memoization below lives one request only, so a throwing warmUp() would
+                // rebuild the route collection on every request — the exact cost this map avoids.
+                if (is_dir($directory) ? !is_writable($directory) : !is_writable(dirname($directory))) {
+                    $this->unavailable = true;
+
+                    return false;
+                }
+
+                $this->warmUp('');
+            }
+        } catch (Throwable) {
+            $this->unavailable = true;
+
+            return false;
+        }
+
+        if ($this->paths === null) {
+            if (!$this->cache->isFresh()) {
+                $this->unavailable = true;
+
+                return false;
+            }
+
+            /** @var array<string, string> $paths */
+            $paths = require $this->cache->getPath();
+            $this->paths = $paths;
+        }
+
+        return true;
+    }
+}

src/bridge/symfony/telemetry-bundle/src/Flow/Bridge/Symfony/TelemetryBundle/Resources/config/instrumentation/http_kernel.php

@@ -5,6 +5,7 @@
 use Flow\Bridge\Symfony\TelemetryBundle\Instrumentation\HttpKernel\ControllerSpanSubscriber;
 use Flow\Bridge\Symfony\TelemetryBundle\Instrumentation\HttpKernel\HttpKernelFlushSubscriber;
 use Flow\Bridge\Symfony\TelemetryBundle\Instrumentation\HttpKernel\HttpKernelSpanSubscriber;
+use Flow\Bridge\Symfony\TelemetryBundle\Instrumentation\HttpKernel\RouteNamePathMap;
 use Flow\Telemetry\Telemetry;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 
@@ -14,6 +15,15 @@
 return static function (ContainerConfigurator $container): void {
     $services = $container->services();
 
+    $services
+        ->set('flow.telemetry.http_kernel.route_name_path_map', RouteNamePathMap::class)
+        ->args([
+            service('router')->ignoreOnInvalid(),
+            '%kernel.build_dir%',
+            '%kernel.debug%',
+        ])
+        ->tag('kernel.cache_warmer');
+
     $services
         ->set('flow.telemetry.http_kernel.span_subscriber', HttpKernelSpanSubscriber::class)
         ->args([
@@ -23,7 +33,7 @@
             service('flow.telemetry.propagator'),
             '%flow.telemetry.http_kernel.context_propagation%',
             '%flow.telemetry.http_kernel.context_propagation_query%',
-            service('router')->ignoreOnInvalid(),
+            service('flow.telemetry.http_kernel.route_name_path_map'),
             // arg $routeNaming (RouteNaming enum) is set in FlowTelemetryBundle::registerInstrumentation.
         ])
         ->tag('kernel.event_subscriber');

src/bridge/symfony/telemetry-bundle/tests/Flow/Bridge/Symfony/TelemetryBundle/Tests/Context/TempDirectoryContext.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\Bridge\Symfony\TelemetryBundle\Tests\Context;
+
+use FilesystemIterator;
+use RecursiveDirectoryIterator;
+use RecursiveIteratorIterator;
+
+use function bin2hex;
+use function chmod;
+use function is_dir;
+use function mkdir;
+use function random_bytes;
+use function rmdir;
+use function sys_get_temp_dir;
+use function unlink;
+
+final class TempDirectoryContext
+{
+    public static function remove(string $directory): void
+    {
+        if (!is_dir($directory)) {
+            return;
+        }
+
+        // The read-only degradation tests leave directories without write permission behind.
+        chmod($directory, 0o755);
+
+        /** @var iterable<\SplFileInfo> $files */
+        $files = new RecursiveIteratorIterator(
+            new RecursiveDirectoryIterator($directory, FilesystemIterator::SKIP_DOTS),
+            RecursiveIteratorIterator::CHILD_FIRST,
+        );
+
+        foreach ($files as $file) {
+            if ($file->isDir()) {
+                chmod($file->getPathname(), 0o755);
+                rmdir($file->getPathname());
+            } else {
+                unlink($file->getPathname());
+            }
+        }
+
+        rmdir($directory);
+    }
+
+    /**
+     * @param callable(string): void $test
+     */
+    public static function with(callable $test): void
+    {
+        $directory = sys_get_temp_dir() . '/flow_telemetry_bundle_test_' . bin2hex(random_bytes(8));
+        mkdir($directory, 0o777, true);
+
+        try {
+            $test($directory);
+        } finally {
+            self::remove($directory);
+        }
+    }
+}

src/bridge/symfony/telemetry-bundle/tests/Flow/Bridge/Symfony/TelemetryBundle/Tests/Fixtures/Routing/FakeRouter.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\Bridge\Symfony\TelemetryBundle\Tests\Fixtures\Routing;
+
+use Symfony\Component\Routing\RequestContext;
+use Symfony\Component\Routing\RouteCollection;
+use Symfony\Component\Routing\RouterInterface;
+
+final class FakeRouter implements RouterInterface
+{
+    public int $getRouteCollectionCalls = 0;
+
+    private RequestContext $context;
+
+    public function __construct(
+        private RouteCollection $routes = new RouteCollection(),
+    ) {
+        $this->context = new RequestContext();
+    }
+
+    public function generate(string $name, array $parameters = [], int $referenceType = self::ABSOLUTE_PATH): string
+    {
+        return '/generated';
+    }
+
+    public function getContext(): RequestContext
+    {
+        return $this->context;
+    }
+
+    public function getRouteCollection(): RouteCollection
+    {
+        $this->getRouteCollectionCalls++;
+
+        return $this->routes;
+    }
+
+    public function match(string $pathinfo): array
+    {
+        return [];
+    }
+
+    public function setContext(RequestContext $context): void
+    {
+        $this->context = $context;
+    }
+
+    public function setRouteCollection(RouteCollection $routes): void
+    {
+        $this->routes = $routes;
+    }
+}