Metrics Bundle Laravel Package

Getting Started

This bundle is a thin, under-documented Symfony integration for recording and reading application metrics. With 10 stars, no dependents, and a last release in January 2017, there are no tutorials or Stack Overflow answers to lean on — the bundle source is the specification. Start there, not with the README.

1. Confirm compatibility before installing. The 2017 release targets Symfony 2.7/3.x and PHP 5.6–7.1. On a modern stack you will almost certainly need to fork it or vendor it in. Pin to a commit SHA rather than a branch:

   composer require troopers/metrics-bundle:dev-master#<sha>
   

   If constraints collide with your Symfony version, fork the repo and relax the composer.json constraints yourself.

2. Register the bundle. Legacy: new Troopers\MetricsBundle\TroopersMetricsBundle() in AppKernel. Symfony 4+: add it to config/bundles.php.

3. Read these three files first, in order:

   • DependencyInjection/Configuration.php — the complete, authoritative list of config keys (storage driver, entity class, collection toggles, etc.).
   • Resources/config/services.yml (and any services/*.yml it imports) — the real service IDs. Old bundles rarely expose clean aliases, so find the manager service with bin/console debug:container | grep -i metric.
   • The bundle's own Tests/ directory — the only working usage examples that exist.

4. Your first use case: instrument one thing. Inject the metrics manager into a single service or controller and record a counter or timing around an operation:

   $metrics = $this->get('troopers_metrics.manager'); // verify exact ID first
   $metrics->increment('user.signup');
   

   Then confirm the value actually lands where you expect (DB table, log, or backend) before instrumenting anything else.

5. Verify your configuration resolves. Run bin/console debug:config troopers_metrics (if the bundle exposes it) — this is faster than guessing which storage backend the defaults selected.

Implementation Patterns

Wrap it behind your own interface immediately. Because the package is unmaintained, the single most valuable pattern is a one-method-deep abstraction:

final class AppMetrics
{
    public function __construct(private MetricsManager $inner) {}

    public function increment(string $key, int $by = 1): void
    {
        $this->inner->increment($key, $by);
    }

    public function timing(string $key, callable $fn): mixed
    {
        $start = microtime(true);
        try {
            return $fn();
        } finally {
            $this->inner->timing($key, microtime(true) - $start);
        }
    }
}

Swapping to StatsD, Prometheus, or a home-grown implementation later becomes a one-file change.

Instrument at boundaries, not mid-logic. The natural collection points are:

• A kernel.request/kernel.terminate listener for request duration and status-code counters.
• A Doctrine postFlush/postPersist subscriber for query and write counts.
• A console ConsoleEvents::COMMAND/TERMINATE listener for job duration.
• Around external HTTP calls and message-consumer handlers, where latency regressions actually matter.

Tag-driven collection. If the bundle offers collector tags, prefer declaring a service with the collector tag over hard-wiring every call site — it lets you add instrumentation without touching business code.

Batch writes when backed by Doctrine. If metrics persist to an entity, do not flush per metric. Accumulate in the request and flush once on kernel.terminate, or you will multiply your write load by your metric count.

Environment-specific config. Disable collection in test and reduce sampling in dev; keep prod the only fully-instrumented environment. This also keeps test suites fast and deterministic.

Decorator for sampling. Add a decorator around the manager that records only N% of events when cardinality or write volume becomes a concern, rather than scattering if (rand()) checks through call sites.

Gotchas and Tips

• Deprecated APIs are the default risk. Expect PHP 5-era type hints, get()-style service access, and container patterns removed in Symfony 4+. Budget for a fork, not a composer require.
• Service visibility. Old bundles frequently define services as public and without autowiring-friendly aliases. $this->get() may work while constructor autowiring of the manager fails; bind the exact service ID in services.yaml explicitly.
• Silent default backends. If the bundle supports multiple storage drivers, the default may write somewhere you did not intend (an unused table, a log channel). Always confirm with debug:config before writing production instrumentation.
• Doctrine mapping conflicts. Bundled entities and mappings from 2017 can clash with current Doctrine ORM versions (annotation driver removal, type changes). If you only need the recorder, consider bypassing the persistence layer entirely and pointing the manager at your own writer.
• Cardinality will bite you. Never use user IDs, raw URLs, or request payloads as metric keys. Use fixed, low-cardinality names with prefixes — this is true of every metrics backend, and especially of DB-backed ones where the table grows unbounded.
• Double-counting on retries. If collection happens inside a transaction that rolls back and retries, naive counters can increment more than once. Flush metrics after commit, in kernel.terminate, or an explicit finalizer.
• Debugging workflow: bin/console debug:container | grep -i metric to find real service IDs, debug:config to confirm resolved settings, then a one-line throwaway command or test that calls the manager directly. With no external documentation, a 10-line functional test is the fastest ground truth.
• Extension points. Override the manager via a compiler pass or a service alias rather than editing vendor code; the bundle's decoupled manager interface (if present) is the intended seam. Confirm by inspecting the class type-hinted in the bundle's own services.
• Pin and archive. Record the exact commit you vendored, and note the fork in your project README — future developers will otherwise assume this package is maintained.