Runtime Log and Debug Trace Storage

Overview

The Runtime Log Repository is a server-side component responsible for persisting API transaction logs and detailed debug traces to a database. It provides a durable storage mechanism for runtime observability data generated by the API gateway.

This component is called by the API runtime after processing a request. It takes structured data describing the transaction—including identifiers, metrics, status codes, and error details—and writes it to the s2r_runtime_log table. For transactions where full payload debugging is enabled, it can also store request/response headers and bodies in a separate s2r_debug_trace table.

The data stored by this repository is the canonical source for features such as the Log Search UI, analytics, and monitoring.

How it Works

The repository provides two primary methods for data persistence: insertRuntimeLog for summary transaction data and insertDebugTrace for detailed payload traces.

When an API transaction is completed, the runtime calls insertRuntimeLog with various metrics and metadata. The repository generates a unique log ID (id), captures the current timestamp (occurred_at), and executes a SQL INSERT statement into the s2r_runtime_log database table.

If debug tracing is active for the transaction, the runtime subsequently calls insertDebugTrace. This method stores request and response payloads, linking them to the original transaction log via a runtime_log_id. Debug traces have a configurable retention period, after which they are eligible for deletion.

The following diagram illustrates the data flow from the API runtime to the database via the repository.

sequenceDiagram
    participant API Gateway Runtime
    participant Log Repository
    participant Log Database

    API Gateway Runtime->>Log Repository: insertRuntimeLog(...)
    activate Log Repository
    Log Repository->>Log Database: INSERT INTO s2r_runtime_log
    Log Database-->>Log Repository: (Success)
    Log Repository-->>API Gateway Runtime: logId (UUID)
    deactivate Log Repository

    alt Debug Trace Enabled
        API Gateway Runtime->>Log Repository: insertDebugTrace(...)
        activate Log Repository
        Log Repository->>Log Database: INSERT INTO s2r_debug_trace
        Log Database-->>Log Repository: (Success)
        deactivate Log Repository
    end

Data Sanitization and Defaults

To ensure data integrity and prevent insertion failures, the repository applies transformations to certain fields:

• Null or Blank Strings: For fields like environment, serviceKey, operationKey, and resultCode, null or blank values are replaced with fallback strings such as "unknown" or "error".
• JSON Serialization: The requestHeaders map provided to insertDebugTrace is serialized into a JSON string. If serialization fails, it defaults to an empty JSON object ({}) to avoid losing the entire trace record.

API Reference

The repository exposes Java methods for use by the API runtime.

insertRuntimeLog

This method inserts a record into the s2r_runtime_log table. It has several overloaded versions to support progressively more detailed logging context. The most comprehensive version accepts all parameters listed below.

Earlier versions exist for backward compatibility and for logging requests that fail before full context (like direction or service version) can be determined.

• insertRuntimeLog(correlationId, ...): The base version.
• insertRuntimeLog(correlationId, direction, ...): A direction-aware overload that adds the direction of the API call (PUBLISH or CONSUME).
• insertRuntimeLog(..., monitorViolationsJson): A monitor-aware overload that adds a JSON string detailing any detected schema violations.
• insertRuntimeLog(..., serviceVersionId): A version-aware overload that links the log to a specific service version ID, allowing for per-version traffic analysis.

Upon successful insertion, the method returns the UUID generated for the new log record.

insertDebugTrace

void insertDebugTrace(UUID correlationId,
                      UUID runtimeLogId,
                      Map<String, String> requestHeaders,
                      String requestPayload,
                      String soapRequestPayload,
                      String soapResponsePayload,
                      String responsePayload,
                      int retentionDays)

This method inserts a detailed debug trace into the s2r_debug_trace table. It links the trace to a transaction via correlationId and runtimeLogId. The retentionDays parameter determines the retention_until timestamp, which controls the trace's lifecycle.

insertRuntimeLog Parameters

The following table details the parameters for the most comprehensive insertRuntimeLog method.

insertDebugTrace Parameters

Database Operations

The repository methods ultimately execute SQL INSERT statements.

Runtime Log Insertion

A call to insertRuntimeLog results in the execution of the following SQL statement. Placeholders (?) are replaced by the method parameters.

insert into s2r_runtime_log (
    id, occurred_at, correlation_id, direction, environment, service_key, operation_key, http_status, result_code,
    latency_ms, backend_latency_ms, converter_overhead_ms, request_size_bytes, response_size_bytes, payload_logged, error_code, error_message,
    monitor_violations, service_version_id
) values (?, now(), ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?::jsonb, ?)

Debug Trace Insertion

A call to insertDebugTrace results in the execution of the following SQL statement.

insert into s2r_debug_trace (
    id, correlation_id, runtime_log_id, request_headers, request_payload, soap_request_payload,
    soap_response_payload, response_payload, retention_until, created_at
) values (?, ?, ?, ?::jsonb, ?, ?, ?, ?, ?, ?)

Troubleshooting

JSON Serialization Failure

When insertDebugTrace is called, it serializes the requestHeaders map into a JSON string. If this process fails for any reason (e.g., due to unexpected data types), the repository catches the JsonProcessingException and writes an empty JSON object ({}) to the request_headers column in the database. This ensures that the trace record is still saved, even if the headers are lost.

Null or Blank String Handling

The repository prevents null or empty strings from being inserted for key metadata fields (environment, serviceKey, operationKey, resultCode). If a null or blank value is passed for one of these parameters, a predefined fallback is used (e.g., "unknown"). This ensures that log records are always queryable by these fields and prevents database constraint violations.

See Also

• Log Search UI: The data persisted by this repository is made available for searching and analysis in the Log Search UI.
• Service Versioning: The serviceVersionId field is critical for distinguishing traffic between different versions of the same service, which can be used for features like per-version analytics.

All SOAP-to-REST docs