Observability
See what changed, what is failing and how the platform is behaving, in the console and in your own monitoring.
Events#
The Events page turns the audit log into typed events in four categories: flags, releases, security and configuration. Filter by category, type, project, person and date. It has the same access as the audit log, and developers see only their own changes. There is no separate event store, so events and audit entries always agree.
Metrics#
Metrics shows evaluation volume, the share served on, the busiest flags, reasons and environments. Counts are written in memory and flushed every 10 seconds into hourly rows, kept for 30 days by default. Only counts are stored, never who was evaluated.
What is and is not counted
Errors#
Errors shows the API error rate and breaks failures down by type, flag, SDK and endpoint. Errors that SDKs report themselves are shown separately and kept out of the error rate. Latency is recorded in buckets from 5 ms to 5 s, so percentiles are upper-bound estimates.
Every response carries X-Request-Id; a valid id you send is kept, otherwise one is generated. The server writes structured JSON log lines with the same id. Set the detail with LOG_LEVEL (debug, info, warn, error or silent).
Alerts#
Alerts watch a project, and optionally one environment, and fire when a value reaches a threshold. A badge in the sidebar and a count on the Overview show what is firing.
| Kind | Unit | Description |
|---|---|---|
| error_rate | % | Failed API calls as a share of API requests. |
| latency_p95 | ms | The 95th percentile latency (an upper-bound estimate). |
| volume_drop | % | Evaluation volume fell compared with the previous period. |
| volume_spike | % | Evaluation volume rose compared with the previous period. |
| release_failures | count | Releases that failed in the window. |
- Windows are 1, 2, 3, 6, 12 or 24 hours. Volume rules compare the last complete hours with the ones before.
- A rule needs a minimum number of observations; below it the state is No data, not OK, so quiet periods do not raise false alarms.
- The evaluator runs every 60 seconds. Several server instances record a state change once.
- Editing or disabling a rule resets it. Each rule keeps its last 20 state changes. An organization can have 50 rules.
- Everyone can view alerts; release managers and administrators manage them.
Delivery: console, webhook and email
Email notifications#
Email is required to run the server: your operator sets a provider (RESEND_API_KEY with MAIL_FROM, or SMTP_HOST with SMTP_FROM; see Self-hosting), and the server shows a setup screen until one is set. If a send still fails (for example a rejected sender), the action succeeds and the invitation link is shown in the console. Sending never blocks or fails the action that caused it. The person who caused an event is not emailed about their own action, except where noted.
| Event | Recipients | Description |
|---|---|---|
| Invitation created or reissued | The invitee | The invitation link. The response of the call says whether it was sent (emailed, and emailError when sending failed). |
| Organization created | The new admin | A welcome message. |
| Invitation accepted | The new member, and whoever sent the invitation | A welcome to the new member and a note to the inviter. |
| Release needs approval | Everyone who can review (releases.review) except the proposer | A reviewer named on the request gets a separate message asking for their review. |
| Release approved or rejected | The proposer | Includes the reviewer's note. |
| Approval request expired | The proposer | Sent when nobody reviewed it within 72 hours. |
| Release step failed | The proposer and the reviewer | A scheduled or staged release stopped. |
| Alert fired or resolved | Everyone who can manage alerts (alerts.manage) | Also posted to ALERT_WEBHOOK_URL when it is set. |
| Kill switch activated or lifted | Everyone who can use the kill switch, except the person who did it | Lists the environments and how many flags were affected. |
| API key rotated or revoked | Everyone who can revoke keys (api_keys.revoke), except the person who did it | Names the key and who rotated or revoked it. |
| Role changed, or removed from the organization | The member affected | Names the previous and new role, or the removal, and who did it. |
| Password changed | The account holder | A security notice after they change their own password. |
| Password reset by an admin | The member | The new password is never emailed; the admin passes it on. |
| Ownership transferred | The new owner and the previous owner | Tells one they now own the organization and confirms the transfer to the other. |
| Organization deactivated or reactivated | Everyone who can edit the organization (organization.update) | Says who switched the organization off or back on. |
Health and Prometheus#
| Path | Description |
|---|---|
| /health | Overall status and uptime. Public. |
| /health/live | The process is running. Use for liveness probes. |
| /health/ready | The database answers. Use for readiness probes and load balancers. |
| /api/prometheus | Prometheus text format. Returns 404 unless METRICS_TOKEN is set, then needs Authorization: Bearer <token>. |
Health endpoints report only ok or down; the reason goes to the logs. Prometheus is served at /api/prometheus because the console uses /metrics.
scrape_configs:
- job_name: flagswift
metrics_path: /api/prometheus
authorization:
credentials: ${METRICS_TOKEN}
static_configs:
- targets: ["flags.example.com"]Series include flagswift_evaluations_total, flagswift_evaluation_errors_total, flagswift_api_requests_total, flagswift_api_request_duration_seconds, flagswift_flag_changes_total and flagswift_release_changes_total, plus gauges for cache hits and misses and uptime. Values are per process, so scrape every instance.