README

Treblle

Integrations • Website • Docs • Blog • Twitter • Discord

API Intelligence Platform. 🚀

Treblle is a lightweight SDK that helps Engineering and Product teams build, ship & maintain REST-based APIs faster.

Features

How Treblle Works

Once you’ve integrated a Treblle SDK in your codebase, this SDK will send requests and response data to your Treblle Dashboard.

In your Treblle Dashboard you get to see real-time requests to your API, auto-generated API docs, API analytics like how fast the response was for an endpoint, the load size of the response, etc.

Treblle also uses the requests sent to your Dashboard to calculate your API score which is a quality score that’s calculated based on the performance, quality, and security best practices for your API.

Visit https://docs.treblle.com for the complete documentation.

Security

Masking fields

Masking fields ensure certain sensitive data are removed before being sent to Treblle.

To make sure masking is done before any data leaves your server we built it into all our SDKs.

This means data masking is super fast and happens on a programming level before the API request is sent to Treblle. You can customize exactly which fields are masked when you’re integrating the SDK.

Visit the Masked fields section of the docs for the complete documentation.

Get Started

Sign in to Treblle.
Create a Treblle project.
Setup the SDK for your platform.

Install the SDK

composer require treblle/treblle-symfony

Enable it by adding it to the list of registered bundles in config/bundles.php:

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

Configure the SDK by adding the following snippet to config/packages/treblle.yaml:

treblle:
  api_key: "%env(TREBLLE_API_KEY)%"
  sdk_token: "%env(TREBLLE_SDK_TOKEN)%"
  debug: false
  ignored_environments: dev,test,testing
  masked_fields:
    - password
    - pwd
    - secret
    - password_confirmation
    - cc
    - card_number
    - ccv
    - ssn
    - credit_score
  excluded_headers:
    - Authorization
    - X-Api-Key

Configuration Options

api_key (required): Your Treblle API key (project ID)
sdk_token (required): Your Treblle SDK token
debug (optional, default: false): Enable debug mode for development
ignored_environments (optional, default: dev,test,testing): Comma-separated list of environments to ignore
masked_fields (optional): Array of field names to mask in request/response data
excluded_headers (optional): Array of header patterns to exclude from tracking
url (optional): Custom Treblle endpoint URL for self-hosted instances

Requirements

PHP 8.2, 8.3, or 8.4
Symfony 6.4, 7.x, or 8.x
JSON extension

See the docs for this SDK to learn more.

Available SDKs

Treblle provides open-source SDKs that let you seamlessly integrate Treblle with your REST-based APIs.

treblle-symfony: SDK for Symfony
treblle-laravel: SDK for Laravel
treblle-php: SDK for PHP
treblle-lumen: SDK for Lumen
treblle-sails: SDK for Sails
treblle-adonisjs: SDK for AdonisJS
treblle-fastify: SDK for Fastify
treblle-directus: SDK for Directus
treblle-strapi: SDK for Strapi
treblle-express: SDK for Express
treblle-koa: SDK for Koa
treblle-go: SDK for Go
treblle-ruby: SDK for Ruby on Rails
treblle-python: SDK for Python/Django

See the docs for more on SDKs and Integrations.

Community 💙

First and foremost: Star and watch this repository to stay up-to-date.

Also, follow our Blog, and on Twitter.

You can chat with the team and other members on Discord and follow our tutorials and other video material at YouTube.

How to contribute

Here are some ways of contributing to making Treblle better:

Try out Treblle, and let us know ways to make Treblle better for you. Let us know here on Discord.
Join our Discord and connect with other members to share and learn from.
Send a pull request to any of our open source repositories on Github. Check the contribution guide on the repo you want to contribute to for more details about how to contribute. We're looking forward to your contribution!

Upgrading

Upgrading from v2.x to v3.0

Version 3.0 introduces breaking changes to align with treblle-php v5.0 naming conventions. This is a major release that requires configuration updates.

What's New in v3.0

New Configuration Option: excluded_headers
- You can now exclude specific headers from being tracked
- Supports exact matching, wildcards, and regex patterns
Support for Guzzle v9.0
- The SDK now supports Guzzle HTTP client versions 7.x, 8.x, and 9.x
Better Integration with treblle-php
- Now uses SensitiveDataMasker from treblle-php package
- Removed custom helpers in favor of treblle-php utilities
Updated Default Masked Fields
- Removed api_key from default masked fields
- Updated to match treblle-php v5.0 defaults exactly

Breaking Changes

1. Configuration Parameter Names (BREAKING)

The configuration parameter names have been updated to match treblle-php v5.0 conventions:

Before (v2.x):

treblle:
  project_id: "%env(TREBLLE_PROJECT_ID)%"
  api_key: "%env(TREBLLE_API_KEY)%"

After (v3.0):

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

2. Environment Variable Names (BREAKING)

You need to update your environment variables:

Before (v2.x):

TREBLLE_PROJECT_ID - Your project ID
TREBLLE_API_KEY - Your API key

After (v3.0):

TREBLLE_API_KEY - Your project ID (this is what was TREBLLE_PROJECT_ID)
TREBLLE_SDK_TOKEN - Your SDK token (this is what was TREBLLE_API_KEY)

Important: The values stay the same, only the variable names change:

# Before
TREBLLE_PROJECT_ID=your-project-id
TREBLLE_API_KEY=your-api-key

# After
TREBLLE_API_KEY=your-project-id      # Same value as old TREBLLE_PROJECT_ID
TREBLLE_SDK_TOKEN=your-api-key       # Same value as old TREBLLE_API_KEY

3. Default Masked Fields (BREAKING)

The field api_key is no longer masked by default. If you need to mask it, add it explicitly:

treblle:
  masked_fields:
    - api_key  # Add this if you need it masked

Step-by-Step Upgrade Instructions

Update your composer.json

composer require treblle/treblle-symfony:^3.0

Update your configuration file

Update config/packages/treblle.yaml:

treblle:
  api_key: "%env(TREBLLE_API_KEY)%"        # Was project_id
  sdk_token: "%env(TREBLLE_SDK_TOKEN)%"    # Was api_key
  debug: false
  ignored_environments: dev,test,testing
  masked_fields:
    - password
    - pwd
    - secret
    - password_confirmation
    - cc
    - card_number
    - ccv
    - ssn
    - credit_score
  excluded_headers:  # NEW in v3.0 (optional)
    - Authorization
    - X-Api-Key

Update your .env file

# Update variable names (keep the same values!)
TREBLLE_API_KEY=your-project-id        # This is your old TREBLLE_PROJECT_ID value
TREBLLE_SDK_TOKEN=your-api-key-token   # This is your old TREBLLE_API_KEY value

Clear your cache
```
php bin/console cache:clear
```
Test your application

Verify that Treblle is tracking your API requests correctly by checking your Treblle dashboard.

Troubleshooting

Issue: SDK not tracking requests after upgrade

Solution: Clear your application cache and restart your web server:

php bin/console cache:clear
# If using PHP-FPM
sudo service php-fpm restart
# If using Symfony server
symfony server:restart

Issue: Headers still being tracked despite excluded_headers

Solution: Make sure the header names match exactly (case-sensitive) and clear your cache.

Need Help?

If you encounter any issues during the upgrade:

Check the CHANGELOG.md for detailed changes
Review the configuration examples above
Open an issue on GitHub
Join our Discord community

Rollback Instructions

If you need to rollback to v2.x:

composer require treblle/treblle-symfony:^2.0
php bin/console cache:clear

Note that v2.x configuration will continue to work in v3.0, so you can upgrade without immediately changing your config files.

treblle / treblle-symfony

Maintainers

Details