Protokol strukturovaných aplikací pro Azure Spring Apps

  • Článek

Poznámka:

Azure Spring Apps je nový název služby Azure Spring Cloud. Přestože má služba nový název, na některých místech uvidíte starý název, protože pracujeme na aktualizaci prostředků, jako jsou snímky obrazovky, videa a diagramy.

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
Logger string No Logger Logger
úroveň string No CustomLevel úroveň protokolu
vlákno string No Vlákno vlákno
zpráva string No Message 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ě platí, že 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á aplikace Přehledy agent v procesu. 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-jsonpom.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:

    Screenshot of the Azure portal showing the log Results pane.

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