logging

Herokuにおけるログとは、アプリケーションが実行中のプロセス、システムコンポーネント、後方で実行されるサービスの各アウトプットから収集された時系列イベントのストリームのことです。HerokuのLogplexは、このような多種多様なソースからのログのストリームを単一のチャンネルへルーティングし、実に理解し易いログを収集するための基礎を提供します。

ログのタイプ

Herokuは、アプリケーションから3つのカテゴリのログを収集します。:

• App logs - アプリケーションからのアウトプットです。アプリケーション、アプリケーションサーバー、ライブラリ内から生成されるログを含むこととなります。（--source appでフィルターして下さい: ）

• System logs - Messages about actions taken by the Heroku platform infrastructure on behalf of your app, such as: restarting a crashed process, idling or unidling a web dyno, or serving an error page due to a problem in your app. (Filter: --source heroku)

• System logs - アプリケーションに代わって、Herokuのインフラが実行するアクションに関するメッセージ群です。以下のようなアクションがあります。: クラッシュしたプロセスの再起動、web dynoをアイドリングさせる、またはアイドリングから復帰させる、アプリケーションの問題によりエラーページを提供すると言ったアクションがあります。

• API logs - Messages about administrative actions taken by you and other developers working on your app, such as: deploying new code, scaling the process formation, or toggling maintenance mode. (Filter: --source heroku --ps api)

Writing to your log

Anything written to standard out (stdout) or standard error (stderr) is captured into your logs. This means that you can log from anywhere in your application code with a simple output statement.

In Ruby, you could use something like:

:::ruby
puts "Hello, logs!"

In Java:

:::java
System.err.println("Hello, logs!");
System.out.println("Hello, logs!");

The same holds true for all other languages supported by Cedar.

Log retrieval

To fetch your logs:

:::term
$ heroku logs
2010-09-16T15:13:46-07:00 app[web.1]: Processing PostController#list (for 208.39.138.12 at 2010-09-16 15:13:46) [GET]
2010-09-16T15:13:46-07:00 app[web.1]: Rendering template within layouts/application
2010-09-16T15:13:46-07:00 app[web.1]: Rendering post/list
2010-09-16T15:13:46-07:00 app[web.1]: Rendered includes/_header (0.1ms)
2010-09-16T15:13:46-07:00 app[web.1]: Completed in 74ms (View: 31, DB: 40) | 200 OK [http://myapp.heroku.com/]
2010-09-16T15:13:46-07:00 heroku[router]: GET myapp.heroku.com/posts queue=0 wait=0ms service=1ms bytes=975
2010-09-16T15:13:47-07:00 app[worker.1]: 2 jobs processed at 16.6761 j/s, 0 failed ...

In this example, the output includes log lines from one of the app's web dynos, the Heroku HTTP router, and one of the app's workers.

The logs command retrieves 100 log lines by default. You can fetch up to 1500 lines using the --num (or -n) option:

:::term
$ heroku logs -n 200

Log format

Each line is formatted as follows:

timestamp source[process]: message

• Timestamp - The date and time recorded at the time the log line was produced by the process or component.
• Source - All of your app's processes (web processes, background workers, cron) have a source of app. All of Heroku's system components (HTTP router, process manager) have a source of heroku.
• Process - The name of the process or component that wrote this log line. For example, worker #3 appears as worker.3, and the Heroku HTTP router appears as router.
• Message - The content of the log line.

Realtime tail

Similar to tail -f, realtime tail displays recent logs and leaves the session open for realtime logs to stream in. By viewing a live stream of logs from your app, you can gain insight into the behavior of your live application and debug current problems.

You may tail your logs using --tail (or -t).

:::term
$ heroku logs --tail

When you are done, press Ctrl-C to close the session.

Filtering

If you only want to fetch logs with a certain source, a certain process, or both, you can use the --source (or -s) and --ps (or -p) filtering arguments:

:::term
$ heroku logs --ps router
2012-02-07T09:43:06+00:00 heroku[router]: GET devcenter.heroku.com/stylesheets/dev-center/library.css dyno=web.5 queue=0 wait=0ms service=3ms status=200 bytes=1753
2012-02-07T09:43:06+00:00 heroku[router]: GET devcenter.heroku.com/articles/bundler dyno=web.6 queue=0 wait=0ms service=61ms status=200 bytes=20375

$ heroku logs --source app
2012-02-07T09:45:47+00:00 app[web.1]: Rendered shared/_search.html.erb (1.0ms)
2012-02-07T09:45:47+00:00 app[web.1]: Completed 200 OK in 83ms (Views: 48.7ms | ActiveRecord: 32.2ms)
2012-02-07T09:45:47+00:00 app[worker.1]: [Worker(host:465cf64e-61c8-46d3-b480-362bfd4ecff9 pid:1)] 1 jobs processed at 23.0330 j/s, 0 failed ...
2012-02-07T09:46:01+00:00 app[web.6]: Started GET "/articles/buildpacks" for 4.1.81.209 at 2012-02-07 09:46:01 +0000

$ heroku logs --source app --ps worker
2012-02-07T09:47:59+00:00 app[worker.1]: [Worker(host:260cf64e-61c8-46d3-b480-362bfd4ecff9 pid:1)] Article#record_view_without_delay completed after 0.0221
2012-02-07T09:47:59+00:00 app[worker.1]: [Worker(host:260cf64e-61c8-46d3-b480-362bfd4ecff9 pid:1)] 5 jobs processed at 31.6842 j/s, 0 failed ...

When filtering by process, either the base name, --ps web, or the full name, --ps web.1, may be used.

You can also combine the filtering switches with --tail to get a realtime stream of filtered output.

:::term
$ heroku logs --source app --tail

Syslog drains

Logplex drains allow you to forward your Heroku logs to an external syslog server for long-term archiving. You must configure the service or your server to be able to receive syslog packets from Heroku, and then add its syslog URL (which contains the host and port) as a syslog drain. Drain logs are delivered via the syslog TCP protocol and the octet counting framing method.

Visit Heroku Add-ons to find log management services.

Creating your own Syslog drain

You can run a standalone EC2 instance with Ubuntu and rsyslog. To begin, boot an instance and allow Heroku's servers access to the syslog port:

:::term
$ ec2-run-instances -t t1.micro ami-6006f309
$ ec2-authorize default -P tcp -p 514 -u 098166147350 -o logplex

After the instance has booted, ssh to it and edit /etc/rsyslog.conf to add the following lines:

# provides TCP syslog reception
$ModLoad imtcp
$InputTCPServerRun 514

Restart rsyslog:

:::term
$ restart rsyslog

Now your instance is ready to receive syslog messages from Heroku. Cut and paste your EC2 instance public IP or hostname into a drains add command:

:::term
$ heroku drains:add syslog://host1.example.com:514
Drain syslog://host1.example.com:514 added to myapp

You can add multiple drains:

:::term
$ heroku drains:add syslog://host2.example.com:9999
Drain syslog://host2.example.com:9999 added to myapp

And get a list of existing drains:

:::term
$ heroku drains
syslog://host1.example.com:514
syslog://host2.example.com:9999

To remove a drain:

:::term
$ heroku drains:remove syslog://two.example.org:584
Removing syslog drain... done

Security Access

When you use EC2 security groups, the hostname used when you add the drain must resolve to the 10/8 private IP address of your instance (which must be in the us-east Amazon region). If you use the EC2 public IP address, or a name that resolves to the public IP address, then logplex will not be able to connect to your drain.