PHPackages                             treblle/treblle-symfony - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. treblle/treblle-symfony

ActiveLibrary[Logging & Monitoring](/categories/logging)

treblle/treblle-symfony
=======================

Runtime Intelligence Platform

v4.0.1(1mo ago)728.0k↑19.4%4[1 issues](https://github.com/Treblle/treblle-symfony/issues)MITPHPPHP ^8.2|^8.3|^8.4

Since Oct 26Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/Treblle/treblle-symfony)[ Packagist](https://packagist.org/packages/treblle/treblle-symfony)[ Docs](https://treblle.com/)[ RSS](/packages/treblle-treblle-symfony/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (10)Dependencies (16)Versions (15)Used By (0)

Treblle - Runtime Intelligence Platform
=======================================

[](#treblle---runtime-intelligence-platform)

[Website](http://treblle.com/) • [Documentation](https://docs.treblle.com/) • [Pricing](https://treblle.com/pricing)

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

Treblle Symfony SDK
-------------------

[](#treblle-symfony-sdk)

[![Latest Version](https://camo.githubusercontent.com/6f891500d69f2891a8c6b5e96b35b4c78f8d959fd9c110579b36d85b7e04030c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f747265626c6c652f747265626c6c652d73796d666f6e79)](https://packagist.org/packages/treblle/treblle-symfony)[![Total Downloads](https://camo.githubusercontent.com/878bbc5d0a6fefd4a7156e6c289ce6cc5f95e70b4e42a34f6a48461cea07050c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f747265626c6c652f747265626c6c652d73796d666f6e79)](https://packagist.org/packages/treblle/treblle-symfony)

Requirements
------------

[](#requirements)

DependencyVersionPHP8.2, 8.3, 8.4Symfony6.4, 7.x, 8.xext-curlanyext-jsonanyext-zlibany> **Async mode** (optional): `symfony/messenger` + a Redis or AMQP transport.

Installation
------------

[](#installation)

```
composer require treblle/treblle-symfony
```

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

Setup
-----

[](#setup)

### 1. Register the bundle

[](#1-register-the-bundle)

Add the bundle to `config/bundles.php`:

```
return [
    // ...
    Treblle\Symfony\TreblleBundle::class => ['all' => true],
];
```

### 2. Configure the SDK

[](#2-configure-the-sdk)

Create `config/packages/treblle.yaml`:

```
treblle:
  sdk_token: "%env(TREBLLE_SDK_TOKEN)%"
  api_key: "%env(TREBLLE_API_KEY)%"
```

### 3. Set your credentials

[](#3-set-your-credentials)

Add to your `.env`:

```
TREBLLE_SDK_TOKEN=your-sdk-token-from-treblle-dashboard
TREBLLE_API_KEY=your-api-key-from-treblle-dashboard
```

Both values are available in your [Treblle Dashboard](https://treblle.com).

---

Configuration Reference
-----------------------

[](#configuration-reference)

All options with their defaults:

```
treblle:
  sdk_token: ""               # Required - SDK Token from Treblle Dashboard
  api_key: ""                 # Required - API Key from Treblle Dashboard
  enabled: true               # Set to false to disable Treblle (e.g. in dev/test)
  async: false                # Dispatch via Symfony Messenger (requires Redis or AMQP transport)
  masked_keywords:            # Fields to mask - set to [] to disable masking entirely
    - password
    - pwd
    - secret
    - password_confirmation
    - passwordConfirmation
    - cc
    - card_number
    - cardNumber
    - ccv
    - ssn
    - credit_score
    - creditScore
  excluded_paths: []          # Paths to skip (exact or wildcard)
  ingress_url: "https://ingress.treblle.com"  # Ingress endpoint
  metadata: {}                # Key/Value metadata added to every request (user-id enables Customer Tracking)
```

### `sdk_token`

[](#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`

[](#api_key)

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

### `enabled`

[](#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:

```
# config/packages/dev/treblle.yaml
treblle:
  enabled: false
```

```
# config/packages/test/treblle.yaml
treblle:
  enabled: false
```

You can also drive it from an environment variable:

```
# config/packages/treblle.yaml
treblle:
  enabled: "%env(bool:TREBLLE_ENABLED)%"
```

### `masked_keywords`

[](#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:**

```
treblle:
  masked_keywords:
    - password
    - pwd
    - secret
    - password_confirmation
    - passwordConfirmation
    - cc
    - card_number
    - cardNumber
    - ccv
    - ssn
    - credit_score
    - creditScore
    - authorization
    - x-api-key
    - access_token
```

**Disabling masking entirely:**

```
treblle:
  masked_keywords: []
```

### `excluded_paths`

[](#excluded_paths)

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

```
treblle:
  excluded_paths:
    - health           # exact: /health
    - health/check     # exact: /health/check
    - admin/*          # wildcard: /admin/anything
    - internal/*       # wildcard: /internal/anything
```

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

### `ingress_url`

[](#ingress_url)

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

```
treblle:
  ingress_url: "https://ingress-eu.treblle.com"
```

### `metadata`

[](#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.

```
treblle:
  metadata:
    env: production
    region: us-east-1
    tier: enterprise
```

> **`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](#per-request-metadata) for adding dynamic values (e.g. the authenticated user's ID) at runtime.

---

### `async`

[](#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:

```
composer require 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:**

```
framework:
    messenger:
        transports:
            treblle:
                dsn: "%env(REDIS_URL)%"
                options:
                    stream: treblle_payloads

        routing:
            'Treblle\Symfony\Messenger\SendTrebllePayload': treblle
```

**AMQP (RabbitMQ):**

```
framework:
    messenger:
        transports:
            treblle:
                dsn: "%env(RABBITMQ_URL)%"
                options:
                    exchange:
                        name: treblle

        routing:
            'Treblle\Symfony\Messenger\SendTrebllePayload': treblle
```

3. Enable async in your Treblle config:

```
treblle:
  async: true
```

4. Start the Messenger worker:

```
php bin/console messenger:consume treblle --time-limit=3600
```

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
--------------------

[](#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.

```
use Treblle\Symfony\Metadata\MetadataRegistry;

final class OrderController extends AbstractController
{
    public function __construct(private readonly MetadataRegistry $treblle) {}

    #[Route('/orders', methods: ['POST'])]
    public function create(Request $request): JsonResponse
    {
        $this->treblle->add([
            'user-id'  => $this->getUser()?->getId(),
            'plan'     => 'enterprise',
            'tenant'   => 'acme-corp',
        ]);

        // ... handle request
    }
}
```

Multiple calls within the same request are merged together:

```
$this->treblle->add(['user-id' => 42]);
$this->treblle->add(['plan' => 'pro']);
// payload contains: { user-id: 42, plan: "pro" }
```

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
-----------------------

[](#migrating-from-v3-to-v4)

### 1. Update the package

[](#1-update-the-package)

```
composer require treblle/treblle-symfony:^4.0
```

### 2. Update your config file

[](#2-update-your-config-file)

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

v3 keyv4 keyNotes`masked_fields``masked_keywords`Renamed`url``ingress_url`Renamed`ignored_environments`*(removed)*Use `enabled` instead (see below)`debug`*(removed)*Use Monolog `treblle` channel instead`excluded_headers``excluded_paths`Different concept - now excludes by path, not header name**Before (v3):**

```
treblle:
  api_key: "%env(TREBLLE_API_KEY)%"
  sdk_token: "%env(TREBLLE_SDK_TOKEN)%"
  debug: false
  ignored_environments: dev,test,testing
  masked_fields:
    - password
    - secret
  excluded_headers:
    - Authorization
  url: "https://custom.treblle.com"
```

**After (v4):**

```
treblle:
  api_key: "%env(TREBLLE_API_KEY)%"
  sdk_token: "%env(TREBLLE_SDK_TOKEN)%"
  masked_keywords:
    - password
    - secret
  excluded_paths:
    - admin/*
  ingress_url: "https://custom.treblle.com"
```

### 3. Replace `ignored_environments` with `enabled`

[](#3-replace-ignored_environments-with-enabled)

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

```
# config/packages/dev/treblle.yaml
treblle:
  enabled: false
```

```
# config/packages/test/treblle.yaml
treblle:
  enabled: false
```

### 4. Remove the `debug` key

[](#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](#sdk-log-events) section for details.

### 5. Review `excluded_headers` vs `excluded_paths`

[](#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

[](#6-clear-your-cache)

```
php bin/console cache:clear
```

---

SDK Log Events
--------------

[](#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

[](#what-gets-logged)

LevelMessage`debug`Payload sent (with HTTP status code)`debug`Skipped paths, disabled state, async dispatch`warning`Missing `sdk_token` or `api_key` configuration`warning`cURL errors or non-2xx responses from the ingressWarnings 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

[](#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

[](#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`:

```
monolog:
    handlers:
        treblle:
            type: stream
            path: "%kernel.logs_dir%/treblle.log"
            level: debug
            channels: [treblle]
```

### Silencing Treblle logs in production

[](#silencing-treblle-logs-in-production)

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

```
# config/packages/prod/monolog.yaml
monolog:
    handlers:
        main:
            type: fingers_crossed
            channels: ['!treblle']  # exclude treblle from your main handler
```

---

License
-------

[](#license)

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

###  Health Score

58

—

FairBetter than 98% of packages

Maintenance89

Actively maintained with recent releases

Popularity35

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity76

Established project with proven stability

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~142 days

Recently: every ~79 days

Total

13

Last Release

30d ago

Major Versions

1.1.0 → 2.0.02025-02-11

2.0.2 → v3.0.02025-10-13

v3.0.0 → v4.0.02026-06-11

PHP version history (3 changes)1.0.0PHP ^7.4|^8.0

2.0.0PHP ^8.2

v3.0.0PHP ^8.2|^8.3|^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/795076376a2a3f5c648841fcc7da9d93c65184a815537c06639298f3997e264d?d=identicon)[cindreta](/maintainers/cindreta)

---

Top Contributors

[![JustSteveKing](https://avatars.githubusercontent.com/u/6368379?v=4)](https://github.com/JustSteveKing "JustSteveKing (11 commits)")[![cindreta](https://avatars.githubusercontent.com/u/628464?v=4)](https://github.com/cindreta "cindreta (10 commits)")[![bhushan](https://avatars.githubusercontent.com/u/43483545?v=4)](https://github.com/bhushan "bhushan (7 commits)")[![zoka123](https://avatars.githubusercontent.com/u/3052111?v=4)](https://github.com/zoka123 "zoka123 (4 commits)")[![Rahulkhinchi03](https://avatars.githubusercontent.com/u/71710042?v=4)](https://github.com/Rahulkhinchi03 "Rahulkhinchi03 (2 commits)")[![DominusKelvin](https://avatars.githubusercontent.com/u/24433274?v=4)](https://github.com/DominusKelvin "DominusKelvin (1 commits)")[![alenpokos](https://avatars.githubusercontent.com/u/1493829?v=4)](https://github.com/alenpokos "alenpokos (1 commits)")

---

Tags

apiapi-monitoringapi-observabilitybackenddeveloper-toolloggingphprest-apirestful-apisdksdk-phpsymfonytreblletreblle-sdkphpsymfonymonitoringlogsruntimeanalyticsobservabilityintelligencetrebllegovernance

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/treblle-treblle-symfony/health.svg)

```
[![Health](https://phpackages.com/badges/treblle-treblle-symfony/health.svg)](https://phpackages.com/packages/treblle-treblle-symfony)
```

###  Alternatives

[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.6M600](/packages/shopware-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)