Logs & tracing

Every runtime request produces a structured log entry, and selected requests capture full payload traces. Together they take you from "a consumer reported an error at 14:32" to the exact call — its payloads, headers, and conversion trace — in seconds, all keyed by the correlation ID.

---

Structured runtime logs

Each request writes a structured log event with these fields:

Always present

• occurred_at
• correlation_id
• environment, service_key, operation_key
• http_status
• result_code
• latency_ms
• request_size_bytes
• payload_logged — whether the full payload trace was captured for this call

When available

• backend_latency_ms
• converter_overhead_ms — max(0, latency_ms − backend_latency_ms)
• response_size_bytes
• error_code, error_message

Result codes

result_code is the quickest way to classify a call:

| result_code | Meaning | |---|---| | success | The call completed and converted cleanly. | | error | The call failed (validation, transport, or backend error). | | fault | The backend returned a SOAP fault, mapped to a REST error. | | fallback | A configured transport-failure fallback was applied (X-S2R-Fallback: true on the response). | | contract_drift | The backend response did not match the stored contract (UI label: Backend Response Mismatch; S2R-RUN-0506). | | response_schema_violation | The backend response failed OpenAPI schema validation while response enforcement was enforce (S2R-VAL-0430, HTTP 502). |

---

Searching logs

GET /admin/v1/runtime-logs searches the structured logs. Filters:

• environment, serviceKey, operationKey — each repeatable (multi-value).
• correlationId — pinpoint a single call.
• resultCode (alias status) — for example resultCode=contract_drift for backend mismatches.
• window (15m/1h/24h/7d/30d/60d) or a custom start/end range.
• page / pageSize — results are paged server-side rather than capped in the browser.

Each row includes the converter-overhead figure so you can sort slow conversions from slow backends.

---

Live traffic log

The live traffic surface is the drill-down layer: when a dashboard number looks wrong, you can inspect the actual traffic behind it. For a real call it shows the full request and response payloads and the request and response headers, alongside the correlation ID and gateway metadata.

Payload capture policy:

• Errors (non-200) — full payload traces are always captured.
• Successes (200) — full payload traces are captured only when debug mode is enabled for the service or the call (X-Debug-Enabled for authorized internal callers).

This keeps storage bounded in steady state while guaranteeing you have the full picture for anything that failed. Payload handling is UTF-8 end to end, so Hebrew and other non-Latin text render correctly in the trace.

---

Contract-drift detection

When a backend's response stops matching the expected contract — a field changes type, a required element disappears, the shape diverges — the platform flags the call as contract drift (result_code=contract_drift, error code S2R-RUN-0506) rather than silently passing malformed data downstream. The error carries a path-aware driftReason, and the dashboard surfaces a backend-response-mismatch count plus the latest reason. You find out a backend changed before your REST consumers do. Drift rows are searchable directly via GET /admin/v1/runtime-logs?resultCode=contract_drift.

---

Async callback tracking

For asynchronous, callback-style integrations the platform tracks the full lifecycle, queryable via GET /admin/v1/async-executions:

• the initial request and the generated SOAP request,
• the backend acknowledgement,
• the inbound callback SOAP payload and the mapped callback result,
• correlation lifecycle timestamps (callbackReceivedAt, completedAt),
• a status that moves through waiting_callback → completed / failed, and surfaces as expired once the callback window elapses.

Operators can act on a stuck or mis-mapped execution without waiting for a new backend callback:

• Replay a stored callback through the current response mapping to check whether a mapping fix would now succeed ({id}/replay-preview).
• Reprocess and persist the remapped result after fixing response rules ({id}/reprocess).
• Submit a callback payload manually for preview or persistence ({id}/callback-preview, {id}/callback-reprocess).
• Manually complete or fail an execution ({id}/manual-complete, {id}/manual-fail), or reopen a failed/expired one back into waiting_callback.

---

Debug traces

GET /admin/v1/debug-traces/{correlationId} returns the captured payload chain for one correlation ID — the inbound payload, the generated SOAP request, the backend SOAP response, and the mapped REST response. A companion {correlationId}/replay-metadata endpoint returns runtime context (environment, service, operation, HTTP status, result code), the active route hint (restMethod / restPath), and payload-presence flags, so you can decide what a replay would exercise before running one.

Saved backend test previews (from the onboarding/test endpoints) are also visible in Observability via GET /admin/v1/backend-test-previews. These are operator-initiated test runs and are kept distinct from live runtime traffic.

---

Related pages

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

---

All Specaria SOAP to REST docs