# Part 1 · The logs

## 1.1 Reading the audit log

**Who** · An Owner or Admin (`audit.view`); the Service for every workspace (`platform_audit.view`).

**Where** · **Audit log** in the menu (`/audit`); the Service's under Platform (`/console/audit`).

**Before you start** · Nothing.

**The steps**
1. The newest change comes first: when, who, how (Web, API or System) and what, with the record it was about. A change
   made through the support lens says so.
2. Search a name, or **Add a filter**: the day, how, the event; the Service also by workspace (or the platform's own).
3. Open a change (the folder): each field before and after, who, how, the record by the name it had then, and the
   address it came from.

**What the record shows** · Nothing new: reading isn't recorded.

**Who is told** · Nobody.

**What can go wrong**
- *A change you expected isn't there.* It was older than the log's age and went in a night's purge (1.4), or it was
  made in another workspace: a person changed elsewhere is in that workspace's log.
- *A record shows its old name.* That is the name it had when the change was made; history isn't rewritten.

## 1.2 Exporting the audit log

**Who** · An Owner or Admin (`audit.export`); the Service for every workspace (`platform_audit.export`).

**Where** · **Audit log** › **Export**.

**Before you start** · The period: from and to, both required.

**The steps**
1. Press **Export**, choose **From** and **To**, and press **Export**. It is made in the background, as CSV.
2. An e-mail, **Your export is ready**, brings the link. It works only for you, only while you may still export the
   log, and only for the days shown (**Keep an export for**, 7 as shipped).
3. Open the link in the workspace the export was made in.

**What the record shows** · The audit log: **Export asked for** (the period) and **Export downloaded** each time.

**Who is told** · You, by e-mail (`export.ready`).

**What can go wrong**
- *"The to must be a date after or equal to from."* The period ends before it starts.
- *The link finds nothing.* It has expired, or you opened it in another workspace, or you may no longer export the
  log. Ask for a new one.
- *A cell starts with an apostrophe.* A value that a spreadsheet would run as a formula is kept as text.

## 1.3 Reading the sign-in log (Service)

**Who** · The Service (`auth_event.view`).

**Where** · Platform › **Sign-in log** (`/console/sign-in-log`).

**Before you start** · Nothing.

**The steps**
1. Every sign-in and security event, newest first: who (or the e-mail tried), the event, the address and the reason.
   Failures and locks stand out.
2. Search a name, an e-mail or an address, or filter by day and event.

**What the record shows** · Nothing new.

**Who is told** · Nobody.

**What can go wrong**
- *A workspace asks for its people's sign-ins.* The sign-in log is the Service's: a sign-in belongs to an account, not
  a workspace, and would show what someone did elsewhere.

## 1.4 Choosing how long the logs are kept

**Who** · The Service for the platform (`platform_setting.manage`, the password again); an Owner or Admin for the
workspace (`setting.manage`).

**Where** · Platform settings › **Logs**; a workspace's **Settings** › **Logs**.

**Before you start** · The least each log keeps can't be passed (365 days for the audit log, 30 for mail).

**The steps**
1. Open **Keep the audit log for** (or another), type the days, and save.
2. A workspace's own age applies to its own changes and mail from the next night; the platform's to everything else.

**What the record shows** · The audit log: **Setting changed**.

**Who is told** · Nobody.

**What can go wrong**
- *"… must be between …"* The age is outside the range: the least is the floor, the Service may narrow the range.
- *The sign-in log isn't on a workspace's page.* Its age is the platform's.

## 1.5 Purging now (Service)

**Who** · The Service (`purge.view`; `purge.run` to run one).

**Where** · Platform › **Purges** (`/console/purge`).

**Before you start** · The ages you want (1.4).

**The steps**
1. Each log shows how long it keeps, how many workspaces keep their own, its oldest entry, how many are due now and
   how many went last time.
2. **Run it now** › **Run it now**, then your password: the night's purge runs at once, in the background.
3. **Every purge** lists each run, by the schedule (the system) or by hand, how it went, and how many each log lost,
   with each archive (gzipped JSON lines, its checksum kept).

**What the record shows** · A `log_purge` row kept for good; the audit log: **Logs purged**.

**Who is told** · Nobody.

**What can go wrong**
- *Nothing is due.* Every entry is younger than its age.
- *Failed.* The error is kept on the purge; nothing of a log is removed before its archive is written.

## 1.6 Purging to a day by hand (operator)

**Who** · The operator, on the server.

**Where** · `php artisan logs:purge --before=YYYY-MM-DD [--log=audit --log=auth_event --log=email_message]`; the night's
purge is `php artisan logs:purge --due`.

**Before you start** · The day. No log loses anything inside its least age.

**The steps**
1. Run it without `--force`: how many would go; nothing is removed.
2. Run it again with `--force`: archived to `storage/app/private/purge/<id>/<log>-before-<day>.jsonl.gz`, then removed.

**What the record shows** · A `log_purge` row; the audit log: **Logs purged**.

**Who is told** · Nobody.

**What can go wrong**
- *"The … keeps its newest entries."* The day is inside the log's least age.
- *"Say --due or --before".* Choose one: by each log's age, or one day everywhere.