Apache Camel Advent Calendar 7日目の記事は、サポート担当古市が担当します。 テーマは、「Debugging Camel」
基本的には、以下の流れで camel route のデバッグをすすめていくことをお勧めします。
- Camel trace を使い、ルーティングの状況を把握
- ログレベルを変更し、より詳細な情報を把握
- デバッガーを使い、ソースコードレベルの調査
Camel trace
想定通りにルーティングされない場合、exchange の状態と、どの経路でルーティングされたかを把握する必要があります。 実際、製品サポートの現場でかなり大掛かりな camelルートに関する調査をする場合も、traceログからピンポイントで調査が必要な箇所を絞り混みます。
CamelContext の trace アトリビュートを有効にすることで、これらルーティング情報の詳細がログ出力されます。 (どのエンドポイントで処理されるかが、exchange の内容とセットで把握できます。)
実は、camel-jbang にも trace 機能が提供されており、手元でサクッと検証する場合には便利です。 camel-jbang をご存知ない方は、まずこちらの記事をご覧ください。
camel-jbang は稼働中のインテグレーション(camel ルート)の統計を取得することも可能です。まずは、バックグラウンドでインテグレーションを実行します。
camel init Hello.java camel run Hello.java --background
稼働中のインテグレーションの trace status は "Standby" になっています。この状態ではまだトレースが開始されていません。 action オプションを使い、trace status を "started" に変更します。
% camel trace PID NAME AGE STATUS TOTAL QUEUE FILTER PATTERN 4795 Hello 6s Standby 0 0 % camel trace --action=start % camel trace PID NAME AGE STATUS TOTAL QUEUE FILTER PATTERN 4795 Hello 2m15s Started 12 8 %
トレーシングが開始されました。actoinオプションを使い、トレース情報を出力します。
% camel trace --action=dump 2025-08-15 09:35:43.895 4795 --- [ thread #5 - timer://java] route1/*--> : 1 - Created Endpoint timer://java?period=1000 Exchange (DefaultExchange) InOnly 97F301CDA23540D-0000000000000081 Message (DefaultMessage) Body (null) 2025-08-15 09:35:43.895 4795 --- [ thread #5 - timer://java] route1/setBody1 : 2 - Processed (0ms) Exchange (DefaultExchange) InOnly 97F301CDA23540D-0000000000000081 Message (DefaultMessage) Body (null) 2025-08-15 09:35:43.899 4795 --- [ thread #5 - timer://java] route1/log1 : 3 - Processed (0ms) Exchange (DefaultExchange) InOnly 97F301CDA23540D-0000000000000081 Message (DefaultMessage) Body (String) (bytes: 23) Hello Camel from route1 2025-08-15 09:35:43.895 4795 --- [ thread #5 - timer://java] route1/*<-- : 4 - Completed (success) (1ms) Endpoint timer://java?period=1000 Exchange (DefaultExchange) InOnly 97F301CDA23540D-0000000000000081 Message (DefaultMessage) Body (String) (bytes: 23) Hello Camel from route1 ~~省略~~
トレース情報は収集され続けるので、収集を止める場合は "Standby"ステータスへ変更します。
camel trace --action=stop
収集したトレース情報は、保持され続けています。消去することも可能です。
camel trace --action=clear
出力されたトレース情報を確認すると、どのように exchangeがルーティングされているか把握できるかと思います。 exchange id (先ほど掲示した例では、 97F301CDA23540D-0000000000000081)も重要な情報です。後述するログを確認する際、camel trace で特定した exchange id を使いログの絞り込みが可能だからです。
トレース情報にはエンドポイント情報(例: route1/setBody1)も出力されますが、ファイルの行番号で出力することも可能です。
camel trace --source -action=dump
exchange の property や variable も合わせて出力させることも可能です。
camel trace --show-exchange-properties --show-exchange-variables --action=dump
他にも色々とオプションがありますので、詳細は --help でご確認ください。
camel trace --help
いきなりアプリケーションログの解析やデバッガーによるデバッグをせず、一旦 camel trace を使ったルーティング状況の把握を強くお勧めします。
ログレベルの変更
アプリケーションログレベルの変更はデバッグをする上で一般的だと思います。camel trace で問題箇所を調べることができれば、ルートログレベルの変更ではなく、パッケージを指定したログレベルの変更をお勧めします。 camel-jbang を使い、camel全般のログレベルを変更する方法はこちらです。
camel run Hello.java --logging-category=org.apache.camel=DEBUG
camel のログを読み解くにはソースコードレベルの読解が必要となります。無理に DEBUG/TRACE レベルログの解析に時間を使わず、製品サポートへ問い合わせる方法をお勧めします。調査の過程でログレベルの変更をお願いすることもありますので、ご留意ください。
breakpoint を使って止める
camel-jbang は、camel engine レベルでのデバッガーも提供しています。例えば、特定の endpoint にブレイクポイントをセットし、ステップ実行ができます。 exchange の内容も出力されるので、traceログ出力して後から読むのではなく、こちらの方法で調査しても良いかもしれません。
camel debug Hello.java --brakpoint=setBody
このコマンドでは、setBody() 実行箇所にブレイクポイントをセットし実行しています。camel ルートの実行後、自動でデバッグメニューが出力されます。
Source: Hello.java History
-------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------
4: ---> route1/from1 7: from("timer:java?period=1000")
5: @Override
6: public void configure() throws Exception {
7: *--> from("timer:java?period=1000")
8: .setBody()
9: .simple("Hello Camel from ${routeId}")
10: .log("${body}");
11: }
12: }
2025-08-19 09:09:27.979 4135 --- [ thread #6 - timer://java] route1/*--> : 1 - Created
Exchange (DefaultExchange) InOnly 1296773E4359222-0000000000000000
Message (DefaultMessage)
Body (null)
Breakpoint suspended (i = step into (default), o = step over). Press ENTER to continue.
豊富なオプションが用意されていますので、最新バージョンの camel-jbang を用意し、ヘルプコマンドでオプション内容を確認することを推奨します。
camel debug --help
camel は vscode extensionも用意しており、VSCode が提供する GUI を使いデバッグすることも可能です。 marketplace.visualstudio.com
camel engine レベルではなく Javaレベルでのデバッグももちろん可能ですが、traceログなど各種リソースを取得した時点で一旦製品サポート窓口へお問い合わせいただき、camelのデバッグではなくビジネスロジックの開発にリソースを集中していただければと思います。
明日の advent calendar 8日目では、「Camel File コンポーネント」 についてご紹介します。 アドベントカレンダーの一覧はこちらです。 qiita.com
