Treblle with .NET

Requirements

.NET Framework 4.6.2 or higher (supports 4.6.2, 4.7.x, 4.8, and 4.8.1)
ASP.NET Web API 5.2.7+
Newtonsoft.Json 13.0.3+

Installation

You can install Treblle .NET via NuGet Package Manager Console, .NET CLI, or the NuGet Package Manager UI.

Via NuGet Package Manager Console


Install-Package Treblle.Net

Via .NET CLI


dotnet add package Treblle.Net

Via NuGet Package Manager UI

Right-click on your project in Solution Explorer
Select “Manage NuGet Packages”
Search for “Treblle.Net”
Click “Install”

Quick Start

Step 1: Configure Credentials

Add your Treblle API Key and SDK Token to Web.config. Get these from your Treblle Dashboard → API Settings.

Step 2: Register Handler

Add TreblleHandler to WebApiConfig.cs for automatic tracking of all API endpoints.

Step 1: Configure Your Credentials

Add your Treblle credentials to Web.config:


<configuration>
  <appSettings>
    <add key="Treblle:ApiKey" value="{Your_API_Key}" />
    <add key="Treblle:SdkToken" value="{Your_SDK_Token}" />
  </appSettings>
</configuration>

Note

Get your credentials: Visit your Treblle Dashboard → Find your API → Navigate to Settings → Copy SDK Token and API Key

Step 2: Register the Handler (Automatic Tracking - Recommended)

Simply register the Treblle handler in your WebApiConfig.cs and all API endpoints will be tracked automatically:


using Treblle.Net;
 
public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Add Treblle handler - tracks all endpoints automatically
        config.MessageHandlers.Add(new TreblleHandler());
 
        // Your existing Web API configuration
        config.MapHttpAttributeRoutes();
        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );
    }
}

That’s it! All your API endpoints are now being monitored. 🎉

Alternative: Manual Tracking (Legacy)

For fine-grained control, you can use the [Treblle] attribute on specific controllers or methods:


[Treblle]
public class ProductsController : ApiController
{
    public IHttpActionResult Get()
    {
        return Ok(_productService.GetAll());
    }
}

Configuration

Required Settings

These two settings are required for the SDK to function:


<configuration>
  <appSettings>
    <add key="Treblle:ApiKey" value="{Your_API_Key}" />
    <add key="Treblle:SdkToken" value="{Your_SDK_Token}" />
  </appSettings>
</configuration>

Optional Settings

Configuration Option

Description & Default Value

Treblle:ExcludedPaths

Comma-separated paths to exclude from tracking. Type: string. Default: (none)

Treblle:AdditionalFieldsToMask

Comma-separated field names to mask. Type: string. Default: (none)

Treblle:DisableMasking

Disable data masking. Type: bool. Default: false

Treblle:Debug

Enable detailed debug logging. Type: bool. Default: false

Complete Configuration Example


<configuration>
  <appSettings>
    <!-- Required -->
    <add key="Treblle:ApiKey" value="{Your_API_Key}" />
    <add key="Treblle:SdkToken" value="{Your_SDK_Token}" />
 
    <!-- Optional -->
    <add key="Treblle:ExcludedPaths" value="/health,/admin/*,/internal/*" />
    <add key="Treblle:AdditionalFieldsToMask" value="apiKey,authToken,internalId" />
    <add key="Treblle:Debug" value="false" />
    <add key="Treblle:DisableMasking" value="false" />
  </appSettings>
</configuration>

Advanced Features

Data Masking

The SDK automatically masks sensitive fields before sending data to Treblle. This happens on your server before any data leaves your infrastructure.

Default Masked Fields

The following fields are automatically masked:

Authentication & Secrets:

password, pwd
secret
password_confirmation, passwordConfirmation

Financial Data:

cc, card_number, cardNumber, ccv
credit_score, creditScore

Personal Information:

email
ssn
account.* (all account fields)

Nested Fields:

user.email, user.dob, user.password, user.ss
user.payments.cc

Masking Strategies

Different field types use different masking strategies:

Field Type

Strategy & Example

Passwords/Secrets

Complete masking. Example: *****

Credit Cards

Last 4 digits visible. Example: ****-****-****-1234

Emails

Partial masking. Example: j***@example.com

SSN

Last 4 digits visible. Example: ***-**-1234

Dates

Year masked. Example: 12/25/****

Custom Field Masking

Add your own fields to mask:


<add key="Treblle:AdditionalFieldsToMask" value="apiKey: DefaultStringMasker,authToken: DefaultStringMasker,dob: DateMasker" />

Available Maskers:

DefaultStringMasker - Complete masking
CreditCardMasker - Credit card number masking
EmailMasker - Email address masking
SocialSecurityMasker - SSN masking
DateMasker - Date masking

Simple format (uses DefaultStringMasker):


<add key="Treblle:AdditionalFieldsToMask" value="customSecret,apiToken,internalId" />

Disabling Masking


<add key="Treblle:DisableMasking" value="true" />

Caution

Warning: This sends all data (passwords, credit cards, emails, etc.) in plain text. Only use this in development/testing environments.

Path Exclusion

Automatic Exclusions

The SDK automatically excludes common non-API requests:

File Extensions:

.css, .js, .map
.jpg, .jpeg, .png, .gif, .svg, .ico
.woff, .woff2, .ttf, .eot
.mp4, .mp3, .webm
.pdf, .zip, .rar, .tar, .gz
.html, .htm

Default Paths:

/swagger/*, /swagger-ui/*, /swagger-resources/*
/assets/*, /static/*, /public/*
/css/*, /js/*, /images/*, /img/*, /fonts/*
/favicon.ico, /robots.txt, /sitemap.xml
/_next/*, /_nuxt/*, /node_modules/*
/.well-known/*

Content Types:

HTML, CSS, JavaScript
Images, videos, audio
Fonts
Binary files

Custom Path Exclusions

Exclude specific endpoints using pattern matching:


<add key="Treblle:ExcludedPaths" value="/health,/admin/*,internal,/debug/info" />

Pattern Matching:

Pattern

Behavior & Example

/health

Exact match - Excludes only /health

/admin/*

Wildcard match - Excludes all paths starting with /admin/

internal

Segment match - Excludes any path containing 'internal'

/api/v1/status,/api/v2/status

Multiple patterns - Comma-separated list

Examples:

/health → Matches /health only
/admin/* → Matches /admin/users, /admin/settings, etc.
swagger → Matches /swagger, /api/swagger, /v1/swagger/docs, etc.
/api/internal/*,/debug/* → Matches both patterns

Debug Mode

Enable debug mode to see detailed logging of SDK operations:


<add key="Treblle:Debug" value="true" />

Debug Output Includes:

Configuration Status:


[TREBLLE DEBUG] === TREBLLE CONFIGURATION ===
[TREBLLE DEBUG] SDK Token: ab12****ef78
[TREBLLE DEBUG] API Key: cd34****gh90
[TREBLLE DEBUG] Debug Mode: ENABLED

Request Tracking:


[TREBLLE DEBUG] Request Started: POST /api/users
[TREBLLE DEBUG] Applied data masking to 12 fields
[TREBLLE DEBUG] Payload size: 2.34 KB
[TREBLLE DEBUG] Request Completed: POST /api/users - Status: 201 - Load Time: 155ms
[TREBLLE DEBUG] Payload sent to Treblle - Response: 200

Skipped Requests:


[TREBLLE DEBUG] Request skipped: Missing SDK Token or API Key configuration
[TREBLLE DEBUG] Request skipped: Filtered out (static asset)
[TREBLLE DEBUG] Request skipped: Response content type not tracked (text/html)

Error Tracking:


[TREBLLE DEBUG] Error in request capture: NullReferenceException
[TREBLLE DEBUG] Error in payload sending: HTTP 401: Unauthorized

ASP.NET Web API Integration

Tracking with Handler (Recommended)

The recommended approach is to register the TreblleHandler in your WebApiConfig.cs, which automatically tracks all API endpoints:


using Treblle.Net;
 
public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // Add Treblle handler - tracks all endpoints automatically
        config.MessageHandlers.Add(new TreblleHandler());
 
        // Your existing configuration
        config.MapHttpAttributeRoutes();
        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );
    }
}

All controllers will now be tracked automatically without any additional attributes.

Tracking Specific Methods (Legacy)

For fine-grained control, you can use the [Treblle] attribute on specific controllers or methods:


public class ProductsController : ApiController
{
    [Treblle]
    public IHttpActionResult GetPublic()
    {
        // This endpoint is tracked
        return Ok(_productService.GetAll());
    }
 
    public IHttpActionResult GetInternal()
    {
        // This endpoint is NOT tracked
        return Ok(_productService.GetInternalProducts());
    }
}

Supported Content Types

Requests (Accepted)

application/json | application/x-www-form-urlencoded | multipart/form-data

Responses (Tracked)

All JSON-based content types including application/json, application/vnd.api+json, application/ld+json, application/hal+json, application/problem+json, text/json, and empty responses (201, 204, etc.) ✅

Note

XML-based content types (application/xml, text/xml), HTML (text/html), and binary content types are not supported by this SDK.

Migration Guide (v1 → v2)

Upgrading from Treblle.Net v1.x to v2.x requires a few configuration changes.

Breaking Changes

1. Configuration Key Changes

The configuration keys have been renamed to use the Treblle: prefix:

Old (v1.x):


<appSettings>
  <add key="TreblleApiKey" value="{Your_API_Key}" />
  <add key="TrebllesdkToken" value="{Your_SDK_TOKEN}" />
</appSettings>

New (v2.x):


<appSettings>
  <add key="Treblle:ApiKey" value="{Your_API_Key}" />
  <add key="Treblle:SdkToken" value="{Your_SDK_Token}" />
</appSettings>

Note

TrebllesdkToken is now called Treblle:SdkToken. You can find your SDK Token in the Treblle Dashboard .

2. Additional Configuration Keys

All optional configuration keys now use the Treblle: prefix:

v1.x Key

v2.x Key

AdditionalFieldsToMask

Treblle:AdditionalFieldsToMask

DisableMasking

Treblle:DisableMasking

Debug

Treblle:Debug

N/A

Treblle:ExcludedPaths (new feature)

Step-by-Step Migration

Step 1: Update NuGet Package


# Update to v2.x
Update-Package Treblle.Net

Or via .NET CLI:


dotnet add package Treblle.Net --version 2.0.1

Step 2: Update Web.config

Replace your old configuration:


<!-- OLD - Remove this -->
<appSettings>
  <add key="TreblleApiKey" value="your-api-key-here" />
  <add key="TreblleSdkToken" value="your-sdk-token-here" />
  <add key="AdditionalFieldsToMask" value="field1,field2" />
</appSettings>

With the new configuration:


<!-- NEW - Use this -->
<appSettings>
  <add key="Treblle:ApiKey" value="your-api-key-here" />
  <add key="Treblle:SdkToken" value="your-sdk-token-here" />
  <add key="Treblle:AdditionalFieldsToMask" value="field1,field2" />
</appSettings>

Important: Global HTTP Configuration

The Treblle SDK modifies some global ServicePointManager settings when first initialized. These changes affect all HTTP clients in your application, including third-party libraries.

Modified Settings

The SDK configures the following global settings for optimal performance and security:

Setting

Value & Purpose

SecurityProtocol

TLS 1.2 + TLS 1.1 - Ensures secure HTTPS communication

DefaultConnectionLimit

10 - Allows up to 10 concurrent connections per endpoint

MaxServicePointIdleTime

90 seconds - Keeps connections alive for connection reuse

Expect100Continue

Disabled - Improves request performance

UseNagleAlgorithm

Disabled - Reduces latency for small packets

Impact on Your Application

These settings will apply to all HttpClient, WebClient, and HttpWebRequest instances in your application, not just Treblle’s HTTP calls.

Tip

These are generally beneficial defaults that improve performance and security for most applications.

When You Need Different Settings

If your application requires different ServicePointManager settings:

Configure after Treblle initializes: Add your custom settings in Global.asax.cs or your startup code after the first Treblle request
Override specific settings: You can change any setting after Treblle loads - your changes will persist


// In Global.asax.cs Application_Start
protected void Application_Start()
{
    // Your Web API config (Treblle gets initialized here)
    GlobalConfiguration.Configure(WebApiConfig.Register);
 
    // Override Treblle's settings if needed
    ServicePointManager.DefaultConnectionLimit = 100; // Your custom value
    ServicePointManager.UseNagleAlgorithm = true;      // Your custom value
}

Need help?: If this causes issues, please open an issue on GitHub

Treblle Docs

Treblle with .NET

Requirements

Installation

Via NuGet Package Manager Console

Via .NET CLI

Via NuGet Package Manager UI

Quick Start

Step 1: Configure Credentials

Step 2: Register Handler

Step 1: Configure Your Credentials

Note

Step 2: Register the Handler (Automatic Tracking - Recommended)

Alternative: Manual Tracking (Legacy)

Configuration

Required Settings

Optional Settings

Complete Configuration Example

Advanced Features

Data Masking

Default Masked Fields

Masking Strategies

Custom Field Masking

Disabling Masking

Caution

Path Exclusion

Automatic Exclusions

Custom Path Exclusions

Debug Mode

Debug Output Includes:

ASP.NET Web API Integration

Tracking with Handler (Recommended)

Tracking Specific Methods (Legacy)

Supported Content Types

Requests (Accepted)

Responses (Tracked)

Note

Migration Guide (v1 → v2)

Breaking Changes

1. Configuration Key Changes

Note

2. Additional Configuration Keys

Step-by-Step Migration

Step 1: Update NuGet Package

Step 2: Update Web.config

Important: Global HTTP Configuration

Modified Settings

Impact on Your Application

Tip

When You Need Different Settings