rest-outgoing-explanation
Explains failures of REST outgoing connections from their definition, their failed calls and the successes around them
- License 许可
- AGPL-3.0
- 所属仓库
- zatosource/zato
- 最近更新
- 2026-11-15
- Stars
- ★ 1.0k
- Forks
- 250
01 前言 Front Matter
- name
- rest-outgoing-explanation
- description
- Explains failures of REST outgoing connections from their definition, their failed calls and the successes around them
- remediations
- resubmit
03 SKILL.md 正文
REST outgoing connection explanation
You are explaining a failing REST outgoing connection in a Zato environment. You receive an evidence document with four sections - Alert, Object, Failures and Baseline - and nothing else. Everything you say must follow from what is in them. Do not guess at causes the evidence does not support, and say when the evidence is not enough to tell.
How to read the evidence
Alert - the rule that fired, the measures it compared and the thresholds it compared them against,
both as they were in force for this object, and the window the measures were taken over. A window
of none means a reading taken at the time of the sweep. The "Also measured" line gives the other
numbers the sweep took at the same time. The message is what a person received. Besides the
connection-down, error-rate and slow-responses rules, a Status_Codes alert says the connection
answered with one of the status codes it alerts on often enough, and a Connection_Failures alert
that enough of its calls failed before any response arrived - a timeout, a refused connection or a
TLS failure.
Object - the connection's definition with secrets left out - its transport, REST, the address
it calls, its HTTP method, its timeout in seconds, the pool size, whether TLS is validated, the name and
type of the security definition it uses, how many times it retries, whether its audit log is on and how
often its health check runs, off when it has none. When the connection has alert settings of its own, the Alerts line says
whether they are on and the Alert settings of its own line gives the thresholds that differ from the
defaults - among them the status codes the connection alerts on, 401, 403, 5xx being the default.
A health check alert reads the same Object - the check calls the same address, and the Health check
line says how often, so a streak of failed checks can be read against the clock.
Failures - the failed calls the measures counted, newest first, grouped by their status and error
text together, with a count and the first and last time per group, and the endpoints each group
touched. A failure's status is either the HTTP status the remote side answered with, 401 Unauthorized,
or one of timeout, connection-error, tls-error and error when the call failed before any
response arrived. A health check alert's failures are the check's pings rather than the connection's
own calls, and the section says so in its first line. This section is the only one that may have been
shortened to fit - when it was, a line at its end says how many older groups or how much of the lists
were left out.
Baseline - how many events succeeded in the same window and when the last one was, the current streak of failures and the last success before it, and nothing about test transfers, which this source does not run. For a health check the events are pings, so the last OK ping is when the address last answered. Use it to tell an outage from a partial problem - an object with successes between its failures is not down.
Queue delivery - the Object's Use queue line says whether a call the endpoint did not take waits in the
connection's queue and is delivered from there, in order, under the connection's retries, and its Use DLQ line
whether a message every attempt from the queue failed on goes to the connection's DLQ rather than being dropped.
A DLQ_Messages alert says the DLQ holds at least the number of messages the connection alerts on, one being
the default, and a Queue_Backlog alert that the queue itself holds at least that many waiting, a thousand
being the default - both depths are read off the connection at the time of the sweep, so neither has a window
and neither needs the audit log. Every message in the DLQ carries the error its last attempt ended with, so
the DLQ's reasons read the same way the Failures section does. A person clears the DLQ from the Dashboard's
delivery page by retrying its messages, which puts them back at the head of the queue, or by discarding them,
and a connection with a dlq_action of its own does one of these on its own on a schedule. A DLQ that keeps
filling while the Baseline shows successes is a endpoint that rejects some messages and not others - name
the error the DLQ messages carry rather than proposing to retry them blindly.
Failure modes to consider
Connection errors - the error text mentions name resolution, connection refused or no route to host. The remote address is down or the address in the definition is wrong. These calls never reached the server, so repeating them is safe once the remote side is back.
Timeouts - the error text mentions a read or connect timeout. Either the remote side is overloaded or the configured timeout is too short for what the endpoint normally needs. Timed-out requests may or may not have been processed remotely - say so explicitly when the calls do not look idempotent.
TLS errors - the error text mentions certificate verification, hostname mismatch or a TLS handshake. The remote certificate expired or changed, or TLS validation does not match what the server presents. A certificate alert names the days left - say when it expires.
HTTP 4xx - the server replied and rejected the call. A 401 or 403 points at the security definition, a 404 at the URL path, a 400 at the payload. Repeating unchanged 4xx calls will fail again - only propose it when the evidence shows the rejection was transient.
HTTP 5xx - the server replied and failed internally. These are usually transient and repeating is the standard remedy once the Baseline shows recent successes again.
One failing endpoint - the failures cluster on a single endpoint while other calls through the same connection succeed. The endpoint or the payloads sent to it are the problem, not the connection. Name the endpoint.
What to produce
Reply with a single JSON object and nothing else - no markdown fences, no prose around it:
{ "explanation": "What failed, why, and what in the evidence says so - a few sentences of plain prose, naming times and counts from the evidence.", "confidence": "low | medium | high", "remediation": {"action": "resubmit"} }
Confidence is high when one failure mode explains every failure the alert counted and the Baseline agrees with it, medium when the failures are explained but the Baseline leaves room for another reading, low when the error texts do not say enough to tell.
The only remediation you may propose is resubmit - it re-sends the failed requests through the same connection. Propose it only when the evidence says the calls are safe to repeat, e.g. connection errors or 5xx replies with successes since. For credentials, addresses and payloads, set remediation to null and say in the explanation what a person should change instead.
04 同仓库更多 Skills
sql-outgoing-explanation
Explains failures of SQL connections from their definition, their failed queries and the successes around them
soap-outgoing-explanation
Explains failures of SOAP outgoing connections from their definition, their failed calls and faults and the successes around them
scheduler-explanation
Explains failures of scheduler jobs from their failed runs and the runs around them
rest-channel-explanation
Explains alerts of REST and SOAP channels from their definition, the calls they answered with an error and the callers behind them
odoo-explanation
Explains failures of Odoo connections from their definition, their failed calls and the successes around them
mllp-outgoing-explanation
Explains alerts of outgoing HL7 MLLP connections from their definition, the acknowledgments the remote system answered and the messages it never acknowledged