---
title: "Apigee - MessageLogging Policy"
slug: "apigee-policy"
updated: 2025-03-20T04:19:29Z
published: 2025-03-20T04:19:29Z
---
> ## Documentation Index
> Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Apigee Policy
Apigee is a platform for developing and managing APIs. By fronting services with a proxy layer, Apigee provides an abstraction for your backend service APIs, including security, rate limiting, quotas, analytics, and more. Traceable offers a message for capturing requests and responses passing through your Apigee deployment to detect anomalous behavior or attacks. The following deployment diagram shows a high-level traffic flow architecture through Apigee and Traceable agent. Traceable's policy captures the incoming request and makes an asynchronous call to Traceable's platform.
.png)
### Data export options
Traceable provides three options to export data: MessageLogging, ServiceCallout, and JavaScript. Here is a high-level difference between them:
- **MessageLogging**: The `MessageLogging` policy logs information from an API proxy's flow, such as request or response data, headers, or custom messages. It's typically used for monitoring, debugging, auditing, or analytics purposes. The logged data can be stored in various destinations such as files, syslog, or external systems such as Traceable. Note that the Apigee agent sends data to the Platform agent through a TCP syslog call.
> [!NOTE]
> Note
>
> MessageLogging policy is preferred if you have Syslog configured in the Traceable Platform agent. Also, MessageLogging policy is less resource intensive for Apigee.
- **ServiceCallout**: The `ServiceCallout` policy allows you to call external HTTP or HTTPS services within an API proxy. This is typically used to interact with third-party APIs, backend systems, or other services to retrieve or send data while processing an API request.
- **JavaScriptCallout**: This option enables making HTTP or HTTPS requests using the HTTP client within JavaScript code. The implementation employs a "fire-and-forget" approach, ensuring calls are fully asynchronous and do not wait for a connection to be established.
---
## Before you begin
Note the following points before you start the deployment. The following prerequisites apply to both the MessageLogging policy and the ServiceCallout policy.
- The document expects a basic working knowledge of the Apigee environment.
- Traceable supports Apigee-x, hybrid, and Apigee Edge cloud.
- Download the Traceable’s policy file. The bundle has both MessageLogging policy and ServiceCallout policy files.
- Ensure the Traceable platform agent is already deployed on a VM accessible from the Apigee environment. For more information, see [Virtual Machine](/docs/vm).
- Note the IP address of the Traceable platform agent. This will be used in the Traceable policy configuration.
#### MessageLogging policy
Following are a few MessageLogging policy-specific prerequisites:
- Traceable’s MessageLogging Apigee agent requires a minimum Traceable Platform agent version 1.43.0.
- 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]
> Note
>
> Apigee log server is a part of Traceable Platform agent. The port number of Apigee log server is part of Traceable Platform agent configuration. The Apigee log server recieves data from Apigee.
- 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).
> [!NOTE]
> Note
>
> You can configure either a MessageLogging policy or a ServiceCallout policy.
---
## Download
Download the Traceable policy for Apigee from Traceable's [download site](https://downloads.traceable.ai/#agent/apigee/latest/). Navigate to **agent** → **apigee** → **latest** to download the `traceable-shareflow.zip` file. Save the file. This file would be used in the Configuration section.
---
## Configuration
The configuration of the Traceable policy for Apigee consists of the following two steps:
1. Adding Traceable agent for Apigee as sharedflow
2. Attaching Traceable agent to:
1. All API proxies using FlowHooks, or
2. To a specific API proxy only
### Policy bundle
The policy bundle has the following files based on the export method you use:
#### Common file
The `TraceableJS.xml` file is common between the different exporting options. The configuration in this file decides which export method will be used. This file also has the other data capture configurations.
```xml
TraceableJS
apigee
apigee
131072
true
true
true
true
false
json,graphql,x-www-form-urlencoded,xml
service_callout
jsc://Traceable.js
```
The following table lists the various Traceable agent configurations.
> [!NOTE]
> Note
>
> The table lists both dynamic and static properties. Dynamic property names end with `_var`, for example, `ta_service_name_var`. The policy first checks the dynamic property; if it is not set, the policy then uses the value from the corresponding static property. You can configure both properties at the same time.
| Configuration | Description |
| --- | --- |
| `ta_service_name` | The name of the service. This is the name that will be displayed on the Traceable Platform. The default name is `apigee`. |
| `ta_environment_name` | Defines the environment name. |
| `ta_data_capture_body_max_size` | Configure the maximum size of the request's body that you would like to capture. |
| `ta_data_capture_http_body_request` | Set it to `true` if you wish to capture the HTTP request body, otherwise set it to `false`. |
| `ta_data_capture_http_body_response` | Set it to `true` if you wish to capture the HTTP request body, otherwise set it to `false`. |
| `ta_data_capture_http_headers_request` | Set it to `true` if you wish to capture the HTTP request header, otherwise set it to `false`. |
| `ta_data_capture_http_headers_response` | Set it to `true` if you wish to capture the HTTP response header, otherwise set it to `false`. |
| `ta_data_capture_allowed_types` | Defines the type of data that is captured. List without spaces: `json,graphql,x-www-form-urlencoded,xml`. |
| `ta_data_capture_target_request_response` | Defines whether to capture outgoing calls to target the backend from Apigee. The default value is `true`. |
| `ta_reporting_trace_reporter_type` | Defines the type of exporter to use between MessageLogging or ServiceCallout. The values are: - `message_logging` - `service_callout` |
| `ta_extra_attribute_list` | This is an optional property. Use it to capture additional context variables other than those captured by default. The property defines a list of pairs to extract variables into span attributes, a list of variable names, and an attributeName separated by `\|`. For example, `apiproxy.name, apigee.api.name \| custom.variable, custom.span.attribute.name` |
| **Context Variables** |
| `ta_service_name_var` | The context variable to get the value to be set in `ta_service_name` dynamically. Check the description for `ta_service_name` for further information on this configuration. |
| `ta_environment_name_var` | The context variable to get the value to be set in `ta_environment_name` dynamically. |
| `ta_data_capture_body_max_size_bytes_var` | The context variable to get the value to be set in `ta_data_capture_body_max_size_bytes` dynamically. Check the description for `ta_data_capture_body_max_size_bytes` for further information on this configuration. |
| `ta_data_capture_http_body_request_var` | The context variable to get the value to be set in `ta_data_capture_http_body_request` dynamically. Check the description for `ta_data_capture_http_body_request` for further information on this configuration. |
| `ta_data_capture_http_body_response_var` | The context variable to get the value to be set in `ta_data_capture_http_body_response` dynamically. Check the description for `ta_data_capture_http_body_response` for further information on this configuration. |
| `ta_data_capture_http_headers_request_var` | The context variable to get the value to be set in `ta_data_capture_http_headers_request` dynamically. Check the description for `ta_data_capture_http_headers_request` for further information on this configuration. |
| `ta_data_capture_http_headers_response_var` | The context variable to get the value to be set in `ta_data_capture_http_headers_response` dynamically. Check the description for `ta_data_capture_http_headers_response` for further information on this configuration. |
| `ta_data_capture_target_request_response_var` | The context variable to get the value to be set in `ta_data_capture_target_request_response` dynamically. Check the description for `ta_data_capture_target_request_response` for further information on this configuration. |
| `ta_data_capture_allowed_types_var` | The context variable to get the value to be set in `ta_data_capture_allowed_types` dynamically. Check the description for `ta_data_capture_allowed_types` for further information on this configuration. |
| `ta_reporting_trace_reporter_type_var` | The context variable to get the value to be set in `ta_reporting_trace_reporter_type` dynamically. Check the description for `ta_reporting_trace_reporter_type` for further information on this configuration. |
#### MessageLogging
If you are using MessageLogging policy, then` ExportSpansML.xml` file is used. This file has the Traceable Platform agent endpoint and TLS configuration.
```xml
{TRACEABLE_DATA}__SPAN_END__
8444
TCP
true
false
false
ref://give_your_truststore_reference
false
ALERT
250
http://TPA_HOST:5442/ext_cap/v1/req_res_cap
false
false
ref://give_your_truststore_reference
false
```
**JavaScriptCallout**
If you are using JavaScriptCallout policy, then `ExportSpansJS.xml` file is used. Make sure that `ta_reporting_endpoint` property is mandatorily configured in `TraceableJS.xml` file.
```xml
ExportSpansJS
false
false
ref://give_your_truststore_reference
false
jsc://ExportSpans.js
```
---
### Step 1 - Add Traceable agent for Apigee as Shared Flow
Complete the following steps to add Traceable's Shared Flow:
1. Login to your Apigee account.
2. Click on the **Develop**tab and navigate to **SharedFlows**.
3. Add a new SharedFlow. Click on **Upload Bundle**. Navigate to the location where you have downloaded Traceable's Apigee policy.
.png)
4. Upload the Traceable SharedFlow zip. You may wish to change the name of the file and import it.
5. Click on the imported SharedFlow and navigate to the **Develop**tab.
.png)
6. Click on the ExportSpansML/ExportSpansSC and TraceableJS policy and update the configuration values. The sample files and configurations are listed above in the [Policy bundle](/v1/docs/apigee-messagelogging-policy#policy-bundle) section. In ExportSpansML/ExportSpansC, configuring the Traceable Platform agent IP address or hostname is mandatory. The other configurations are optional.
.png)
7. Click on **Save**.
8. **Deploy the SharedFlow** — Click the **Deploy**button and select the environment to which you wish to deploy the agent. This will deploy the agent as a SharedFlow to that environment.
---
## Step 2 - Attach the traceable agent
You can attach the Traceable agent to all the API proxies or a specific API proxy. Follow the steps in one of the following sections. Make a note of the following while attaching Traceable's Flow Callout policy. If you are attaching the policy directly to an API proxy, then make Traceable's Flow Callout policy as follows:
- Traceable policy should be the first one in Proxy → Request → Preflow
- Traceable policy should be the last one in Target → Request → Preflow
- Traceable policy should be the first one in Target → Response → Postflow
- Traceable policy should be the last one in Proxy → Response → Postflow
#### Option 1 - Attach Traceable agent to all API proxies using Flow Hooks
Complete the following steps to attach Traceable agent to all the API proxies:
1. Navigate to **Admin Environment**→**Flow Hooks**.
2. Edit the Flow Hooks and attach the `traceable-agent` sharedflow to Pre-proxy, Pre-target, Post-target, and Post-proxy Flow Hooks. This will attach the Traceable agent with all API Proxies.
.png)
You can now make requests to your API proxy. Traceable will capture these requests for analysis.
#### Option 2 - Attach Traceable agent to a specific API proxy
Complete the following steps to attach the Traceable agent to a specific API proxy:
1. Navigate to the API Proxy to which you wish to attach the traceable-apigee agent and click on the Develop tab.
.png)
2. Click on Add a policy, the **+** sign beside Policies.
.png)
3. Select Policy Type Flow Callout (refer to the above screenshot), update the names, and select traceable-shared-flow from the list of sharedflows.
4. In the Proxy Endpoints, click on PreFlow for the endpoint to which you want to attach the agent.
5. Click **+Step** for **PreFlow** on the request side in the flow diagram.
.png)
6. In the Add Step dialogue box, click on the Existing Policy instance.
7. Select the Flow Callout Policy we added earlier and click on **Add**.
8. Click on **Postflow** for the proxy endpoint.
9. Click **+Step** for Preflow on the response side in the flow diagram.
.png)
10. In the Add Step dialogue box, click on the Existing Policy instance.
11. Select the Flow Callout Policy we added earlier and click on **Add**.
12. Repeat the above steps for **Target endpoints**while keeping the following in mind to attach the policy.
1. Traceable policy should be the last one in Target → Request → Postflow
2. Traceable policy should be the first one in Target → Response → Preflow
13. Add a Fault Rule in both the **Proxy Endpoints** and **Target Endpoints**in XML as follows. Update the name of the flow callout policy.
ActionScript ActionScript
** **
```actionscript
NAME_OF_TRACEABLE_FLOW_CALLOUT_POLICY_ADDED_ABOVE
```
14. Click on **Save** the Configuration.
You can now make requests to your API proxy. Traceable will capture these requests for analysis.
#### (Optional) PostClientFlow instrumentation
1. Update the sharedflow `default.xml` as given below. Save and deploy the sharedflow.
2. Already attached to PreProxy, PreTarget, PostTarget, PostProxy. Now attach it to PostClientFlow as well.
> [!NOTE]
> Note
>
> If you are attaching to each API, you should not have the sharedflow in flowhook. Therefore, remove it from all flowhooks if present.
```xml
current.flow.name != "PostClientFlow"
TraceableJS
(current.flow.name = "PostClientFlow") and (TA_REPORTING_TRACE_REPORTER_TYPE = "message_logging")
ExportSpansML
(current.flow.name = "PostClientFlow") and (TA_REPORTING_TRACE_REPORTER_TYPE = "service_callout")
ExportSpansSC
```
Contact the Traceable support team at support@traceable.ai for more help with this option.
---
## Uninstall
If you have attached a Traceable agent as a flow hook, remove it from the flow hook. If you have attached it to specific APIs, remove it from the APIs. Navigate to traceable sharedflow and click on **Status**. Click on **Status > Undeploy**.
To delete it completely, navigate back to the SharedFlows Tab. In the list, delete traceable-sharedflow.
---
## Troubleshooting
In Apigee UI, you can go to any API Proxy on which a Traceable agent is attached and click the Traces/Debug tab. Start the trace session, send a request, and check the flow of requests and variables in TraceableJS policy on both the request and response side. Verify that the `ExportSpansML `or `ExportSpansSC` policy was executed on the Response side (not skipped). Also, ensure the connection from Apigee to the Traceable Platform is proper.
