📝

Unity Loggingのハマりポイントまとめ

2023/12/18に公開

Unity

ログ

tech

概要

Unity公式のLoggingパッケージであるUnity Loggingが非常に良いとTwitterで見たので、
触ってみました。そこで得られたハマりポイントを、まとめた記事になります。

Unity Loggingとは？

Unityで昔から使用されてきたDebug.Log()を更に高機能化させたパッケージ。

・ログレベルを6段階で指定できる
・json形式でのロギング対応
・表示する最小のログレベルの指定
など、多くの機能を有している。

導入方法

PackageManagerからPackage: Unity Registry を選択し、
Unity Loggingと検索で導入できる。

公式に記載は無いが、いくつかのバージョンで試した感じ、
UnityLoggingのバージョン1.0.16は
Unityのバージョンが2022.3以上でないと検索に表示されない。

ログ出力

重要度は低い順にVerbose < Debug < Info < Warning < Error < Fatal。
デフォルトではDebug以上のログしか出力されない。
それぞれ Log.Error(""), Log.Info("")のように書くことで、
重要度に応じたログの記録が可能になる。

後述の方法でjsonファイルに出力する時に、Propertiesにキーワードを追加したい場合、
Log.Fatal("Fatal {error_code}", 404);
のように指定してあげる必要がある。上のように出力すると、

{"Timestamp":"2023/12/16 19:24:46.330","Level":"FATAL","Message":"Fatal {error_code}","Stacktrace":"(略)","Properties":{"error_code":404}}

のように、Propertiesパラメータに設定したものが表示されるようになる。

また、外部ファイルに出力する設定をしていた場合、
出力ファイルはUnityエディタのConsoleタブのClearボタンを押すと消えるので注意。

Log.Loggerによるログ出力設定

下記のようにLog.Loggerに設定を代入することで、出力設定を変更することができる。

Log.Logger = new Logger(new LoggerConfig()
	.MinimumLevel.Debug()
	.OutputTemplate("{Timestamp} - {Level} - {Message}")
	.WriteTo.File("..absolutPath.../LogName.log", minLevel: LogLevel.Verbose)
	.WriteTo.StdOut(outputTemplate: "{Level} || {Timestamp} || {Message}"));

設定を行う関数でよく使いそうなものをまとめてみた。

OutputTemplate()

EditorのConsoleタブやテキストファイルへの出力時に、
どのような表記で出力を行うかを指定できる。

ログエントリ日時を表示する{Timestamp}やログレベルを表示する{Level}といった
出力テンプレートが用意されており、ログ出力時に情報が入力される。

例えば

OutputTemplate("{Timestamp} - {Level}{NewLine}")

を指定すると、後述するUnityDebugLog()を用いた時、

2023/12/17 13:50:00.686 - FATAL

と出力される。

使用できる出力テンプレートに関しては公式ドキュメントを参照のこと。

注意点としては、WriteToを伴う後述する書き出し関数より、
前に呼ばないと設定が反映されないので注意。

CaptureStacktrace()

スタックトレースをキャプチャしない設定を行える。
引数にfalseを指定すると、出力時のの負荷軽減を望める。

WriteTo.●●()

書き出し先を指定する際に用いる。

File(): ファイルに出力
JsonFile(): jsonファイルとして出力
UnityEditorConsole(): Consoleに今まで通り表示
UnityDebugLog(): Consoleに、OutputTemplate()で指定した形式で表示
StdOut(): OSの標準出力
UnityDebugLog(): UnityEngine.Debug.Log()で出力
など様々な指定が可能です。複数指定することもできる。

MinimumLevel.●●()

表示する最小のログレベルを指定する。
MinimumLevel.Verbose()のように指定すると指定したレベル以上のログしか表示されなくなる。

WriteToを伴う後述する書き出し関数より、前に呼ばないと設定が反映されないので注意。
また、書き出し先指定時にminLevelを指定した場合、その設定が優先される。

また、ここで指定したログレベルは
Debug.Log()、Debug.LogWarning()、Debug.LogAssertion()といった旧ログ関数には適用されない。

ログソリューションの同期タイミング

ログソリューションはデフォルトではFatalを除き、
パフォーマンスを上げるため非同期でログエントリからコンソール表示まで行っている。
ただ、非同期の場合最大2回更新遅延が発生するため、
ログがフラッシュしていない(=書き込まれていない)場合、情報が消える可能性がある。

情報が消えるのを避けたい場合はFullSync()を指定すると良いが、
ストレージアクセスの速度の遅さからプロセスをブロッキングしやすいので注意。

FatalIsSync(): Fatalは同期。それ以外は非同期
FullSync(): すべて同期
FullAsync(): すべて非同期

RedirectUnityLogs()

Debug.Log()の出力をConsoleタブ以外のLogの出力先にも反映するか。

既定値はfalseで、この場合実行時エラーやDebug.Log()、Debug.LogError()
といったものはjsonログやtxtログに反映されない。

注意点として、実行時エラーが発生した場合、
その後のDebug.Log()やDebug.LogError()が出力されないので注意。
(ただし、Loggingパッケージの関数であるLog.●●関数は問題なく出力される)

        Log.Logger = new Logger(new LoggerConfig()
            .WriteTo.UnityDebugLog()
            .RedirectUnityLogs());
	Log.Fatal("Fatal");

のように、 UnityDebugLog() と RedirectUnityLogs()を両方呼んだあと、
Log.Fatal("Fatal")を実行するとUnityがクラッシュするようなので注意。

MinimumLevel.●●()でログの最小レベルを指定した場合、
Debug.Log()はInfo、Debug.LogWarning()はWarning、
Debug.LogAssertion()はFatalレベルのログとして扱われる。

参考

Logging package

【Unity】Debug.Logはもう古い！？ Unity公式のLoggingパッケージ「Unity Logging」の使い方まとめ