# The ELOG logbook

WebDAQ can read and write the collaboration's ELOG logbook, so a shift entry does
not mean leaving run control. It is the same logbook you open in a browser — the
entries are identical, whichever way you write them.

There are two logbooks in the interface and they are not the same thing:

* **Logbook → Runs** — WebDAQ's own run record: run number, times, target,
  voltages, accumulated charge, notes. Generated by the DAQ.
* **Logbook → ELOG** — the collaboration's ELOG server. Written by people.

---

## 1. Setting it up

Settings → ELOG.

| Field | What to put in |
|-------|----------------|
| Logbook URL | The full address as it appears in the browser, e.g. `https://elog.hzdr.de/B10_alpha/`. |
| Username / Password | One shared account for the DAQ machine. Leave empty if the logbook needs no login. |
| Default attributes | Fields filled into every entry — for instance `Category: Shift`. |
| Allow WebDAQ to post entries | Reading works without it; posting does not. Off until you turn it on. |

Press **Test connection**. It reports the last entry number in the logbook if
everything is right, and says what is wrong if not — a wrong password and an
unreachable host give different messages.

**Requirement:** the server needs PSI's `py_elog` package. It is not on PyPI —
`pip install py_elog` cannot work. Install it from PSI's conda channel:

```bash
conda activate luna
conda install -c paulscherrerinstitute elog
```

The Settings page says so explicitly when the package is missing.

### Accounts and attribution

Authentication and attribution are separate in ELOG. The shared account
authenticates the connection; the **Author** attribute signs the entry, and
WebDAQ fills it with the username of whoever is logged into WebDAQ. Entries
therefore carry a real name even though one account posts them all.

Use an account created for the DAQ, with write access to the one logbook. The
password is stored in `conf/elog_settings.json` in plain text — the same
arrangement as the Telegram token — so it should not be anybody's personal
account.

Note that `py_elog` does not verify TLS certificates. Traffic to an `https://`
logbook is encrypted but the certificate is not checked.

---

## 2. Reading

Logbook → ELOG.

The list shows the most recent entries: subject, author, date, type, and a paper
clip with the number of attachments. Click one to read it on the right, with all
its attributes, its full text and its attachments — pictures inline, everything
else as a download. Attachments come through the WebDAQ server, because your
browser has no session on the ELOG machine.

**Search** matches text in the entries. Clear the box to go back to the list.
The list loads twenty entries at a time; *Load more* fetches the next twenty.

Reading does not need the *Allow posting* switch.

---

## 3. Writing

**New entry** opens the composer. The attribute fields are read from the
logbook's own entry form, so the names, the allowed values and which attributes
are required are the logbook's, not a guess — a required Category cannot be left
blank here and rejected after you have written the entry.

**Write up a run** drafts the entry from the run itself: the timing, the beam
current and accumulated charge, the regions of interest and the board
configuration, assembled out of the database row, `metadata.json`, `current.txt`,
`stats.csv` (including any `stats.csv.partN`) and `roi.json`. Everything stays
editable before you post, and if some of those sources are missing for that run
the toast names which — so a thin draft is never mistaken for a complete one.

* Author is filled with your WebDAQ user; change it if you are writing for
  someone else.
* Attach files with the file picker — screenshots of a spectrum, a plot, a photo
  of the setup.
* **Reply** on an open entry threads the new one under it, keeping the shift's
  attributes and prefixing the subject with `Re:`.

Entries are posted as plain text. An entry that was written elsewhere in HTML is
shown as text here — the words are all there, the formatting is not.

---

## 4. What is worth writing

WebDAQ does not post anything by itself: nothing appears in the logbook unless a
person writes it. The run record in Logbook → Runs already holds run numbers,
times, charge and notes, so the ELOG entry is for what the DAQ cannot know:

* what you changed and why — target, threshold, geometry, gas pressure;
* what went wrong, what you did about it, and whether it worked;
* the state of the accelerator at the start and the end of the shift;
* a screenshot when a spectrum looks different from yesterday.

Reference the run numbers. The run record holds the numbers; the logbook holds
the reasons.

---

## 5. When it does not work

| Message | Cause |
|---------|-------|
| "The py_elog package is not installed" | Either it really is not installed — use the conda command above — or the server is running in the wrong environment. Check with `lsof -ti tcp:5001 -sTCP:LISTEN \| xargs ps -o command=`: the interpreter must be `…/envs/luna/bin/python`. See [Troubleshooting](troubleshooting.md#7-the-server). |
| "check the ELOG user and password" | Wrong credentials, or the account has no access to that logbook. |
| "the ELOG server did not answer in time" | The logbook is unreachable — check the VPN. Every call gives up after 10 seconds so the DAQ is never held up by it. |
| "ELOG rejected the entry" | A required attribute is missing or has a value the logbook does not allow. The message repeats what ELOG said. |
| "ELOG posting is switched off" | Turn on *Allow WebDAQ to post entries* in Settings → ELOG. |
| "That attachment does not belong to the configured ELOG server" | The attachment proxy only fetches from the configured host. |