Logs and request inspection

Gateway logs connect a user-visible response to the route and provider attempts that produced it. Use them to answer which model and provider ran, whether fallback occurred, how long attempts took, and which error stopped execution.

The metadata-only statement is verified for the inspected chat handler and should not be generalized to every Ethen product.

Inspection should move from the outside of the request inward. Start with the final status and error code, then use request and trace IDs to locate provider attempts and usage. If attempts are absent, focus on validation, authentication, readiness, policy, or budget. If attempts exist, compare provider, alias, latency, and redacted error information in order. This method avoids assuming that the final provider field alone explains a fallback sequence or that an empty result set proves records were deleted.

Request logs

A request-log record includes request ID, trace ID, route ID, model ID, provider ID, status code, latency, estimated cost, input and output tokens, fallback state, error code, project, API-key ID, and user ID. The inspected chat handler uses metadata-only logging, so its log contract should not be described as storing prompts or generated content.

The default list limit is 50 when a caller does not override it. That is a query behavior, not proof that only 50 records exist or that older records are deleted.

Request logs include request ID, trace ID, route ID, model ID, provider ID, status code, latency, estimated cost, token counts, fallback state, error code, project, API-key ID, and user ID.

These fields support correlation without requiring prompt or response text in this handler.

A default list limit in implementation is not a retention or availability guarantee.

A request log summarizes the call from the Gateway perspective. It includes identifiers, route, model, selected provider, final status, latency, token counts, estimated cost, fallback state, error code, project, key, and user context.

No provider attempts usually points to an earlier validation or policy gate; populated attempts shift attention to routing or execution. Attempt rows include sequence number, provider, model, success, latency, error code, and a redacted message. Metadata-only mode on the inspected route does not claim to persist prompt or response content.

The chat handler writes logs and attempts for streaming and non-streaming paths. The default list limit of 50 can be overridden and is not a product guarantee. Metadata-only logging is verified only for the inspected chat handler and should not be generalized to every route.

Trace fields

Request ID and trace ID serve different correlation needs. The request ID identifies the Gateway request returned to the caller, while the trace ID links related operational records across routing, attempts, usage, and errors. Preserve both in application telemetry. Provider, model, route, fallback state, latency, and error fields can then be joined to the exact response without logging prompt or completion content on the inspected chat path.

Trace correlation is especially important for streams because delivery and persistence can complete at different times. The client event history, response headers, request log, provider attempts, and usage event should reference the same operation before they are combined into one incident record.

Use the request ID to identify one inbound call and the trace ID to correlate related routing, attempt, log, and usage records. Route ID and model ID describe the requested path. The final provider and fallback fields summarize the outcome, while attempt rows preserve intermediate failures.

When a result cannot be found, verify the identifier, project context, filters, time window, and retrieval limit before concluding that the record was never written. Retention behavior is not established by this source pack.

Request ID identifies the Gateway call, while trace ID supports correlation across related execution records.

Route and model fields describe what was requested and selected at that time.

Include the request and trace identifiers in a support case so operators can locate the same record.

Request and trace IDs are the primary correlation fields. Model and provider names can recur across many calls, while the identifiers connect one response to its attempts, usage event, and error information.

Correlating request and trace IDs is safer than relying on model or provider names alone. Redacted error details and identifiers are safer diagnostic material than raw prompts, credentials, or provider responses.

Metadata-only mode means the inspected route does not claim to persist prompt or response content. Request logs include project, API-key ID, and user ID alongside routing and usage fields. When retries or fallback occur, inspect the attempt sequence rather than relying only on the final provider field.

An empty result should not be interpreted as deletion or expiration without a verified retention or filtering rule.

Provider details

A successful final provider does not erase earlier failed attempts. Keep the ordered attempt rows when comparing latency or diagnosing fallback.

Provider-attempt records contain the attempt number, provider ID, provider-specific model ID, success state, error code, redacted error message, and latency. Read them in numeric order. An unavailable provider removed before execution may not appear as an adapter attempt, while a timeout or adapter error should.

Redacted error messages are intended for diagnosis without exposing raw provider secrets or unnecessary payload data. The selected provider field describes the final route; it does not replace the attempt sequence when retries or fallback occurred.

Several attempts can exist when policy allows retry or fallback.

The final selected provider should be read alongside the complete attempt sequence.

Provider-attempt records explain retries and fallbacks. Read them in attempt-number order and compare provider, model alias, success, latency, error code, and redacted error details.

Provider-attempt rows include attempt number, provider, model, success, latency, error code, and a redacted error message.

Errors

Start with the request status and public error code. If the failure occurred before routing, there may be no provider attempts. If attempts exist, locate the first failure and note whether a later attempt succeeded. provider_stream_error can occur after a stream begins, so compare the request record with the event history.

An internal_error is less specific than a key, model, policy, budget, or provider code. Preserve the request and trace IDs when a deeper investigation is required.

Error codes allow operators to distinguish key, readiness, policy, budget, provider, streaming, and internal failures.

Redacted provider messages are safer for diagnostics but may omit provider-specific detail.

Use the error family to select remediation before sending the request again.

An overall error can occur before any provider attempt or after several failed attempts. The absence of attempts therefore points toward validation, authentication, model status, budget, policy, or route eligibility.

Keep the identifiers together with the original state before retrying so the new result can be compared with a known baseline.

Privacy considerations

The metadata-only statement is verified for the inspected chat handler. It should not be generalized to every Gateway, agent, workflow, playground, or provider path. Fields such as project, user, API-key ID, provider, model, tokens, cost estimate, latency, and error code can still be sensitive operational metadata.

Share only the identifiers and redacted fields needed for diagnosis. Do not copy Bearer keys, BYOK credentials, raw provider responses, or unnecessary user content into tickets or handoffs. Consult the approved Privacy and Terms pages for published policy boundaries.

The chat route is configured for metadata-only logging and should not be described as storing prompt or completion content.

Identifiers, model names, provider choices, token counts, and error data can still be operationally sensitive.

Access, export, and retention guarantees require separate policy evidence.

Metadata-only logging is verified for the inspected chat handler. Do not extend that claim to every Ethen surface, promise a retention period, or state that exports and deletion controls exist without additional sources.

Request logs include project, API-key ID, and user ID in addition to routing and usage fields.

Begin with the request or trace identifier, review the final status, then read attempts in order to locate validation, routing, provider, or fallback failure.

Redacted provider errors reduce accidental secret exposure, but metadata can still identify projects, users, API-key records, models, routes, and timing. Access to logs should therefore follow the project’s authorization boundary. No retention period, export guarantee, or platform-wide content policy is established for every log surface.

Troubleshooting

If no matching log appears, determine whether authentication or request parsing failed before log creation, whether persistence was best effort, or whether the query filters exclude the event.

When attempt rows are present without a successful final provider, compare their error codes and latency to the final request status. When the request succeeds after fallback, verify that fallbackUsed, the selected provider, and the ordered attempts agree. Inconsistent identifiers usually indicate that records from different requests or environments were combined.

If the log and response disagree, verify that both identifiers refer to the same request and project. For fallback requests, compare final metadata with every attempt rather than expecting one provider row. For streams, determine whether final persistence completed or only partial events were delivered.

A missing record may reflect the wrong filter, retrieval limit, project, or environment. No log-retention period is defined; an absent entry therefore cannot be treated as proof of expiry or deletion.

Start from the request or trace ID returned to the caller.

Compare status, model readiness, selected route, attempt sequence, fallback state, latency, and budget outcome.

When a record is absent, distinguish a pre-handler failure, best-effort persistence issue, and query-scope problem before assuming execution never occurred.

When logs appear incomplete, check whether the request failed before persistence, whether streaming persistence was best-effort, and whether the list query used an implementation limit. A default limit is not evidence that older records were deleted.

Interpret cost, token, and fallback fields only when they are present on the matching request record.

Metadata-only logging is verified for the inspected chat handler only; the source pack does not establish universal retention, export, or prompt-content behavior.

Reconstruct one request from its identifiers outward. Locate the request ID and trace ID, then read route, model, selected provider, status, latency, token counts, estimated cost, fallback state, and error code. Provider-attempt rows add attempt number, provider-specific model, success, latency, and redacted error detail, making it possible to distinguish preflight rejection from adapter failure and later fallback.

A successful final response can still contain failed attempts. Conversely, an authentication, validation, policy, model-readiness, or budget error may produce no provider attempt at all. Keep those cases separate when building dashboards or support procedures. Metadata-only logging is verified for the inspected chat-completions handler; this documentation does not claim that every product route omits prompt and response content or shares the same retention behavior.