> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/plugins/traffic-observability.md).

# Traffic and observability plugins

Traffic plugins enforce quotas, protect services, route requests, cache responses, and transform payloads. Observability plugins send request lifecycle data to approved operational systems.

## Request rate limiting

| Plugin                  | Deployment model      | Use                                                    |
| ----------------------- | --------------------- | ------------------------------------------------------ |
| `rate_limiter`          | Shared Redis counters | Fixed-window quotas across workers and replicas.       |
| `advanced_rate_limiter` | Per-process counters  | Fixed or sliding windows for a single gateway process. |
| `response_rate_limiter` | Per-process counters  | Quotas based on selected completed response statuses.  |

### Shared fixed-window example

```json
{
  "limit": 100,
  "window_seconds": 60,
  "limit_by": "consumer",
  "fault_tolerant": false,
  "hide_client_headers": false,
  "error_code": 429,
  "error_message": "API rate limit exceeded"
}
```

`rate_limiter` accepts `limit` with `window_seconds`, named windows such as `minute: 100`, or a `limits` array. Use `fault_tolerant: false` when quota enforcement is a security or cost-control requirement.

### Sliding multi-window example

```json
{
  "namespace": "orders",
  "limit_by": "credential",
  "strategy": "sliding_window",
  "cost": 1,
  "include_method": true,
  "include_path": true,
  "limits": [
    { "name": "burst", "limit": 10, "window_seconds": 1 },
    { "name": "minute", "limit": 300, "window_seconds": 60 }
  ]
}
```

Use `advanced_rate_limiter` when one gateway process owns the quota. For consistent enforcement across multiple workers or replicas, use the Redis-backed `rate_limiter`.

### Response quota example

```json
{
  "namespace": "billable-orders",
  "limit": 1000,
  "window_seconds": 3600,
  "limit_by": "consumer",
  "strategy": "fixed_window",
  "count_statuses": ["2xx", 409],
  "cost": 1,
  "cost_header": "X-Response-Cost"
}
```

Configure `response_rate_limiter` with `trigger: "both"`. Size per-process quotas for the number of gateway workers and replicas in the deployment.

## Service and routing controls

| Plugin                  | Main configuration                                                             | Use                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `service_protection`    | Concurrency, failure thresholds, cooldown, service key, response controls      | Limits concurrent requests and opens a service circuit. Use `trigger: "all"` so failed requests are included. |
| `canary_shadow_traffic` | Canary percentage, stable bucket identity, canary URL/header, decision headers | Selects canary traffic deterministically and routes it to the configured canary upstream.                     |
| `forward_proxy`         | `forward_url`                                                                  | Replaces the selected upstream target.                                                                        |
| `redirect`              | `url` or `location`, status, path/query preservation                           | Returns a redirect before upstream proxying.                                                                  |
| `mock_response`         | `body`, `status_code`, `enabled`                                               | Returns a controlled static response.                                                                         |
| `request_termination`   | Header condition, status, message                                              | Stops requests that match an explicit header condition.                                                       |
| `response_cache`        | Namespace, TTL, methods, statuses, vary headers, body limits                   | Caches responses in the gateway process.                                                                      |

Use HTTPS for canary and forward-proxy targets. Restrict administrator-controlled outbound destinations with network policy. Process-local protection and cache state must be sized per worker and is refreshed when that worker restarts.

## Request and response transformation

Supported transformation packages can:

* set, rename, or remove request and response headers;
* add, replace, rename, or remove JSON and XML fields;
* apply bounded `{{ variable.path }}` templates;
* mask selected headers and JSON paths.

Set `max_body_bytes` where available. Apply body transformations only to bounded payloads whose content type matches the plugin configuration. See the [supported plugin reference](/plugins/reference.md) for fields and triggers.

## Observability emitters

| Plugin                | Destination                                | Use                                                                          |
| --------------------- | ------------------------------------------ | ---------------------------------------------------------------------------- |
| `correlation_id`      | Request and response headers               | Generates or propagates a request identifier.                                |
| `http_log`            | Approved HTTP collector                    | Sends a JSON request lifecycle record.                                       |
| `audit_event_stream`  | Approved HTTP audit collector              | Sends a normalized gateway audit event.                                      |
| `datadog`             | Datadog log intake or approved endpoint    | Sends structured request records with service, environment, and tag context. |
| `kafka_log`           | Kafka topic                                | Sends JSON records with configurable acknowledgement and timeout.            |
| `tcp_log` / `udp_log` | Network collector                          | Sends a JSON line to the configured host and port.                           |
| `statsd_metrics`      | StatsD/DogStatsD endpoint                  | Sends request, status, latency, and error metrics over UDP.                  |
| `file_log`            | Local diagnostics file                     | Writes JSON lines for controlled local diagnostics.                          |
| `sampling`            | Request state and optional decision header | Produces a random or stable hash-based sampling decision.                    |

Use `trigger: "both"` for emitters that need request start time and a completed response. Use `trigger: "all"` when the selected package must also receive request failures.

### Sampling and audit example

Run sampling before the emitter:

```json
{
  "name": "sampling",
  "trigger": "before_request",
  "priority": 1000,
  "config": {
    "rate": 0.1,
    "strategy": "hash",
    "seed": "production",
    "include_decision_header": true,
    "decision_header": "X-Kangal-Sampled"
  }
}
```

```json
{
  "name": "audit_event_stream",
  "trigger": "both",
  "priority": 100,
  "config": {
    "endpoint": "https://audit.example.com/events",
    "event_type": "gateway.request",
    "include_headers": false,
    "timeout": 1,
    "fail_on_error": false
  }
}
```

## Security and delivery requirements

* Keep `include_headers: false` unless an approved data policy and collector explicitly allow credential-bearing headers.
* Use HTTPS and authentication for HTTP collectors. Restrict every collector destination with outbound network policy.
* Keep emitter timeouts short and send high-volume traffic to a nearby collector to protect request latency.
* Use `fail_on_error: false` for operational telemetry that must not interrupt customer traffic. Enable it only when delivery is part of the request's enforcement contract.
* Use persistent storage and rotation for `file_log` when retaining local diagnostics.
* Store collector credentials and API keys in approved secret storage.

## Troubleshooting

| Symptom                            | Check                                                                                                                                     |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Shared quota is not enforced       | Confirm the instance uses `rate_limiter`, Redis is reachable, `fault_tolerant` matches policy, and every replica uses the same namespace. |
| Sliding-window quota is unexpected | Verify the configured worker count, namespace, identity, method/path partitioning, windows, and request cost.                             |
| Service circuit opens too often    | Review the service key, failure statuses, minimum request count, thresholds, cooldown, and per-worker traffic volume.                     |
| Canary traffic is not selected     | Verify percentage, bucket source, salt, canary target URL, scope, trigger, and plugin priority.                                           |
| Collector receives no events       | Verify the trigger, scope, endpoint, network policy, authentication, timeout, and collector response.                                     |
| Telemetry adds latency             | Reduce emitter timeout or volume and route traffic through a nearby collector.                                                            |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kangal.dev/plugins/traffic-observability.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.