Logs and Tracing for Runtime Requests

Overview

The platform's logging and tracing capabilities provide deep visibility into every API request. When a consumer reports an error or unexpected behavior, these tools allow you to find the exact transaction and inspect its complete lifecycle.

Every runtime request generates a structured log entry. For failing requests, and for successful requests in debug mode, the platform also captures a full payload trace. All related events for a single transaction—from the initial API call to the backend response and final conversion—are linked by a unique correlation_id. This allows you to move from a high-level symptom, like an error at a specific time, to the precise request and response payloads that caused it.

This document details the structured logs, payload traces, and the APIs used to query them.

Structured Runtime Logs

Each request processed by the runtime generates a structured log event containing key operational metrics and metadata. These logs are the primary source for searching and analyzing traffic patterns, performance, and errors.

Log Fields

The fields below are present in each structured log record.

Always Present

When Available

Result Codes

The result_code provides a quick classification of the request's outcome. It is a key field for filtering and troubleshooting.

Searching Logs

You can search and filter structured logs using the Admin API.

API Endpoint

GET /admin/v1/runtime-logs

This endpoint retrieves a paginated list of structured log entries. Results are paged on the server, allowing for efficient retrieval of large datasets.

Query Parameters

Example

To find all requests where the backend response did not match the expected contract, you can filter by resultCode.

GET /admin/v1/runtime-logs?resultCode=contract_drift

Live Traffic and Payload Tracing

The live traffic view provides a drill-down layer for inspecting the full data of individual transactions. When a structured log indicates an issue, you can retrieve the corresponding payload trace to see the exact data that was processed.

A full trace includes:

• Full request and response payloads.
• Full request and response headers.
• Correlation ID and gateway metadata.

Payload Capture Policy

To balance storage costs with debugging needs, payload capture follows a specific policy:

• Errors (non-2xx status codes): Full payload traces are always captured.
• Successes (2xx status codes): Full payload traces are captured only if debug mode is enabled for the service or for the specific call (via the X-Debug-Enabled header for authorized callers).

This policy ensures that you have complete diagnostic information for any failure while managing storage in normal operation. The platform handles all payload data as UTF-8, ensuring correct rendering of non-Latin character sets in traces.

Contract-Drift Detection

The platform automatically detects when a backend response deviates from its expected contract (e.g., a field changes type, a required element is omitted). Instead of passing potentially malformed data to the API consumer, the platform flags the call with result_code=contract_drift and the error code S2R-RUN-0506.

The resulting error includes a driftReason field that specifies the path to the divergence. This allows API publishers to identify and address backend changes before they impact downstream consumers. You can search for these events directly using the runtime logs API: GET /admin/v1/runtime-logs?resultCode=contract_drift.

Asynchronous Operation Tracking

For asynchronous integrations that use callbacks, the platform tracks the full operation lifecycle. You can query the state of these executions via the GET /admin/v1/async-executions endpoint.

Tracked lifecycle information includes:

• The initial request and the generated SOAP request.
• The backend's acknowledgement.
• The inbound callback SOAP payload and the mapped result.
• Lifecycle timestamps such as callbackReceivedAt and completedAt.
• A status field that transitions through a defined lifecycle.

Asynchronous Execution Status Lifecycle

The status of an asynchronous execution progresses through the following states:

stateDiagram-v2
    [*] --> waiting_callback: Initial request
    waiting_callback --> completed: Callback received & processed
    waiting_callback --> failed: Callback processing failed
    waiting_callback --> expired: Callback window elapses
    failed --> waiting_callback: Reopened by operator
    expired --> waiting_callback: Reopened by operator

Operator Actions

Operators can manage stuck or failed asynchronous executions using several API endpoints, avoiding the need to wait for a new backend callback.

• Replay Preview ({id}/replay-preview): Test a stored callback against the current response mapping to see if a fix would work.
• Reprocess ({id}/reprocess): Re-apply the response mapping to a stored callback and persist the new result.
• Submit Callback ({id}/callback-preview, {id}/callback-reprocess): Manually submit a callback payload for preview or for reprocessing and persistence.
• Manual State Change ({id}/manual-complete, {id}/manual-fail): Manually force an execution into a completed or failed state.
• Reopen: An operator can move an execution from a failed or expired state back to waiting_callback.

Debug Traces

To retrieve the complete payload chain for a specific transaction, use the debug traces API.

• GET /admin/v1/debug-traces/{correlationId}: Returns the captured payload chain, including the inbound payload, generated SOAP request, backend SOAP response, and the final mapped REST response for a given correlationId.

A companion endpoint provides metadata to help understand the context of a trace before replaying it:

• GET /admin/v1/debug-traces/{correlationId}/replay-metadata: Returns runtime context like environment, service, operation, http_status, result_code, the active route hint (restMethod, restPath), and flags indicating which payloads were captured.

Troubleshooting

Interpreting Failure Result Codes

Use the result_code in structured logs to identify the nature of a failure:

• error: A generic failure. Check error_code and error_message for details.
• fault: The backend returned a SOAP fault. The trace will contain the original fault from the backend.
• fallback: The request failed, but a configured fallback was successfully applied.
• contract_drift: The backend response structure has changed. See the driftReason in the trace.
• response_schema_violation: The backend response failed OpenAPI validation.

Specific Error Codes

• S2R-RUN-0506: Indicates a Contract Drift. The backend's response did not match the stored contract.
• S2R-VAL-0430: Indicates a Response Schema Violation. The backend's response failed schema validation when enforce mode was active. This is accompanied by an HTTP 502 Bad Gateway status.

See Also

• Observability overview
• Dashboards & KPIs
• Error codes
• Admin API — observability endpoints

All SOAP-to-REST docs