> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hr-easy.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring

> Structured logging, Application Insights correlation, alerts, and health checks.

## Logging

Two loggers, deliberately separate:

| Import                                    | Use                                                                            |
| ----------------------------------------- | ------------------------------------------------------------------------------ |
| `@/lib/observability/services/logger`     | Structured logging. **Client-safe** — works in the browser and in SSR.         |
| `@/modules/observability/services/logger` | Server-side logging that must reach Application Insights with correlation IDs. |

The `lib` logger does **not** import the App Insights sink. The sink dynamically imports
the Node-only `applicationinsights` package and is server-only; pulling it into a
client-safe module would break the browser bundle.

Every `error`, `warn` and `info` on the module logger routes to Application Insights
when `APPLICATIONINSIGHTS_CONNECTION_STRING` is set.

<Warning>
  `console.*` is an ESLint **error** in `src/` outside test files. Ad-hoc logging is how personal
  data ends up in a log aggregator with no retention policy — and it bypasses correlation entirely.
</Warning>

## Correlation

Server-side logs carry a correlation ID, so a single user action can be followed across
the request, the service calls, and the outbound integration calls it triggered. When a
customer reports "it failed at about eleven", the correlation ID is what turns that into
a trace.

## Alerts

Application Insights alerts are wired per environment and documented in a dedicated
playbook. The signals worth alerting on:

| Signal                        | Why                                                        |
| ----------------------------- | ---------------------------------------------------------- |
| Health endpoint failing       | The application is down.                                   |
| Error rate spike              | A regression reached production.                           |
| Graph authentication failures | The mailbox has stopped working — often an expired secret. |
| Scheduled job not reporting   | A cron endpoint has stopped being called.                  |
| Database connection errors    | Credential rotation, capacity, or a network issue.         |
| Response-time degradation     | Capacity pressure — see the capacity-planning playbook.    |

## Health checks

A health endpoint reports application and dependency status. The deployment pipeline
waits for it before considering a release complete, and the platform monitor polls it
continuously.

## The observability dashboard

An in-product surface shows recent errors and operational state to administrators
without server-log access. `SYSTEM_ADMIN` holds it — it is technical operation, and it
is deliberately one of the few surfaces that role can reach.

A separate read-only **mailbox diagnostic** reports Graph credential drift, an
unconfigured mailbox, or an outage, with all values masked. Administrators can triage
the most common integration failure themselves.

## Audit versus logs

Different systems for different questions:

| Question                                   | Where to look                     |
| ------------------------------------------ | --------------------------------- |
| Who changed this record, and to what?      | The audit trail.                  |
| Why did this request fail?                 | The logs.                         |
| What was sent to an AI provider, and when? | The audit trail (`AI_OPERATION`). |
| Which version was running when this broke? | Version logging.                  |

Audit entries are masked and permanent; logs are detailed and retained per policy.
Do not use logs as an audit trail — they are not designed to be one.

## Capacity

Capacity planning has its own playbook: what to watch, what to scale, and in what order.
The usual first mover is the App Service plan; the database follows.