Monitoring & alerts

/healthzCopy Anchor Link

GET /healthz returns 200 with the plain-text body ok and needs no authentication. It only means the process is running and its HTTP server responds; it does not check the database, channels or the job queue. Use it for liveness checks and external uptime probes; for channel health, use metrics and alerts.

Requests to /healthz and /metrics themselves are not counted in the HTTP metrics.

/metricsCopy Anchor Link

GET /metrics serves metrics in the Prometheus text format on the same port as everything else.

Access control: only clients whose address is inside IMGYOUNG_METRICS_ALLOW (loopback and private ranges when the variable is unset) are allowed; everyone else gets 403. Setting the variable to an empty string (or only whitespace) closes /metrics to everyone. The client address is resolved by the rules in Reverse proxy & HTTPS. Metrics expose route templates, channel names and usage and should not be public:

• the public entry point (the reverse proxy) must never forward /metrics; the Caddy and Nginx examples in deploy/ answer it with 404;
• let Prometheus reach ImgYoung's listen address directly over the internal network;
• get IMGYOUNG_TRUSTED_PROXIES right. If it is wrong, every proxied request appears to come from the proxy, and if the proxy's address is in the allowed networks, a proxy that forwards /metrics exposes the metrics to everyone.

MetricsCopy Anchor Link

All application metrics are prefixed with imgyoung_:

The Prometheus Go client's own go_* (runtime) and process_* (process) metrics are exported as well.

Prometheus scrape configurationCopy Anchor Link

scrape_configs:
  - job_name: imgyoung
    static_configs:
      - targets: ["10.0.0.5:8721"]   # ImgYoung's internal address and port

If Prometheus is outside the default private ranges, add its address to IMGYOUNG_METRICS_ALLOW (together with any default ranges you still need — setting the variable replaces the default list).

A few useful alerting expressions:

# A channel is unhealthy
imgyoung_channels_healthy_total < imgyoung_channels_total

# Writes to a channel keep failing
sum by (channel) (rate(imgyoung_channel_puts_total{result="error"}[10m])) > 0

# Uploads failing because of infrastructure
sum(rate(imgyoung_upload_duration_seconds_count{outcome="failed"}[10m])) > 0

# Job queue backlog
imgyoung_queue_jobs_waiting > 1000

AlertsCopy Anchor Link

Alerts come from an evaluation loop that runs once at startup and then every Health check interval (health_check_seconds, 60 seconds by default). Each round checks which conditions currently hold and reconciles them with the open alerts: new conditions open an alert, conditions that no longer hold resolve theirs automatically. There is at most one open alert per kind and target; while a condition persists, its details are refreshed every round.

backup_failed reflects the most recent backup in the current process, so after a restart it does not reappear until a backup fails again.

Where to see them: the Alerts card on the Dashboard lists open alerts; History leads to Settings → Alert history, which pages through every alert including resolved ones. Opening and resolving are also logged (告警开启, 告警恢复).

WebhookCopy Anchor Link

With an http / https URL in Settings → Runtime settings → Alerts & audit → Alert webhook URL, every alert is POSTed as JSON (Content-Type: application/json) once when it opens and once when it resolves:

{
  "kind": "channel_unhealthy",
  "target": "r2-main",
  "message": "连接超时",
  "status": "open",
  "opened_at": "2026-10-15 08:30:00"
}

{
  "kind": "channel_unhealthy",
  "target": "r2-main",
  "message": "连接超时",
  "status": "resolved",
  "opened_at": "2026-10-15 08:30:00",
  "resolved_at": "2026-10-15 09:05:00"
}

Delivery rules:

• any 2xx response counts as delivered; connection errors, timeouts (10 seconds) and non-2xx responses are retried on the next evaluation round until they succeed;
• for any one alert, the opening is always delivered before the resolution;
• requests carry no signature or authentication header; if the receiver needs to verify the sender, put a secret in the URL (for example as a query parameter) and use https;
• a transition that happens while no webhook is configured is marked as delivered and is not sent later, even if a webhook is configured afterwards;
• the payload format is fixed; to post to a chat tool, put a small relay in between that converts the format.

LogsCopy Anchor Link

• Logs go to standard error in Go's log/slog text format: each line starts with time=, level= and msg=, followed by key=value fields; messages are in Chinese. The level is fixed at INFO and above; there is no setting to change it.
• To read them: journalctl -u imgyoung for systemd, docker logs imgyoung for Docker, docker compose logs imgyoung for Compose.
• Credentials stay out of the logs: channel configuration parameters never appear in logs or error messages, the Cloudflare API token exists in plaintext only in memory, and audit entries for configuration changes only record (已配置) (set) or (空) (empty). Upload tokens and sessions are stored as hashes only. The one password ever logged is the factory password seeded on first start (or after a password reset), which is public anyway.

Log lines worth knowing when troubleshooting: