Search by

rezilio / collector-bundle

rezilio

Symfony bundle that records API requests and sends them to an activity-log pipeline through RabbitMQ

Package info

bitbucket.org/productionv3/rezilio-collector-bundle

Type:symfony-bundle

pkg:composer/rezilio/collector-bundle

Statistics

Installs: 285

Dependents: 0

Suggesters: 0

1.0.21 2026-11-08 06:35 UTC

This package is auto-updated.

Last update: 2026-11-08 15:55:50 UTC


README

Symfony bundle that records what users do in an API (which route they called, with which parameters, from where) and sends each record to the activity-log pipeline, where it gets an action name and becomes visible in the activity journal.

This README is written so that a person or an AI assistant can follow it step by step. Every step says which file to change, what to write, and how to check that it is done. It only describes the API side and what the other services expect from it: the addresses, queue prefixes and database names of your environments are not in this file (section 3 says which values to ask for).

Contents:

  1. Rules for AI assistants
  2. How a record travels
  3. Values to collect before starting
  4. New installation or upgrade?
  5. Requirements
  6. New installation
  7. Upgrading a project that uses the old install method
  8. Declare the project in the activity service
  9. Check that it works
  10. Reference

1. Rules for AI assistants

If you are an AI assistant applying this README to a project:

  1. Read the project before changing anything. Run the detection commands in section 4 and show their output to the person.
  2. Never invent a value. The values listed in section 3 come from the person or from files you have read. If one is missing, ask. Do not guess a queue prefix, a project name, a host or a route.
  3. Follow one path only: section 6 (new installation) or section 7 (upgrade), as decided in section 4. Then section 8, then section 9.
  4. Apply the steps in order. After each step, check its "Done when" condition.
  5. Only change the files a step names. Do not reformat, reorder or "clean up" other files.
  6. Show every change as a diff and list the files you changed at the end.
  7. Deleting files: list the files and let the person confirm before deleting (git rm).
  8. When you cannot get an answer or cannot edit a file: leave that item undone, do not work around it, and report it at the end with the exact change it needs. Everything else continues.
  9. Commands you cannot run (Composer, bin/console, RabbitMQ, SQL on the activity database): give them to the person as a list, in order. Never report a check as passed if you did not see its output.
  10. Do not change the collector service or this bundle. Section 8 changes the activity service, which is a separate repository: say so and do it only if the person agrees.
  11. Do not write secrets (DSN passwords, keys, tokens) into the report or into files that are not already meant to hold them.
  12. Things to never do: see Things to avoid.
  13. At the end, report: the path followed, the diff, the files to delete, the commands left for the person (in order), and the open questions.

2. How a record travels

Your API + this bundle            records the request; user context comes from the JWT
  → RabbitMQ  {prefix}-CollectionQueue
  → collector service             reads the queue, appends each record to a per-minute file,
                                  then sends each finished file (HTTPS POST /api/1.0/batch_collect)
  → activity service              names the action from the project's configs.yaml, then stores it in
                                  the live / auth / monitoring / system / unclassified table
  → activity database
  → activity journal              reads the live table only

The bundle only does the first step. A record shows up in the journal only if all of these are true:

ConditionSet inSection
The route is listed in collector.yamlyour API6.3 / 7.4
The JWT carries the required claimsthe token issuer5
The message reaches the queue the collector service reads (same server, vhost and prefix)your API6.4
getenv('APP_PROJECT') returns this project's nameyour API's runtime configuration6.5
The activity service knows the project and gives the request an action nameactivity service8
The collector service can reach the activity serviceoperations9

Each environment (production, staging…) has its own queue prefix, collector service, activity service and database. If a hop fails (for example an expired TLS certificate on the activity service), the collector service retries a batch a few times and then drops it: the records are lost, not delayed.

3. Values to collect before starting

Ask the person for anything you cannot read in the project. Infrastructure values usually come from the team's internal deployment documentation, not from this README.

ValueExampleWhere it comes from
Project name (APP_PROJECT)my_apiUsually the repository name, snake_case. It must match the project folder in the activity service: my_api → MyApi (section 8). If the deploy files already set APP_PROJECT, check that the value really is this project's (copied deploy scripts often carry another project's name).
Routes to collect^/api/v1/items, ^/api/v1/listThe person decides. Check them against the real paths (bin/console debug:router), including any route prefix (for example API Platform's prefix: /api/v1).
Fields to hidepassword, address fieldsThe person decides (passwords, tokens, free text or contact details with personal data).
Symfony environments and their queue prefixprod → /productionThe prefix the collector service of that environment reads. Ask for every deployed environment.
RabbitMQ DSN per deployed environmentamqp://user:***@<rabbitmq host>:5672/%2fUsually written by the deploy scripts or set on the server. If you cannot see it for an environment, list it as a question: the person must confirm it points to the same server and vhost as that environment's collector service.
How PHP gets its environment in each deployed environmentpool file mounted into the container, or container/service variablesRead the Dockerfile, compose/stack and deploy files. Needed for step 6.5.
Default zoneca (or a parameter such as %zone%)The project's parameters per environment.
Bundle repository URLhttps://<git host>/<team>/rezilio-collector-bundle.gitOnly if the project does not resolve the package yet (step 6.1).
Where to check resultscollector service host and batch folder, activity database name per environmentNeeded for section 9. Ask the person or the operations team.

4. New installation or upgrade?

Run these from the Symfony project root: the folder with composer.json and bin/console (it can be a subfolder of the repository, for example api/). If composer.lock does not exist, ignore that command's error and rely on composer.json.

grep -n "rezilio/collector-bundle" composer.json
grep -A2 '"name": "rezilio/collector-bundle"' composer.lock      # installed version, even without vendor/
grep -rn "pre_auth_collection" config/
grep -rn "CollectorListener\|UserResolver\|collector.user_resolver\|CollectableUser\|CollectorBundle\\\\Contract" config/ src/
grep -rn "CollectionResponse\|CollectorService" config/ src/
grep -n "CollectorBundle" config/bundles.php
ResultPath to follow
Nothing found by any commandSection 6, new installation
The bundle is installed (any version) or any command finds somethingSection 7, upgrade

Signs of an older setup: pre_auth_collection in collector.yaml (versions up to 1.0.16), an AppCollectorListener registered in services.yaml, a service override of Rezilio\CollectorBundle\EventListener\CollectorListener, classes using Rezilio\CollectorBundle\Contract\… (CollectorUserResolver, CollectableUser), an app:queue:publish command, or a copy of the collector inside the project (for example App\Service\CollectorService and an App\Message\CollectionResponse class).

5. Requirements

WhatNotes
PHP 7.4+
Symfony 4.4 → 7.xframework-bundle, messenger, http-client, http-foundation
AMQP transportPHP extension amqp on every server/container that runs the API, plus symfony/amqp-messenger on Symfony ≥ 5.1 (on 4.4 the AMQP transport ships inside symfony/messenger)
JWT bearer tokensWith the claims below
Authorization header reaching PHPnginx + php-fpm passes it. Apache needs SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 (or CGIPassAuth On)
Collected routes behind the firewallThe bundle reads the token without checking its signature; it relies on your firewall having authenticated the request
A deploy that can run composer installThe machine or container that installs vendor/ needs Composer, read access to the bundle's repository, and every PHP extension the lock file requires (or --ignore-platform-req=… for an extension the image cannot have and the API does not use). A project that never used a private package before may fail here on its first deploy.

JWT claims

User context is read only from the token payload. The first seven claims below are required: if one is missing, the request is not collected (a warning [CollectorBundle] JWT payload missing required claims is logged; the request itself is never affected).

ClaimTypeRequiredNotes
usernamestringyesStored as user and email. The journal groups records by it.
rolesarrayyes
zonestringyesca, fr…
localestringyes
user_idintyes
org_idintyesThe journal filters on this organization
role_idintyes
partner_idstring (UUID)no (since 1.0.20)Stored as null when absent
first_namestringno (since 1.0.21)- when absent
last_namestringno (since 1.0.21)- when absent

A token issuer may put different claims in a sign-in token and in a refreshed token. Most API calls carry a refreshed one, so decode both kinds when you check the claims.

Requests made with an impersonation token (claim authenticating_user present) are never collected.

6. New installation

6.1 Install the package

The bundle is not on Packagist. If the project does not already reach it (no repositories entry, no global Composer configuration), add its repository to composer.json, top level, next to require (URL from section 3):

"repositories": [
    { "type": "vcs", "url": "<bundle repository URL>" }
]

Use an HTTPS URL with Composer credentials (auth.json), or an SSH URL if the machines running Composer have an SSH key. Never commit auth.json.

Then:

composer require rezilio/collector-bundle:^1.0.21
composer require symfony/amqp-messenger      # Symfony >= 5.1 only, skip if already required
php -m | grep amqp                           # must print "amqp"

Every machine running composer install (CI and deploy included) needs read access to the bundle's repository. If composer.json has "bump-after-update": true, Composer rewrites the constraint after an update; that is expected. If Symfony Flex creates a recipe entry in symfony.lock, commit it too.

Done when: composer show rezilio/collector-bundle shows 1.0.21 or later, and the updated composer.json and composer.lock are committed.

6.2 Register the bundle

// config/bundles.php
return [
    // ...
    Rezilio\CollectorBundle\CollectorBundle::class => ['all' => true],
];

The bundle registers its own services: the route listener, the 401/403 subscriber and CollectorServiceFactory. Do not register any of them yourself and do not import files from the bundle's config/ folder.

Done when: the line is present exactly once.

6.3 Configure what to collect

Create config/packages/collector.yaml:

collector:
    default_zone: 'ca'            # required; a parameter such as '%zone%' also works
    rejected_collection: true     # default: also record requests refused with 401/403
    routes:
        - { path: '^/api/v1/items' }
        - path: '^/api/v1/profile/reset-password'
          sanitize:
              - { field: password, action: redact }

Rules:

  • default_zone is required: without it the container does not compile. If the project already has a zone parameter that the rest of its configuration uses (for example %zone%), use it. Otherwise write the value ('ca').
  • rejected_collection defaults to true; writing it is optional.
  • routes lists the requests to collect. With no routes, nothing is collected except 401/403.
  • path is a regular expression tested against the request URI including the query string. Write it against the real path, with the route prefix (^/api/v1/…, not ^/items). To collect a whole API, list its prefixes (^/api/v1/, ^/api/v2/).
  • Only list paths covered by a firewall that authenticates the JWT (security.yaml, firewalls).
  • controller (FQCN) can replace or complement path. Both must match when both are given. For API Platform resources, use path: the controller is an API Platform class, not your processor or provider.
  • The first matching route wins. To hide the same fields on several routes, repeat sanitize or use a YAML anchor (sanitize: &hidden [...], then sanitize: *hidden).
  • sanitize actions, applied in order:
    • redact: the value becomes -
    • hash: adds {field}_md5
    • length: adds {field}_length

Done when: bin/console debug:config collector prints the configuration without error.

6.4 Send the records to RabbitMQ

In config/packages/messenger.yaml, add the transport and the routing (keep what is already there):

framework:
    messenger:
        transports:
            collection_queue: '%env(MESSENGER_TRANSPORT_DSN)%%rabbitmq_prefix%-CollectionQueue'
        routing:
            'Rezilio\CollectorBundle\Message\CollectionResponse': collection_queue

Then define rabbitmq_prefix in every environment the application runs in (each deployed one, plus test if the test suite boots the kernel), in config/packages/<env>/parameters.yaml (or services.yaml), with the prefix collected in section 3. If a project already lacks test parameters for other values too, list it as a question instead of creating the file. The leading slash is part of the value:

# config/packages/prod/parameters.yaml
parameters:
    rabbitmq_prefix: '/production'      # the value the production collector service reads

MESSENGER_TRANSPORT_DSN must, in every deployed environment, be an amqp:// DSN pointing to the same RabbitMQ server and vhost as that environment's collector service. With a wrong prefix or vhost the messages go to a queue nobody reads. If the variable is sync:// there (for example the .env default was never overridden), nothing is sent. In both cases nothing reports an error.

Keep Messenger's default serializer for this transport: the collector service unserializes the PHP class Rezilio\CollectorBundle\Message\CollectionResponse.

An environment whose transport is sync:// (often dev on a laptop, through .env or a when@dev block) sends nothing to RabbitMQ: that is fine locally, but if that environment is a deployed server whose activity must be collected, ask. A sync:// environment needs the handler of step 6.6.

Done when: bin/console debug:config framework messenger --env=<env> shows collection_queue and the routing for every deployed environment, and the person has confirmed the DSN of each deployed environment is the one its collector service reads.

6.5 Name the project: APP_PROJECT

Every record carries project, read with PHP's getenv('APP_PROJECT'). The activity service uses it to find the project's actions. Without it the value is unknown; with a wrong value the records are filed under another project. Either way nothing reaches the journal under this project.

What getenv() returns under php-fpm depends on the setup:

  • php-fpm empties the environment of its workers by default (clear_env = yes). Then only env[...] lines of the pool configuration reach PHP; a container or host variable does not.
  • With clear_env = no, the container's (or service's) environment reaches PHP.
  • .env / .env.local values may or may not reach getenv(), depending on the Symfony version and runtime, and when they do they can win over the pool or container value. Do not rely on them, and never leave a wrong value there.

Do this:

  1. Set the value where php-fpm reads it in every deployed environment:
    • if the pool file used on the server comes from the project (for example www.conf committed and mounted into the container), add inside its [www] section:
      ; rezilio/collector-bundle reads the project name with getenv()
      env[APP_PROJECT] = my_api
      

      If the project has several deployed copies of the pool file, change every copy;

    • if the pool file on the server is not the project's (generated or replaced at deploy time) and it has clear_env = no, set the variable on the container instead, in the compose/stack file or with docker service update --env-add APP_PROJECT=my_api <service> (then also in the file the service is created from).
  2. Make every other occurrence agree: grep -rn APP_PROJECT . in the project, its deploy scripts and the .env.local files they write. Fix or remove any value that is not this project's name.
  3. Console commands that record events also need the variable in the shell environment (APP_PROJECT=my_api bin/console …).

Done when: after a deploy, a collected request carries the right name. Check the record itself (section 9, step 3): php-fpm -tt only shows env[...] pool lines, not container variables, and /proc/<pid>/environ of php-fpm cannot be trusted (php-fpm overwrites it with its process title).

6.6 Message handler (only for sync:// environments)

The API only sends these messages; no handler is needed with RabbitMQ. If an environment uses sync://, add this stub, otherwise every collection logs a "no handler" warning there:

<?php
// src/MessageHandler/CollectionResponseHandler.php
namespace App\MessageHandler;

use Rezilio\CollectorBundle\Message\CollectionResponse;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]   // Symfony >= 5.4. On 4.4 – 5.3: remove the attribute and implement
                      // Symfony\Component\Messenger\Handler\MessageHandlerInterface
class CollectionResponseHandler
{
    public function __invoke(CollectionResponse $message): void
    {
        // Real processing is done by the collector service.
    }
}

If the project already has a handler for Rezilio\CollectorBundle\Message\CollectionResponse, keep it as it is (any signature works).

Never run messenger:consume collection_queue (or messenger:consume --all) in the API: with this stub the worker would take the records off the queue and drop them.

6.7 Optional: organization from planId

When a request has ctxId, it is stored as organisationId. When it only has planId, the bundle can look the organization up (one HTTP call per plan, cached in /tmp/cache.plan.{id}.cache) if this parameter points to the data API that serves /plans/{id}.json:

parameters:
    collector.api_directdata_v2_base_url: '<data API base URL>'

Continue with section 8.

7. Upgrading a project that uses the old install method

Older setups are installed differently, and several of their pieces turn collection off without any error, so they must be removed. Apply every step; skip a step only when its "Look for" finds nothing.

7.1 Upgrade the package and the lock file

composer require alone is not enough on an existing project: the lock file must change, otherwise every deploy keeps installing the old version, which refuses the new configuration.

  1. In composer.json, set "rezilio/collector-bundle": "^1.0.21". Do not add a repositories entry if the project already resolves the package (global Composer configuration or an existing entry). Add the entry of step 6.1 only if composer update reports that the package cannot be found.
  2. Run, then commit composer.json and composer.lock together:
composer update rezilio/collector-bundle
composer show rezilio/collector-bundle | grep -E '^versions'

Done when: the version shown is 1.0.21 or later and composer.lock is in the commit.

If you cannot run Composer: still make the composer.json change and the other steps, but tell the person that nothing may be committed or deployed until composer.lock is updated, then commit everything together (old lock + new config = a container that does not compile).

7.2 Remove the old listener registration and in-project collector

Look for in config/services.yaml (and any other services file):

    App\EventListener\AppCollectorListener:        # whole block, any arguments
        arguments:
            $factory: '@Rezilio\CollectorBundle\Service\CollectorServiceFactory'
            ...
        tags:
            - { name: kernel.event_subscriber }

    Rezilio\CollectorBundle\EventListener\CollectorListener:   # whole block: it turns the bundle's listener off
        autoconfigure: false
        tags: [ ]

Do: delete both blocks completely.

Leave the exclude pattern of the App\: resource unchanged even if it lists EventListener: other classes may depend on it.

Also look for code that collects by itself (an event subscriber calling an in-project CollectorService, often on kernel.request). Do: remove that call (and any helper used only by it), otherwise every request is recorded twice, once by each collector.

7.3 Remove the old user resolver

Look for in config/services.yaml:

    App\Service\CollectorUserResolver:
        tags: ['collector.user_resolver']
    Rezilio\CollectorBundle\Contract\UserResolverInterface: '@App\Service\CollectorUserResolver'

Do: delete these entries.

7.4 Update config/packages/collector.yaml

  1. Remove pre_auth_collection (current versions refuse it).
  2. Add default_zone (required).
  3. Check every path against the real routes (bin/console debug:router), with the route prefix:
    • remove an entry that matches no route (for example ^/items when every route starts with /api/v1);
    • remove an entry that sits outside every JWT firewall;
    • leave an entry that is also matched by an earlier, broader entry (^/api/v1/items/export after ^/api/v1/items): it is redundant but harmless. If you cannot run debug:router and the person has not told you which routes exist, keep the entry and list it as a question.
  4. Do not add other keys: rejected_collection already defaults to true.
  5. Ask whether fields must be hidden (sanitize, step 6.3), especially for routes that carry free text or personal data. An in-project collector may already have removed some fields: hide the same ones.

Result, for example:

collector:
    default_zone: '%zone%'
    routes:
        - { path: '^/api/v1/items' }
        - { path: '^/api/v1/list' }

7.5 Delete the old classes

Look for these files (names may vary; use the grep of section 4):

FileWhy it must go
src/EventListener/AppCollectorListener.phpUnused once 7.2 is done; extending the listener is not supported (see Known limitations)
src/Service/CollectorUserResolver.phpImplements Rezilio\CollectorBundle\Contract\UserResolverInterface, which no longer exists
src/Service/CollectableUser.phpImplements Rezilio\CollectorBundle\Contract\CollectableUserInterface, which no longer exists
Any other class using Rezilio\CollectorBundle\Contract\…Same reason
An in-project CollectorService, App\Message\CollectionResponse and its handlerReplaced by the bundle (7.2)

Do: list them to the person, then git rm them, in the same change as 7.1.

src/Command/QueuePublishCommand.php (app:queue:publish) can stay as a transport test tool, but the records it sends have no user or path and end up in unclassified. Do not use it to record real events (see Recording an event yourself).

7.6 Check messenger

In config/packages/messenger.yaml (and every when@<env> block or environment file):

  • the transport and routing match step 6.4 exactly;
  • there is no routing for an old App\Message\CollectionResponse class;
  • environments using sync:// have the handler of step 6.6;
  • every deployed environment defines rabbitmq_prefix with the value collected in section 3;
  • every deployed environment's DSN is the one its collector service reads (6.4). A when@dev block or .env forcing sync:// is fine on laptops; if dev is also a deployed server whose activity must be collected, ask;
  • no worker of the API (supervisor, systemd, Docker command, cron) runs messenger:consume --all or messenger:consume collection_queue. If you cannot see the worker configuration, ask.

7.7 APP_PROJECT

Older setups often set APP_PROJECT only in .env or .env.local (sometimes written by the deploy script), or passed the project name in code. Apply step 6.5 in full.

7.8 Rebuild the cache

bin/console cache:clear
bin/console debug:config collector
bin/console debug:event-dispatcher kernel.controller | grep -i collector    # exactly one CollectorListener
bin/console debug:event-dispatcher kernel.response | grep -i collector      # CollectorRejectedSubscriber

Done when: the container compiles, debug:config collector shows default_zone and the routes, and CollectorListener (the bundle's class, not AppCollectorListener) is listed once.

Step 6.7 (organization from planId) is optional and unchanged by the upgrade.

Continue with section 8.

8. Declare the project in the activity service

Separate repository, with one folder per project under api/src/Model/Project/. Without this step every record of the project goes to the unclassified table and never reaches the journal.

8.1 Create the project folder (new project only)

Folder name = APP_PROJECT in CamelCase: my_api → MyApi.

Copy Process.php and Hydrator.php from an existing project folder into the new one, and change only the namespace line (namespace App\Model\Project\MyApi;). Create an empty configs.yaml next to them, and a Decorator/ folder only if titles must be fetched (see existing projects).

8.2 Find what the bundle records for each request

configs.yaml is matched on the method, the path (without the query string) and the class the bundle recorded:

  • the class is the controller's class name, without ::method (App\Controller\ItemController, not App\Controller\ItemController::show);
  • API Platform 3 operations that have no custom controller are recorded as ApiPlatform\Action\PlaceholderAction (not your processor or provider, and not the service id api_platform.action.placeholder).

Do not guess: deploy sections 6/7 first, use the API, then read the real values in the activity database of that environment:

SELECT DISTINCT class, method, path
FROM <activity database>.unclassified
WHERE project = 'my_api'
  AND year = year(current_date) AND month = month(current_date) AND day = day(current_date);

The columns of these tables come from the records first written to them, so names can differ between environments: if a column is missing, run SELECT * with a LIMIT and use the names it shows.

8.3 Write configs.yaml

Format: origin label → recorded class → METHOD path-or-regex: action. Follow the existing project files for style and action names (<product>:<object>:<verb>):

MyApi:                                        # origin shown in the journal
    App\Controller\ItemController:            # value of "class" from 8.2
        GET /api/v1/items/([0-9a-z\-]+):          myapi:items:access
    'ApiPlatform\Action\PlaceholderAction':
        PUT /api/v1/items/([0-9a-z\-]+):          myapi:items:update
        POST /api/v1/items:                       myapi:items:create

An exact path is matched before a regular expression, and the first matching line wins. Requests with no matching line stay in unclassified.

The action names are a product decision: propose them, let the person confirm them.

After deploying configs.yaml to an activity service host, restart all of its workers: they keep the old file in memory.

Done when: after the deploy and the restart, new requests of the project appear in that environment's live table with an action, and no longer in unclassified.

9. Check that it works

Use the values collected in section 3 (collector service host and batch folder, activity database).

  1. Configuration (in the API):
    bin/console debug:config collector
    bin/console debug:config framework messenger --env=prod
    bin/console debug:event-dispatcher kernel.controller | grep -i collector    # one CollectorListener
    
  2. Call a configured route with a valid token. A successful collection writes nothing to the API's logs; only skips and errors are logged ([CollectorBundle] …). In the RabbitMQ management UI, queue <prefix>-CollectionQueue: the message count goes up, then back to 0 once the collector service has read it. The queue shows 0 consumers even when the collector service runs: Symfony's AMQP transport polls the queue instead of subscribing.
  3. On the collector service host, in its batch folder, the record is in the current _minute_*.dat file with this project's name:
    grep -ho '"project":"[^"]*"' _minute_* | sort | uniq -c
    

    About a minute later the file is sent to the activity service and renamed .dat.done.

  4. A minute or two later, in the activity database:
    SELECT from_unixtime(datecollected), method, path, action
    FROM <activity database>.live
    WHERE user = 'someone@example.com'
      AND year = year(current_date) AND month = month(current_date) AND day = day(current_date)
    ORDER BY datecollected DESC;
    

    Partitions are UTC days. The action also appears in the user's activity journal.

Nothing shows up?

SymptomLikely cause
Container does not compile: Unrecognized option "pre_auth_collection" under "collector"Old config, step 7.4
Container does not compile: The child config "default_zone" under "collector" must be configuredStep 6.3 / 7.4
composer install installs an old version after deployLock file not updated, step 7.1
Deploy fails at composer installNo access to the bundle's repository, no Composer in the image, or a PHP extension missing (section 5)
Log: JWT payload missing required claimsA required claim is missing. Decode a real token of each kind (sign-in and refreshed, section 5)
Log: Messenger bus not availablesymfony/messenger not installed or no default bus
Nothing logged, nothing in RabbitMQRoute does not match routes; old listener override still present (7.2); Authorization header not reaching PHP; impersonation token
Every request recorded twiceCollectorListener registered twice, or an in-project collector still running (7.2)
Messages stay in a queueWrong rabbitmq_prefix or vhost: the collector service reads another queue
Queue shows 0 consumersNormal: the transport polls (step 9.2). Check the minute files instead
Records in the minute files, nothing in the databaseThe collector service cannot send its batches. curl -X POST -d '' https://<activity service host>/api/1.0/batch_collect from the collector host must answer {"status":"success"} (DNS, firewall and TLS certificate)
Nothing in the database you queryEach environment writes to its own database (section 2)
In unclassified with project = 'unknown'APP_PROJECT does not reach getenv(), step 6.5
Recorded under another project's nameA wrong APP_PROJECT somewhere (often .env.local written by a copied deploy script), step 6.5
In unclassified with the right projectNo matching line in the activity service's configs.yaml, or its workers were not restarted (section 8)

10. Reference

Rejected requests (401 / 403)

CollectorRejectedSubscriber records requests refused by the firewall before any controller ran, with class = "AuthRejected", a status_code field and siteUuid when present. Whatever claims the (possibly invalid) token carries are used; the zone falls back to default_zone. Requests already recorded by the route listener are not recorded twice. Disable with rejected_collection: false.

Recording an event yourself

To record something outside the route listener (a command, a message handler…), go through the factory so the record has the shape the activity service expects. Dispatching a raw CollectionResponse with your own array skips the user, path and request fields, and the record lands in unclassified.

use Rezilio\CollectorBundle\Service\CollectorServiceFactory;

private CollectorServiceFactory $collector;

public function __construct(CollectorServiceFactory $collector)   // autowired
{
    $this->collector = $collector;
}

// $claims: the decoded JWT payload of the user the event belongs to (same claims as section 5)
$this->collector
    ->createFromPayload($claims)
    ->collect(static::class, ['order_id' => $orderId]);

Things to avoid

  • Registering CollectorListener or a subclass in your services. The bundle already registers it with your routes. A second registration with $routes: [] does nothing; with routes, every request is recorded twice. A service override of CollectorListener (tags: [ ]) turns collection off.
  • Importing the bundle's config/collector.yaml. It is an old service definition and registers a second, empty listener.
  • Consuming collection_queue from your API. See step 6.6.
  • Copying another project's deploy scripts or .env.local without changing APP_PROJECT. See step 6.5.
  • Using a custom Messenger serializer for collection_queue. The collector service expects the default PHP serialization.
  • Writing debug output (records, payloads) to files under a web root while investigating: those files are publicly downloadable and contain personal data.

Known limitations (1.0.21)

  • buildExtra() (extra fields per project) has no supported way to be enabled: the extension always registers the base CollectorListener.
  • Service/DataProviderAbstract.php does not load: its namespace does not match its folder, and it uses classes and methods that no longer exist (CollectableUserInterface, CollectorServiceFactory::create()). Use the routes configuration instead.
  • UserResolverPass is not registered and does nothing.
  • The listener does not verify the JWT signature: only list routes that sit behind the firewall.
  • redact writes - for every listed field, even when the request did not contain it, so request shows those keys on every record.
  • trxid is recorded as - even when the URL carries trxId.

What is included

ClassPurpose
CollectorBundleBundle entry point
DependencyInjection\CollectorExtension / ConfigurationRegisters the services, validates collector.yaml
EventListener\CollectorListenerkernel.controller: collects requests matching routes
EventListener\CollectorRejectedSubscriberkernel.response: collects 401/403 rejected before a controller ran
Service\CollectorServiceFactoryCreates a CollectorService from a JWT payload
Service\CollectorServiceBuilds the record (user, request, server data, sanitizing) and dispatches it
Message\CollectionResponseThe Messenger message (zone + data) read by the collector service