Log Management

Last Updated October 2014

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

The Pagoda Logger is a centralized logging system that captures and persists all application logs. These logs can be accessed through both your dashboard and the Pagoda CLI.

Stdout & Stderr

Everything pushed to stdout and stderr is captured by the Pagoda Logger.

Custom App Logs

Boxfile 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.

Dashboard Logs

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

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

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

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.

A log_watch conists of the following:

  1. A Key - This is prepended to log entries originating from the log_watch'd file. Keys must be unique.

  2. A Filepath - The path to the actual log file.

log_watch YAML

  # 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"

/Boxfile

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 ( /data ).

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
/Boxfile

To change the actual level of error reporting use the following settings:

PHP Error Reporting
Apache Log Level

If you have any questions, suggestions, or corrections, let us know.