It's hard to fix it when you don't know what's wrong! That's where logs come in handy. Pagoda Box streams logs in both your dashboard and through the Pagoda CLI, allowing you to view and manage them as you like. After reading this doc, you should be familiar with:
- Viewing and managing your app's logs
- Drinking out of your log "fire-hose" and loving it
The Pagoda Logger
Stdout & Stderr
Everything pushed to stdout and stderr is captured by the Pagoda Logger.
Custom App Logs
log_watch's allow you to pipe anything written to specific files into the Pagoda Logger. More information below.
One Week Persistence
All log entries persist for one week, after which they expire and are no longer accessible.
Logs can be accessed in your app dashboard under the "Logs" tab. There are three types of available logs: Streaming, Historical, and Deploy Logs.
Streaming logs display your app's live log stream. These allow you to see errors in your application as they happen. They are an aggregated stream of everything your app's services push to stdout and stderr. Each log entry is timestamped and flagged with the service-id and specific log from which it came.
With Streaming logs, only logs entries written after the stream is started are viewable. Any log entries written prior can be viewed in Historical logs.
Historical logs contain all of your app's log entries from the last week. These help in troubleshooting issues in your running application. Each log entry is timestamped and flagged with the service-id and specific log from which it came. When viewing historical logs, the entries are loaded 100 at a time. To load more, click the "View More" button and the next 100 entries will be loaded.
Deploy logs are output streams of app's deploys and service build transactions. Theyre great for identifying causes of failed deploys and/or service builds.
Historical & Deploy Logs Persist for One Week
Historical and Deploy Logs expired after one week. Once expired, they are no longer accessible.
Logs Through the Pagoda CLI
The Pagoda CLI makes viewing logs quick and easy. Detailed information about options available to the "log" command can be found here. Below are just a view simple examples of how to view logs from the CLI.
Viewing Logs Through the Pagoda CLI Terminal
# View the last 500 historical log entries $ pagoda log -a app-name -c 500 # Stream app logs $ pagoda log -a app-name -l
Deploy Logs Not Viewable in the CLI
Past deploy logs can only be reviewed in the dashboard. They are not accessible through the CLI.
Custom Application Logs
If your app stores logs in a custom log file or files, you can us a Boxfile
log_watch to pipe anything written to those files into the Pagoda Logger.
log_watch conists of the following:
A Key - This is prepended to log entries originating from the log_watch'd file. Keys must be unique.
A Filepath - The path to the actual log file.
# Pattern web1: log_watch: key: "path/to/log.file" # Example web1: log_watch: laravel[error]: "app/storage/logs/laravel.log" api[auth]: "app/logs/api_auth.log"
You Can Only log_watch Individual Files
Log watches only work on individual files. You cannot log_watch a directory.
Log Filepaths Must Be Relative to the Root of Your Repo
When specying the path to your log file, the filepath should be relative to the root of your app's repo. Don't use the absolute server path (
Key Naming Restrictions
Log_watch "keys" can not contain special characters other than brackets
. For logs captured by Pagoda Box, we use the following pattern:
abc124[abc123], but you're not bound to this.
Keys Must Be Unique
Log_watch keys must be unique. If you have identical keys, only one will be watched and there's no guarantee which one it will be.
Log_watch'd Files Are Writable
Any files specified as a log_watch will be given writable permissions. These files do not need to be stored in a network directory.
Logs Aren't Actually Written to log_watch'd Files
While log_watch'd files have writable permissions, the files themselves don't actually get updated. Log_watch'd files are symlinked to a centralized file that is piped into the Pagoda Logger. If you SSH into your code service and inspect log_watch'd files, you'll see the contents of the centralized log file.
Log_watch'd Logs Persist for 1 Week
Because logs gathered from log_watch'd files are piped into the Pagoda Logger, they are subject to the Pagoda Logger expiration (1 week).
PHP & Apache Logs
Certain PHP and Apache (httpd) logs can be enabled/disabled in the Boxfile for PHP services. These settings will not change the error reporting set in the application. They simply toggle whether or not the logs are output to your application log stream.
Enabling/Disabling PHP & Apache Logs in the Boxfile YAML
# default settings web1: type: php httpd_access_log: false httpd_error_log: true php_error_log: true php_fpm_log: true
To change the actual level of error reporting use the following settings:
Table of Contents
- You Can Only log_watch Individual Files
- Log Filepaths Must Be Relative to the Root of Your Repo
- Key Naming Restrictions
- Keys Must Be Unique
- Log_watch'd Files Are Writable
- Logs Aren't Actually Written to log_watch'd Files
- Log_watch'd Logs Persist for 1 Week
If you have any questions, suggestions, or corrections, let us know.