fix(sls-flusher): propagate send failures and classify by actionability

docs/sls-output.md

@@ -153,6 +153,19 @@ ls ~/.loongsuite-pilot/logs/sls-failed-logs/
 
 These JSONL records contain the endpoint, error summary, batch count, and batch byte estimate. They do **not** contain the failed batch payload, message content, request headers, or credentials, so they cannot be used to replay failed uploads. Files rotate by local date and at 10 MiB; the directory is limited to 50 MiB and also follows `retention.slsFailedDays` (7 days by default).
 
+## Send Failure Classification, Cooldown & Circuit Breaker
+
+After retries are exhausted, a send failure is classified by actionability, which drives the alarm level and recovery behavior:
+
+| Class | Trigger | Alarm behavior |
+|-------|---------|----------------|
+| `transient` | Timeout / network failure / 5xx | Not alarmed per-occurrence; failures are only reflected in the failure metric. A single alarm is raised only when one endpoint fails whole batches for several consecutive flush cycles. |
+| `quota` | 429 throttling | Alarmed per-occurrence (aggregated). |
+| `config` | 404 / 403 with an SLS error code, or project not-exist / forbidden / in-recycle-bin | Alarm is cooldown-gated (once per hour) and trips a circuit breaker for that endpoint. |
+| `payload` | 413, or a single entry larger than the per-request body cap | Alarmed (an oversize entry's largest field is truncated to fit, or the entry is dropped). |
+
+Circuit breaker: when an endpoint keeps returning terminal `config` failures, Pilot stops retrying it at high frequency and backs off exponentially (capped at 10 minutes). When the backoff elapses, one probe request is allowed through, and success clears the breaker automatically. Breaker state is in-memory and does not survive a restart. Regardless of whether an alarm is raised, failed entries are always counted in the flusher metric `out_failed_entries_total`.
+
 Local JSONL output can help confirm whether collection itself is working before debugging SLS delivery:
 
 ```bash

docs/zh-CN/sls-output.md

@@ -153,6 +153,19 @@ ls ~/.loongsuite-pilot/logs/sls-failed-logs/
 
 这些 JSONL 记录只包含 endpoint、错误摘要、batch 条数和 batch 字节数估算，不包含失败 batch payload、消息正文、请求 headers 或凭证，因此不能用于重放失败数据。日志按本地日期和单文件 10MiB 轮转，目录总量限制为 50MiB，同时遵循 `retention.slsFailedDays`（默认 7 天）。
 
+## 发送失败的分类、冷却与熔断
+
+重试耗尽后的发送失败会按可操作性分类，并驱动告警级别与恢复行为：
+
+| 分类 | 判据 | 告警行为 |
+|------|------|----------|
+| `transient` | 超时 / 网络失败 / 5xx | 默认不逐条告警，只计入失败指标；同一 endpoint 连续多个周期全批失败才升级一条告警 |
+| `quota` | 429 限流 | 逐条上报（聚合） |
+| `config` | 404 / 403 / project 不存在、被禁用、在回收站 | 上报受冷却窗口抑制（每小时一条），并对该 endpoint 触发熔断退避 |
+| `payload` | 413 / 单条超过单请求体积上限 | 上报（超限条目先尝试截断最大字段，仍超限则丢弃） |
+
+熔断说明：当某 endpoint 连续出现 `config` 类终态失败时，Pilot 会停止对它高频重试，按指数退避（上界 10 分钟）降低尝试频率；退避到达后放行一次探测，成功即自动恢复。熔断为内存态，不跨重启保留。无论是否告警，失败条数都会计入 flusher 指标的 `out_failed_entries_total`。
+
 调试 SLS 前，可以先通过本地 JSONL 确认采集本身是否正常：
 
 ```bash