GitHub

The official Treblle SDK for Java frameworks including Javax. Seamlessly integrate Treblle to manage communication with your dashboard, send errors, and secure sensitive data.

Treblle with JavaX

Requirements

Java (1.8+)

Compiled with Java 8 to ensure broad compatibility.

Servlet API (3.1.0+)

Required when using TreblleServletFilter.

JAX-RS API (2.1.1+)

Required when using TreblleContainerFilter.

Supported Java Versions

Java 8 (1.8)
Java 11 (LTS)
Java 17 (LTS)
Java 21 (LTS)

Installation

Add the following dependency to your project:

Maven


<dependency>
    <groupId>com.treblle</groupId>
    <artifactId>treblle-javax</artifactId>
    <version>2.0.2</version>
</dependency>

Gradle


implementation 'com.treblle:treblle-javax:2.0.2'

Gradle (Kotlin DSL)


implementation("com.treblle:treblle-javax:2.0.2")

Tip

For all available versions and metadata, visit the Maven Central Repository .

Quick Start

Sign up at treblle.com
Create a new API
Copy your SDK Token and API Key
Replace the placeholders in the configuration below

Servlet Filter Setup

For traditional Servlet applications (Tomcat, Jetty, WildFly, etc.)

Step 1: Add filter configuration to `web.xml`


<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
 
    <filter>
        <filter-name>TreblleServletFilter</filter-name>
        <filter-class>com.treblle.javax.TreblleServletFilter</filter-class>
 
        <!-- Required: Your Treblle credentials -->
        <init-param>
            <param-name>sdkToken</param-name>
            <param-value>YOUR_SDK_TOKEN_HERE</param-value>
        </init-param>
        <init-param>
            <param-name>apiKey</param-name>
            <param-value>YOUR_API_KEY_HERE</param-value>
        </init-param>
 
        <!-- Optional: Enable debug logging -->
        <init-param>
            <param-name>debugMode</param-name>
            <param-value>false</param-value>
        </init-param>
    </filter>
 
</web-app>

JAX-RS Filter Setup

For JAX-RS applications (Jersey, RESTEasy, Apache CXF, etc.)

Option A: Using JAX-RS Application Class


import com.treblle.javax.TreblleContainerFilter;
 
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;
import java.util.*;
 
@ApplicationPath("/api")
public class MyApplication extends Application {
 
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> classes = new HashSet<>();
 
        // Register Treblle filter
        classes.add(TreblleContainerFilter.class);
 
        // Your resource classes
        classes.add(MyResource.class);
 
        return classes;
    }
 
    @Override
    public Map<String, Object> getProperties() {
        Map<String, Object> props = new HashMap<>();
 
        // Required: Treblle credentials
        props.put("sdkToken", "YOUR_SDK_TOKEN_HERE");
        props.put("apiKey", "YOUR_API_KEY_HERE");
 
        // Optional: Debug mode
        props.put("debugMode", false);
 
        return props;
    }
}

Option B: Programmatic Registration (Jersey)


import com.treblle.common.configuration.TreblleProperties;
import com.treblle.javax.TreblleContainerFilter;
import org.glassfish.jersey.server.ResourceConfig;
 
public class MyResourceConfig extends ResourceConfig {
 
    public MyResourceConfig() {
        // Create custom configuration
        TreblleProperties treblleConfig = new TreblleProperties() {
            @Override
            public String getSdkToken() {
                return System.getenv("TREBLLE_SDK_TOKEN");
            }
 
            @Override
            public String getApiKey() {
                return System.getenv("TREBLLE_API_KEY");
            }
 
            @Override
            public boolean isDebugMode() {
                return Boolean.parseBoolean(System.getenv("TREBLLE_DEBUG"));
            }
        };
 
        // Register filter with custom configuration
        register(new TreblleContainerFilter(treblleConfig));
 
        // Register your resources
        packages("com.example.resources");
    }
}

Option C: Using web.xml (Jersey in Servlet container)


<servlet>
    <servlet-name>Jersey Web Application</servlet-name>
    <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>
    <init-param>
        <param-name>jersey.config.server.provider.classnames</param-name>
        <param-value>com.treblle.javax.TreblleContainerFilter</param-value>
    </init-param>
    <init-param>
        <param-name>sdkToken</param-name>
        <param-value>YOUR_SDK_TOKEN_HERE</param-value>
    </init-param>
    <init-param>
        <param-name>apiKey</param-name>
        <param-value>YOUR_API_KEY_HERE</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

Configuration Reference

Required Parameters

sdkToken

Your Treblle SDK token. You can get this from the Treblle dashboard.

apiKey

Your Treblle API key. You can get this from the Treblle dashboard.

Optional Parameters

customTreblleEndpoint

Custom Treblle endpoint URL for self-hosted setups. Default: null

debugMode

Enable debug logging to log HTTP requests and responses. Default: false

excludedPaths

Comma-separated path patterns to exclude from tracking. Supports wildcards like /health or admin/*. Default: empty

maskedKeywords

Additional request/response field names to mask. Provide as comma-separated values. Default: empty

connectTimeoutInSeconds

HTTP connection timeout when calling the Treblle API. Default: 3 seconds

readTimeoutInSeconds

HTTP read timeout for Treblle API responses. Default: 3 seconds

maxBodySizeInBytes

Maximum request/response body size captured for telemetry. Default: 2MB (2097152 bytes)

Parameter Examples

Excluded Paths

Exclude specific endpoints from monitoring (health checks, admin panels, etc.):


<init-param>
    <param-name>excludedPaths</param-name>
    <param-value>/health,/metrics,/admin/*,*/internal</param-value>
</init-param>

Pattern Examples:

/health - Exclude exact path
admin/* - Exclude all admin endpoints
*/internal - Exclude any path ending with /internal
/api/*/debug - Exclude debug endpoints at any version

Custom Masking Keywords

Add custom fields to mask (in addition to defaults):


<init-param>
    <param-name>maskedKeywords</param-name>
    <param-value>custom_token,sensitive_field,internal_.*</param-value>
</init-param>

Memory Limit

Reduce memory usage for high-traffic APIs:


<init-param>
    <param-name>maxBodySizeInBytes</param-name>
    <param-value>1048576</param-value> <!-- 1MB -->
</init-param>

Integration Examples

Spring Boot with Embedded Tomcat


import com.treblle.common.configuration.TreblleProperties;
import com.treblle.javax.TreblleServletFilter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
 
@Configuration
public class TreblleConfig {
 
    private final Environment env;
 
    public TreblleConfig(Environment env) {
        this.env = env;
    }
 
    @Bean
    public FilterRegistrationBean<TreblleServletFilter> treblleFilter() {
        FilterRegistrationBean<TreblleServletFilter> registrationBean =
            new FilterRegistrationBean<>();
 
        TreblleProperties props = new TreblleProperties() {
            @Override
            public String getSdkToken() {
                return env.getProperty("treblle.sdk-token");
            }
 
            @Override
            public String getApiKey() {
                return env.getProperty("treblle.api-key");
            }
 
            @Override
            public boolean isDebugMode() {
                return env.getProperty("treblle.debug", Boolean.class, false);
            }
        };
 
        registrationBean.setFilter(new TreblleServletFilter(props));
        registrationBean.addUrlPatterns("/api/*");
        registrationBean.setOrder(1);  // Run early in filter chain
 
        return registrationBean;
    }
}

application.properties:


treblle.sdk-token=${TREBLLE_SDK_TOKEN}
treblle.api-key=${TREBLLE_API_KEY}
treblle.debug=false

Jersey with Grizzly Server


import com.treblle.javax.TreblleContainerFilter;
import org.glassfish.grizzly.http.server.HttpServer;
import org.glassfish.jersey.grizzly2.httpserver.GrizzlyHttpServerFactory;
import org.glassfish.jersey.server.ResourceConfig;
 
import java.net.URI;
 
public class Main {
 
    public static void main(String[] args) {
        ResourceConfig config = new ResourceConfig();
 
        // Register Treblle filter
        config.register(TreblleContainerFilter.class);
 
        // Configure Treblle
        config.property("sdkToken", System.getenv("TREBLLE_SDK_TOKEN"));
        config.property("apiKey", System.getenv("TREBLLE_API_KEY"));
        config.property("debugMode", false);
 
        // Register your resources
        config.packages("com.example.resources");
 
        // Start server
        URI baseUri = URI.create("http://localhost:8080/api/");
        HttpServer server = GrizzlyHttpServerFactory.createHttpServer(baseUri, config);
 
        System.out.println("Server started at " + baseUri);
    }
}

RESTEasy with WildFly

web.xml:


<web-app>
    <context-param>
        <param-name>resteasy.providers</param-name>
        <param-value>com.treblle.javax.TreblleContainerFilter</param-value>
    </context-param>
 
    <context-param>
        <param-name>sdkToken</param-name>
        <param-value>${env.TREBLLE_SDK_TOKEN}</param-value>
    </context-param>
 
    <context-param>
        <param-name>apiKey</param-name>
        <param-value>${env.TREBLLE_API_KEY}</param-value>
    </context-param>
 
    <!-- RESTEasy servlet -->
    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    </servlet>
</web-app>

Quarkus