Skip to content
FlagSwiftDocs

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

A call to the server endpoint counts each evaluation. Flags that an SDK evaluates locally from the downloaded configuration are not counted, so a flag can look unused while a backend uses it. SDKs report their errors so those still show up.

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.

Alert kinds
KindUnitDescription
error_rate%Failed API calls as a share of API requests.
latency_p95msThe 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_failurescountReleases 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

When your operator sets ALERT_WEBHOOK_URL, a firing or resolved alert is posted there, and with an email provider configured it is emailed to the people who can manage alerts. There is no built-in paging or chat integration beyond that webhook, so for on-call paging scrape the Prometheus endpoint and alert from your own system.

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.

What is emailed, and to whom
EventRecipientsDescription
Invitation created or reissuedThe inviteeThe invitation link. The response of the call says whether it was sent (emailed, and emailError when sending failed).
Organization createdThe new adminA welcome message.
Invitation acceptedThe new member, and whoever sent the invitationA welcome to the new member and a note to the inviter.
Release needs approvalEveryone who can review (releases.review) except the proposerA reviewer named on the request gets a separate message asking for their review.
Release approved or rejectedThe proposerIncludes the reviewer's note.
Approval request expiredThe proposerSent when nobody reviewed it within 72 hours.
Release step failedThe proposer and the reviewerA scheduled or staged release stopped.
Alert fired or resolvedEveryone who can manage alerts (alerts.manage)Also posted to ALERT_WEBHOOK_URL when it is set.
Kill switch activated or liftedEveryone who can use the kill switch, except the person who did itLists the environments and how many flags were affected.
API key rotated or revokedEveryone who can revoke keys (api_keys.revoke), except the person who did itNames the key and who rotated or revoked it.
Role changed, or removed from the organizationThe member affectedNames the previous and new role, or the removal, and who did it.
Password changedThe account holderA security notice after they change their own password.
Password reset by an adminThe memberThe new password is never emailed; the admin passes it on.
Ownership transferredThe new owner and the previous ownerTells one they now own the organization and confirms the transfer to the other.
Organization deactivated or reactivatedEveryone who can edit the organization (organization.update)Says who switched the organization off or back on.

Health and Prometheus#

Operational endpoints
PathDescription
/healthOverall status and uptime. Public.
/health/liveThe process is running. Use for liveness probes.
/health/readyThe database answers. Use for readiness probes and load balancers.
/api/prometheusPrometheus 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.

prometheus.yml
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.