ログから処理の流れを可視化する「log2mermaid」を作った

はじめに

組み込み開発やマイクロサービスの不具合解析は以下の流れで対応することが多いです。

1. 不具合発生時のログを取得（ログは数千〜数万行）
2. どのコンポーネントが、どの順番で動いたのかを追う
3. 問題の箇所を突き止める

このような不具合解析は、そのプロジェクトの詳しい方に集中することがあり負担になってるケースがあります。そこで、「ログ→シーケンス図を自動作成」することで"2"と"3"を楽にできないか？と思い、ログから Mermaid のシーケンス図を自動生成するツール「log2mermaid」を作りました。

• GitHub リポジトリ
  https://github.com/yusan25c/log2mermaid-cli/

• 動作確認ができるデモサイト
  https://yusan25c.github.io/log2mermaid/

仕組み

やっていることはシンプルです。

1. キーワードをmatch.csvに登録する
2. ログを１行ずつ読み出してmatch.csvに登録されているキーワードがあるかチェックする
3. キーワードがあればmermaid形式でシーケンス図を出力する

mermaid形式シーケンスについて
https://docs.mermaidchart.com/mermaid-oss/syntax/sequenceDiagram.html

実際に使ってみる

キーワードをmatch.csvに登録

title	match	src	dst	kind
requestMessage	Sample1 .* requestMessage	Sample1	Sample2	message
notifyMessage	Sample2 .* notifyMessage	Sample2	Sample1	message
requestMessage	Sample2 .* requestMessage	Sample2	Sample3	message
notifyMessage	Sample3 .* notifyMessage	Sample3	Sample2	message
State:Executing	Sample2 State:.* -> 1	Sample2		note
state:Executing	Sample3 State:.* -> 1	Sample3		note

対象のログ（log.txt）を準備

Nov  2 12:34:56 : [12345678.012345] hogehoge1
Nov  2 12:34:56 : [12345678.012345] hogehoge2
Nov  2 12:34:56 : [12345678.012345] Sample1 func:1245 requestMessage msg:helloWorld
Nov  2 12:34:56 : [12345678.012345] hogehoge3
Nov  2 12:34:56 : [12345678.012345] Sample2 State:0 -> 1
Nov  2 12:34:56 : [12345678.012345] hogehoge4
Nov  2 12:34:56 : [12345678.012345] Sample2 func:1245 requestMessage msg:helloWorld
Nov  2 12:34:56 : [12345678.012345] Sample3 State:0 -> 1
Nov  2 12:34:56 : [12345678.012345] hogehoge5
Nov  2 12:34:56 : [12345678.012345] hogehoge6
Nov  2 12:34:56 : [12345678.012345] Sample3 func:1245 notifyMessage val:0
Nov  2 12:34:56 : [12345678.012345] Sample2 func:1245 notifyMessage val:0
Nov  2 12:34:56 : [12345678.012345] hogehoge7

スクリプトを実行

python3 log2mermaid.py log.txt match.csv

実行結果

sequenceDiagram
    autonumber
    participant Sample1
    participant Sample2
    participant Sample3
    Sample1 ->> Sample2: requestMessage<br/>L:3
    Note over Sample2: State:Executing<br/>L:5
    Sample2 ->> Sample3: requestMessage<br/>L:7
    Note over Sample3: state:Executing<br/>L:8
    Sample3 ->> Sample2: notifyMessage<br/>L:11
    Sample2 ->> Sample1: notifyMessage<br/>L:12

mermaid live editor等で変換かける

ポイント

キーワードには正規表現を使うことができます。例えば以下のようなログの場合「Sample1 func」と「requestMessage」でマッチさせたいことがあります。

Nov  2 12:34:56 : [12345678.012345] Sample1 func:1245 requestMessage msg:helloWorld

その場合は以下をキーワードとして使えばマッチします。

Sample1 .* requestMessage

どんなときに便利か？

match.csv を整備をしてしまえば、ログを流し込むだけでシーケンス図を出すことができるので、

• ある操作をしたときに、内部でどのコンポーネントがどの順番で動いているか？を確認したいとき
• 不具合解析の最初の一歩として全体の流れを掴みたいとき
• ログ解析を詳しい方に毎回依頼しなくてもよくなる（負担軽減）
• ログ解析の属人化を減らしたいとき

といった場面で便利だと感じています。

最後に

シンプルな作りにしているため、本スクリプトをベースに改造することで別の用途にも利用できると思います。

• ログの前処理を挟んでから流し込む
• Note の内容をリッチにする（タイムスタンプを表示するなど）
• CI から自動でログ → シーケンス図を生成し、レビュー用の資料にする

などもアイデアとしてはありそうです。
不具合や機能の要望、「こういうログに使ってみた」といった事例などあれば、コメント / GitHub Issue / X 等でご連絡をお願いします。