Sdílet prostřednictvím

Protokol strukturovaných aplikací pro Azure Spring Apps

  • Článek

Poznámka:

Plány Basic, Standard a Enterprise budou od poloviny března 2025 vyřazeny ze 3letého období vyřazení. Doporučujeme přejít na Azure Container Apps. Další informace najdete v oznámení o vyřazení Azure Spring Apps.

Od 30. září 2024 bude od 30. září 2024 zastaralý plán s úplným vypnutím po šesti měsících. Doporučujeme přejít na Azure Container Apps. Další informace najdete v tématu Migrace spotřeby Azure Spring Apps Úrovně Standard a vyhrazeného plánu do Azure Container Apps.

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

Tento článek vysvětluje, jak generovat a shromažďovat data protokolu strukturovaných 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 streamování protokolu z konzoly. Pokud chcete získat čitelný výstup člověka, připojte --format-json argument k příkazu rozhraní příkazového az spring app logs řádku. Viz Formát strukturovaných protokolů JSON.

Požadavky na schéma JSON:

Klíč JSON Typ hodnoty JSON Požaduje se Sloupec v Log Analytics Popis
časové razítko string Ano AppTimestamp časové razítko ve formátu UTC
dřevorubec string No Dřevorubec dřevorubec
úroveň string No CustomLevel úroveň protokolu
vlákno string No Vlákno vlákno
zpráva string No Zpráva zpráva protokolu
stackTrace string No StackTrace Trasování zásobníku výjimek
exceptionClass string No ExceptionClass název třídy výjimky
Mdc vnořený JSON No mapovaný diagnostický kontext
mdc.traceId string No TraceId ID trasování pro distribuované trasování
mdc.spanId string No 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 měli jistotu, že se konečný výstup správně parsuje.

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

U aplikací Spring můžete vygenerovat očekávaný formát protokolu JSON pomocí běžných rozhraní protokolování, jako je logback a Log4j2.

Protokol s využitím zpětného protokolování

Při použití úvodních aplikací Spring Boot se ve výchozím nastavení používá zpětný protokol. Pro aplikace logback použijte k vygenerování protokolu ve formátu JSON kodér logstash. Tato metoda je podporována ve Spring Bootu verze 2.1 nebo novější.

Postup:

  1. Přidejte do pom.xml souboru závislost logstash.

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

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

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

Protokol s protokolem log4j2

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

Postup:

  1. Vyloučíte spring-boot-starter-logging z spring-boot-startersouboru , přidáte závislosti spring-boot-starter-log4j2log4j-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>

  2. Připravte soubor jsonTemplate.json šablony rozložení JSON v cestě ke třídě.

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

  3. 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:

  1. Přejděte na stránku přehledu služby vaší instance služby.

  2. V části Monitorování vyberte položku Protokoly.

  3. Spusťte tento dotaz.

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

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

    Snímek obrazovky webu Azure Portal s podoknem výsledky protokolu

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.

Zobrazení položek protokolu pro konkrétní id trasování

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