> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/incidents-and-status-pages/services.md). # Services A service is the business capability your users care about. Alerts attach to it, incidents name it, status pages publish it, and people subscribe to it. Your monitoring knows about hosts, containers and queues. Your customers know about **Checkout**, **Search** and **Login**. A service is the second thing, and it is what makes the rest of ilert legible to somebody who does not have your architecture diagram in their head. Services are the join between the two halves of ilert. On the alerting side, alerts attach to them. On the communication side, [status updates](/incidents-and-status-pages/status-updates.md) publish them, [status pages](/incidents-and-status-pages/status-pages.md) display them, and people [subscribe](#add-remove-subscribers-to-a-service) to them. Services live under **Catalog** in the sidebar.
The ilert Services page. A row shows a green Operational icon, the service name, its uptime percentage over the past 60 days, a bar chart of daily status across those 60 days, and a Subscribe button.

Each service carries its own 60-day uptime history, and anyone can subscribe to it.

## Service statuses | Status | Means | | --------------------- | ------------------------------------------------------------------ | | **Operational** | Working as expected | | **Under maintenance** | Down or degraded on purpose, and announced | | **Degraded** | Working, but impaired — slower than usual, say | | **Partial outage** | Not working for a subset of users — one region, one payment method | | **Major outage** | Not available | {% hint style="warning" %} **Changing the status here does not tell anybody.** It records the change internally. Nothing appears on a status page and no subscriber is notified until a [status update](/incidents-and-status-pages/status-updates.md) publishes it — see [Public and internal uptime](#public-and-internal-uptime) below. {% endhint %} ## Create a service Go to **Services** and click **Create new service**. A name is all it asks for; everything else is on the service afterwards.
The new service dialog, containing a single Name field filled in with Checkout API, above Create new service and Cancel buttons.

Name it after the capability, not the component. Your customers will read it.

## What a service holds
The Settings tab of an ilert service, showing Teams, Name, Status, Description, Optional aliases, Labels and Reference links, with Dependencies and Subscribers as sibling tabs.

The Settings tab. Dependencies and Subscribers are the other two.

| Field | What it does | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Teams** | Who manages the service | | **Name** | Shown to everyone, including readers of a public status page | | **Status** | The current [service status](#service-statuses) | | **Description** | Shown on status pages as a tooltip beside the service name | | **Optional aliases** | Other names this service answers to. See [How alerts reach a service](#how-alerts-reach-a-service) | | **Labels** | Key/value metadata — `tier`, `criticality`, `domain`, `env`, `squad`. Used to filter the catalogue and the [Service Health map](/incidents-and-status-pages/service-topology.md#filtering-the-map) | | **Reference links** | A label and a URL: runbooks, repositories, dashboards, docs. They travel with the service to wherever it is shown | | **Never show historical uptime** | Hides the uptime history — and the uptime SLA figure — on every status page this service appears on | | **Only allow one open incident at a time** | Stops [automation](#automation-with-alert-sources) opening a second status update on this service while one is still open | ### Renaming a service is not free Alerts and integrations that name a service through the [Events API](/developer-docs/rest-api/api-reference/events.md) match it by name or alias. Rename it and those references stop matching. ilert notices: renaming offers to **keep the old name as an alias**, which keeps everything pointing at it working. Take the offer unless you know what is referencing the service. ## How alerts reach a service An alert becomes an alert *on a service* in one of three ways. All three match by **name or alias**, which is what aliases are for — an alias is easier than renaming a service to match whatever your monitoring already calls it. 1. **The event says so.** An event posted to the [Events API](/developer-docs/rest-api/api-reference/events.md) can carry a `services` array naming them by alias. 2. **The alert source has defaults.** **Default services** on an [alert source](/alerting/configure-alerting/alert-sources.md#affected-services) are linked to every alert it creates. 3. **The alert source extracts them.** **Dynamic mapping** reads a field out of the payload and matches its value against your catalogue.
The Affected services section of an ilert alert source, with a Default services picker, a Dynamic mapping checkbox reading Use the following alert fields to extract affected services, an Add field control, and an Auto-create a service if no match is found checkbox.

Dynamic mapping, expanded. Auto-create is how a catalogue fills itself in.

Dynamic mapping can also **auto-create a service if no match is found**. New services get the extracted value as both name and alias, and inherit the alert source's team. It is the fastest way to populate a catalogue, and the fastest way to end up with a catalogue full of hostnames — so turn it on where the field you are extracting is already the name of a business capability, and leave it off where it is not. ## Automation with alert sources An alert source can move a service's status and publish a [status update](/incidents-and-status-pages/status-updates.md) with nobody watching. That is the **Update status page** alert action. Create it from **Alert actions** in the sidebar, pick **Update status page** as the type, and choose the alert sources that should trigger it.
The action section of an ilert Update status page alert action: set the status of the Checkout service to Degraded, open an incident using the Data center outage template, a resolve checkbox, a send notifications checkbox, and a hint explaining that the action publishes a status update.

The labels still say incident. What the action produces is a status update.

| Setting | What it does | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Set the status of following services … to …** | The services to move, and what to move them to | | **Open an incident using template** | Publishes a status update from an incident template. Optional — without it the action only moves the status | | **Resolve the incident when the alert is resolved …** | Closes the loop: when the alert resolves, the update is resolved and the services go back to **Operational** | | **Send notifications to subscribers when incidents are updated** | Whether subscribers hear about it | | **Trigger mode** | **Automatic** runs it for every alert. **Manually via alert action** puts it on the alert as a button | | **Trigger events** | Which points in an alert's life it runs at — created, accepted, resolved | | **Conditional execution** | Run only for alerts that match a condition | {% hint style="info" %} Set **Trigger mode** to **Automatic** if you want this to happen without a human. On **Manually via alert action** it waits for somebody to press it, which is often what you want for anything customers will read. {% endhint %} ### What stops it flooding your status page An automated update is one alert away from a wall of noise, so two rules limit it. Neither applies to updates a person posts. * **Always:** an alert source will not open a second status update on a service that already has one open from that same alert source. Ten alerts from the same monitor produce one update, not ten. * **When the service has "Only allow one open incident at a time" ticked:** no automation opens a second update on that service at all, whichever alert source it came from. If every affected service is already spoken for, the action does nothing and the alert is simply not published. ## Service uptime ### Public and internal uptime A service keeps **two** uptime histories, and the tabs above the graph switch between them.
The uptime history card on an ilert service, with Public and Internal tabs, a 60-day bar chart, the hint Click a day to open its 24-hour timeline and edit its outage overrides, and the Never show historical uptime and Only allow one open incident at a time checkboxes below.

Two timelines of the same service: what happened, and what you told people.

* **Internal** — every status change ilert recorded, including the ones you never published. * **Public** — only the changes your status pages showed. A status change stays internal until a [status update](/incidents-and-status-pages/status-updates.md) publishes it, which is why the two can differ. Reach for **Internal** when you want to know what actually happened, and **Public** when you want to know what your customers were told. [Outage overrides](#outage-overrides) apply to both. Status pages show the public timeline. ### How is the uptime of a service calculated? ilert displays uptime over a period of up to 90 days. **Operational**, **Degraded** and **Under maintenance** count as uptime. **Major outage** and **Partial outage** count as downtime, with partial-outage minutes weighted at 30% of major-outage minutes. Over a period *t*: $$ u=1-{m+(p\*0.3) \above{1pt} t} $$ where *u* is the uptime percentage, *m* the major outage in minutes, *p* the partial outage in minutes, and *t* the period in minutes. **Example.** In 24 hours a service spent 5 minutes in **Major outage** and 30 minutes in **Partial outage**: $$ u=1-{5+(30\*0.3) \above{1pt} 1440}=99.03 % $$ {% hint style="info" %} Outages shorter than a minute are ignored and do not show up in the graph. {% endhint %} ### Outage overrides The recorded history is not always the true one. A monitoring gap records nothing where there was a real outage; a false alarm records an outage that never happened. Click any day in the uptime graph to open its 24-hour timeline. It shows what was recorded, and lets you **add an outage override** — a start, an end and a status — to correct it. An override cannot end in the future, and it changes the uptime history on every status page the service appears on. ### How to hide historical service uptime Each status page has its own **Show uptime history** switch per service, so you can publish a service's uptime on one page and not on another. To prevent *every* status page from showing it, tick **Never show historical uptime** on the service itself and save. That wins over the per-page switch, and it hides the service's uptime SLA figure along with the graph. ### How is the color of each day in the uptime graph determined? Each day is coloured by its total outage minutes, weighted the same way as above. | Total outage minutes | Colour | | -------------------- | ------------ | | 0 minutes | Green | | > 0 – 6 minutes | Light green | | > 6 – 9 minutes | Lime | | 9 – 12 minutes | Light yellow | | 12 – 25 minutes | Yellow | | 25 – 30 minutes | Light orange | | 30 – 40 minutes | Orange | | 40 – 45 minutes | Dark orange | | 45 – 50 minutes | Light red | | 50 – 60 minutes | Red | | 60+ minutes | Dark red | Days in the future, and days before the service existed, are **grey**. {% hint style="info" %} The transition is gradual rather than banded, so a few minutes of outage tints the day slightly instead of flipping it — which is what makes a row of bars readable at a glance. {% endhint %} ## Add / remove subscribers to a service Subscribers are notified when a [status update](/incidents-and-status-pages/status-updates.md) affecting the service is published with notifications on. There are two ways to become one. **People subscribe themselves.** On the Services page, click **Subscribe** on the row. **Unsubscribe** undoes it. **Someone with Responder privileges subscribes them.** Open the service, go to the **Subscribers** tab, and add users or whole teams.
The Subscribers tab of an ilert service with no subscribers yet, explaining that subscribers receive updates when notifications are enabled, and offering an Add subscribers button.

Teams can be added here too, which subscribes everyone in them.

{% hint style="info" %} **Unsubscribing beats a team subscription.** If you are subscribed because your team is, and you unsubscribe yourself, you stay unsubscribed. The team subscription does not pull you back in. {% endhint %} ## Dependencies Services can depend on one another, and the **Dependencies** tab shows both directions — what this service calls, and what calls it. You can draw an edge by hand, or let ilert reconstruct the whole graph from your OpenTelemetry traces. See [Service topology](/incidents-and-status-pages/service-topology.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ilert.com/incidents-and-status-pages/services.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.