What are in my logs and error reports?

When PhotoStructure encounters errors, it may automatically send a report to our error system, Sentry.

These error help us determine both what resulted in the error, and how to resolve it in the future.

What’s included in an error report? 🔗

• Operating system (macOS, Linux distribution, Windows) and version
• Hardware information (RAM free/used, and CPU make/model)
• Mounted volume metadata (mount points, free/used, and if the volume is remote)
• Recent health check results (viewable in the “About” page)
• Your email address, only if you’ve provided it via the email library setting.
• Context around the error
• Recent log messages

What are in log messages? 🔗

Log messages can (but do not always) include:

• Names of files and directories that are being synchronized
• File metadata extracted during synchronization
• System metadata (OS, version, and hardware metadata)

What’s not included in error reports? 🔗

Error reports never include actual image content from any of your photos and videos.

PhotoStructure also uses Sentry’s enhanced privacy and data scrubbers for all error reports.

What’s actually sent? 🔗

A JSON file with the full error report payload is saved into your events directory on your local disk when error reports are sent.

• %APPDATA%\PhotoStructure\events on Windows,
• $HOME/Library/Application Support/PhotoStructure/events on macOS, and
• $HOME/.config/Photostructure/events on Linux

How frequently are these sent? 🔗

Only unexpected or internal errors result in an error report. Ideally, these events are rare.

PhotoStructure limits the number of error reports sent per day, via the maxErrorsPerDay library setting. The default is 3 events per day.

How to opt out of sending error reports 🔗

You can opt out of all error reporting via advanced settings. Shut down PhotoStructure, open your library settings, set reportErrors to false, save your changes, and restart PhotoStructure.

As of version 0.9.1, the settings page also allows you to easily opt-out of error reporting.

Log levels 🔗

• error (the default, only egregious problems)
• warn (minor and expected errors)
• info (verbose high-level execution paths, impacts performance)
• debug (extremely verbose, substantively impacts performance)

What happens if I change my log level? 🔗

If you change your log level, PhotoStructure will write tracing and debug information to log files in your logging directory.

Note that PhotoStructure only sends log excerpts if reportErrors is true, and there is an error.

How to manually send your logs 🔗

If you’ve been asked to manually send in logs, first off: thank you for your time and assistance, and our apologies if PhotoStructure is misbehaving for you.

Step 1: Shut down PhotoStructure 🔗

Make sure PhotoStructure is shut down.

Step 2: Set logLevel to info 🔗

Edit your logLevel setting to be info. It’s probably easiest to do this via environment variables:

For PhotoStructure for Desktops on macOS 🔗

1. Open Terminal.app (hit command+space, type terminal, then tap return)
2. Type launchctl setenv PS_LOG_LEVEL info
3. Tap return

For PhotoStructure for Desktops on Windows 🔗

1. Tap the Windows key, type “environment”, select “Edit the system environment vairables” control panel
2. Click the Environment Variables... button in the bottom right
3. Click the New... button in the top User variables for ___ pane
4. In “Variable name:” enter PS_LOG_LEVEL
5. In “Variable value:” enter info
6. Click OK, then OK, then OK.

For other platforms 🔗

Consult the environment variables page to set PS_LOG_LEVEL=info

Step 3: Start PhotoStructure and reproduce the error 🔗

If this involves sync problems, just let it run for a couple minutes.

Then shut down PhotoStructure.

Step 4: Open your log directory 🔗

The default log directory is

• $HOME/Library/Logs/PhotoStructure on macOS,
• %APPDATA%\PhotoStructure\logs on Windows,
• $HOME/.cache/photostructure/logs on Linux, and
• /ps/library/.photostructure/logs on Docker

On recent versions of PhotoStructure, this path is shown on the About page.

If you’re on macOS, note that the Finder hides the Library folder by default. It may be easier to open a terminal window (see above), and run open "$HOME/Library/Logs/PhotoStructure". A Finder window should open for this folder.

If you’re on Windows, note that the File Explorer hides the %APPDATA% directory by default. It may be easier to open a command prompt (tap Windows, type “cmd”, tap Enter), and run start "%APPDATA%\PhotoStructure\logs". A File Explorer window should open for this directory.

Step 5: Compress and email your logs 🔗

1. Right-click the folder with the current date
2. Select “create archive” or “compress…”
3. Send us the zipfile or .tar.xz archive via email or any other method available to you (Dropbox, OneDrive, Google Drive, iCloud, …)

Step 6: Restore the prior log level 🔗

After sending us your logfiles, please reset your log level back to either warn, or the default value of error, to preserve disk space. Logging at info or debug levels also adversely impacts PhotoStructure’s performance.

Step 6 for PhotoStructure for Desktops on macOS 🔗

1. Open Terminal.app (hit command+space, type terminal, then tap return)
2. Type launchctl unsetenv PS_LOG_LEVEL
3. Tap return

Step 6 for PhotoStructure for Desktops on Windows 🔗

1. Tap the Windows key, type “environment”, select “Edit the system environment vairables” control panel
2. Click the Environment Variables... button in the bottom right
3. Click the line with PS_LOG_LEVEL
4. Click Delete
5. Click OK, then OK, then OK.

Step 6 for other platforms 🔗

Run unset PS_LOG_LEVEL in any existing shell. If you used docker-compose, remove the environment line in your docker-compose.yml and restart your container.

• FAQ
• Docs

Hi! I’m Matthew, the author of PhotoStructure. I’m a dad, amateur photographer, and author of open source, adtech, fintech, and edtech software since the turn of the millennium. He/him. I am building a self-hosted, safe, and fast new home for all your photos and videos.
Your memories deserve PhotoStructure. Try it out for free!