Logs
Free & PremiumThe Logs page brings all logs of your local setup into one place: what WebDonkey itself did, what your services print, what the web servers of your sites write and, with Premium, any log files of your own. It is the first place to look when a service does not start, a page shows an error or a nightly backup did not run.
What you do here
- Read service and site logs: follow them live, search, copy, export.
- Go through the WebDonkey journal: backups, scheduled tasks and what went wrong.
- Follow custom logs: watch log files of your projects live, clear and remove them.
- Add a custom log.
Page layout
At the top left you choose in a picker which log you see. Next to it is Add custom log. The picker is split into groups:
| Group | Content |
|---|---|
| WebDonkey | The app's own journal. It is selected the first time you open the page. |
| Custom logs | Your own log files. The group sits right below WebDonkey so you find it without scrolling. |
| Services | One entry per log file of your services: each service's log (“Service: …”) and further files such as the MySQL error log. |
| Sites | Each site's access and error log (“Site …: access” and “Site …: error”). |
The page subtitle tells you what you are looking at. For service and site logs it names the <SANDBOX>/runtime/ folder they come from and that the view refreshes every 1.5 seconds. Your choice stays when you open another page in between.
The logs of your servers have a page of their own: Remote › Logs.
Free and Premium
| Part | Free | Premium |
|---|---|---|
| WebDonkey journal | fully usable | fully usable |
| Service and site logs | The note Embedded log view is Premium and Open file, to read the file in another program | Live view in the app |
| Custom logs | The group is visible, Add custom log carries the Premium badge and is disabled | Add, follow live, clear, remove |
If you switched on Hide Premium features under Settings › Navigation on Free, the Custom logs group and its button disappear entirely.
Service and site logs Free & Premium
The Services and Sites groups of the picker show the log files your services and the web servers of your sites write. You see the last 500 lines live, formatted for reading: timestamps set apart, errors and warnings in color, multi-line entries such as stack traces folded together. That is how you quickly find a PHP fatal in the FPM log, the cause of a 500 in a site's error log or the reason a service does not start.
Where to find it
Sidebar Local › Logs, then an entry from Services or Sites in the picker at the top left. On the command line, wd logs list lists all logs and wd logs tail <name> prints the end of one, with -f it keeps following new lines. More in Tasks, backups and logs.
How to do it
- Open Logs.
- Pick an entry from Services or Sites in the picker.
- The last 500 lines appear, newest at the bottom. The view fetches new lines every 1.5 seconds and stays at the end as long as you are there.
- If you scroll up, the view stays put. When new lines arrive, New lines takes you back to the end.
- Click a line to expand it. Then you see the full text, even for long lines.
Which logs there are
- Services: every file ending in
.logunderruntime/in the sandbox. A service's log is called “Service: …” with service and version, other files appear with their path, such as the MySQL error log or the OpenSearch log. New files show up by themselves. - Sites: for each site “Site …: access” and “Site …: error”, once the web server has created the file. Instead of the site name, the entry shows the site's internal ID, a long string of characters.
Common formats
The view recognizes lines from Apache and nginx (error and access log), PHP and PHP-FPM, Laravel and Monolog, syslog and every log with ISO timestamps:
- The timestamp is set apart in front of the message.
- Errors are red and carry an icon, warnings yellow, debug lines dimmed.
- Lines without a timestamp of their own, such as a stack trace, are folded under the entry before them. A badge shows how many (n more lines).
Lines in unknown formats stay plain lines.
Fields and buttons
| Element | What it does |
|---|---|
| Search… | Filters the lines. Case does not matter. Above the list it says “x of y lines”. If nothing matches, it says No lines match this search. |
| Copy | Puts exactly the lines that match the search on the clipboard. Afterwards it briefly says Copied. |
| Export as text | Saves the same lines as a .txt file. The suggested file name is the log file's name plus today's date. |
| Open file | Opens the log file itself, as set under Settings › Open with › Folders and files: with Automatic in the WebDonkey Editor if it is installed, otherwise with your Mac's default app. |
Good to know
- If a service has not written anything yet, it says (no entries yet).
- If a service fails to start, the Services page already shows the matching excerpt in the error note.
- The view only reads files in WebDonkey's sandbox. For other files, use Custom logs.
Free and Premium
The live view is Premium. On Free you see the note Embedded log view is Premium and the Open file button instead, to read the log in another program.
See also
WebDonkey journal Free
The WebDonkey entry in the picker of the Logs page is the app's own journal: what WebDonkey did by itself, mainly backups and scheduled tasks, and what went wrong. This is where you find out why a nightly backup is missing, which task ended with which exit code and whether a run was missed because the Mac was asleep. The journal is fully usable on Free.
Where to find it
Sidebar Local › Logs. WebDonkey is the first entry in the picker and selected the first time you open the page.
What it records
Every run leaves events: start, end and whatever went wrong in between. It records:
| Area | What |
|---|---|
| Backups | Runs of your backup sets |
| Scheduled tasks | Runs of your scheduled tasks |
| Remote backups | Backups of your servers |
| Remote cron jobs | Tasks WebDonkey triggers on your servers |
| Database safety copy | The copy WebDonkey takes of its own database before an update |
What counts is what WebDonkey runs, whether in the app, in the background service without the app open, or on the command line. Tasks a server starts with its own crontab are not listed here. WebDonkey keeps events for 90 days.
Filters
When you open it, you only see what needs your attention: Error and Aborted in the Last 7 days. If nothing like that happened, it says Nothing went wrong with Show all events.
| Filter | Effect |
|---|---|
| Error, Aborted, Warning, Success, Start | Toggles for the severity. Each click turns one on or off. With all five on you see every event. |
| All areas | Limits to one area from the table above. |
| Last 7 days or Everything | The period. |
| Search… | Searches names, servers, sites, reasons, codes and details. Case does not matter. |
Below it says “x of y events”. At most the newest 500 are shown, copying and exporting cover all that match the filter. If there are no events at all yet, it says No events yet. The filters stay when you open another page in between. The list refreshes every 5 seconds.
Reading an event
Each row shows the severity icon, the time, the area, the name (with the server for remote runs), the event, the first line of the reason and the duration. Possible events:
| Event | Meaning |
|---|---|
| Started | The run began. |
| Finished | The run is done. |
| Failed | The run ended with an error, for example an exit code other than 0. |
| Cancelled | You cancelled the run. |
| Interrupted | The process was ended from outside: app quit, Mac off or asleep. |
| Not run when planned | Nothing ran at the planned time, the run came later or not at all. |
| Skipped | The run never started, for example because there was not enough space on the server. |
A click expands the details: the full Reason and, depending on the run, Trigger (Scheduled or Manual), Written by (WebDonkey, WebDonkey Editor, wd (CLI) or Background service), server, site, Exit code, Size, Archive, Code and Run.
Find a missed backup
- Keep Error and Aborted on and turn on Warning as well.
- Choose Backups under All areas.
- Set the period to Everything if it was a while ago.
- Expand the event.
“Not run when planned” with the reason that the Mac was off or asleep, or WebDonkey was closed, means no background service took over. Set up Run without the app open then. A Warning saying “Partly backed up: the files only” means the database server was not running at the planned time: the files are backed up, the databases are not. The details name the missing ones.
Copy and export
| Button | What it does |
|---|---|
| Copy | Puts all events that match the filter on the clipboard as text. |
| Export as text | Saves them as a .txt file. |
| Export as CSV | Saves them as a .csv file, for a spreadsheet for example. |
| Show in Finder | Shows the file in which WebDonkey keeps the journal. |
See also
Custom logs Premium
With Custom logs you follow any log file live inside WebDonkey: a framework's log, a shop's error log, a worker's log, anything readable as text. The file may live anywhere on your Mac, outside the sandbox too. You no longer need a terminal running tail -f. Custom logs are a Premium feature.
Where to find it
Sidebar Local › Logs, then the Custom logs group in the picker. It sits right below WebDonkey. In ⌘K the entry Custom logs jumps straight into this group. On the command line there is wd logs custom. More in Tasks, backups and logs.
How to do it
- Open Logs.
- Pick the log in the Custom logs group. If there is none yet, it says (no custom logs), and the view tells you to add one (see Add a custom log).
- The last 500 lines appear and refresh every 1.5 seconds.
The view is the same as for service logs: formats recognized, lines expandable, Search…, Copy, Export as text and Open file. All of that is described under Service and site logs.
Clear and remove
With a custom log open, two more buttons appear on the right:
| Button | What it does |
|---|---|
| Clear | Asks Clear this log? and then empties the file. The content is deleted and cannot be brought back. The file itself stays, and the application keeps writing to it. |
| Trash can (Remove) | Asks Remove this custom log? and then takes the log off the list. The log file stays on disk. |
What happens in the background
For each custom log, WebDonkey only remembers name and path, in its own database. The file is only read when you open the log, and only while the page is open.
Free and Premium
Custom logs are Premium. On Free you see the group in the picker, and Add custom log carries the Premium badge and is disabled. If you open a custom log left over from Premium, the view shows the note Custom logs are Premium, with Open file to read the file in another program. With Hide Premium features under Settings › Navigation, the group disappears entirely.
Troubleshooting
| What you see | What to do |
|---|---|
| (no entries yet) | The file is empty. Trigger something in your application that writes to the log. |
| An error message instead of lines | The file was moved, deleted or is no longer readable. Remove the log and add it again with the new path. |
See also
Add a custom log Premium
Add custom log puts a log file into the Custom logs group of the Logs page. From then on you follow it there live like any other log. The feature is Premium.
Where to find it
Sidebar Local › Logs, Add custom log to the right of the picker. The button is there whichever log is open. On the command line, wd logs custom add adds a log. More in Tasks, backups and logs.
How to do it
- Click Add custom log. Add a custom log opens.
- Name: what the log is called in the picker, for example “Shop · Error log”.
- File: enter the full path, or click Choose… and pick the file. If the name is still empty, WebDonkey takes the file name.
- Click Add. The button is only active once name and file are filled in.
The new log is selected right away and shows its last lines.
If you close the dialog half filled in, your input stays until you quit the app.
Troubleshooting
| Message | Why | What to do |
|---|---|---|
| “Please enter a name.” | The Name field is empty. | Enter a name. |
| “That path is not a readable file.” | The path points to a folder or to nothing. | Check the path or use Choose…. |
| “The file exists but can't be read (permissions?).” | You lack read permission. | Check the file's permissions, for example with ls -l. |