> 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/apigee/blocking-agent/configuration.md).

# Traceable Apigee-Blocking Policy Configuration

This document outlines the configuration options for the Traceable-Blocking policy in Apigee.

## TraceableJS Configuration(Configure in the TraceableJS.xml file)

### Core Configuration Properties

| Property                                  | Required | Default                                    | Description                                                                                                                             |
| ----------------------------------------- | -------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `ta_reporting_endpoint`                   | Yes\*    | `""`                                       | The reporting endpoint URL. Should be `http://TPA_HOST:5442` or `https://TPA_HOST:5443`. **\*Mandatory when using javascript\_callout** |
| `ta_service_name`                         | No       | `"apigee"`                                 | Name of your service that will appear in the Traceable platform                                                                         |
| `ta_environment_name`                     | No       | `""`                                       | Optional environment name. If not provided, the TPA's environment name will be used                                                     |
| `ta_data_capture_body_max_size_bytes`     | No       | 131072                                     | Maximum size in bytes for capturing request/response bodies                                                                             |
| `ta_data_capture_http_body_request`       | No       | `true`                                     | Enable/disable capturing of HTTP request bodies                                                                                         |
| `ta_data_capture_http_body_response`      | No       | `true`                                     | Enable/disable capturing of HTTP response bodies                                                                                        |
| `ta_data_capture_http_headers_request`    | No       | `true`                                     | Enable/disable capturing of HTTP request headers                                                                                        |
| `ta_data_capture_http_headers_response`   | No       | `true`                                     | Enable/disable capturing of HTTP response headers                                                                                       |
| `ta_data_capture_target_request_response` | No       | `false`                                    | Enable/disable capturing of target request/response data                                                                                |
| `ta_data_capture_allowed_types`           | No       | `"json,graphql,x-www-form-urlencoded,xml"` | Comma-separated list of content types to capture                                                                                        |
| `ta_reporting_trace_reporter_type`        | No       | `"message_logging"`                        | Type of trace reporter. Options: message\_logging, service\_callout, javascript\_callout                                                |
| `ta_extra_attribute_list`                 | No       | `""`                                       | Chain of context\_variable,attribute\_name separated by pipe (\|). Example: car.id,vehicle.car.id\|model.id,vehicletype.model.id        |

> **Note:** The `ta_reporting_endpoint` property is mandatory when `ta_reporting_trace_reporter_type` is set to `javascript_callout`. It specifies the HTTP/HTTPS endpoint where span data will be sent asynchronously.

### Dynamic Configuration Override Properties

These properties allow you to specify context variable names that can dynamically override the default configuration values at runtime:

| Property                                      | Description                                                                 |
| --------------------------------------------- | --------------------------------------------------------------------------- |
| `ta_reporting_endpoint_var`                   | Context variable name to override `ta_reporting_endpoint`                   |
| `ta_service_name_var`                         | Context variable name to override `ta_service_name`                         |
| `ta_environment_name_var`                     | Context variable name to override `ta_environment_name`                     |
| `ta_data_capture_body_max_size_bytes_var`     | Context variable name to override `ta_data_capture_body_max_size_bytes`     |
| `ta_data_capture_http_body_request_var`       | Context variable name to override `ta_data_capture_http_body_request`       |
| `ta_data_capture_http_body_response_var`      | Context variable name to override `ta_data_capture_http_body_response`      |
| `ta_data_capture_http_headers_request_var`    | Context variable name to override `ta_data_capture_http_headers_request`    |
| `ta_data_capture_http_headers_response_var`   | Context variable name to override `ta_data_capture_http_headers_response`   |
| `ta_data_capture_target_request_response_var` | Context variable name to override `ta_data_capture_target_request_response` |
| `ta_data_capture_allowed_types_var`           | Context variable name to override `ta_data_capture_allowed_types`           |
| `ta_reporting_trace_reporter_type_var`        | Context variable name to override `ta_reporting_trace_reporter_type`        |

## Message Logging policy usage

In your Platform agent deployment, ensure the Apigee log server is enabled. Edit the config.yaml file to configure the following:

```yaml
global:
  apigee_server:
    enabled: true
    message_end_token: "__SPAN_END__"
    server:
      endpoint: "0.0.0.0:8444"
      key_file: ""
      cert_file: ""
      max_queue_size: 1000
      max_buffer_size: 1024
```

* Ensure that port 8444 (or the configured port for the Apigee log server) of the instance where the Platform agent is installed is accessible from the Apigee servers.
* Note that the port of the Apigee log server is a TCP port. Make sure that from your Apigee setup, there should be outgoing data access to the TCP port of the Apigee log server (part of the Platform agent).

Also configure the host field in the ExportSpansML policy:

```xml
<Syslog>
    <Message>{TRACEABLE_DATA}__SPAN_END__</Message>
    <!-- Host IP/address TPA -->
    <Host>[TPA_IP]</Host>
</Syslog>
```

## ExtCapReqCapSC Policy usage

Set the IP address of TPA in the following field

```xml
<HTTPTargetConnection>
    <!-- The URL would be https://TPA_HOST:5443/ext_cap/v1/req_cap in case of TLS configuration -->
    <URL>http://TPA_HOST:5442/ext_cap/v1/req_cap</URL>
</HTTPTargetConnection>
```

## Latency Impact of the Inline Blocking Policy

Unlike post-response policies (`ExportSpansSC`, `ExportSpansML`, `ExportSpansJS`), which run after the response is already delivered to the client, `ExtCapReqCapSC` executes **inline during the request path** — meaning its timeouts directly add to the latency experienced by the caller. The two timeout controls below determine the worst-case latency Traceable can add to every API request.

For a full reference architecture treatment (sequence diagrams, tuning, TPA settings), see [Latency and Timeouts](https://github.com/harness/harness-developer-hub/tree/main/traceable-dc-agent/agent-docs/apigee/deployment-architectures/latency-and-timeouts.md).

### Timeout configuration in ExtCapReqCapSC

```xml
<ServiceCallout name="ExtCapReqCapSC">
    <Request>
        <!-- ... -->
    </Request>
    <Response>TA_REQ_CAP_RESPONSE</Response>
    <!-- Time (ms) to wait for a blocking evaluation response from TPA -->
    <Timeout>250</Timeout>
    <HTTPTargetConnection>
        <!-- The <Properties> block below is NOT present in the default policy. -->
        <!-- Add it manually if you want to set a hard connection timeout.      -->
        <Properties>
            <!-- Time (ms) to establish a TCP connection to TPA -->
            <Property name="connect.timeout.millis">150</Property>
        </Properties>
        <URL>http://TPA_HOST:5442/ext_cap/v1/req_cap</URL>
    </HTTPTargetConnection>
</ServiceCallout>
```

### Timeout fields explained

| Field                    | Default   | Description                                                                                                             |
| ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `<Timeout>`              | `250` ms  | Maximum time (ms) Apigee will wait for a blocking evaluation response from the TPA after the connection is established. |
| `connect.timeout.millis` | `3000` ms | Maximum time (ms) to establish a TCP connection to the TPA.                                                             |

**Total worst-case blocking time = `connect.timeout.millis` + `<Timeout>`**

* When **TPA is reachable but slow**: request is held for up to `connect.timeout.millis + <Timeout>`.
* When **TPA is unreachable**: only `connect.timeout.millis` applies — `<Timeout>` is never reached because the connection itself fails.

### Behavior on timeout

When `<Timeout>` is exceeded, the policy treats the evaluation as a failure and **allows the request to proceed** to the backend (fail-open). Impact: any request whose blocking evaluation takes longer than the configured timeout will bypass the security check and reach the upstream service.

> **Note:** The appropriate timeout values depend on the network proximity between Apigee and the TPA and the number of blocking rules enabled. Tighter timeouts reduce worst-case added latency but increase the probability of fail-open under load spikes or TPA slowdowns.

### Timeouts in post-response policies

The same `<Timeout>` and `connect.timeout.millis` fields apply to `ExportSpansSC` as well, since it is also a ServiceCallout. However, because `ExportSpansSC` runs post-response with `continueOnError="true"`, its timeouts have **no impact on caller latency** — they only determine whether the trace export to TPA succeeds or is silently dropped.

`ExportSpansJS` is a **true fire-and-forget** — it calls `httpClient.send()` without `waitForComplete()`, meaning Apigee dispatches the HTTP request and immediately moves on without waiting for a response. The `timeLimit="200"` attribute on the policy caps only the JavaScript execution time (building and dispatching the request), not the HTTP round-trip itself.

## Enabling ssl

If ssl needs to be enabled, follow the steps mentioned in the installation.md file

## ExportSpansSC Usage

Configure the following fields when this policy is being used

```xml
<Request>
    <!-- Configure the timeout in milliseconds -->
    <Timeout>250</Timeout>
    <HTTPTargetConnection>
        <!-- The URL would be https://TPA_HOST:5443/ext_cap/v1/res_cap in case of TLS configuration -->
        <URL>http://TPA_HOST:5442/ext_cap/v1/res_cap</URL>
    </HTTPTargetConnection>
</Request>
```