Metadata

Treblle Metadata allows you to send additional contextual information about your API requests, enabling you to correlate your key business metrics with the API data, usage, and insights that Treblle provides.

Through metadata, you can pass information that ties into your business logic, helping you filter and analyze API data with more specificity and context.

What is Treblle Metadata?

Metadata in Treblle is additional information you can attach to each API request to provide business context. This could include:

• Company identifiers to track which organization made the request
• User information to understand individual user behavior
• Customer data to analyze usage patterns by customer segment
• Environment tags to differentiate between development, staging, and production
• Custom business identifiers like transaction IDs, campaign codes, or feature flags

Why Use Treblle Metadata?

How Metadata Works

Metadata is sent by adding a treblle-metadata header to your API requests. The value should be a stringified JSON object containing key-value pairs with your business context.

Implementation Format

You need to append the treblle-metadata header to your API request calls with a stringified JSON object:

// Example API request headers
const headers = {
    "Host": "api.yourservice.com",
    "Accept-Encoding": "br;q=1.0, gzip;q=0.9, deflate;q=0.8",
    "Accept-Language": "en;q=1.0, hr-US;q=0.9",
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Edg/91.0.864.48",
    "Content-Type": "application/json",
    'treblle-metadata': JSON.stringify({
        'trace-id': 'seeder-we3e3er321e312e2',
        'env-id': 'development',
        'user-id': 'rahul',
        'x-customer-id': 'rah1510',
        'custom-username': 'rahul-1503',
    })
};

How Headers Are Transmitted

When you use JSON.stringify(), the metadata object gets converted to an escaped JSON string. Here’s what actually gets sent in the HTTP headers:

{
  "accept-encoding": "br;q=1.0, gzip;q=0.9, deflate;q=0.8",
  "accept-language": "en;q=1.0, hr-US;q=0.9",
  "authorization": "Bearer 5940100",
  "cache-control": "no-cache",
  "cookie": "XSRF-TOKEN=8648303; treblle_session=4239811",
  "host": "test.treblle.com",
  "user-agent": "Mozilla/5.0 (X11; U; Linux armv7l like Android; en-us) AppleWebKit/531.2+ (KHTML, like Gecko) Version/5.0 Safari/533.2+ Kindle/3.0+",
  "treblle-metadata": "{\"tag-id\":\"2ef634ed-1875-473b-a06a-1b6dd354db93\",\"trace-id\":\"seeder-817ee077-6436-4aa0-ae8d-21381c32745e\",\"env-id\":\"develpment\",\"user-id\":\"I5paNJD0miydDAJ\",\"x-customer-id\":\"sdwfer2332\",\"treblle-username\":\"rahul\",\"company_gv2iK\":\"IeiulI0mpf\",\"company_5FasU\":\"zKhfdvPaxq\",\"company_8r6nP\":\"a2fUftO0Pk\",\"company_joJhj\":\"EGGJeDyiHz\",\"company_b1FG7\":\"PDd3mVj6Aj\"}"
}

You can see this exact format in the Treblle dashboard when inspecting request headers:

The screenshot shows the treblle-metadata header highlighted in line 11, containing the escaped JSON string exactly as transmitted by the client.

Key Points

Special Metadata Fields

Some metadata fields have special meaning in Treblle:

Trace ID

Trace ID Priority

If you send a trace ID both as a root header and within the metadata object, the one in metadata will override the root header:

const headers = {
    'trace-id': 'seeder-3',  // Root header
    "Host": "test.treblle.com",
    "Accept-Encoding": "br;q=1.0, gzip;q=0.9, deflate;q=0.8",
    "Accept-Language": "en;q=1.0, hr-US;q=0.9",
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Edg/91.0.864.48",
    "Refreshcache": "refreshCache",
    'treblle-metadata': JSON.stringify({
        'trace-id': 'seeder-we3e3er321e312e2',  // This will override the root header
        'env-id': "development",
        'user-id': 'rahul',
        'x-customer-id': 'rahul1510',
        'custom-username': 'rahul-1503',
    }),
};

User ID

Custom Business Fields

All other metadata fields appear in the Metadata section of request details and can be used for filtering, allowing you to:

• Filter requests by any custom business identifier
• Track custom business identifiers and values
• Add environment, campaign, or feature flag information
• Store any business-relevant data for analysis and debugging

Metadata Requirements and Limitations

Format Requirements

• Must be valid JSON: The metadata must be properly formatted JSON
• Flat structure only: No nested objects or arrays are allowed
• Key-value pairs: Only simple key-value pairs are supported

Size Limitations

• Maximum 2000 characters: The entire metadata JSON string cannot exceed 2000 characters
• Reasonable key names: Use descriptive but concise key names to maximize available space

Valid Metadata Example

{
  "trace-id": "abc-123-def",
  "user-id": "user123",
  "company": "acme-corp",
  "environment": "production",
  "version": "v2.1",
  "feature": "beta-checkout"
}

Invalid Metadata Example

{
  "user": {
    "id": "123",
    "name": "John"
  },
  "tags": ["important", "urgent"]
}

Viewing Metadata in Treblle

Once you’ve implemented metadata, you can view it in several places within Treblle:

Request Details - Headers Tab

1. Go to the Requests section
2. Click on any request to view details
3. Navigate to the Headers tab to see the raw treblle-metadata header

In the Headers section, you can see the treblle-metadata header containing the stringified JSON with all your custom metadata fields.

Request Details - Metadata Tab

1. Go to the Requests section
2. Click on any request to view details
3. Navigate to the Metadata tab to see all parsed metadata fields in a clean interface

The Metadata tab displays each metadata field as a separate, easy-to-read entry:

Customer Dashboard

Requests with user-id metadata will automatically appear in the Customers section, allowing you to:

• Track individual customer API usage
• Analyze customer behavior patterns
• Monitor customer-specific issues

API Traceability

Requests with trace-id metadata will be grouped together in the Trace section, enabling you to:

• Follow requests across multiple services
• Understand complete transaction flows
• Debug complex distributed system interactions

Custom Filtering

All other metadata fields become available for filtering and analysis:

• Filter requests by company, environment, or any custom identifier
• Analyze API usage by business segments
• Debug issues with specific business context