rezilio / collector-bundle
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
Requires
- php: ^7.4|^8.0
- symfony/framework-bundle: ^4.4|^5.0|^6.0|^7.0
- symfony/http-client: ^4.4|^5.0|^6.0|^7.0
- symfony/http-foundation: ^4.4|^5.0|^6.0|^7.0
- symfony/messenger: ^4.4|^5.0|^6.0|^7.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
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:
- Rules for AI assistants
- How a record travels
- Values to collect before starting
- New installation or upgrade?
- Requirements
- New installation
- Upgrading a project that uses the old install method
- Declare the project in the activity service
- Check that it works
- Reference
1. Rules for AI assistants
If you are an AI assistant applying this README to a project:
- Read the project before changing anything. Run the detection commands in section 4 and show their output to the person.
- 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.
- Follow one path only: section 6 (new installation) or section 7 (upgrade), as decided in section 4. Then section 8, then section 9.
- Apply the steps in order. After each step, check its "Done when" condition.
- Only change the files a step names. Do not reformat, reorder or "clean up" other files.
- Show every change as a diff and list the files you changed at the end.
- Deleting files: list the files and let the person confirm before deleting (
git rm). - 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.
- 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. - 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.
- Do not write secrets (DSN passwords, keys, tokens) into the report or into files that are not already meant to hold them.
- Things to never do: see Things to avoid.
- 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:
| Condition | Set in | Section |
|---|---|---|
The route is listed in collector.yaml | your API | 6.3 / 7.4 |
| The JWT carries the required claims | the token issuer | 5 |
| The message reaches the queue the collector service reads (same server, vhost and prefix) | your API | 6.4 |
getenv('APP_PROJECT') returns this project's name | your API's runtime configuration | 6.5 |
| The activity service knows the project and gives the request an action name | activity service | 8 |
| The collector service can reach the activity service | operations | 9 |
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.
| Value | Example | Where it comes from |
|---|---|---|
Project name (APP_PROJECT) | my_api | Usually 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/list | The 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 hide | password, address fields | The person decides (passwords, tokens, free text or contact details with personal data). |
| Symfony environments and their queue prefix | prod → /production | The prefix the collector service of that environment reads. Ask for every deployed environment. |
| RabbitMQ DSN per deployed environment | amqp://user:***@<rabbitmq host>:5672/%2f | Usually 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 environment | pool file mounted into the container, or container/service variables | Read the Dockerfile, compose/stack and deploy files. Needed for step 6.5. |
| Default zone | ca (or a parameter such as %zone%) | The project's parameters per environment. |
| Bundle repository URL | https://<git host>/<team>/rezilio-collector-bundle.git | Only if the project does not resolve the package yet (step 6.1). |
| Where to check results | collector service host and batch folder, activity database name per environment | Needed 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
| Result | Path to follow |
|---|---|
| Nothing found by any command | Section 6, new installation |
| The bundle is installed (any version) or any command finds something | Section 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
| What | Notes |
|---|---|
| PHP 7.4+ | |
| Symfony 4.4 → 7.x | framework-bundle, messenger, http-client, http-foundation |
| AMQP transport | PHP 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 tokens | With the claims below |
Authorization header reaching PHP | nginx + php-fpm passes it. Apache needs SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 (or CGIPassAuth On) |
| Collected routes behind the firewall | The bundle reads the token without checking its signature; it relies on your firewall having authenticated the request |
A deploy that can run composer install | The 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).
| Claim | Type | Required | Notes |
|---|---|---|---|
username | string | yes | Stored as user and email. The journal groups records by it. |
roles | array | yes | |
zone | string | yes | ca, fr… |
locale | string | yes | |
user_id | int | yes | |
org_id | int | yes | The journal filters on this organization |
role_id | int | yes | |
partner_id | string (UUID) | no (since 1.0.20) | Stored as null when absent |
first_name | string | no (since 1.0.21) | - when absent |
last_name | string | no (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_zoneis 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_collectiondefaults totrue; writing it is optional.routeslists the requests to collect. With no routes, nothing is collected except 401/403.pathis 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 complementpath. Both must match when both are given. For API Platform resources, usepath: 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
sanitizeor use a YAML anchor (sanitize: &hidden [...], thensanitize: *hidden). sanitizeactions, applied in order:redact: the value becomes-hash: adds{field}_md5length: 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 onlyenv[...]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.localvalues may or may not reachgetenv(), 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:
- 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.confcommitted and mounted into the container), add inside its[www]section:; rezilio/collector-bundle reads the project name with getenv() env[APP_PROJECT] = my_apiIf 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 withdocker service update --env-add APP_PROJECT=my_api <service>(then also in the file the service is created from).
- if the pool file used on the server comes from the project (for example
- Make every other occurrence agree:
grep -rn APP_PROJECT .in the project, its deploy scripts and the.env.localfiles they write. Fix or remove any value that is not this project's name. - 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.
- In
composer.json, set"rezilio/collector-bundle": "^1.0.21". Do not add arepositoriesentry if the project already resolves the package (global Composer configuration or an existing entry). Add the entry of step 6.1 only ifcomposer updatereports that the package cannot be found. - Run, then commit
composer.jsonandcomposer.locktogether:
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
- Remove
pre_auth_collection(current versions refuse it). - Add
default_zone(required). - Check every
pathagainst the real routes (bin/console debug:router), with the route prefix:- remove an entry that matches no route (for example
^/itemswhen 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/exportafter^/api/v1/items): it is redundant but harmless. If you cannot rundebug:routerand the person has not told you which routes exist, keep the entry and list it as a question.
- remove an entry that matches no route (for example
- Do not add other keys:
rejected_collectionalready defaults totrue. - 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):
| File | Why it must go |
|---|---|
src/EventListener/AppCollectorListener.php | Unused once 7.2 is done; extending the listener is not supported (see Known limitations) |
src/Service/CollectorUserResolver.php | Implements Rezilio\CollectorBundle\Contract\UserResolverInterface, which no longer exists |
src/Service/CollectableUser.php | Implements 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 handler | Replaced 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\CollectionResponseclass; - environments using
sync://have the handler of step 6.6; - every deployed environment defines
rabbitmq_prefixwith the value collected in section 3; - every deployed environment's DSN is the one its collector service reads (6.4). A
when@devblock or.envforcingsync://is fine on laptops; ifdevis also a deployed server whose activity must be collected, ask; - no worker of the API (supervisor, systemd, Docker command, cron) runs
messenger:consume --allormessenger: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, notApp\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 idapi_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).
- 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 - 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. - On the collector service host, in its batch folder, the record is in the current
_minute_*.datfile with this project's name:grep -ho '"project":"[^"]*"' _minute_* | sort | uniq -cAbout a minute later the file is sent to the activity service and renamed
.dat.done. - 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?
| Symptom | Likely 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 configured | Step 6.3 / 7.4 |
composer install installs an old version after deploy | Lock file not updated, step 7.1 |
Deploy fails at composer install | No access to the bundle's repository, no Composer in the image, or a PHP extension missing (section 5) |
Log: JWT payload missing required claims | A required claim is missing. Decode a real token of each kind (sign-in and refreshed, section 5) |
Log: Messenger bus not available | symfony/messenger not installed or no default bus |
| Nothing logged, nothing in RabbitMQ | Route does not match routes; old listener override still present (7.2); Authorization header not reaching PHP; impersonation token |
| Every request recorded twice | CollectorListener registered twice, or an in-project collector still running (7.2) |
| Messages stay in a queue | Wrong rabbitmq_prefix or vhost: the collector service reads another queue |
| Queue shows 0 consumers | Normal: the transport polls (step 9.2). Check the minute files instead |
| Records in the minute files, nothing in the database | The 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 query | Each 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 name | A wrong APP_PROJECT somewhere (often .env.local written by a copied deploy script), step 6.5 |
In unclassified with the right project | No 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
CollectorListeneror a subclass in your services. The bundle already registers it with yourroutes. A second registration with$routes: []does nothing; with routes, every request is recorded twice. A service override ofCollectorListener(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_queuefrom your API. See step 6.6. - Copying another project's deploy scripts or
.env.localwithout changingAPP_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 baseCollectorListener.Service/DataProviderAbstract.phpdoes not load: its namespace does not match its folder, and it uses classes and methods that no longer exist (CollectableUserInterface,CollectorServiceFactory::create()). Use theroutesconfiguration instead.UserResolverPassis not registered and does nothing.- The listener does not verify the JWT signature: only list routes that sit behind the firewall.
redactwrites-for every listed field, even when the request did not contain it, sorequestshows those keys on every record.trxidis recorded as-even when the URL carriestrxId.
What is included
| Class | Purpose |
|---|---|
CollectorBundle | Bundle entry point |
DependencyInjection\CollectorExtension / Configuration | Registers the services, validates collector.yaml |
EventListener\CollectorListener | kernel.controller: collects requests matching routes |
EventListener\CollectorRejectedSubscriber | kernel.response: collects 401/403 rejected before a controller ran |
Service\CollectorServiceFactory | Creates a CollectorService from a JWT payload |
Service\CollectorService | Builds the record (user, request, server data, sanitizing) and dispatches it |
Message\CollectionResponse | The Messenger message (zone + data) read by the collector service |