Azure Spring Apps の構造化アプリケーションログ

[アーティクル]
10/02/2024

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 でログクエリの使用を開始する」を参照してください

次の方法で共有

Azure Spring Apps の構造化アプリケーションログ

ログスキーマの要件

制限事項

スキーマ準拠の JSON ログを生成する

logback でログを記録する

log4j2 でログを記録する

Log Analytics でログを分析する

Log Analytics でログの構造を確認する

エラーを含むログエントリを表示する

特定のトレース ID のログエントリを表示する

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure Spring Apps の構造化アプリケーション ログ

ログ スキーマの要件

制限事項

スキーマ準拠の JSON ログを生成する

logback でログを記録する

log4j2 でログを記録する

Log Analytics でログを分析する

Log Analytics でログの構造を確認する

エラーを含むログ エントリを表示する

特定のトレース ID のログ エントリを表示する

次のステップ

フィードバック

その他のリソース

Azure Spring Apps の構造化アプリケーションログ

ログスキーマの要件

エラーを含むログエントリを表示する

特定のトレース ID のログエントリを表示する