Azure Spring Apps の構造化アプリケーション ログ
Note
Basic、Standard、および Enterprise プランは、2025 年 3 月中旬以降に非推奨になり、3 年間の廃止期間となります。 Azure Container Apps に移行することをお勧めします。 詳細については、「Azure Spring Apps の廃止のお知らせ」を参照してください。
Standard 従量課金と専用プランは、2024 年 9 月 30 日以降に非推奨となり、6 か月後に完全にシャットダウンされます。 Azure Container Apps に移行することをお勧めします。 詳細については、「Azure Spring Apps の Standard 従量課金と専用プランを Azure Container Apps に移行する」を参照してください。
この記事の適用対象: ✔️ Basic または Standard ✔️ Enterprise
この記事では、Azure Spring Apps で構造化アプリケーション ログ データを生成および収集する方法について説明します。 正しく構成すれば、Azure Spring Apps で、アプリケーション ログの有用なクエリと分析が Log Analytics を通じて提供されます。
ログ スキーマの要件
ログ クエリのエクスペリエンスを向上させるには、アプリケーション ログが JSON 形式であり、スキーマに準拠している必要があります。 Azure Spring Apps では、このスキーマを使用してアプリケーションを解析し、Log Analytics にストリームします。
Note
JSON ログ形式を有効にすると、コンソールからのログ ストリーミング出力を読み取るのが困難になります。 人間が判読できる出力を取得するには、 --format-json
引数を az spring app logs
CLI コマンドに追加します。 「Format JSON structured logs (JSON の構造化されたログの書式設定)」を参照してください。
JSON スキーマの要件:
JSON キー | JSON 値の型 | 必須 | Log Analytics の列 | 説明 |
---|---|---|---|---|
タイムスタンプ | string | はい | AppTimestamp | UTC 形式のタイムスタンプ |
logger | string | いいえ | ロガー | logger |
level | string | いいえ | CustomLevel | ログ レベル |
スレッド | string | いいえ | スレッド | スレッド |
message | string | いいえ | メッセージ | ログ メッセージ |
stackTrace | string | いいえ | StackTrace | 例外スタック トレース |
exceptionClass | string | いいえ | ExceptionClass | 例外クラス名 |
mdc | 入れ子の JSON | いいえ | マップされた診断コンテキスト | |
mdc.traceId | string | いいえ | TraceId | 分散トレース用のトレース ID |
mdc.spanId | string | いいえ | SpanId | 分散トレース用のスパン ID |
- "timestamp" フィールドは必須であり、UTC 形式である必要があります。他のすべてのフィールドは省略可能です。
- "mdc" フィールドの "traceId" と "spanId" はトレースに使用されます。
- 個々の JSON レコードはログに 1 行で記録されます。
ログ レコードのサンプル
{"timestamp":"2021-01-08T09:23:51.280Z","logger":"com.example.demo.HelloController","level":"ERROR","thread":"http-nio-1456-exec-4","mdc":{"traceId":"c84f8a897041f634","spanId":"c84f8a897041f634"},"stackTrace":"java.lang.RuntimeException: get an exception\r\n\tat com.example.demo.HelloController.throwEx(HelloController.java:54)\r\n\","message":"Got an exception","exceptionClass":"RuntimeException"}
制限事項
JSON ログの各行には最大 16 K バイトが含まれます。 1 つのログ レコードの JSON 出力がこの制限を超えると、そのレコードは複数の行に分割され、未加工の各行は、構造的に解析されることなく、Log
列に収集されます。
通常、この状況は、特に AppInsights In-Process エージェント が有効になっている場合に、深いスタックトレースを使用した例外ログで発生します。 最終的な出力が適切に解析されるように、スタックトレース出力に制限設定を適用します (次の構成サンプルを参照)。
スキーマ準拠の JSON ログを生成する
Spring アプリケーションの場合、Logback や Log4j2 などの一般的なログ記録フレームワークを使用して、期待される JSON ログ形式を生成できます。
logback でログを記録する
Spring Boot スターターを使用する場合は、既定で Logback が使用されます。 Logback アプリの場合は、logstash-encoder を使用して JSON 形式のログを生成します。 この方法は Spring Boot バージョン 2.1 以降でサポートされています。
手順:
logstash の依存関係を
pom.xml
ファイルに追加します。<dependency> <groupId>net.logstash.logback</groupId> <artifactId>logstash-logback-encoder</artifactId> <version>6.5</version> </dependency>
logback-spring.xml
構成ファイルを更新して、JSON 形式を設定します。<configuration> <appender name="stdout" class="ch.qos.logback.core.ConsoleAppender"> <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder"> <providers> <timestamp> <fieldName>timestamp</fieldName> <timeZone>UTC</timeZone> </timestamp> <loggerName> <fieldName>logger</fieldName> </loggerName> <logLevel> <fieldName>level</fieldName> </logLevel> <threadName> <fieldName>thread</fieldName> </threadName> <nestedField> <fieldName>mdc</fieldName> <providers> <mdc /> </providers> </nestedField> <stackTrace> <fieldName>stackTrace</fieldName> <!-- maxLength - limit the length of the stack trace --> <throwableConverter class="net.logstash.logback.stacktrace.ShortenedThrowableConverter"> <maxDepthPerThrowable>200</maxDepthPerThrowable> <maxLength>14000</maxLength> <rootCauseFirst>true</rootCauseFirst> </throwableConverter> </stackTrace> <message /> <throwableClassName> <fieldName>exceptionClass</fieldName> </throwableClassName> </providers> </encoder> </appender> <root level="info"> <appender-ref ref="stdout" /> </root> </configuration>
logback-spring.xml
のような-spring
サフィックスが付いたログ構成ファイルを使用する場合は、ログ構成を Spring アクティブ プロファイルに基づいて設定できます。<configuration> <springProfile name="dev"> <!-- JSON appender definitions for local development, in human readable format --> <include resource="org/springframework/boot/logging/logback/defaults.xml" /> <include resource="org/springframework/boot/logging/logback/console-appender.xml" /> <root level="info"> <appender-ref ref="CONSOLE" /> </root> </springProfile> <springProfile name="!dev"> <!-- JSON appender configuration from previous step, used for staging / production --> ... </springProfile> </configuration>
ローカル開発では、Spring アプリケーションの JVM 引数を
-Dspring.profiles.active=dev
にして実行すると、JSON 形式の行でなく人間が読み取り可能なログを表示できます。
log4j2 でログを記録する
log4j2 アプリの場合、json-template-layout を使用して JSON 形式のログを生成します。 この方法は Spring Boot バージョン 2.1 以降でサポートされています。
手順:
spring-boot-starter-logging
をspring-boot-starter
から除外し、依存関係spring-boot-starter-log4j2
、log4j-layout-template-json
をpom.xml
ファイルに追加します。<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <exclusions> <exclusion> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-logging</artifactId> </exclusion> </exclusions> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-log4j2</artifactId> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-layout-template-json</artifactId> <version>2.14.0</version> </dependency>
JSON レイアウト テンプレート ファイル
jsonTemplate.json
をクラス パスに準備します。{ "mdc": { "$resolver": "mdc" }, "exceptionClass": { "$resolver": "exception", "field": "className" }, "stackTrace": { "$resolver": "exception", "field": "stackTrace", "stringified": true }, "message": { "$resolver": "message", "stringified": true }, "thread": { "$resolver": "thread", "field": "name" }, "timestamp": { "$resolver": "timestamp", "pattern": { "format": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", "timeZone": "UTC" } }, "level": { "$resolver": "level", "field": "name" }, "logger": { "$resolver": "logger", "field": "name" } }
この JSON レイアウト テンプレートを
log4j2-spring.xml
構成ファイルで使用します。<configuration> <appenders> <console name="Console" target="SYSTEM_OUT"> <!-- maxStringLength - limit the length of the stack trace --> <JsonTemplateLayout eventTemplateUri="classpath:jsonTemplate.json" maxStringLength="14000" /> </console> </appenders> <loggers> <root level="info"> <appender-ref ref="Console" /> </root> </loggers> </configuration>
Log Analytics でログを分析する
アプリケーションが正しくセットアップされると、アプリケーション コンソールのログが Log Analytics にストリームされます。 Log Analytics で効率的なクエリができる構造になっています。
Log Analytics でログの構造を確認する
次の手順に従います。
サービス インスタンスのサービスの概要ページに移動します。
[監視] セクションで [ログ] エントリを選択します。
このクエリを実行します。
AppPlatformLogsforSpring | where TimeGenerated > ago(1h) | project AppTimestamp, Logger, CustomLevel, Thread, Message, ExceptionClass, StackTrace, TraceId, SpanId
次の図に示すように、アプリケーション ログが返されます。
エラーを含むログ エントリを表示する
エラーがあるログ エントリを確認するには、次のクエリを実行します。
AppPlatformLogsforSpring
| where TimeGenerated > ago(1h) and CustomLevel == "ERROR"
| project AppTimestamp, Logger, ExceptionClass, StackTrace, Message, AppName
| sort by AppTimestamp
このクエリを使用してエラーを検出するか、クエリ用語を変更して特定の例外クラスまたはエラー コードを検索します。
特定のトレース ID のログ エントリを表示する
特定のトレース ID "trace_id" のログ エントリを確認するには、次のクエリを実行します。
AppPlatformLogsforSpring
| where TimeGenerated > ago(1h)
| where TraceId == "trace_id"
| project AppTimestamp, Logger, TraceId, SpanId, StackTrace, Message, AppName
| sort by AppTimestamp
次のステップ
- ログ クエリの詳細については「Azure Monitor でログ クエリの使用を開始する」を参照してください