> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/traceable/agent-docs/common/ta-tpa-platform-responsibilities.md).

# 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](#architecture-overview)
* [Sampling](#sampling)
  * [Rate-Limiting Sampling Rules](#rate-limiting-sampling-rules)
  * [Exclusion Sampling Rules](#exclusion-sampling-rules)
  * [Sampling on Platform](#sampling-on-platform)
* [Blocking](#blocking)
* [Detection](#detection)
* [Special Cases](#specific-cases-in-tracing-agents)

## 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](/traceable/agent-docs/common/sampling.md) 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** | <p>Agents without embedded libtraceable<br>Examples: Apigee, Mulesoft, istio</p>       | In ext\_cap module of TPA       |
| **Other Agents**   | <p>Agents with embedded libtraceable<br>Examples: Javaagent, eBPF, mirroring agent</p> | 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** | <p>Without embedded libtraceable<br>Examples: Apigee, Mulesoft, istio</p>         | In ext\_cap module of TPA       |
| **Other Agents**   | <p>With embedded libtraceable<br>Examples: Javaagent, pythonagent, nginxagent</p> | 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.