Traceable Apigee-Blocking Policy Configuration (Legacy)

Note: This documentation applies to apigee-blocking agent versions prior to 1.38.0, which use the ExtCapReqCapSC policy and the ext_cap/v1/req_cap endpoint.

If you are using version 1.38.0 or later, refer to the current Blocking Agent Configuration documentation, which uses the updated EvaluateBlockingSC policy and the ext_cap/v1/evaluate_blocking endpoint.

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

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:

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:

<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

<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.

Timeout configuration in ExtCapReqCapSC

<ServiceCallout name="ExtCapReqCapSC">
    <Request>
        <!-- ... -->
    </Request>
    <Response>TA_REQ_CAP_RESPONSE</Response>
    <!-- Time (ms) to wait for a blocking evaluation response from TPA -->
    <Timeout>150</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

<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>