¶Nightwatch

Laravel Nightwatch watches your application and groups what goes wrong. Félagi mirrors that list, so an exception becomes an issue somebody owns instead of a notification somebody skims.

Administration → Nightwatch.

¶What is mirrored, and what is not

Nightwatch does the hard part. It does not send exceptions — it sends issues, one per group, with a life of their own. Félagi follows that life:

There is no second grouping. Félagi does not fingerprint occurrences, because Nightwatch already decided what counts as the same problem and two answers to that question diverge on the first message containing a request id.

issue.reopened is the one worth waiting for. "It is happening" is a fact anybody can see; "it came back after we fixed it" is the one nobody discovers on their own.

¶Resolving does not always close

An engineer resolving an alert has said the errors stopped. They have not said the work is done.

So Félagi comments always, and finishes the issue only while it is still in the backlog or unstarted. If somebody has picked it up, the state is left alone — a monitoring tool closing an issue a colleague is working in is a tool overruling a person.

¶Connecting

1. Administration → Nightwatch → Connect Nightwatch. This produces an address and a signing secret.
2. In Nightwatch, open your application's Issues → Webhooks and paste both.

Nightwatch allows one webhook per application, so every application you run points at the same Félagi address. Which project each belongs to is decided here, not there.

The secret is checked against the raw body with HMAC-SHA256, the scheme Nightwatch documents. An unknown token gets a 404, never a 401: a 401 tells somebody they have found the right URL and need only the key.

¶Where problems land, and who gets them

The Applications table fills itself. The first time an application reports anything, Félagi records it and points it at the default project — a new application arrives without warning, and dropping its first event would mean the first problem from every new service is the one nobody hears about.

Each row has two things to set:

• Project — where its issues are filed
• Assign to — the developer who picks its problems up

The assignee is held per application rather than per project on purpose. Staging and production can be two applications pointing at one project and go to different people, and "who gets the exceptions" is not the same question as "who gets the work".

Leaving it unassigned is a real answer. A name chosen by a rule nobody remembers writing is worse than no name.

¶What an issue looks like

The link to Nightwatch comes first, because the details in Félagi are a summary and theirs is the record — occurrences, stack, affected users. Copying that here would be a copy going stale from the moment it was written.

Below it: the exception class, the message, the file and line, and the environment. A performance issue gets its path, duration and threshold instead.

The type follows theirs: an exception becomes an Exception, a performance problem becomes a Performance problem. Both already existed as issue types, which saved inventing a label to carry the difference.

¶Three states, never two

The settings page says which:

• never called — the address has not been used
• refusing — something arrived and was turned away, with the reason
• listening — the last delivery was accepted

A hook that has never been called and a hook that refuses every call look identical unless somebody says which, and the second is the one that costs you a week.

¶Not there yet

• No triage queue. Issues land in the backlog of their project. A label and a status are the current answer; a queue of their own is not built.
• No cap on new issues per hour. Nightwatch's own grouping makes a storm unlikely — one issue per group, not per occurrence — but nothing here would stop one.
• Nothing is sent back. Resolving in Félagi does not resolve in Nightwatch. Their list is about errors and this one is about work, and the two finish at different moments.
• One hook per workspace. Every application in a workspace shares the address and is told apart by its application_id.