SimpleRotate

The documentation for version 1.1.0

Definitions

• ログを書き込むファイル名をログファイルと表記することがあります。
• ログファイルに書き込む内容(#w(message)のmessageの部分)をログと表記することがあります。

Jump quickly

• Public Class Methods
  • instance
• Public Instance Methods
  • init
  • with_stdout
  • compress
  • compress_level
  • w
  • <<
  • enable_wflush
  • disable_wflush
  • e
  • reopen
  • flush
  • threshold
  • logging_format
  • date_format
  • rename_format
  • no_wcheck
  • file_closed?
  • debug
  • info
  • warn
  • error
  • fatal
  • sleep_time
  • psync
  • sync_inode
  • no_sync_inode

Public Class Methods

instance

SimpleRotateクラスはSingletonパターンで実装されています。 従って返却するオブジェクトは唯一のSimpleRotateオブジェクトです。 initilizeメソッドがprivateになりオブジェクトからのアクセスはできないためnewメソッドを使うとエラーなります。

Returns

SimpleRotateオブジェクトを返します。

Public Instance Methods

init([file_name, [limit, [generation]]])

ログの取り方に関する設定をします。

ここで設定した内容は、後にSimpleRotate::instanceで返されるオブジェクトも保持し続けます。返り値はselfです。

Returns

SimpleRotateオブジェクトを返します。

Parameters

• file_name = File.absolute_path($0+".log")

ログを書き込むファイル名をStringかSymbolで指定します。デフォルトは./実行ファイル名.logです。フルパス、もしくは相対パスで指定します。 相対パスの場合は、実行ファイルが起点になります。指定したファイルが存在しない場合はこのタイミングでファイルが生成されます。

ファイルの1行目はローテーションに関する情報です。この行は消さないでください。

ここで指定したファイルと同じファイルが存在する場合、そのファイルに追加書き込みします。ファイルではなく標準出力のみに出力したい場合はシンボルで:STDOUTと指定します。

• limit = "100M"

ログファイルの最大サイズをIntegerもしくは"1G"等の文字列で指定します。"K", "M", "G"が認識されます。デフォルトは"100M"です。 例えばSimpleRotate.init("/var/log/ruby/app/foo.log", "500M")と指定すると 500MB までファイルにログを書き込みます。

500MBと書いてはいけません。認識するのは末尾の"K", "M", "G"だけです。それ以外の文字列はto_iによって排除されます。従って500MBと書いたときは500バイトと認識されます。

initメソッド、wメソッドでログファイルのサイズを評価し ここで指定した設定値を超えていた場合、次のファイルに書き込みます。
その際、古いファイルはfile_name.1, file_name.2, file_name.3, file_name.4のようにリネームされ、古いログファイルほど古い数字が記されることになります。

また、"DAILY", "WEEKLY", "MONTHLY"を指定することでファイルの容量でなく一定の期日ごとにローテーションする事も可能です。 その場合は、それぞれログを書き込んだファイルの作成日を起点に1日毎, 7日毎, 30日毎に次のファイルに書き込みされます。 次のファイルにログを書き込む際に古いファイル名はfile_name.YYYYmmddというフォーマットでリネームされます。

• generation=0

古いログファイルの最大数を指定します。古いログファイルはここで指定した数で世代交代します。

例えばgenerationに4を設定すると、古いログファイルはfile_name.1, file_name.2, file_name.3, file_name.4の 4世代まで作られます。 この場合、新しいログファイルを入れると最大 5つのファイルでローテーションします。

値を0に設定すると世代交代は行わません。デフォルトは0ですので世代交代は行われません。

ブロック付きでコールする事もできます。ブロックを抜けると自動でログファイルの I/O ポートを閉じます。

For Example

logger = SimpleRotate.instance

logger.init("foo.log") do |sr|
  sr << "log message"
end

logger.init("bar.log") do |sr|
  sr << "log message"
end

with_stdout

ログを標準出力(STDOUT)にも出すようにします。

Returns

返り値はありません。nilを返します。

compress

ローテーションする際に古いログファイルを gzip 圧縮します。zlibを読み込みます。デフォルトは圧縮は行いません。 initメソッドでログファイルのローテーションが行われる可能性がある為initメソッドの前に行うべきです。

Returns

返り値はありません。nilを返します。

compress_level(level)

古いログファイルを圧縮する際の圧縮レベルを指定します。数字が高い方が圧縮度が高くなります。デフォルトの圧縮レベルはZlib::DEFAULT_COMPRESSIONです。 このメソッドを呼び出すとログファイルの圧縮が有効に切り替わります。

Returns

返り値はありません。nilを返します。

Parameters

• lelvel

圧縮レベルを0-9までのIntegerで指定します。

w(log_message)

パラメータlog_messageをログファイルに書き込みます。

ここでログファイルに書き込むログは必ず深刻度（ログレベル）の情報を持ちます。 直近に実行したログレベルを決めるメソッド(#debug,#info,#warn,#error,#fatal)でログレベルは決まります。 一度ログレベルを決めたあとはログレベルの情報は保持され続けます。 ログレベルを決めるメソッドが一度も実行されてないオブジェクトはINFOをログレベルに持ちます。

Returns

引数で指定したlog_messageを返します。

Parameters

• log_message

ログファイルに出力するログを指定します。stringでなくてもintegerやfloatでも構いません。arrayを指定する事も可能です。

For Example

logger = SimpleRotate.instance
logger.init("/var/log/ruby/app/foo.log")
ary = [111, 333, 555]
logger.w ary
logger.error.w("エラーです")

下記のようにログファイルに出力されます。

[2014/01/15 19:44:22] - INFO : [111, 333, 555]
[2014/01/15 19:44:22] - ERROR : エラーです

<< log_message

#wのエイリアスです。

For Example

logger = SimpleRotate.instance
logger.init("/var/log/ruby/app/foo.log")
logger << "エラーです"

enable_wflush

#wを呼び出した後 I/Oポートの内部バッファをフラッシュします。

Returns

返り値はありません。nilを返します。

disable_wflush

#wを呼び出した後 I/Oポートの内部バッファをフラッシュしません。デフォルトはこの挙動です。

Returns

返り値はありません。nilを返します。

e

ログファイルの I/Oポートを閉じます。

Returns

#initのパラメータfile_nameに:STDOUTを指定した場合はnilを返します。それ以外はtrueを返します。

reopen

閉じたログファイルの I/Oポートを開きます。

Returns

ログを記録するファイルのFile classのオブジェクトを返します。

#initのパラメータfile_nameに:STDOUTを指定した場合はnilを返します。また、I/Oポートを閉じていない時に呼び出すと WARNINGメッセージを出しnilを返します。

flush

新しくファイルを生成し、今後はそのファイルにログを書き込むようにします。 ファイルサイズがlimitに満たないファイルをローテーションしたい時に使います。

Returns

#initのパラメータlimitに"DAILY"や"WEEKLY"などのファイルサイズ以外のものを指定した場合はローテーションせずnilを返します。 #initのパラメータfile_nameに:STDOUTを指定した場合も同様にnilを返します。

threshold [= log_level]

全てのログは"DEBUG" > "INFO" > "WARN" > "ERROR" > "FATAL"までのログレベルを持ちます。左から右にかけてログの深刻度は増していきます。 ここで指定するのはどのログレベル以降のログをログファイルに出力するかです。

例えば、ERRORを閾値に指定するとERRORもしくはそれ以上のログレベルを持つFATALをログだけがログファイルに出力されるようになります。

Returns

現在値をstringで返します。

Parameters

• log_lelvel

DEBUG,INFO,WARN,ERROR,FATALのいずれかをstringで指定します。デフォルトはINFOです。

For Example

logger = SimpleRotate.instance
logger.init("/var/log/ruby/app/foo.log", "DAILY")

# ERROR 以上のログレベルを持つログだけがファイルに出力されます。
logger.threshold = "ERROR"

logger.debug << "message" #=> DEBUG は書き込まれません。
logger.info << "message" #=> INFO は書き込まれません。
logger.warn << "message" #=> WARN は書き込まれません。
logger.error << "message" #=> ERROR は書き込まれます。
logger.fatal << "message" #=> FATAL は書き込まれます。

logging_format [= format]

ファイルにログを出力する際のフォーマットを指定します。デフォルトのformatの値は"[$DATE] - $LEVEL : $LOG"です。

Returns

現在値をstringで返します。

Parameters

• format

stringで指定します。フォーマットで使用できる定数は以下です。

• $DATE - 日付です。日付のフォーマットは #date_format で定義できます。
• $PID - プログラムのプロセスIDです。
• $LEVEL - ログのレベルです。
• $LOG - ログすなわち #w(message) の message です。
• $FILE - 現在実行中の Ruby スクリプトのファイル名(ファイル名のみ)です。
• $FILE-FUL - 現在実行中の Ruby スクリプトのファイル名(絶対パス)です。

For Example

logger = SimpleRotate.instance
logger.init("/var/log/ruby/app/foo.log", "1G")
logger << "message"

下記のようにログファイルに出力されます。

[2013/10/23 20:15:13] - INFO : message

For Example

logger = SimpleRotate.instance
logger.init("/var/log/ruby/app/foo.log", "1G")

logger.logging_format = "[$LEVEL] : $DATE => $LEVEL: [$LOG] @ $FILE-FUL"
logger.fatal << "message"

下記のようにログファイルに出力されます。

[FATAL] : 2013/10/23 20:15:13 => FATAL: [message] @ /var/log/ruby/app/foo.log

date_format [= format]

ログをファイルに出力する時の $DATE のフォーマットを指定します。 デフォルトは"%Y/%m/%d %H:%M:%S"ですので日付のフォーマットは2013/10/04 20:04:59のようになります。

Returns

現在値をstringで返します。

Parameters

• format

stringで指定します。formatの書式はDate#strftime(format)の引数と同様です。

For Example

logger = SimpleRotate.instance
logger.init("/var/log/ruby/app/foo.log", "DAILY")

logger.date_format = "%y-%m-%d %H:%M:%S"
logger << "message"

下記のようにログファイルに出力されます。

[13-10-04 20:04:59] - INFO : message

rename_format [= format]

Returns

現在値をstringで返します。

Parameters

• format

新しくログファイルを作る際に古いログファイルはリネームされます。ファイル名はfile_name.1やfile_name.20131024のような命名規則でリネームされます。 この古いファイル名の.の部分をformatで指定する任意のstringに変更できます。デフォルトは.です。

For Example

logger = SimpleRotate.instance

# init でローテーションが行われることがあるので init の前で定義します。
logger.rename_format = ".example."

logger.init("/var/log/ruby/app/foo.log", "1G")

この場合ローテーションする際にapp.log.example.1というファイル名でリネームされます。

no_wcheck

次のログファイルを作成するべきかどうかの判断は#wか#initで行われます。

このメソッドをコールすると#w実行時にローテーションを行うべきかチェックを行いません。従って#w の実行によってファイルのローテーションは行われません。

Returns

返り値はありません。nilを返します。

file_closed?

ログファイルがI/Oポートが閉じているかどうかを調べます。

Returns

ログファイルのI/Oポートが開いているときはtrue、それ以外でfalseを返します。 なお、#initのパラメータfile_nameに:STDOUTを指定した場合はnilを返します。

silence

WARNINGメッセージを出力しないようにします。 WARNINGメッセージとはSimpleRotateクラス内部で予期せぬ状況が発生した時に標準エラー出力に吐かれる[WARNING] File is already open! - (SimpleRotate::Error) のようなメッセージです。

Returns

返り値はありません。nilを返します。

debug

ログレベルをDEBUGにします。DEBUGはデバッグ用のログです。

Returns

SimpleRotateオブジェクトを返します。従ってそのままメソッドチェインで#wにつなぐことができます。

info

ログレベルをINFOにします。INFOはプログラム上のある特定の情報を知らせるログです。

Returns

SimpleRotateオブジェクトを返します。従ってそのままメソッドチェインで#wにつなぐことができます。

warn

ログレベルをWARNにします。WARNは深刻なエラーではありませんが警告を促すログです。

Returns

SimpleRotateオブジェクトを返します。従ってそのままメソッドチェインで#wにつなぐことができます。

error

ログレベルをERRORにします。ERRORはエラーを知らせるログです。

Returns

SimpleRotateオブジェクトを返します。従ってそのままメソッドチェインで#wにつなぐことができます。

fatal

ログレベルをFATALにします。FATALはプログラムが停止するような致命的なログです。

Returns

SimpleRotateオブジェクトを返します。従ってそのままメソッドチェインで#wにつなぐことができます。

For Example

logger = SimpleRotate.instance
logger.init("/var/log/ruby/app/foo.log")
logger.warn << "log message"
logger << "log message" # 省略してもログレベルは"WARN"を引き継ぎます。
logger.fatal << "log message"
logger << "log message" # 省略してもログレベルは"FATAL"を引き継ぎます。

以下のようにログファイルに書き込まれます。

[2013/12/16 14:15:03] - WARN : log message
[2013/12/16 14:15:03] - WARN : log message
[2013/12/16 14:15:03] - FATAL : log message
[2013/12/16 14:15:03] - FATAL : log message

sleep_time [= sec]

ログファイルのローテーションが完了したあと停止する時間を秒で指定します。これはマルチスレッド、マルチプロセスの際に重要です。 シングルで動かす場合は特に呼び出す意味はありません。この値は#psyncのパラメータでも指定可能です。

もし複数のスレッドやプロセスが同時にローテーションを行ってしまう場合はこの値を大きくしてみてください。 実際にリネームが行われるまでのオーバーヘッドを考慮しての事です。

Returns

現在値をfloatもしくはfixnumで返します。

Parameters

• sec

floatもしくはfixnumで指定します。デフォルトは0.1です。#psyncをコールしてない場合は0です。

psync(sec=0.1)

プロセス間でクリティカルセクションを排他制御し、複数のプロセスによる実行でも安全にロギングできるようにします。#initにクリティカルセクションがある為#initの前に行うべきです。 書き込みの際に inode番号を調べ常に新しいファイルに書き込みできるように同期を試みます。また、書き込みのあと I/Oポートの内部バッファをフラッシュします。

このメソッドをコールすると排他制御用の一時ファイルが生成されます。 一時ファイルは.SimpleRotate_tempfile_【プログラムのファイル名】という命名規則でログファイルと同じディレクトリに生成され、Ruby の終了処理で削除されるようにスケジューリングされます。 一時ファイル生成の際に既に同じ名前のファイルが存在する場合や終了処理で一時ファイルが空でない場合や削除するパーミッションがない場合は一時ファイルの削除は実行されません。 通常起こり得ませんがロック取得時に予期しないエラーが起きると3回まで再びロック取得を試みます。3度目が失敗するとロックを取得しないで処理を行います。

Returns

返り値はありません。nilを返します。

Parameters

• sec

ログファイルのローテーションが完了したあと停止する時間を秒で指定します。floatもしくはfixnumで指定します。デフォルトは0.1です。

For Example

logger = SimpleRotate.instance
logger.psync(0.5)
logger.init("/var/log/ruby/app/foo.log")

sync_inode

現在開いているファイルの inode番号と#initのfile_nameで指定したファイルの inode番号を比較し差異を確認した場合file_nameで指定したファイルを開き直します。これは#w呼び出し時に自動で行われるのであまり意識して呼び出すメソッドではありません。

Returns

inode番号に差異があった場合やなんらかの原因で inode番号を取得できない場合は最大で 3回開き直し、それでも inode番号が一致しなければ WARNINGメッセージを出力しfalseを返します。 ログファイルが正常に開けていない場合や#initのfile_nameに:STDOUTを指定している場合はnilを返します。 それ以外ではtrueを返します。

no_sync_inode

現在開いているファイルの inode番号と#initのfile_nameで指定したファイルの inode番号を比較しません。 シングルスレッド、シングルプロセス時に使用すべきです。

Returns

返り値はありません。nilを返します。

Required

SimpleRotateクラスが使用している標準添付ライブラリです。

singleton

monitor

zlib

Classes

SimpleRotate::Error

SimpleRotateクラス内での例外を取り扱う内部クラスです。 基本的にSimpleRotateクラス内部で発生し得るエラーはこの例外です。

SimpleRotate::ProcessSync

プロセス間で安全にロギングするための機能を提供する内部クラスです。 SimpleRotate::ProcessSyncMixinをMix-inしています。

Modules

SimpleRotateクラス内で使用している内部モジュールです。

SimpleRotate::LogLevel

SimpleRotate::RotateTerm

SimpleRotate::ProcessSyncMixin

SimpleRotate::Validator