Download the PHP package treblle/treblle-symfony without Composer

Treblle - Runtime Intelligence Platform

Website • Documentation • Pricing

Discover, Govern, and Secure APIs, Agents, and AI Across Any Cloud, Gateway or Technology.

Treblle Symfony SDK

Requirements

Async mode (optional): symfony/messenger + a Redis or AMQP transport.

Installation

Symfony Flex users: Steps 1–3 below happen automatically on install

Setup

1. Register the bundle

Add the bundle to config/bundles.php:

2. Configure the SDK

Create config/packages/treblle.yaml:

3. Set your credentials

Add to your .env:

Both values are available in your Treblle Dashboard.

Configuration Reference

All options with their defaults:

sdk_token

Your SDK Token from the Treblle Dashboard. This is sent as the x-api-key header on every request to the ingress.

api_key

Your project's API Key from the Treblle Dashboard. Identifies which project this data belongs to.

enabled

Controls whether Treblle is active. Defaults to true. Set to false to disable the SDK in specific environments without removing your credentials.

The recommended approach is an environment-specific config file:

You can also drive it from an environment variable:

masked_keywords

The list of field names to mask in request bodies, response bodies, request headers, and response headers. The SDK ships with a default list of common sensitive fields (see the configuration reference above). You control the list entirely - add, remove, or replace entries as needed.

Masking replaces each character of the value with *, preserving the original length, and is applied recursively to nested objects and arrays.

Adding fields to the default list:

Disabling masking entirely:

excluded_paths

Paths that should not be tracked by Treblle. Supports exact paths and wildcard patterns.

Paths are matched against the request's path without the leading /.

ingress_url

Override the default ingress endpoint. Useful for EU-hosted or self-hosted Treblle deployments:

metadata

Key/Value metadata attached to every request. Useful for environment tags, region, tier, or any data you always want visible and searcable in Treblle.

user-id is a reserved keyword. When present in metadata, Treblle uses it to enable Customer Tracking — linking requests to individual users so you can filter, search, and analyse traffic per customer in the dashboard.

See Per-request metadata for adding dynamic values (e.g. the authenticated user's ID) at runtime.

async

When true, the SDK dispatches payloads as Symfony Messenger messages instead of sending them inline. This moves the HTTP call to a background worker process, freeing your application immediately.

When to use async mode:

By default, the SDK sends data in the kernel.terminate event - after the HTTP response has already been delivered to your client (Symfony calls fastcgi_finish_request() first). For most applications this is sufficient.

Enable async: true if:

• You run at high request volume and need to free PHP-FPM workers immediately rather than holding them during the HTTP call to Treblle
• Your hosting environment does not use PHP-FPM (e.g. Apache mod_php, Swoole) and you want guaranteed zero impact on response time

Setup:

1. Install Symfony Messenger:

2. Configure a transport in config/packages/messenger.yaml. We recommend Redis or AMQP - the Doctrine (database) transport is not recommended at scale as it adds a DB write per request.

Redis:

AMQP (RabbitMQ):

3. Enable async in your Treblle config:

4. Start the Messenger worker:

Run this as a supervised process (Supervisor, systemd, etc.) so it restarts automatically.

Fallback behaviour:

If async: true is set but symfony/messenger is not installed, the SDK silently falls back to the default synchronous send. No errors, no data loss - it just skips the queue.

Per-request metadata

Inject MetadataRegistry into any controller or service and call add() with an associative array. Values are merged with the globally defined metadata in YAML for that request only and cleared automatically after the response is sent.

Multiple calls within the same request are merged together:

Runtime values take precedence over any static keys defined under treblle.metadata in your config — so you can set a sensible default in YAML and override it per-request when needed.

Customer Tracking: user-id is a reserved metadata keyword. When set, Treblle automatically links the request to that user in the dashboard, enabling per-customer traffic filtering, error tracking, and usage analysis.

Migrating from v3 to v4

1. Update the package

2. Update your config file

The following keys changed in config/packages/treblle.yaml:

Before (v3):

After (v4):

3. Replace ignored_environments with enabled

v4 has no ignored_environments option. Instead, disable Treblle per environment using Symfony's standard config override mechanism:

4. Remove the debug key

The debug flag no longer exists. Log output is controlled entirely through your monolog.yaml configuration via the treblle channel. See the SDK Log Events section for details.

5. Review excluded_headers vs excluded_paths

excluded_headers (v3) excluded specific header names from being tracked. excluded_paths (v4) excludes entire request paths from being tracked. These are different concepts - if you were using excluded_headers, review whether excluded_paths covers your use case, and use masked_keywords if you need to hide sensitive header values.

6. Clear your cache

SDK Log Events

The SDK logs through Symfony's standard logging system using a dedicated treblle Monolog channel. There is no separate debug flag - log visibility is controlled entirely by your existing monolog.yaml configuration, exactly as you would for any other Symfony component.

What gets logged

Warnings from the SDK indicate transient network issues on Treblle's side or misconfiguration. They are intentionally warning rather than error so that a Treblle outage never pollutes your application's error logs.

Viewing logs in development

The treblle channel appears automatically in the Symfony Web Profiler under the Logs tab. No configuration is needed - install the bundle and open any request in the profiler to see exactly what the SDK did.

Routing logs to a dedicated file

To send Treblle logs to their own file, add a handler for the treblle channel in config/packages/monolog.yaml:

Silencing Treblle logs in production

If you want to suppress all Treblle log output in production, exclude the channel from your existing handlers:

License

The MIT License (MIT). See LICENSE for details.