Responsibilities of Tracing Agents, TPA, and Platform wrt Sampling/Blocking/Detection

This document details the responsibilities of Tracing Agents, TPA (Traceable Platform Agent), and Platform with respect to Sampling, Blocking, and Detection of vulnerabilities.

Table of Contents

• Architecture Overview

• Sampling

  • Rate-Limiting Sampling Rules

  • Exclusion Sampling Rules

  • Sampling on Platform

• Blocking

• Detection

• Special Cases

Architecture Overview

Key Flow: Rules are configured in platform and sent to agents through TPA.

Platform → TPA → Tracing Agents

Key Components

Component	Responsibility
libtraceable	Fetches sampling and blocking rules from TPA and evaluates them on each request
TPA Collector	Applies exclusion and detection rules on redacted parameters only
Platform	Configures rules and performs final sampling and detection on all parameters

Sampling

Refer Sampling Configuration for adding sampling rules and on more details on each agent's sampling behavior.

Sampling rules are configured in the platform and applied at different levels:

Rule Type	Applied At
Span Protection	libtraceable
Rate-Limiting	Tracing Agent (libtraceable), Platform
Exclusion	Tracing Agent (libtraceable), TPA(collector), Platform

Sampling happens after blocking evaluation if blocking is enabled. In this case, all blocked spans are allowed to pass through to the platform in the agents, no matter the sampling rule. Platform rate limit may still drop these spans.

Sampling rules can mention if the span has to be dropped or to be made a barespan. Barespan are spans that only have minimal attributes and headers required to indentify the API call. These do not have any other custom headers or bodies.

Span Protection Rules

Span protection rules are configured in the platform and applied at libtraceable only. These rules are applied first (before sampling), so any protected span is always sent to TPA collector.

Rate-Limiting Sampling Rules

Rate-limiting sampling rules are configured in the platform and applied at the Tracing Agent and Platform levels (not at TPA).

Tracing Agents

There are two types of Tracing Agents in this regard:

Agent Type	Description	libtraceable Location
ext_cap based	Agents without embedded libtraceable Examples: Apigee, Mulesoft, istio	In ext_cap module of TPA
Other Agents	Agents with embedded libtraceable Examples: Javaagent, eBPF, mirroring agent	Within the tracing agent itself

Important: When sampling happens at Tracing Agents, they add an attribute to the span to indicate whether the span is already sampled. If this attribute is present, the platform does not apply additional sampling to this span.

Ext-cap based Tracing Agents

┌─────────────────┐    ┌──────────────────────────────┐    ┌───────────────┐
│  Tracing Agent  │───>│  ext_cap (with libtraceable) │───>│ TPA Collector │───> Platform
└─────────────────┘    └──────────────────────────────┘    └───────────────┘
     Send data              Evaluate sampling               Forward

Since libtraceable is in ext_cap in TPA:

1. Tracing agents send all requests' data to ext_cap endpoints in TPA

2. ext_cap component calls libtraceable to evaluate sampling

3. If sampled, spans are sent to TPA's collector and then to platform

Other Tracing Agents

┌─────────────────────────────┐    ┌───────────────┐
│ Tracing Agent (libtraceable)│───>│ TPA Collector │───> Platform
└─────────────────────────────┘    └───────────────┘
   Collect & evaluate sampling        Forward

In these agents:

1. libtraceable is embedded within the tracing agent

2. Agents evaluate sampling rules internally

3. Only sampled spans are sent to TPA's collector

Exclusion Sampling Rules

Exclusion sampling rules are configured in platform and applied at all three levels: Tracing Agent, TPA, and Platform.

Tracing Agents

The behavior is similar to rate limiting sampling rules as described above.

TPA

┌───────────────┐    ┌──────────────────────┐    ┌─────────────┐
│ Tracing Agent │───>│ TPA Collector        │───>│  Platform   │
└───────────────┘    │ (Exclusion Sampling) │    └─────────────┘
                     └──────────────────────┘

Processing flow:

1. Spans reach TPA's collector

2. Processors in collector evaluate exclusion sampling rules

3. Only sampled spans are forwarded to platform

Sampling on Platform

Conditional Sampling: Platform only samples spans that weren't already sampled by agents (indicated by an attribute added by agents).

Processing flow:

1. Span is evaluated for sampling

2. Only sampled spans are forwarded to other processing (like detection)

Blocking

Blocking rules follow this flow: Platform → TPA → Tracing Agents

Aspect	Details
Configuration	Rules are configured in platform
Application	Rules are applied at the Tracing Agent level
Evaluation	Rules are fetched and evaluated by libtraceable

Similar to sampling, there are two types of Tracing agents:

Agent Type	Description	libtraceable Location
ext_cap based	Without embedded libtraceable Examples: Apigee, Mulesoft, istio	In ext_cap module of TPA
Other Agents	With embedded libtraceable Examples: Javaagent, pythonagent, nginxagent	Within the tracing agent itself

Ext-cap based Tracing Agents

┌─────────────────┐    ┌──────────────────────────────┐
│  Tracing Agent  │───>│  ext_cap (with libtraceable) │
└─────────────────┘    └──────────────────────────────┘
        ▲                          │
        │                          │
        └──────────────────────────┘
          Evaluation response

Blocking flow:

1. Request data is sent to ext_cap

2. libtraceable in ext_cap evaluates blocking rules

3. ext_cap sends evaluation result back to Tracing agent

4. Tracing agent blocks/allows the request based on this evaluation

Other Tracing Agents

┌─────────────────────────────────────────┐
│ Tracing Agent                           │
│  ┌─────────────────┐                    │
│  │   libtraceable  │                    │
│  └─────────────────┘                    │
└─────────────────────────────────────────┘

Blocking flow:

1. Request data remains within tracing agent

2. Embedded libtraceable evaluates blocking rules

3. Tracing agent blocks/allows request based on internal evaluation

If Blocking is disabled, refer Detection section for how detection is handled wrt Protection.

Detection

Detection happens after sampling(sampling happens at Tracing Agent(libtraceable) or extCap(libtraceable) before the collector at TPA). TPA's collector performs detection on redacted parameters only, while the platform performs detection on all parameters after sampling.

Location	Scope
TPA's collector	Detection on redacted parameters only after sampling at TA/libtraceable
Platform	Detection on all parameters after sampling

┌─────────────────┐    ┌───────────────────────────────┐    ┌─────────────────────────────┐
│  Tracing Agent  │───>│  TPA (Detection on redacted)  │───>│  Platform (Detection on all)│
└─────────────────┘    └───────────────────────────────┘    └─────────────────────────────┘

Important: Sampling, Blocking, and Detection happen at different places in the data flow. If data is dropped at any point, it will not be processed by subsequent components.

Specific Cases in Tracing Agents

Note: This section is under development.

Special Sampling Behaviors

Some agents have special behaviors that differ from the standard flow:

Case	Behavior
span.type=barespan	Some agents(python, nodejs, dotnet) only add span.type=barespan attribute to span without actually making the span bare. In this case, the span will be stripped down at TPA using rule on span.type=barespan.
Windows Limitations	Today, we only have sampling using IIS agent on windows

Additional special cases will be documented here as they are identified.

Special Blocking Behaviors

Blocking on windows is not supported. Because we cannot run modsec on windows.