本页由英文页面机器翻译而来。内容以英文页面为准。 阅读英文页面
告警和运行手册
本页介绍服务器自身的指标应当就哪些情况向你发出告警、每个告警的紧急程度,以及告警触发时要检查什么、做什么。从外部监控服务器(可用性监控和状态页面)的内容见从外部监控服务器;也请把它配置好,因为宕机的服务器不会发来任何指标。
设置 metrics_exporter 后,服务器会导出其指标(配置参考);运行指南列出了每个指标及其标签。下面的告警是为 Prometheus 编写的,使用的名称是 Prometheus 看到的名称:点号变为下划线,并加上单位和计数器后缀(my.queue.oldest_ready_age 变为 my_queue_oldest_ready_age_seconds,my.delivery.attempts 变为 my_delivery_attempts_total)。
| 目标环境 | 设置 | 告警方式 |
|---|---|---|
| 自托管(Docker Compose、Kubernetes、虚拟机) | metrics_exporter = prometheus |
Prometheus 抓取 metrics_listen 上的 GET /metrics,由 Alertmanager 路由告警。下面的规则可以直接使用 |
| 任何带有 OpenTelemetry Collector 的环境 | metrics_exporter = otlp |
Collector 转发到你选择的后端。添加单位和类型后缀的 Prometheus 兼容后端(Prometheus 自带的 OTLP 接收器默认如此)看到的名称相同 |
| Google Cloud(Cloud Run) | metrics_exporter = none |
基于可用性检查、平台指标和基于日志的指标的 Cloud Monitoring 告警策略(参见 Cloud Run) |
| AWS(ECS) | metrics_exporter = emf |
基于 CloudWatch Logs 提取的指标的 CloudWatch 告警(参见 AWS ECS) |
Prometheus 和 Alertmanager
Section titled “Prometheus 和 Alertmanager”规则位于 deploy/monitoring/prometheus/alerts.yml。把该文件复制到你的 prometheus.yml 旁边并加载它:
rule_files: - alerts.yml
scrape_configs: - job_name: my # the rules expect this job name static_configs: - targets: ["my:9464"]metrics_listen默认为127.0.0.1:9464,只有同一主机上的 Prometheus 能访问。在 Docker Compose 或 Kubernetes 中,请设置MY_METRICS_LISTEN=0.0.0.0:9464,并把该端口限制在私有网络中:这个监听器没有身份验证。- 抓取每个进程(每个
role = web和role = worker的进程都有自己的监听器)。队列、媒体、数据库大小、远程服务器、账单导入和快照这些仪表在每个进程中都携带相同的实例级数值,因此规则取它们的最大值。 - 每条规则都有一个
severity标签:page需要立即有人处理(用户已经或即将受到影响),ticket可以等到工作时间处理。请在 Alertmanager 中把它们路由到不同的接收方。每条规则的runbook_url指向下面对应的小节。 - 这些阈值是针对小型服务器的起点。观察一周的数值,再根据你的流量调整阈值和
for持续时间。MyRemoteMediaCacheOverLimit、MyMediaStorageLarge和MyDatabaseStorageLarge中的大小必须按你自己的限制设置。 - 维护模式期间,服务器不提供指标并返回
503,因此MyTargetDown和 HTTP 告警会触发。请在开始之前,在 Alertmanager 中为这段时间静默告警(维护)。
更改规则后,用 Prometheus 自带的 promtool 检查文件并运行其单元测试(alerts.test.yml):
cd deploy/monitoring/prometheuspromtool check rules alerts.ymlpromtool test rules alerts.test.ymlGrafana 仪表盘
Section titled “Grafana 仪表盘”deploy/monitoring/grafana/my.json 是基于同一组 Prometheus 指标的 Grafana 仪表盘:请求速率、状态码和延迟;任务运行次数、各任务类型的 worker 耗时和队列;投递、收件箱活动和远程服务器;以及每个进程的 CPU 和内存。在 Grafana 中导入它(Dashboards → New → Import),并选择你的 Prometheus 数据源;它的 Job 变量用于选择抓取任务(默认是 my)。
Google Cloud(Cloud Run)
Section titled “Google Cloud(Cloud Run)”在 metrics_exporter = none 时,请用 Cloud Run 和 Cloud Logging 已有的数据来构建告警:
- HTTP 错误和延迟:Cloud Run 按响应码类别统计的请求数,以及该服务的请求延迟指标。
- 错误:
error report日志行会进入 Error Reporting,它会对错误分组,并可在出现新错误和重复错误时通知你(错误报告)。 - 任务和请求:服务器为每个 HTTP 请求(
msg=http request)和每次任务运行(msg=job)写一行日志,标签与指标相同。可以据此创建基于日志的指标,例如用jsonPayload.msg="job" AND jsonPayload."my.outcome"="dead"对失败的任务计数,或者对按jsonPayload."my.surface"="client_api"过滤的jsonPayload.duration_seconds做分布统计来得到延迟。 - 队列积压和存储:任务
metrics.snapshot每 15 分钟写一行日志(msg=metrics snapshot),其中是整个实例范围的值,例如my.queue.oldest_ready_age、my.queue.dead、my.db.size和my.media.stored_bytes。请根据它的字段创建基于日志的指标;这些日志行出现间隔,说明定时触发或队列已停止。Cloud Tasks 的队列深度指标统计的是等待投递的信号。 - 数据库:Cloud SQL 的磁盘使用率和连接数指标,或你的数据库提供商的用量告警。
- 成本:带有告警阈值的 Cloud Billing 预算(成本和预算)。
mycroblog-gcp 的 monitoring 部分会以下表中的名称把它们创建为策略,其背后模块的 README 列出了它以不同方式覆盖或无法表达的每一项告警。它从未被应用过。只有流量才会产生的指标,在缩容到零的服务上会有空缺,因此针对其缺失的告警会误报;能发现空闲状态下服务器已挂掉的,是它的可用性检查。
AWS ECS
Section titled “AWS ECS”使用 metrics_exporter = emf 时,CloudWatch Logs 会把服务器的日志行转换为命名空间 metrics_emf_namespace 中的指标,使用带点号的名称(my.job.duration、my.queue.oldest_ready_age)。请求和任务耗时指标来自请求和任务的日志行,维度是你在 metrics_emf_dimensions 中列出的标签;要对失败的任务告警,请包含 my.outcome,要对 5xx 告警,请包含 http.response.status_code。实例级仪表(队列、媒体、数据库大小、远程服务器、账单导入、快照)由周期性的快照任务写入。Go 运行时指标(go.*)不会以 EMF 写入;请改用 ECS 服务的 CPU 和内存指标。
- HTTP 错误:Application Load Balancer 的 5xx 和请求数指标。
- 队列积压:由快照任务写入的
my.queue.oldest_ready_age。 - 数据库:RDS 或 Aurora 的存储和连接指标,或你的数据库服务商的用量告警。
- 邮件(
mail = ses):CloudWatch 中的 SES 信誉指标(退信率和投诉率)。 - 费用:带有告警的 AWS Budgets 预算(费用和预算)。
mycroblog-aws 的 monitoring 部分会以下表中的名称把这些创建为告警,其背后模块的 README 的列表相同。它从未被应用过。
严重程度:page = 立即处理,ticket = 在工作时间处理。规则列中的“–”表示目前还没有对应的指标;请按说明进行检查。
| 领域 | 告警 | 信号 | 阈值 | 严重程度 | 可能的原因 |
|---|---|---|---|---|---|
| 队列 | MyQueueBacklog |
my_queue_oldest_ready_age_seconds |
超过 5 分钟,持续 10 分钟 | ticket | worker 不足以应对突发流量(热门帖子、中继)、任务缓慢、worker 已停止 |
| 队列 | MyQueueStalled |
my_queue_oldest_ready_age_seconds |
超过 30 分钟,持续 5 分钟 | page | 没有 worker 在运行(崩溃、未部署、只有 role = web)、没有 worker 运行某种任务类型、worker 卡在数据库上 |
| 队列 | MyDeadJobsIncreasing |
delta(my_queue_dead[1h]) |
每小时超过 10 个,持续 15 分钟 | ticket | 任务中的缺陷、适配器配置错误(邮件、blob、账单)、远程服务拒绝请求 |
| 队列 | MyMetricsSnapshotStale |
my_metrics_snapshot_age_seconds |
队列部分超过 5 分钟、总量部分超过 1 小时,持续 15 分钟 | ticket | 无法访问 KV 存储、快照的数据库查询失败或超时 |
| 联邦 | MyDeliveryFailuresHigh |
my_outcome 为 retry 或 failed 的 my_delivery_attempts_total |
超过尝试次数的 50%,持续 30 分钟 | ticket | 许多关注者所在的服务器宕机、某个大型服务器宕机、出站网络故障 |
| 联邦 | MyDeliveryAllFailing |
同上 | 超过尝试次数的 95%,持续 15 分钟 | page | 出站网络或 DNS 故障、出口流量被阻止、服务器的密钥或 host 错误 |
| 联邦 | MyRemoteServersPaused |
my_federation_instances{my_federation_instance_state="unavailable"} |
比一天前多 5 个 | ticket | 服务器已关停或屏蔽了本服务器、本方的网络问题持续了数天 |
| 联邦 | MyInboxRejectionsHigh |
my_inbox_activities_total{my_outcome="rejected"} |
超过 POST 的 25%,持续 30 分钟 | ticket | 签名验证失败(时钟偏差、密钥获取失败)、垃圾信息发送者或已停用的域名在重试、速率限制 |
| 联邦 | MyInboxSignatureFailures |
my_inbox_activities_total{my_inbox_rejection="signature"} |
超过 POST 的 10%,持续 30 分钟 | ticket | 服务器的时钟不准、获取发送方的密钥失败、某个服务器更换了密钥 |
| 联邦 | MyInboxErrors |
my_inbox_activities_total{my_outcome="error"} |
超过 POST 的 5%,持续 15 分钟 | ticket | 数据库故障、收件箱中的缺陷 |
| 错误 | MyErrorReportsIncreasing |
my_errors_reported_total |
15 分钟内超过 10 个且为前一天平均值的 3 倍,持续 15 分钟 | ticket | 新版本引入的缺陷、依赖以新的方式失败、配置损坏 |
| HTTP | MyHTTPErrorsHigh |
http_server_request_duration_seconds_count 中的 5xx |
超过 5%,持续 10 分钟 | page | 数据库或 KV 宕机、有问题的版本、维护模式 |
| HTTP | MyHTTPErrorsElevated |
同上 | 超过 1%,持续 30 分钟 | ticket | 某个路由失败、某个适配器时不时失败 |
| HTTP | MyAPILatencyHigh |
客户端 API 的 p95(不含流式传输) | 超过 300 ms,持续 30 分钟 | ticket | 数据库饱和或距离太远、慢查询、CPU 不足、冷启动 |
| 资源 | MyTargetDown |
up{job="my"} |
为 0,持续 5 分钟 | page | 进程宕机、反复崩溃重启或处于维护模式;抓取路径有问题 |
| 资源 | MyNotReady |
my_readiness_failures_total |
有任何增长,持续 5 分钟 | page | 无法访问数据库,或尚未应用 schema |
| 资源 | MyProcessRestarting |
resets(process_uptime_seconds[1h]) |
一小时内重启 3 次 | ticket | 因内存不足被终止(OOM)、panic、存活探针失败 |
| 资源 | MyMemoryNearLimit |
go_memory_used_bytes / go_memory_limit_bytes |
超过 90%,持续 15 分钟 | ticket | GOMEMLIMIT 对当前负载而言太低、打开的流过多、内存泄漏 |
| 资源 | MyDBPoolSaturated |
db_client_connection_count{db_client_connection_state="used"} / db_client_connection_max |
超过 90%,持续 15 分钟 | ticket | 连接池对流量而言太小、慢查询占用连接 |
| 资源 | MyDBPoolWaiting |
db_client_connection_wait_time_seconds_total、db_client_connection_timeouts_total |
每秒等待超过 0.5 秒,或出现任何超时,持续 10 分钟 | ticket | 同上;达到了数据库自身的连接数上限 |
| 资源 | MyDatabaseStorageLarge |
my_db_size_bytes |
超过你的套餐上限减去余量(示例为 8 GiB),持续 1 小时 | ticket | 帖子和缓存的远程内容增长;需要升级套餐或缩短保留期限 |
| 资源 | MyFileDescriptorsNearLimit |
process_unix_file_descriptor_count / my_process_file_descriptor_limit |
超过 80%,持续 15 分钟 | ticket | 打开的流和连接过多、ulimit -n 过低 |
| 资源 | MyAdapterErrors |
my_adapter_operation_duration_seconds_count{my_outcome="error"} |
超过某个适配器操作的 5%,持续 15 分钟 | ticket | Valkey、blob 目录或流后端出现故障 |
| 资源 | MyRemoteMediaCacheOverLimit |
my_media_stored_bytes{my_media_origin="remote_cache"} |
超过 remote_media_cache_max_bytes 的 1.2 倍,持续 3 小时 |
ticket | 每小时的清理没有运行或运行失败 |
| 资源 | MyMediaStorageLarge |
my_media_stored_bytes |
超过你规划的大小(示例为 50 GiB),持续 1 小时 | ticket | 上传量增长;需要升级套餐或提高预算 |
| 邮件 | MyEmailFailing |
邮件任务中 my_outcome="dead" 的 my_job_duration_seconds_count |
一小时内出现任何一个 | ticket | SMTP 或 SES 设置错误、账号被停用或超出配额、地址被永久拒绝 |
| 邮件 | MyEmailRetrying |
同上,my_outcome="retry" |
超过运行次数的 50%,持续 15 分钟 | ticket | 无法访问邮件服务器或其拒绝登录、发送速率限制 |
| TLS | MyTLSCertificateExpiring |
my_tls_certificate_expiry_seconds |
任一进程中低于 7 天,持续 15 分钟 | page | 续期已失败数周、进程没有加载已续期的证书、没有任何东西为证书文件续期 |
| TLS | MyTLSOrdersFailing |
my_tls_order_consecutive_failures |
3 次或更多,持续 5 分钟 | ticket | DNS 不再指向服务器、80 和 443 端口被阻止、证书颁发机构的速率限制或故障 |
| 费用 | MyBillingImportFailing |
my_billing_import_failing |
为 1,持续 6 小时 | ticket | 缺少权限、未设置账单导出、达到请求上限、服务商不可用 |
| 费用 | 超出预算 | – | – | – | 流量、存储或配置错误导致费用超出计划(见下文) |
下面的运维手册条目中,大多会再次用到这些工具。
- 任务页面(管理 → 任务,
/admin/jobs,需要manage_jobs):按状态(排队中、运行中、重试中、失败)和类型统计的数量,以及等待最久的任务;它的 任务 页面(/admin/jobs/list)列出某一状态的任务,每个任务的页面有它最近的错误和未成功的尝试。待处理的任务只会列出保存在数据库中的队列的(queue = db和cloudtasks);失败的任务和尝试则会列出所有队列的。 my job命令,在具有服务器配置的主机上运行(queue = db和cloudtasks):my job list按最新在前列出失败的任务;my job retry <id>...把它们放回队列;my job delete <id>...丢弃它们。任务可以安全地重新运行。- 远程服务器页面(审核 → 远程服务器,
/moderation/instances,需要manage_domains):投递未能到达的服务器,以及投递已暂停的服务器,并附有原因和时间。“恢复投递”会把服务器重新标为可用。“打开服务器”会按域名打开任意服务器的页面,无论它是否在列表中。 - 日志:标准错误上的 JSON 行。每个 HTTP 请求以一行
msg为http request的日志结束,每次任务运行以一行msg为job的日志结束(成功为INFO,重试为WARN,彻底失败的任务为ERROR,并带有error、job_id和my.job.type)。请求内部的日志行带有它的request_id,客户端看到的是X-Request-Id。federation.deliver一次运行的日志行还会说明投递去了哪里以及结果如何:my.delivery.domain(远程服务器的域名)、activity.type(例如Create)、my.delivery.outcome(succeeded、retryable_failure、permanent_failure或skipped),以及http.response.status_code(收件箱的响应,在它没有响应或没有发送任何内容时不存在)。my.outcome仍是这次任务运行的结果。该日志行从不写出发送者、活动或收件箱 URL。Cloud Logging:jsonPayload.msg="job" AND jsonPayload."my.job.type"="federation.deliver" AND jsonPayload."my.delivery.domain"="remote.example"- Docker Compose:
docker compose logs my | jq -c 'select(.msg == "job" and ."my.outcome" == "dead")' - Cloud Logging:
jsonPayload.msg="job" AND jsonPayload."my.outcome"="dead" - CloudWatch Logs Insights:
filter msg = "job" and `my.outcome` = "dead"
- 错误报告:
error report日志行和 错误页面(管理 → 错误,/admin/errors,需要manage_errors)(错误报告)。 - 追踪,在
traces_exporter = otlp时:日志行带有trace_id;在你的追踪后端中打开它,可以看到慢请求的时间花在了哪里。 - 维护模式(维护):以维护页面应答每个请求,并且不触碰任何适配器。在你修复数据库或 KV 存储时使用它。
MyQueueBacklog
Section titled “MyQueueBacklog”任务(投递、通知、邮件、时间线分发)等待 worker 的时间超过 5 分钟。
检查:
- 任务页面:哪些类型在排队,是否有很多在重试。某一类型的突发(发布一条拥有大量关注者的帖子后的
federation.deliver、中继活动)会自行消化;确认等待时间在下降。 - worker 进程(
role = all或role = worker)正在运行,并且其日志中有job行。 - 是否同时出现
MyDBPoolSaturated或MyAPILatencyHigh:worker 在等待数据库。
处理:
- 运行更多 worker 进程(
role = worker),或为现有进程分配更多 CPU。 - 如果某种任务类型很慢,在
job日志行(duration_seconds)中找到它,并查找该类型的错误。
MyQueueStalled
Section titled “MyQueueStalled”最早就绪的任务已等待超过 30 分钟:没有任何任务在处理,或几乎没有。
检查:
- 至少有一个进程以
role = all或role = worker运行,并且没有反复崩溃重启(MyProcessRestarting)。 - worker 日志中是否有每个任务都重复出现的错误(数据库、KV、panic)。
MyNotReady:无法访问数据库的 worker 无法领取任务。max by (my_job_type) (my_queue_oldest_ready_age_seconds):如果某一类型在等待而其他类型没有,请确认有 worker 运行该类型(按任务类型拆分 worker)。
处理:
- 启动或重启 worker。已停止的 worker 持有的任务会在租约到期后回到队列;它们可以安全地重新运行。
- 如果原因是数据库,请按照 MyNotReady 处理。
MyDeadJobsIncreasing
Section titled “MyDeadJobsIncreasing”每小时有超过 10 个任务永久失败:它们用完了重试次数,或者任务拒绝再次运行。
检查:
- 任务页面,按“失败”筛选:类型和最后一次错误。任务的尝试记录显示了过程中的每个错误。
my.outcome=dead的job日志行中的相同错误。
处理:
- 配置错误(邮件、blob、账单导入、Webhook 目标):修正后,在任务页面上重新运行任务(“再次运行”),或使用
my job retry <id>...。 - 发往已消失的服务器的投递在重试约 4 天后会永久失败;这是预期行为,无需处理。
- 无人重试的失败任务会在
dead_job_retention(默认 30 天)后删除。用my job delete删除你不打算重试的任务。 - 看起来像缺陷的错误:附上任务类型和错误进行报告(其中不含个人数据)。
MyMetricsSnapshotStale
Section titled “MyMetricsSnapshotStale”队列和存储仪表来自进程间通过 KV 存储共享的一个快照。该快照已经过时,因此队列和存储告警看到的是旧值,可能不会触发。
检查:
- 日志中有关指标快照或 KV 存储的错误。
kv.valkey或kv.db的MyAdapterErrors,以及数据库的健康状况。
处理:
- 修复 KV 存储或数据库连接。快照会在下一次采集时重新计算;周期性快照任务也会每 15 分钟运行一次。
MyDeliveryFailuresHigh
Section titled “MyDeliveryFailuresHigh”发往其他服务器的投递尝试有一半以上失败。一定程度的失败是正常的:服务器会消失,而本服务器会持续重试约 4 天。
检查:
- 远程服务器页面:失败是集中在少数几个服务器上(它们宕机了;无需处理),还是分散在许多服务器上(怀疑是本服务器的问题)。
- 按
error_type统计的http_client_request_duration_seconds_count:超时、DNS 错误,或forbidden_destination(SSRF 防护拒绝了该目标)。
处理:
- 失败集中在少数几个服务器上:无需处理。在 7 个不同的日子失败后,发往该服务器的投递会被暂停,并每天探测一次该服务器以便恢复投递。
- 处处失败:请按照 MyDeliveryAllFailing 处理。
MyDeliveryAllFailing
Section titled “MyDeliveryAllFailing”几乎所有投递都失败。这几乎总是本服务器这边的问题。
检查:
- 从服务器的主机或容器中确认出站 HTTPS 是否正常(DNS、出口防火墙、NAT、代理)。
federation.deliver的job日志行中的错误:TLS 错误、超时,或来自许多服务器的401(它们无法验证本服务器的签名)。- 更改域名或密钥之后:服务器一旦开始联邦,
host就必须保持不变,KEK 也必须是封装这些密钥时使用的那个(KEK 管理)。
处理:
- 修复出站网络。失败的尝试会以退避方式重试(1 分钟、5 分钟、30 分钟、2 小时,依此类推),因此投递会自行补上。
- 如果投递已用完重试次数,请在任务页面上重新运行失败的
federation.deliver任务。 - 如果远程服务器在故障期间被暂停,它们会在下一次成功投递、收到签名请求或每日探测时恢复;你也可以在远程服务器页面上点击“恢复投递”。
MyRemoteServersPaused
Section titled “MyRemoteServersPaused”过去一天内,有 5 个或更多服务器的投递被暂停。在 7 个不同的日子投递失败后,服务器会被暂停,因此每周有少量暂停是正常的:服务器会关停。一次性出现很多则意味着许多服务器同时失败了数天。my_federation_instance_state = available 的 my_federation_instances 统计的是仍在投递但曾在某天失败的服务器;该值的跳升会先于暂停出现。
该指标没有按服务器区分的标签(标签从不携带远程域名)。检查:
- 远程服务器页面:“已暂停”标签页列出了被暂停的服务器,以及暂停的时间和原因。看看它们是否有共同点(同一托管服务商、同一软件),还是分散各处。
- 过去一周的
MyDeliveryFailuresHigh和MyDeliveryAllFailing:本方持续数天的网络问题会导致许多服务器被暂停。
处理:
- 已消失的服务器:无需处理。被暂停的服务器每天都会被探测,一旦响应就会自行恢复。
- 本方出现问题之后:修复问题,然后为你关心的服务器点击“恢复投递”,或等待每日探测。
- 对方运营者表示屏蔽了本服务器:本方无能为力。要有意停止与某个服务器的联邦,请使用域名措施(审核 → 域名措施)。
MyInboxRejectionsHigh
Section titled “MyInboxRejectionsHigh”其他服务器 POST 到收件箱的活动中,有超过四分之一被拒绝。
检查:
- 按
my_inbox_rejection统计的my_inbox_activities_total{my_outcome="rejected"}:signature(按照 MyInboxSignatureFailures 处理)、suspended(已停用的域名在不断重试)、federation_off(联邦已关闭)、rate_limited(某个客户端 IP 或服务器超出速率限制),或invalid(活动缺少有效的id、type、actor或object)。 - 收件箱路由(
my.surface=activitypub)的http request日志行按http.response.status_code(401、403、429、400)给出了相同的划分,并带有客户端地址,可用于了解请求来自哪里。
处理:
- 来自已停用域名的拒绝,或联邦关闭时的拒绝,无需处理:这是有意为之的拒绝。
- 来自某个服务器的被限速请求:垃圾信息发送者或突发流量;如果持续,请停用该域名。
- 来自某个服务器的无效活动:该服务器的软件发送了本服务器无法读取的内容;请附上该服务器的软件及版本进行报告。
MyInboxSignatureFailures
Section titled “MyInboxSignatureFailures”其他服务器 POST 到收件箱的活动中,有超过 10% 因签名或完整性证明缺失或无法验证,或者因无法获取发送方的密钥而被拒绝。
检查:
- 服务器的时钟:超出时间窗口的签名会被拒绝。请检查主机或容器运行时的 NTP。
- 获取发送方的密钥:
MyDeliveryAllFailing,以及按error_type统计的http_client_request_duration_seconds_count{my_http_purpose="json"}(出站网络、DNS、SSRF 防护)。 - 拒绝来自许多服务器还是一个服务器(状态为
401的http request行):更换了密钥的服务器,或者以本服务器不接受的方式签名的服务器,只影响它自己。
处理:
- 修复时钟或出站网络。其他服务器会重试它们的投递,因此只要在一天左右修复,就不会丢失任何内容。
- 某个服务器失败:向该服务器的运营者报告,或附上该服务器的软件及版本向本项目报告。
MyInboxErrors
Section titled “MyInboxErrors”收件箱对超过 5% 的活动返回 500。发送方会重试,但活动会延迟。
检查收件箱路由的 http request 和错误日志行中的错误,以及数据库的健康状况(MyNotReady、MyDBPoolWaiting)。
处理:修复数据库,或把错误作为缺陷报告。无需重放任何内容:发送方会重试。
MyErrorReportsIncreasing
Section titled “MyErrorReportsIncreasing”服务器报告错误(panic、5xx 背后的错误、失败的任务)的速率超过平时的三倍。
检查:
- 过去一小时的
error report行,按my.error.fingerprint分组:最常见的错误、它们的my.error.where,以及message的首行。在 Cloud Run 上,Google Cloud Error Reporting 会显示相同的分组。 - 是否在同一时间发布了新版本、更改了配置,或某个依赖开始失败(
MyNotReady、MyAdapterErrors)。 - 具有相同
request_id或job_id的请求或任务日志行。
处理:
- 依赖失败或配置错误:修复它;之后可以在任务页面上重新运行失败的任务。
- 有问题的版本:回滚到上一个镜像。
- 缺陷:附上该行的首行和堆栈进行报告。两者都已清除个人数据。
MyHTTPErrorsHigh
Section titled “MyHTTPErrorsHigh”所有请求中有超过 5% 返回 5xx。用户会看到错误。
检查:
- 是否处于维护模式(预期会返回
503;下次请静默该告警)。 MyNotReady(数据库)、MyAdapterErrors(KV、blob、流),以及最近是否发布了新版本。- 按
http.route统计的http.response.status_code≥ 500 的http request行,以及具有相同request_id的错误行。
处理:
- 修复出故障的依赖。如果需要处理数据库,请切换到维护模式,让用户看到明确的页面而不是错误。
- 有问题的版本:回滚到上一个镜像。
- 如果持续时间较长,请告知用户(向用户通报故障)。
MyHTTPErrorsElevated
Section titled “MyHTTPErrorsElevated”在半小时内,有超过 1% 的请求返回 5xx。通常是某一个路由或某一个适配器的问题。
检查按 http.route 统计的返回 5xx 的 http request 行,以及这些请求的错误行。处理:修复依赖,或把错误作为缺陷报告。
MyAPILatencyHigh
Section titled “MyAPILatencyHigh”客户端 API 的第 95 百分位超过 300 ms(这是缓存预热后包含 20 条帖子的主页时间线页面的目标值)。不含流式传输端点。
检查:
- 按
http_route统计的http_server_request_duration_seconds:是某一个路由慢,还是所有路由都慢。 - 数据库:
MyDBPoolWaiting、数据库的 CPU 和慢查询日志、服务器与数据库之间的网络距离。 - 进程:CPU 限流、
MyMemoryNearLimit(内存压力下的 GC)、go_schedule_duration_seconds(等待 CPU 的 goroutine)。 - 如果已启用,查看慢请求的追踪。
处理:
- 为数据库或服务器分配更多资源,或让它们离得更近。
- 在流量很少的服务器上,缩容到零后的冷启动会拉高百分位;这是预期行为。
MyTargetDown
Section titled “MyTargetDown”Prometheus 无法抓取某个进程。
检查:
- 进程是否在运行:
docker compose ps、kubectl get pods,或平台的控制台。它的最后几行日志会说明停止的原因。 - 是否处于维护模式(不提供指标;属于预期)。
- 是否设置了
metrics_exporter = prometheus,以及 Prometheus 能否访问metrics_listen。
处理:
- 重新启动进程。如果无法启动,日志会说明原因:配置错误(
my config check会显示)、无法访问数据库、未应用 schema。
MyNotReady
Section titled “MyNotReady”就绪检查失败:无法访问数据库,或其表与此版本不匹配。负载均衡器会停止向该进程发送流量,外部健康检查端点会报告 unavailable。
检查:
- 就绪检查的日志行:连接错误(网络、凭据、数据库宕机或连接数耗尽),或缺失的表。
- 数据库服务商的状态页面和控制台:数据库是否在运行、存储是否已满、是否在维护中?
- 升级之后:是否在新版本启动之前应用了 schema(初始化数据库)?
处理:
- 数据库宕机或无法访问:恢复它,或进行故障转移。在你处理期间,维护模式会向用户显示明确的页面。
- 数据库存储已满:升级套餐或释放空间(MyDatabaseStorageLarge)。
- 未应用 schema:运行同一版本的
my schema apply,之后进程会自行变为就绪。 - 数据丢失或损坏:从备份恢复,并保留封装备份中密钥时使用的 KEK(KEK 管理)。
MyProcessRestarting
Section titled “MyProcessRestarting”某个进程在一小时内重启了 3 次。
检查:
- 平台给出的重启原因:
OOMKilled(内存)、存活探针失败,或退出码。 - 每次重启前的最后几行日志,查看是否有 panic 或致命的配置错误。
处理:
- 内存不足:把
GOMEMLIMIT设为容器内存上限的 90% 左右,或为容器分配更多内存(MyMemoryNearLimit)。 - panic:附上其前后的日志行进行报告。
- 日志显示数据库属于另一个
host或account_domain:在配置中设置已记录的值,或让database_url指向正确的数据库。这些值无法更改(之后无法更改的设置)。
MyMemoryNearLimit
Section titled “MyMemoryNearLimit”Go 运行时使用了超过 90% 的 GOMEMLIMIT。接近上限时,垃圾回收器的运行频率会大幅增加,消耗 CPU 并增加延迟;超过上限后,平台可能会终止进程。此告警需要设置 GOMEMLIMIT;未设置时,请改为关注容器的内存指标。
检查 http_server_active_requests 和打开的流(my_stream_connections),以及在负载平稳时内存是否持续增长(内存泄漏)。
处理:提高容器的内存,并相应提高 GOMEMLIMIT,或运行更多进程。如果内存稳定增长且与负载无关,请报告。
MyDBPoolSaturated
Section titled “MyDBPoolSaturated”某个进程的数据库连接有超过 90% 正在使用。请求很快就会开始等待连接(MyDBPoolWaiting)。
检查是流量增长了,还是查询变慢了(数据库的慢查询日志、my_adapter_operation_duration_seconds)。
处理:
- 在
database_url中提高连接池大小(PostgreSQL 为pool_max_conns),并让所有进程的总数保持在数据库的连接数上限以下。 - 如果许多进程共享数据库,请在数据库前面放置连接池代理。
MyDBPoolWaiting
Section titled “MyDBPoolWaiting”工作在等待空闲的数据库连接,或在 database_acquire_timeout 之后放弃等待(超时仅适用于 PostgreSQL):请求返回 503,任务稍后再次运行。请按照 MyDBPoolSaturated 处理;同时检查数据库本身是否已达到其连接数上限。
MyDatabaseStorageLarge
Section titled “MyDatabaseStorageLarge”数据库占用的空间超出了你的规划。my_db_size_bytes 是 PostgreSQL 数据库的大小(pg_database_size,即服务商的存储上限所统计的大小),或 SQLite 文件的大小(不含其预写日志)。这是增长,而不是故障。请在规则中把阈值设为比你的数据库套餐存储上限低一定余量的值;对于 SQLite,则是比存放 SQLite 文件的卷的上限低一定余量的值,该卷还必须为预写日志和备份留出空间。
处理:
- 升级套餐或扩大卷。
- 远程帖子会在实例设置
remote_status_retention_days之后被删除;调低该值可以减缓增长。 - 删除的行会释放空间,两种数据库都会重复利用这些空间,但大小很少会下降:PostgreSQL 会保留其表的空间,SQLite 会把空闲页保留在文件中,直到执行
VACUUM(在服务器停止时用sqlite3运行)。
MyFileDescriptorsNearLimit
Section titled “MyFileDescriptorsNearLimit”进程打开的文件描述符超过其上限的 80%。超过上限后,新连接会失败。
处理:提高上限(ulimit -n、容器运行时的 nofile),或运行更多进程。查看 my_stream_connections 和 http_client_open_connections,了解是什么占用了它们。
MyAdapterErrors
Section titled “MyAdapterErrors”某个适配器的操作有超过 5% 失败:kv.valkey(Valkey)、kv.db(KV 表)、blob.fs(媒体目录)、queue.db(队列表),或某个 stream.<backend>(进程间的通知)。
检查该适配器的错误行,以及其背后的服务:Valkey 是否在运行且可以访问,媒体卷是否已挂载、可写且未满。
处理:修复该服务。失败的任务操作会被重试;失败的流通知只会延迟实时更新。
MyRemoteMediaCacheOverLimit
Section titled “MyRemoteMediaCacheOverLimit”远程媒体的副本持续超过 remote_media_cache_max_bytes。每小时的清理通常会删除过期的和最近最少使用的副本。请在规则中把阈值设为你的 remote_media_cache_max_bytes 值。
检查任务页面和日志中清理任务的失败,以及 blob 存储的 MyAdapterErrors。
处理:修复失败的原因,或调低缓存大小,或调整实例的远程媒体策略。
MyMediaStorageLarge
Section titled “MyMediaStorageLarge”媒体文件占用的空间超出了你的规划。这是增长,而不是故障。请在规则中把阈值设为你的存储套餐或预算所允许的值。
处理:升级套餐或提高预算,或调低上传限制(media_max_image_bytes、media_max_av_bytes)。
MyEmailFailing
Section titled “MyEmailFailing”过去一小时内有邮件任务永久失败:验证、密码重置、密码通知、通知或关停邮件。正在等待验证邮件或重置邮件的用户无法完成操作。
检查任务页面(按邮件任务类型筛选,它们以 _email 结尾)以及最后一次错误。发送邮件列出了这些错误及其含义。
处理:
- SMTP 主机、端口或凭据错误,或者 SES 账号或权限有问题:修正后重新运行失败的任务。超过链接有效期的验证邮件和重置邮件在重试时会不发送而直接完成,因此请让这些用户重新申请。
- 被永久拒绝的地址会被抑制;无需处理。
MyEmailRetrying
Section titled “MyEmailRetrying”大多数邮件发送失败并等待重试:无法访问邮件服务器、邮件服务器拒绝登录,或限制了发送速率。事务性邮件会重试约 15 分钟,通知会重试约 4 小时,之后便永久失败。请在此之前按照 MyEmailFailing 处理。
服务器不会就费用发出告警。请在服务商处设置带有告警的预算,因为服务商最先看到费用:
- AWS:AWS Budgets 费用预算,例如在月度金额的 80% 和 100% 时告警,并按本服务器的成本分配标签筛选。
- Google Cloud:项目的 Cloud Billing 预算,告警阈值设为 50%、90% 和 100%。同一预算的通知可以用于费用导入(导入云使用费用)。
导入的费用和本月至今的估算值显示在“管理 → 费用 → 账单导入”中。失败的导入会记录在那里,并由下一次每日导入重试;MyBillingImportFailing 会在当月数据过时之前通知你。
MyBillingImportFailing
Section titled “MyBillingImportFailing”某个账单来源的使用费用最近一次导入失败,并且 6 小时内没有后续导入成功。导入每天运行一次;限流和不可用会在数小时内重试,其他失败则等待第二天的导入,因此在此之前费用页面显示的是较旧的数据。
检查:
- “管理 → 费用和收入 → 账单导入”:该来源的最后一次导入及其错误。
- 按
error_type统计的my_billing_imports_total{my_outcome="failed"},或msg为billing import failed的WARN日志行,其中带有source和error_kind。导入云使用费用列出了各种类型及其修复方法。
处理:
- 修复原因(权限、账单导出、请求上限),然后在“管理 → 费用和收入 → 账单导入”中点击“立即导入”,而不必等到第二天。
如果没有 Prometheus(Cloud Run 上使用 metrics_exporter = none),请改为针对 billing import failed 行创建基于日志的告警。
MyTLSCertificateExpiring
Section titled “MyTLSCertificateExpiring”某个进程提供的证书将在 7 天内过期。在 tls = acme 时,服务器会在证书还剩约三分之一有效期时(即过期前数周)为它续期,所以这意味着续期已经失败了很长时间,或者进程没有加载已续期的证书。在 tls = files 时,则意味着没有任何东西为这些文件续期。
检查:
instance标签:如果其他进程为同一主机提供了更新的证书,就只有这个进程还留着旧证书。my tls status:该主机的当前证书、它何时续期,以及最近的订单及其错误。- 带有原因的日志行
the TLS certificate could not be obtained。
处理:
- 修复订单失败的原因(见 MyTLSOrdersFailing),然后运行
my tls renew -host <host>立即下单,而不必等到下一次下单。 - 如果某个进程留着旧证书,而数据库里已有更新的证书,它会在 5 分钟内加载;如果没有,请重启它。
- 在
tls = files时,请用写入这些文件的工具(certbot)为它们续期;服务器会在一分钟内加载。
MyTLSOrdersFailing
Section titled “MyTLSOrdersFailing”某个主机证书的最近 3 次或更多订单都没有拿到证书。第三次失败之后,服务器会在订单之间先等待 100 分钟,再等待一天,以便保持在证书颁发机构的限制之内。当前的证书在此期间继续使用。
检查:
my tls status:失败次数以及每个订单的错误。出现rejectedIdentifier、dns、connection或unauthorized错误,表示证书颁发机构无法通过该名称访问到服务器;rateLimited表示达到了它的限制。- 该
host解析到了服务器,并且 443 和 80 端口可以从互联网访问。
处理:
- 修复原因,然后运行
my tls renew -host <host>:它会立即下单,无需等待。
向用户通报故障
Section titled “向用户通报故障”- 确认告警,让其他值班人员知道已经有人在处理。
- 一旦用户受到影响,就在状态页面上发布(
status_page_url,参见从外部监控服务器):什么出了问题、从什么时候开始,以及你下一次更新的时间。即使本服务器无法访问,状态页面仍然可以访问,Web 客户端也会链接到它。 - 如果用户仍能访问服务器(性能下降而非宕机),请发布公告:在“管理 → 公告”中撰写文字并发布。公告会显示在所有人的主页时间线上方。如果服务器必须停止,请改用带有
maintenance_message的维护模式。 - 即使没有任何变化,也要在你承诺的时间更新两者。
- 结束:在状态页面上把故障标记为已解决,撤回公告(或发布一条简短的后续说明),并趁记忆犹新记下发生了什么以及你做了哪些更改。
供 LLM 和编程智能体使用:llms.txt,llms-full.txt, llms-small.txt