Issue policies
What counts as an issue, and which policy governs a given service, read-only today.
Issue policies are read-only today. Every organization gets one system default policy, and there is no way to create or edit a policy yet, in the console or through the API.
What a policy decides
A policy is what turns a fingerprinted error into a visible issue. Its fields are:
| Field | Meaning |
|---|---|
severities | Which log severities qualify, for example ERROR, FATAL |
status_codes | Which span status codes qualify |
threshold_occurrences | How many occurrences of the same fingerprint before it becomes a visible issue |
threshold_window_seconds | The window that threshold is counted over, 0 meaning no window (all-time) |
service_id | The service this policy applies to, or unset for org-wide |
The system default ships with every organization: ERROR/FATAL severities, a threshold of 1 occurrence, org-wide. A fresh organization has a working default from the moment it is created, so issues start appearing without anyone configuring a policy first.
Which policy governs a service
A service can have more than one policy in scope at once conceptually (system default, an org-wide user policy, a service-specific user policy), so resolving "which one actually applies" follows a fixed, most-specific-wins ranking:
- A user-defined policy scoped to this exact service.
- A user-defined policy scoped org-wide (no
service_id). - The system default, always org-wide.
The winning policy is used whole. A losing policy's fields are never merged in: resolution replaces, it does not layer, so the effective policy is always fully explained by one row rather than a blend of several. If more than one policy occupies the winning tier (two user policies both scoped to the same service, for example), resolution refuses rather than picking one arbitrarily, because that ambiguity is a bug in how the policies were declared.
The console's Which policy governs a service? lookup runs this resolution for a service name you type in, or org-wide if you leave it blank, and states the reason in plain language, for example "'M06 walk threshold-3' is scoped specifically to this service, the most specific match beats any org-wide or system policy" or "no user-defined policy overrides it here" for a service still on the default.
On this organization only the system default exists (confirmed via GET /api/v1/issue-policies and GET /api/v1/issue-policies/effective, walked live on kind), so every service resolves to it.
Why there is no write path yet
Every other declared organization resource in this product (a rule, an escalation policy, a monitor) is either a GitOps Kind or has a real CRUD API. An issue policy is neither today: the backing table, the org-scoped repository and the resolution algorithm above were built deliberately without a write API, leaving whether it becomes a GitOps Kind an open decision. IssuePolicy is not currently registered as a Kind, so writing a manifest naming it is refused as unsupported rather than accepted.
Console copy is ahead of what's built
The console's own description reads "System-defined policies ship with the
platform; user-defined policies are declared in git and extend or override
them." That describes the intended design, but IssuePolicy is not a
registered Kind today, so no user-defined policy can actually be declared in
git yet, in this organization or any other. Filed as a documentation
correction rather than fixed here.