Strukturiertes Anwendungsprotokoll für Azure Spring Apps
Hinweis
Azure Spring Apps ist der neue Name für den Azure Spring Cloud-Dienst. Obwohl der Dienst umbenannt wurde, wird der alte Name noch an einigen Stellen verwendet, solange wir Ressourcen wie Screenshots, Videos und Diagramme aktualisieren.
Dieser Artikel gilt für: ✔️ Basic/Standard ✔️ Enterprise
In diesem Artikel wird erläutert, wie strukturierte Anwendungsprotokolldaten in Azure Spring Apps generiert und erfasst werden. Mit der richtigen Konfiguration bietet Azure Spring Apps nützliche Anwendungsprotokollabfragen und -analysen über Log Analytics.
Protokollschemaanforderungen
Um die Protokollabfrage zu verbessern, muss ein Anwendungsprotokoll im JSON-Format vorliegen und einem Schema entsprechen. Azure Spring Apps verwendet dieses Schema, um Ihre Anwendung zu analysieren und in Log Analytics zu streamen.
Hinweis
Wenn Sie das JSON-Protokollformat aktivieren, ist es schwierig, die Protokollstreamingausgabe aus der Konsole zu lesen. Um eine von Menschen lesbare Ausgabe zu erhalten, fügen Sie das --format-json
-Argument an den CLI-Befehl az spring app logs
an. Weitere Informationen finden Sie unter Formatieren strukturierter JSON-Protokolle.
JSON-Schemaanforderungen:
JSON-Schlüssel | JSON-Werttyp | Erforderlich | Spalte in Log Analytics | Beschreibung |
---|---|---|---|---|
timestamp | Zeichenfolge | Ja | AppTimestamp | Zeitstempel im UTC-Format |
Protokollierungstool | Zeichenfolge | Nein | Logger | Protokollierungstool |
level | Zeichenfolge | Nein | CustomLevel | log level |
thread | Zeichenfolge | Nein | Thread | thread |
message | Zeichenfolge | Nein | `Message` | Protokollnachricht |
stackTrace | Zeichenfolge | Nein | StackTrace | Ausnahme Stapelüberwachung |
exceptionClass | Zeichenfolge | Nein | exceptionClass | Name der Ausnahmeklasse |
mdc | Geschachteltes JSON | Nein | Zugeordneter Diagnosekontext | |
mdc.traceId | Zeichenfolge | Nein | TraceId | Ablaufverfolgungs-ID für verteilte Ablaufverfolgung |
mdc.spanId | Zeichenfolge | Nein | SpanId | Spannen-ID für verteilte Ablaufverfolgung |
- Das Feld „timestamp“ ist erforderlich und sollte im UTC-Format vorliegen. Alle anderen Felder sind optional.
- „traceid“ und „spanid“ im Feld „mdc“ werden für die Ablaufverfolgungszwecke verwendet.
- Protokolliert jeden JSON-Datensatz in einer Zeile.
Beispiel für Protokolldatensatz
{"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"}
Begrenzungen
Jede Zeile der JSON-Protokolle weist höchstens 16 K Bytes auf. Wenn die JSON-Ausgabe eines einzelnen Protokolldatensatzes diesen Grenzwert überschreitet, wird sie in mehrere Zeilen unterteilt, und jede rohe Zeile wird in der Log
Spalte erfasst, ohne strukturell analysiert zu werden.
Im Allgemeinen geschieht diese Situation bei der Ausnahmeprotokollierung mit deep stacktrace, insbesondere, wenn der In-Process-Agent von AppInsights aktiviert ist. Wenden Sie Grenzwerteinstellungen auf die Stacktrace-Ausgabe an (siehe die folgenden Konfigurationsbeispiele), um sicherzustellen, dass die endgültige Ausgabe ordnungsgemäß analysiert wird.
Generieren eines schemakompatiblen JSON-Protokolls
Für Spring-Anwendungen können Sie das erwartete JSON-Protokollformat mit allgemeinen Protokollierungsframeworks wie Logback und Log4j2 generieren.
Protokollieren mit logback
Bei Verwendung von Spring Boot Starters wird Logback standardmäßig verwendet. Verwenden Sie für Logback-Apps den Logstash-Encoder , um JSON-formatiertes Protokoll zu generieren. Diese Methode wird in Spring Boot Version 2.1 oder höher unterstützt.
Die Prozedur:
Fügen Sie eine logstash-Abhängigkeit in Ihrer Datei
pom.xml
hinzu.<dependency> <groupId>net.logstash.logback</groupId> <artifactId>logstash-logback-encoder</artifactId> <version>6.5</version> </dependency>
Aktualisieren Sie die Konfigurationsdatei
logback-spring.xml
, um das JSON-Format festzulegen.<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>
Wenn Sie die Protokollierungskonfigurationsdatei mit einem
-spring
-Suffix wielogback-spring.xml
verwenden, können Sie die Protokollierungskonfiguration basierend auf dem aktiven Spring-Profil festlegen.<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>
Führen Sie für die lokale Entwicklung die Spring-Anwendung mit dem JVM-Argument
-Dspring.profiles.active=dev
aus. Anschließend werden lesbare Protokolle anstelle von Zeilen im JSON-Format angezeigt.
Protokollieren mit log4j2
Verwenden Sie für log4j2-Apps json-template-layout, um das JSON-formatierte Protokoll zu generieren. Diese Methode wird in Spring Boot, Version 2.1 und höher, unterstützt.
Die Prozedur:
Schließen Sie
spring-boot-starter-logging
ausspring-boot-starter
aus, und fügen Sie die Abhängigkeitenspring-boot-starter-log4j2
,log4j-layout-template-json
in der Dateipom.xml
hinzu.<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>
Bereiten Sie eine JSON-Layoutvorlageandatei
jsonTemplate.json
in Ihrem Klassenpfad vor.{ "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" } }
Verwenden Sie diese JSON-Layoutvorlage in Ihrer Konfigurationsdatei
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>
Analysieren der Protokolle in Log Analytics
Nachdem Ihre Anwendung ordnungsgemäß eingerichtet wurde, wird das Anwendungskonsolenprotokoll in Log Analytics gestreamt. Die Struktur ermöglicht eine effiziente Abfrage in Log Analytics.
Überprüfen der Protokollstruktur in Log Analytics
Gehen Sie dazu wie folgt vor:
Navigieren Sie zur Dienstübersichtsseite Ihrer Dienstinstanz.
Wählen Sie den Eintrag Protokolle im Abschnitt Überwachung aus.
Führen Sie die folgende Abfrage aus.
AppPlatformLogsforSpring | where TimeGenerated > ago(1h) | project AppTimestamp, Logger, CustomLevel, Thread, Message, ExceptionClass, StackTrace, TraceId, SpanId
Die Rückgabe von Anwendungsprotokollen wird in der folgenden Abbildung dargestellt:
Anzeigen von Protokolleinträgen mit Fehlern
Um Protokolleinträge mit einem Fehler zu überprüfen, führen Sie die folgende Abfrage aus:
AppPlatformLogsforSpring
| where TimeGenerated > ago(1h) and CustomLevel == "ERROR"
| project AppTimestamp, Logger, ExceptionClass, StackTrace, Message, AppName
| sort by AppTimestamp
Verwenden Sie diese Abfrage, um Fehler zu finden, oder ändern Sie die Abfragebedingungen, um eine bestimmte Ausnahmeklasse oder Fehlercodes zu ermitteln.
Anzeigen von Protokolleinträgen für eine bestimmte traceId
Zum Überprüfen von Protokolleinträgen für eine bestimmte Ablaufverfolgungs-ID „trace_id“ führen Sie die folgende Abfrage aus:
AppPlatformLogsforSpring
| where TimeGenerated > ago(1h)
| where TraceId == "trace_id"
| project AppTimestamp, Logger, TraceId, SpanId, StackTrace, Message, AppName
| sort by AppTimestamp
Nächste Schritte
- Weitere Informationen zur Protokollabfrage finden Sie unter Erste Schritte mit Protokollabfragen in Azure Monitor.
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für