Logging
Logging モジュールは、計算の履歴や進行状況をイベントログとして記録する機能を提供します。イベントは、たとえば次のように、ソースコードにログ出力文を挿入して生成します。
@warn "Abandon printf debugging, all ye who enter here!"
┌ Warning: Abandon printf debugging, all ye who enter here!
└ @ Main REPL[1]:1ソースコードのあちこちに println() の呼び出しを埋め込む方法と比べて、このシステムにはいくつかの利点があります。まず、ソースコードを編集せずにメッセージの表示や形式を制御できます。たとえば、上記の @warn とは異なり、
@debug "The sum of some values $(sum(rand(100)))"は、デフォルトでは何も出力しません。また、後で無視されるメッセージは評価されないため、このようなデバッグ文をソースコードに残しておいても、ほとんどコストはかかりません。この場合、デバッグログが有効になっていない限り、sum(rand(100)) と、それに伴う文字列処理は実行されません。
次に、ログ機能では、任意のデータをキーと値のペアとして各イベントに付加できます。これにより、ローカル変数やその他のプログラム状態を記録し、後で分析できます。たとえば、ローカル配列変数 A とベクトル v の合計を、キー s の値として付加するには、次のようにします。
A = ones(Int, 4, 4)
v = ones(100)
@info "Some variables" A s=sum(v)
# output
┌ Info: Some variables
│ A =
│ 4×4 Matrix{Int64}:
│ 1 1 1 1
│ 1 1 1 1
│ 1 1 1 1
│ 1 1 1 1
└ s = 100.0すべてのログマクロ @debug、@info、@warn、@error には共通の機能があり、より汎用的なマクロ @logmsg のドキュメントで詳しく説明されています。
Log event structure
各イベントには複数のデータが含まれます。ユーザーが指定するものもあれば、自動的に取得されるものもあります。まず、ユーザーが指定するデータを見てみましょう。
ログレベルは、メッセージの大まかな分類で、早期フィルタリングに使われます。標準のレベルには
LogLevel型のものがいくつかあり、ユーザー定義のレベルも使用できます。それぞれ用途が異なります。Logging.Debug(ログレベル -1000)は、プログラム開発者向けの情報です。このイベントはデフォルトで無効になっています。Logging.Info(ログレベル 0)は、ユーザー向けの一般的な情報です。printlnを直接使う代わりになるものと考えてください。Logging.Warn(ログレベル 1000)は、問題が発生して対応が必要になる可能性はあるものの、現時点ではプログラムが動作を続けていることを示します。Logging.Error(ログレベル 2000)は、問題が発生し、少なくともこのコード部分では復旧が難しいことを示します。例外をスローすれば必要な情報をすべて伝えられることが多いため、このログレベルは不要な場合もあります。
メッセージは、イベントを説明するオブジェクトです。慣例として、メッセージに渡される
AbstractStringは Markdown 形式とみなされます。それ以外の型は、テキストベースの出力ではprint(io, obj)またはstring(obj)を使って表示されます。また、インストールされているロガーで使われる他のマルチメディア表示では、show(io,mime,obj)が使われる場合があります。任意のキーと値のペアを使って、各イベントに任意のデータを付加できます。イベントの解釈に影響する慣例的な意味を持つキーもあります(
@logmsgを参照)。
各イベントには、システムによって次の標準情報も付加されます。
- ログマクロが展開された
module。 - ソースコード内でログマクロが現れる
fileとline。 - ログマクロが現れるソースコード文を一意に識別する固定の識別子であるメッセージ
id。この識別子は、ログ文自体が変わらない限り、ファイルのソースコードが変更されても比較的安定するように設計されています。 - イベントの
group。デフォルトでは、拡張子を除いたファイル名が設定されます。これを使うと、ログレベルより細かい分類(たとえば、すべての非推奨警告に:depwarnというグループを割り当てるなど)や、モジュールをまたいだ、あるいはモジュール内での論理的な分類ができます。
イベントの発生時刻など、有用な情報の一部がデフォルトでは含まれないことに注意してください。こうした情報の取得にはコストがかかる場合があり、また、現在のロガーが動的に取得できる情報だからです。必要に応じて時刻、バックトレース、グローバル変数の値などをイベントデータに追加する custom logger を簡単に定義できます。
Processing log events
例から分かるように、ログ文ではログイベントの出力先や処理方法を指定しません。これは、システムの合成可能性を高め、並行処理でも自然に使えるようにする重要な設計上の特徴です。そのために、次の2つの関心事を分離しています。
- ログイベントの生成は、イベントを発生させる場所と含める情報を決めるモジュール作成者の役割です。
- ログイベントの処理(表示、フィルタリング、集約、記録)は、複数のモジュールを連携するアプリケーションにまとめるアプリケーション作成者の役割です。
Loggers
イベントの処理はロガーが行います。ロガーは、イベントを受け取る最初のユーザー設定可能なコードです。すべてのロガーは AbstractLogger のサブタイプでなければなりません。
イベントが発生すると、タスクローカルなロガーを探し、見つからない場合はグローバルロガーを使います。アプリケーションコードはログイベントの処理方法を把握しており、呼び出しスタックの上位にあるため、呼び出しスタックをたどってロガーを見つけるという考え方です。つまり、ロガーは動的スコープを持ちます。(これは、モジュール作成者が明示的に指定するか、単純なグローバル変数として用意する、字句スコープのロガーを使うログフレームワークとは対照的です。そのようなシステムでは、複数のモジュールの機能を組み合わせる際にログを制御しにくくなります。)
グローバルロガーは global_logger で設定でき、タスクローカルなロガーは with_logger で制御できます。新しく生成されたタスクは、親タスクのロガーを引き継ぎます。
ライブラリには3種類のロガーが用意されています。ConsoleLogger は、REPL の起動時に使われるデフォルトのロガーです。イベントを読みやすいテキスト形式で表示し、書式やフィルタリングを簡単かつ使いやすく制御できるようにします。NullLogger は、必要に応じてすべてのメッセージを破棄するための便利なロガーで、ログ機能における devnull ストリームに相当します。SimpleLogger は非常に単純なテキスト整形ロガーで、主にログシステム自体のデバッグに使います。
カスタムロガーでは、reference section に記載されている関数をオーバーロードしてください。
Early filtering and message handling
イベントが発生すると、破棄されるメッセージの生成を避けるため、いくつかの早期フィルタリングが行われます。
- メッセージのログレベルを、グローバルな最小レベル(
disable_loggingで設定)と比較します。これは大まかな設定ですが、非常に低コストです。 - 現在のロガーの状態を取得し、
Logging.min_enabled_levelの呼び出しで得られる、ロガーにキャッシュされた最小レベルとメッセージのレベルを比較します。この動作は環境変数で上書きできます(詳細は後述)。 - 現在のロガーを引数として
Logging.shouldlog関数を呼び出します。この関数には、静的に計算できる最小限の情報(レベル、モジュール、グループ、ID)が渡されます。特に、shouldlogにはイベントidが渡され、キャッシュされた述語に基づいてイベントを早期に破棄できます。
これらのチェックをすべて通過すると、メッセージとキーと値のペアが完全に評価され、Logging.handle_message 関数を通じて現在のロガーに渡されます。handle_message() は必要に応じて追加のフィルタリングを行い、イベントを画面に表示したり、ファイルに保存したりできます。
ログイベントの生成中に発生した例外は、デフォルトで捕捉され、ログに記録されます。これにより、個々のイベントに問題があってもアプリケーションがクラッシュするのを防げます。本番システムで、あまり使われないデバッグイベントを有効にする場合に便利です。この動作は、ロガーの型ごとに Logging.catch_exceptions を拡張してカスタマイズできます。
Testing log events
ログイベントは通常のコード実行に伴う副作用ですが、特定の情報メッセージや警告をテストしたい場合もあるでしょう。Test モジュールは、ログイベントのストリームに対してパターンマッチングを行う @test_logs マクロを提供します。
Environment variables
メッセージのフィルタリングは JULIA_DEBUG 環境変数で制御できます。これは、ファイルやモジュール単位でデバッグログを有効にする簡単な方法です。JULIA_DEBUG=loading を指定して Julia を起動すると、loading.jl 内の @debug ログメッセージが有効になります。たとえば、Linux のシェルでは次のようにします。
$ JULIA_DEBUG=loading julia -e 'using OhMyREPL'
┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji due to it containing an incompatible cache header
└ @ Base loading.jl:1328
[ Info: Recompiling stale cache file /home/user/.julia/compiled/v0.7/OhMyREPL.ji for module OhMyREPL
┌ Debug: Rejecting cache file /home/user/.julia/compiled/v0.7/Tokenize.ji due to it containing an incompatible cache header
└ @ Base loading.jl:1328
...Windows では、CMD で set JULIA_DEBUG="loading" を実行すると同じ設定ができ、Powershell では $env:JULIA_DEBUG="loading" を使います。
同様に、この環境変数を使って Pkg などのモジュールや、モジュールのルート(Base.moduleroot を参照)のデバッグログを有効にできます。すべてのデバッグログを有効にするには、特別な値 all を指定します。
REPL からデバッグログを有効にするには、ENV["JULIA_DEBUG"] に対象モジュールの名前を設定します。REPL で定義された関数はモジュール Main に属します。これらの関数のログは、次のように有効にできます。
julia> foo() = @debug "foo"
foo (generic function with 1 method)
julia> foo()
julia> ENV["JULIA_DEBUG"] = Main
Main
julia> foo()
┌ Debug: foo
└ @ Main REPL[1]:1
複数のモジュールのデバッグログを有効にするには、カンマで区切って指定します。JULIA_DEBUG=loading,Main。
Examples
Example: Writing log events to a file
ログイベントをファイルに書き出すと便利な場合があります。タスクローカルロガーとグローバルロガーを使って情報をテキストファイルに書き込む例を示します。
# Load the logging module
julia> using Logging
# Open a textfile for writing
julia> io = open("log.txt", "w+")
IOStream(<file log.txt>)
# Create a simple logger
julia> logger = SimpleLogger(io)
SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}())
# Log a task-specific message
julia> with_logger(logger) do
@info("a context specific log message")
end
# Write all buffered messages to the file
julia> flush(io)
# Set the global logger to logger
julia> global_logger(logger)
SimpleLogger(IOStream(<file log.txt>), Info, Dict{Any,Int64}())
# This message will now also be written to the file
julia> @info("a global log message")
# Close the file
julia> close(io)Example: Enable debug-level messages
ログレベルが Logging.Debug 以上のメッセージをすべて通す ConsoleLogger を作成する例を示します。
julia> using Logging
# Create a ConsoleLogger that prints any log messages with level >= Debug to stderr
julia> debuglogger = ConsoleLogger(stderr, Logging.Debug)
# Enable debuglogger for a task
julia> with_logger(debuglogger) do
@debug "a context specific log message"
end
# Set the global logger
julia> global_logger(debuglogger)Reference
Logging module
Logging.Logging — Module
ログイベントのストリームを取得、フィルタリング、表示するためのユーティリティです。通常、ログイベントを作成するためにLoggingをインポートする必要はありません。@infoなどの標準ロギングマクロは、すでにBaseからエクスポートされており、デフォルトで利用できます。
Creating events
Base.CoreLogging.@logmsg — Macro
@debug message [key=value | value ...]
@info message [key=value | value ...]
@warn message [key=value | value ...]
@error message [key=value | value ...]
@logmsg level message [key=value | value ...]情報レベルのログレコードを作成するには、messageを指定します。利便性のため、標準の重大度レベルであるDebug、Info、Warn、Errorでログを記録する4つのマクロ、@debug、@info、@warn、@errorが定義されています。@logmsgを使うと、levelを任意のLogLevelまたはカスタムのログレベル型に、プログラムから設定できます。
messageには、ログイベントを人が読める形で説明する文字列を返す式を指定します。慣例として、この文字列は表示時にMarkdown形式で整形されます。
省略可能なkey=valueのペアのリストを使うと、任意のユーザー定義メタデータをログレコードの一部としてロギングバックエンドに渡せます。value式だけを指定した場合は、Symbolを使って、その式を表すキーが生成されます。たとえば、xはx=xに、foo(10)はSymbol("foo(10)")=foo(10)になります。キーと値のペアのリストをスプラットするには、通常のスプラット構文@info "blah" kws...を使います。
自動生成されるログデータを上書きできるキーもあります。
_module=modを使うと、メッセージのソース位置から特定されるモジュールとは別のモジュールを指定できます。_group=symbolを使うと、メッセージグループを上書きできます(通常はソースファイルのベース名から決定されます)。_id=symbolを使うと、自動生成される一意なメッセージ識別子を上書きできます。異なるソース行で生成されたメッセージを厳密に関連付ける必要がある場合に便利です。_file=stringと_line=integerを使うと、ログメッセージの見かけ上のソース位置を上書きできます。
慣例的な意味を持つキーと値のペアもあります。
maxlog=integerは、メッセージの表示回数をmaxlog回以下にするよう、バックエンドに伝えるヒントとして使います。exception=exは、例外をログメッセージとともに渡すために使います。多くの場合、@errorと組み合わせます。関連するバックトレースbtは、タプルexception=(ex,bt)を使って付加できます。
Examples
@debug "Verbose debugging information. Invisible by default"
@info "An informational message"
@warn "Something was odd. You should pay attention"
@error "A non fatal error occurred"
x = 10
@info "Some variables attached to the message" x a=42.0
@debug begin
sA = sum(A)
"sum(A) = $sA is an expensive operation, evaluated only when `shouldlog` returns true"
end
for i=1:10000
@info "With the default backend, you will only see (i = $i) ten times" maxlog=10
@debug "Algorithm1" i progress=i/10000
endBase.CoreLogging.LogLevel — Type
LogLevel(level)ログレコードの重大度/詳細度。
ログレベルは、ログレコードのデータ構造を構築するための処理を始める前に、ログレコード候補をフィルタリングするための基準となります。
Examples
julia> Logging.LogLevel(0) == Logging.Info
trueBase.CoreLogging.Debug — Constant
DebugLogLevel(-1000) の別名。
Base.CoreLogging.Info — Constant
InfoLogLevel(0) の別名。
Base.CoreLogging.Warn — Constant
WarnLogLevel(1000)の別名。
Base.CoreLogging.Error — Constant
ErrorBase.CoreLogging.BelowMinLevel — Constant
BelowMinLevelLogLevel(-1_000_001) の別名。
Base.CoreLogging.AboveMaxLevel — Constant
AboveMaxLevelLogLevel(1_000_001) の別名。
Processing events with AbstractLogger
イベント処理は、AbstractLogger に関連付けられた関数をオーバーライドして制御します。
| 実装するメソッド | 概要 | |
|---|---|---|
Logging.handle_message | ログイベントを処理する | |
Logging.shouldlog | イベントを早期にフィルタリングする | |
Logging.min_enabled_level | 受け入れるイベントのログレベルの下限 | |
| 任意のメソッド | デフォルト定義 | 概要 |
Logging.catch_exceptions | true | イベント評価中の例外を捕捉する |
Base.CoreLogging.AbstractLogger — Type
ロガーは、ログレコードをどのようにフィルタリングし、振り分けるかを制御します。ログレコードが生成されると、ロガーはそのレコードを調べ、処理方法を決定できる最初のユーザー設定可能なコードです。
Base.CoreLogging.handle_message — Function
handle_message(logger, level, message, _module, group, id, file, line; key1=val1, ...)levelで、loggerにメッセージを記録します。メッセージが生成された論理上の位置は、モジュール_moduleとgroupで示されます。ソース上の位置は、fileとlineで示されます。idは任意の一意な値(通常はSymbol)で、フィルタリング時にログ文を識別するキーとして使用します。
Base.CoreLogging.shouldlog — Function
shouldlog(logger, level, _module, group, id)logger が _module 用に生成されたメッセージを level で受け付けたとき、group と一意のログ識別子 id を含む true を返します。
Base.CoreLogging.min_enabled_level — Function
min_enabled_level(logger)早期フィルタリングに使用する、loggerの有効な最小レベルを返します。つまり、このログレベル以下のメッセージはすべてフィルタリングされます。
Base.CoreLogging.catch_exceptions — Function
catch_exceptions(logger)ログレコードの構築中に発生した例外をロガーで捕捉する場合は、trueを返します。デフォルトでは、メッセージは捕捉されます。
デフォルトでは、ログメッセージの生成によってプログラムがクラッシュしないよう、すべての例外が捕捉されます。これにより、デバッグログなど、あまり使われない機能を本番システムで安心して有効・無効に切り替えられます。
ログを監査証跡として使用する場合は、ロガーの型でこの設定を無効にしてください。
Base.CoreLogging.disable_logging — Function
disable_logging(level)level 以下のログレベルのログメッセージをすべて無効にします。この設定はグローバルに適用され、デバッグログを無効にしたときのコストを極めて低く抑えることを目的としています。ただし、ほかの仕組みによってすでに無効になっているログを有効にすることはできません。
Examples
Logging.disable_logging(Logging.Info) # Disable debug and infoUsing Loggers
ロガーの設定と確認:
Base.CoreLogging.global_logger — Function
global_logger()現在のタスクに固有のロガーが存在しない場合にメッセージを受け取るために使用される、グローバルロガーを返します。
global_logger(logger)グローバルロガーをloggerに設定し、以前のグローバルロガーを返します。
Base.CoreLogging.with_logger — Function
with_logger(function, logger)functionを実行し、すべてのログメッセージをloggerに出力します。
Examples
function test(x)
@info "x = $x"
end
with_logger(logger) do
test(1)
test([1,2])
endBase.CoreLogging.current_logger — Function
current_logger()現在のタスクにロガーが設定されていればそれを返し、設定されていなければグローバルロガーを返します。
システムに用意されているロガー:
Base.CoreLogging.NullLogger — Type
NullLogger()すべてのメッセージを無効にし、何も出力しないロガー。ロガー版の /dev/null。
Base.CoreLogging.ConsoleLogger — Type
ConsoleLogger([stream,] min_level=Info; meta_formatter=default_metafmt,
show_limited=true, right_justify=0)Julia REPLでの対話的な作業など、テキストコンソールでの読みやすさを重視して最適化されたロガーです。
min_level 未満のログレベルはフィルタリングされます。
このロガーはスレッドセーフです。メッセージ数の制限(maxlog)の管理と、ストリームへの書き込みの両方でロックを使用します。
キーワード引数を設定すると、メッセージの書式を制御できます。
meta_formatterは、ログイベントのメタデータ(level, _module, group, id, file, line)を受け取り、ログメッセージの色(printstyled に渡す値)、プレフィックス、サフィックスを返す関数です。デフォルトでは、ログレベルをプレフィックスにし、モジュール、ファイル、行の位置情報をサフィックスにします。show_limitedは、書式設定時に:limitIOContextキーを設定することで、大きなデータ構造の出力を画面に収まる程度に制限します。right_justifyは、ログメタデータを右揃えで表示する列番号を指定する整数です。デフォルトは 0 で、この場合メタデータは独立した行に表示されます。
Base.CoreLogging.SimpleLogger — Type
SimpleLogger([stream,] min_level=Info)min_level以上のレベルのメッセージをすべてstreamに記録する、シンプルなロガーです。ストリームが閉じている場合、ログレベルがWarn以上のメッセージはstderrに、それより低いメッセージはstdoutに記録されます。
このロガーはスレッドセーフです。メッセージ数の制限(maxlog)の調整とストリームへの書き込みは、ロックを取得して行われます。