Strukturovaný protokol aplikací pro Azure Spring Apps

Poznámka:

Plány Basic, Standarda Enterprise vstoupily do důchodového období 17. března 2025. Další informace najdete v oznámení o vyřazení Azure Spring Apps.

Tento článek se vztahuje na:✅ Basic/Standard ✅ Enterprise

Tento článek vysvětluje, jak generovat a shromažďovat strukturovaná protokolová data aplikací v Azure Spring Apps. Díky správné konfiguraci poskytuje Azure Spring Apps užitečné dotazy a analýzy protokolů aplikací prostřednictvím Log Analytics.

Požadavky na schéma protokolu

Aby se zlepšilo prostředí dotazů na protokoly, musí být protokol aplikace ve formátu JSON a v souladu se schématem. Azure Spring Apps používá toto schéma k analýze aplikace a streamování do Log Analytics.

Poznámka:

Povolení formátu protokolu JSON znesnadňuje čtení výstupu přenosu protokolu z konzole. Pro zobrazení výstupu ve formátu čitelném pro lidi, připojte argument --format-json k příkazu CLI az spring app logs. Podívejte se na strukturované protokoly ve formátu JSON.

Požadavky na schéma JSON:

Klíč JSON	Typ hodnoty JSON	Požaduje se	Sloupec v Log Analytics	Popis
časové razítko	řetězec	Ano	AppTimestamp	časové razítko ve formátu UTC
protokolovací nástroj	řetězec	Ne	Dřevorubec	protokolovací nástroj
úroveň	řetězec	Ne	VlastníÚroveň	úroveň protokolu
podproces	řetězec	Ne	Vlákno	podproces
zpráva	řetězec	Ne	Zpráva	zpráva protokolu
stackTrace	řetězec	Ne	StackTrace	Trasování zásobníku výjimek
třída výjimek	řetězec	Ne	TřídaVýjimek	název třídy výjimky
mdc	vnořený JSON	Ne		mapovaný diagnostický kontext
mdc.traceId	řetězec	Ne	TraceId	ID sledování pro distribuované trasování
mdc.spanId	řetězec	Ne	SpanId	span ID pro distribuované trasování

Pole "časové razítko" je povinné a mělo by být ve formátu UTC, všechna ostatní pole jsou nepovinná.
"traceId" a "spanId" v poli "mdc" se používají pro účely trasování.
Protokolujte každý záznam JSON na jednom řádku.

Ukázka záznamu protokolu

{"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"}

Omezení

Každý řádek protokolů JSON má maximálně 16 K bajtů. Pokud výstup JSON jednoho záznamu protokolu tento limit překročí, rozdělí se na několik řádků a každý nezpracovaný řádek se shromáždí do Log sloupce, aniž by se parsoval strukturálně.

Obecně k této situaci dochází při protokolování výjimek s hlubokým trasováním zásobníku, zejména pokud je povolený agent v procesu služby AppInsights. Použijte nastavení omezení pro výstup trasování zásobníku (viz následující ukázky konfigurace), abyste zajistili, že se konečný výstup správně parsuje.

Generování protokolu JSON vyhovujícího schématu

U aplikací Spring můžete generovat očekávaný formát protokolu JSON pomocí běžných logovacích frameworků, jako jsou Logback a Log4j2.

Protokolování s využitím Logbacku

Při použití startérů Spring Boot se ve výchozím nastavení používá Logback. Pro aplikace Logback použijte logstash-encoder k vygenerování protokolu ve formátu JSON. Tato metoda je podporována ve Spring Bootu verze 2.1 nebo novější.

Postup:

Do pom.xml souboru přidejte závislost logstash.

<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>6.5</version>
</dependency>

Aktualizujte logback-spring.xml konfigurační soubor tak, aby nastavil formát 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>

Při použití konfiguračního souboru protokolování s -spring příponou, jako je logback-spring.xml, můžete nastavit konfiguraci protokolování na základě aktivního profilu 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>

Pro místní vývoj spusťte aplikaci Spring s argumentem -Dspring.profiles.active=devJVM a pak můžete zobrazit protokoly čitelné pro člověka místo řádků ve formátu JSON.

Logování s log4j2

Pro aplikace log4j2 použijte json-template-layout k vygenerování protokolu ve formátu JSON. Tato metoda je podporována ve Verzi Spring Boot 2.1 nebo novější.

Postup:

V souboru pom.xml vyloučte spring-boot-starter-logging ze spring-boot-starter a přidejte závislosti spring-boot-starter-log4j2, log4j-layout-template-json.

<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>

Připravte soubor šablony rozložení JSON jsonTemplate.json ve třídní cestě.

{
    "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"
    }
}

Tuto šablonu rozložení JSON použijte v konfiguračním log4j2-spring.xml souboru.

<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>

Analýza protokolů v Log Analytics

Po správném nastavení aplikace se protokol konzoly aplikace streamuje do Log Analytics. Struktura umožňuje efektivní dotaz v Log Analytics.

Kontrola struktury protokolů v Log Analytics

Použijte následující postup:

Přejděte na stránku přehledu služby vaší instance služby.
V části Monitorování vyberte položku Protokoly.

Spusťte tento dotaz.

AppPlatformLogsforSpring
| where TimeGenerated > ago(1h)
| project AppTimestamp, Logger, CustomLevel, Thread, Message, ExceptionClass, StackTrace, TraceId, SpanId

Protokoly aplikací se vrátí, jak je znázorněno na následujícím obrázku:

Zobrazit položky protokolu obsahující chyby

Pokud chcete zkontrolovat položky protokolu s chybou, spusťte následující dotaz:

AppPlatformLogsforSpring
| where TimeGenerated > ago(1h) and CustomLevel == "ERROR"
| project AppTimestamp, Logger, ExceptionClass, StackTrace, Message, AppName
| sort by AppTimestamp

Pomocí tohoto dotazu můžete najít chyby nebo upravit termíny dotazu tak, aby vyhledály konkrétní třídu výjimek nebo kód chyby.

Zobrazit položky protokolu pro konkrétní ID stopy

Pokud chcete zkontrolovat položky protokolu pro konkrétní ID trasování "trace_id", spusťte následující dotaz:

AppPlatformLogsforSpring
| where TimeGenerated > ago(1h)
| where TraceId == "trace_id"
| project AppTimestamp, Logger, TraceId, SpanId, StackTrace, Message, AppName
| sort by AppTimestamp

Další kroky

Další informace o dotazu protokolu najdete v tématu Začínáme s dotazy na protokoly ve službě Azure Monitor.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-31