Treblle with Spring

The Treblle Spring Boot SDK is a Spring Boot auto-configuration starter that captures every API request and response on your application, masks sensitive data before anything leaves your server, and ships the data to Treblle asynchronously. All expensive work happens after the response has been flushed to the client, so the SDK adds no measurable latency and by design — can never break your API.

Requirements

• Java 17 or newer
• Spring Boot 3.x (Spring MVC / Servlet stack)
• A Treblle account with an SDK Token and API Key from the Treblle dashboard 

Installation

1. Install the SDK

Add the dependency to your pom.xml:

<dependency>
    <groupId>com.treblle</groupId>
    <artifactId>treblle-spring-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

Or, for Gradle (build.gradle):

implementation 'com.treblle:treblle-spring-boot-starter:3.0.0'

That is all the wiring you need — the starter auto-configures itself. There are no filters, beans, or annotations to register manually.

2. Configure the SDK

Add your credentials to application.properties:

treblle.sdk-token=YOUR_SDK_TOKEN
treblle.api-key=YOUR_API_KEY

Or application.yml:

treblle:
  sdk-token: YOUR_SDK_TOKEN
  api-key: YOUR_API_KEY

Every option can also be supplied through a TREBLLE_* environment variable (Spring Boot relaxed binding). Explicitly declared properties take precedence over environment variables:

export TREBLLE_SDK_TOKEN=YOUR_SDK_TOKEN
export TREBLLE_API_KEY=YOUR_API_KEY

All configuration options

A complete example:

treblle.sdk-token=YOUR_SDK_TOKEN
treblle.api-key=YOUR_API_KEY
treblle.debug=false
treblle.enabled=true
treblle.ingress-endpoint=https://ingress.treblle.com
treblle.masked-keywords=password,pwd,secret,password_confirmation,cc,card_number,ccv,ssn,authorization,api_key
treblle.excluded-paths=/health,/actuator/*,/admin/*

3. Verify it works

1. Start your application and make a request to any of your API endpoints.
2. Open your API in the Treblle dashboard  — the request should appear within a few seconds.
3. If nothing shows up, set treblle.debug=true and restart. The SDK will log its resolved configuration, initialization status, each captured request, every outgoing send, and Treblle’s responses under the com.treblle logger — enough to pinpoint any configuration problem.

Data masking

Masking happens entirely on your server, before any data is sent to Treblle. The treblle.masked-keywords list drives it:

• Secure by default. A standard set of sensitive keys (password, pwd, secret, password_confirmation, cc, card_number, ccv, ssn, authorization, api_key) is masked out of the box. Override treblle.masked-keywords to customize it, or set it to empty to disable masking entirely (a warning is logged in debug mode when masking is off).
• Matching is case-insensitive and applies to request bodies, response bodies, request headers, and response headers. Query-string values are masked in the captured query map, and the raw URL is recorded without its query string so no unmasked query value can leak through it.
• Each character of a matched value is replaced with *, preserving the original length ("secret123" → "*********").
• Nested objects and arrays are handled recursively; array items are masked individually while the array structure is preserved.
• For Authorization-style headers, the auth scheme is preserved and only the credentials are masked ("Bearer secret123" → "Bearer *********").
• null and empty values are left untouched.

treblle.masked-keywords=password,authorization,credit_card,ssn,cvv

Given a request body of:

{ "email": "alice@example.com", "password": "s3cr3t", "card": { "cvv": "123" } }

Treblle receives:

{ "email": "alice@example.com", "password": "******", "card": { "cvv": "***" } }

Excluding paths

Use treblle.excluded-paths to stop tracking specific routes. It accepts exact paths and wildcard prefixes, and matching is case-sensitive:

# Exact path
treblle.excluded-paths=/health
# Wildcard prefix: excludes everything under /admin/
treblle.excluded-paths=/health,/admin/*,/actuator/*

In addition to your configured exclusions, the SDK automatically skips static and infrastructure resources so they never reach Treblle: images, CSS, JavaScript, fonts, media, favicon.ico, .well-known/ paths, .env files, and similar. Non-JSON request/response bodies are still captured but replaced with a short “not valid JSON” message rather than the raw content.

Per-request metadata

Attach custom key/value metadata to the current request from anywhere on the request thread (controller, service, interceptor) using the static TreblleMetadata helper:

import com.treblle.springboot.metadata.TreblleMetadata;
import org.springframework.web.bind.annotation.*;
 
@RestController
public class OrderController {
 
    @PostMapping("/orders")
    public Order create(@RequestBody OrderRequest request) {
        TreblleMetadata.add("tenant", request.getTenantId());
        TreblleMetadata.add("plan", "enterprise");
        TreblleMetadata.add("is_trial", false);
        return orderService.create(request);
    }
}

Metadata accepts String, Number, and Boolean values, and is sent in the payload’s metadata object. It is cleared automatically once the request completes.

Debug mode

Enable debug mode to diagnose SDK issues:

treblle.debug=true

When enabled, the SDK logs (under the com.treblle logger):

• Resolved configuration and initialization status, so you can confirm the SDK is enabled.
• Warnings when required configuration is missing, or when masking is disabled because masked-keywords is empty.
• Data-collection events and skipped/excluded paths.
• Every outgoing send to Treblle, Treblle’s responses, circuit-breaker state transitions, dropped payloads, and any exceptions or HTTP errors that occur while sending.

If data isn’t appearing in your dashboard, turn on debug mode first — the logs will tell you whether the SDK is disabled, whether your credentials are set, and whether Ingress is responding.