Incidents

Incidents are the core of Statusfy: there is no Status Page System without a record of incidents.

The Incidents information is stored in a Markdown file with attributes and a content that provides extra information to your users.

You must create the incidents in the ./content folder (this path name can be changed, more information here) to be discovered by Statusfy. It's generated an HTML page for Each of your Incidents, and they are listed in the History Section of your Status Page System.

REMEMBER

You must create a sub-folder for each of your Secondary Languages and place the source of the translation of your incidents.

You can create your incidents by hand for each of your available languages or you can use CLI:

npm run new-incident

TIP

With this command, after you answer a few questions, an initial Markdown file is automatically generated for your incident for all the available languages. More information in the Commands Guide.

Naming Convention

You can name the file of your Incidents the way you desire the most but we recommend this pattern: YYYY-MM-DD_slug.md, where YYYY-MM-DD is the creation date and slug a short name. For example:

/content/2018-11-21_networking-issues.md
/content/2018-11-22_origin-server-errors.md
/content/2018-11-22_origin-server-errors_2.md

This way you can easily sort by date your incidents and guarantee a unique filename.

TIP

The new-incident command use this pattern by default.

Front Matter

Front Matter is the way you can define extra properties to your incidents. Must be the first thing in the file and must be defined between triple-dashed lines. YAML front matter is supported out of the box:

---
id: 382ee1ab
title: "Networking Issues"
description: "We detected a networking problem that caused temporary issues for our API and origin servers."
date: 2018-10-16T13:14:03.000Z
modified: 2018-10-16T13:14:03.000Z
severity: "degraded-performance"
affectedsystems:
  - "site-delivery"
  - "api"
resolved: true
---

Supported Parameters

id

  • Type: string
  • Requirement: optional

A unique identifier for the incident. It must be alphanumeric in order to prevent errors when generating/building/accessing the system.

If this value is not explicitly defined, it will be automatically generated a unique string based on the filename of the incident.

title

  • Type: string
  • Requirement: mandatory

The title of the Incident.

description

  • Type: string
  • Requirement: optional but recommended

A short description of the Incident. It's used as a meta description and as a summary for the incident in the History section.

date

  • Type: string
  • Requirement: mandatory

The creation date of the Incident in ISO-8601 format: YYYY-MM-DDTHH:mm:ss.sssZ.

modified

  • Type: string
  • Requirement: optional

The last modification of the incident. If a value is defined, you must update it every time the incident is updated.

TIP

If you use git in your project, this value can be automatically generated from the date of the file's last git commit.

severity

  • Type: string
  • Requirement: mandatory

The severity of the Incident. There are 4 values available:

  • under-maintenance: The system(s) cannot handle requests due to a temporary maintenance update.
  • major-outage: No one can access the system(s) because it is completely down.
  • partial-outage: Limited access to the system(s), because it's probably experiencing difficulties.
  • degraded-performance: The system(s) is not stable, it's working slow otherwise impacted in a minor way.

affectedsystems

  • Type: string
  • Requirement: mandatory

The affected system(s) the incident is referring to. The values that can be used must be defined in the configuration file (More information in the Config Reference).

resolved

  • Type: boolean
  • Requirement: mandatory
  • Default: false

If this field is set to true, the incident is Marked as Resolved.

scheduled 0.2.0+

  • Type: string
  • Requirement: optional
  • Default: undefined

The scheduled start time. This defines the initial of the planned maintenance window.

duration 0.2.0+

  • Type: string
  • Requirement: optional
  • Default: undefined

The scheduled duration in minutes. This defines the duration of the planned maintenance window.

Alternative Front Matter Formats

In addition, you can define your front matter as a JSON or TOML.

JSON front matter needs to start and end in curly braces and needs to be explicitly marked as JSON:

---json
{
  "id": "382ee1ab",
  "title": "Networking Issues",
  "description": "We detected a networking problem that caused temporary issues for our API and origin servers.",
  "date": "2018-10-16T13:14:03.000Z",
  "modified": "2018-10-16T13:14:03.000Z",
  "severity": "degraded-performance",
  "affectedsystems": [
    "site-delivery",
    "api"
  ],
  "resolved": true
}
---

And TOML front matter also needs to be explicitly marked, as TOML:

---toml
id = "382ee1ab"
title = "Networking Issues"
description = "We detected a networking problem that caused temporary issues for our API and origin servers."
date = 2018-10-16T13:14:03.000Z
modified = 2018-10-16T13:14:03.000Z
severity = "degraded-performance"
affectedsystems = [
  "site-delivery",
  "api"
]
resolved = true
---

IMPORTANT

Statusfy only supports the version 0.4.0 of the TOML specification.

Scheduled Maintenance 0.2.0+

Scheduled Maintenances definition is a way to let your users know ahead of time when your system(s) cannot handle requests due to a temporary maintenance update.

Scheduled Maintenances share the same parameters as regular incidents but two parameters are always required: scheduled and duration.

You must keep in mind that these definitions are handled in a different way than regular Incidents:

  • These Special Incidents are displayed in the Scheduled Maintenance section (at the Home Page) while the scheduled date has not arrived.
  • After the scheduled date passes you must set the resolved parameneter to true if the maintenance window has finished.
  • Scheduled Maintenances are not displayed in the Incidents Timeline and the Incidents History while the scheduled date has not arrived.

Content

The content of the Incidents are written in a valid Markdown format but there are extra Extensions that Statusfy provides.

Updates Containers

These containers are the way the Updates of Incidents are defined.

::: update Resolved | 2018-02-06T01:24:45.752Z
We detected a networking problem that caused temporary issues for our API and origin servers. All systems are back to normal now, but we're monitoring closely.
:::

You must provide a Title, a Date in ISO-8601 format (YYYY-MM-DDTHH:mm:ss.sssZ) and a valid Markdown content.

Any absolute or relative link is treated as an internal link.

A link with a defined domain is identified as an outbound link and automatically gets target="_blank" rel="noopener noreferrer" class="external":

Emojis 🤓

Emojis can also be used.

Input

:nerd_face: :tada: :100:

Output

🤓 🎉 💯

A list of all emojis available can be found here.

Example File

---
id: 382ee1ab
title: API Issues
description: Our Files Conversion Process were responding slowly.
date: 2018-01-28T18:28:48.878Z
modified: 2018-01-28T20:28:48.878Z
severity: degraded-performance
affectedsystems:
  - api
  - cdn
resolved: true
---

<!-- Your General content -->
Our Files Conversion Process were responding slowly.

<!-- Definition of the Incident Updates -->
::: update Resolved | 2018-01-28T22:28:48.878Z
Performance is back to normal and we'll continue to monitor.
:::

::: update Monitoring | 2018-01-28T23:28:48.878Z
The Conversion Process is back to normal and we'll continue to monitor.
:::

::: update Resolved | 2018-01-28T23:58:48.878Z
The Files Conversion System is back to normal and we'll continue to monitor.
:::

This file will be rendered as an HTML page similar to this one: Demo Incident - #382ee1ab

Last Updated: 12/11/2018, 2:59:34 PM
Want to keep up with the latest news, tips and tricks from Statusfy?
Subscribe to our Newsletter!