Azure Spring Cloud 的结构化应用程序日志Structured application log for Azure Spring Cloud

本文介绍了如何在 Azure Spring Cloud 中生成和收集结构化应用程序日志数据。This article explains how to generate and collect structured application log data in Azure Spring Cloud. Azure Spring Cloud 使用正确的配置通过 Log Analytics 提供有用的应用程序日志查询和分析。With proper configuration, Azure Spring Cloud provides useful application log query and analysis through Log Analytics.

日志架构要求Log schema requirements

若要改进日志查询体验,应用程序日志必须采用 JSON 格式,并遵循某个架构。To improve log query experience, an application log is required to be in JSON format and conform to a schema. Azure Spring Cloud 使用此架构分析你的应用程序并流式传输到 Log Analytics。Azure Spring Cloud uses this schema to parse your application and stream to Log Analytics.

JSON 架构要求:JSON schema requirements:

Json 键Json Key Json 值类型Json value Type 必需Required Log Analytics 中的列Column in Log Analytics 说明Description
timestamptimestamp stringstring Yes AppTimestampAppTimestamp UTC 格式的时间戳timestamp in UTC format
loggerlogger stringstring No 记录器Logger loggerlogger
级别level stringstring No CustomLevelCustomLevel 日志级别log level
线程 (thread)thread stringstring No 线程Thread 线程 (thread)thread
messagemessage stringstring No MessageMessage 日志消息log message
stackTracestackTrace stringstring No StackTraceStackTrace 异常堆栈跟踪exception stack trace
exceptionClassexceptionClass stringstring No ExceptionClassExceptionClass 异常类名称exception class name
mdcmdc 嵌套的 JSONnested JSON No 映射的诊断上下文mapped diagnostic context
mdc.traceIdmdc.traceId stringstring No TraceIdTraceId 分布式跟踪的跟踪 Idtrace Id for distributed tracing
mdc.spanIdmdc.spanId stringstring No SpanIdSpanId 分布式跟踪的跟踪 Idspan Id for distributed tracing
  • “timestamp”字段是必需的,并且应当采用 UTC 格式,所有其他字段都是可选的。The "timestamp" field is required, and should be in UTC format, all other fields are optional.
  • “mdc”字段中的“traceId”和“spanId”用于跟踪。"traceId" and "spanId" in "mdc" field are used for tracing purpose.
  • 在单个行中记录每条 JSON 记录。Log each JSON record in one line.

日志记录示例Log record sample

{"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 日志Generate schema-compliant JSON log

对于 Spring 应用程序,你可以使用常用的日志记录框架(例如 logbacklog4j2)生成预期的 JSON 日志格式。For Spring applications, you can generate expected JSON log format using common logging frameworks, such as logback and log4j2.

使用 logback 进行记录Log with logback

使用 Spring Boot 入门版时,默认情况下将使用 logback。When using Spring Boot starters, logback is used by default. 对于 logback 应用,请使用 logstash-encoder 生成 JSON 格式的日志。For logback apps, use logstash-encoder to generate JSON formatted log. Spring Boot 2.1+ 版支持此方法。This method is supported in Spring Boot version 2.1+.

此过程:The procedure:

  1. 在 pom.xml 文件中添加 logstash 依赖项。Add logstash dependency in your pom.xml file.

    <dependency>
        <groupId>net.logstash.logback</groupId>
        <artifactId>logstash-logback-encoder</artifactId>
        <version>6.5</version>
    </dependency>
    
  2. 更新 logback.xml 配置文件以设置 JSON 格式。Update your logback.xml config file to set the JSON format.

    <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>
                </stackTrace>
                <message/>
                <throwableClassName>
                    <fieldName>exceptionClass</fieldName>
                </throwableClassName>
            </providers>
            </encoder>
        </appender>
        <root level="info">
            <appender-ref ref="stdout"/>
        </root>
    </configuration>
    

使用 log4j2 进行记录Log with log4j2

对于 log4j2 应用,请使用 json-template-layout 生成 JSON 格式的日志。For log4j2 apps, use json-template-layout to generate JSON formatted log. Spring Boot 2.1+ 版支持此方法。This method is supported in Spring Boot version 2.1+.

此过程:The procedure:

  1. 在 pom.xml 文件中从 spring-boot-starter 中排除 spring-boot-starter-logging,添加依赖项 spring-boot-starter-log4j2log4j-layout-template-jsonExclude spring-boot-starter-logging from spring-boot-starter, add dependencies spring-boot-starter-log4j2, log4j-layout-template-json in your pom.xml file.

        <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. 在类路径中准备一个 JSON 布局模板文件 jsonTemplate.json。Prepare a JSON layout template file jsonTemplate.json in your class path.

        {
            "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. 在 log4j2.xml 配置文件中使用此 JSON 布局模板。Use this JSON layout template in your log4j2.xml config file.

        <configuration>
            <appenders>
                <console name="Console" target="SYSTEM_OUT">
                <JsonTemplateLayout eventTemplateUri="classpath:jsonTemplate.json"/>
                </console>
            </appenders>
            <loggers>
                <root level="info">
                <appender-ref ref="Console"/>
                </root>
            </loggers>
        </configuration>
    

在 Log Analytics 中分析日志Analyze the logs in Log Analytics

正确设置应用程序后,应用程序控制台日志将流式传输到 Log Analytics。After your application is properly set up, your application console log will be streamed to Log Analytics. 此结构可在 Log Analytics 中实现高效查询。The structure enables efficient query in Log Analytics.

在 Log Analytics 中查看日志结构Check log structure in Log Analytics

请按以下过程操作:Use the following procedure:

  1. 转到你的服务实例的服务概述页。Go to service overview page of your service instance.

  2. 单击 Monitoring 部分下的 Logs 条目。Click Logs entry under Monitoring section.

  3. 运行此查询。Run this query.

    AppPlatformLogsforSpring
    | where TimeGenerated > ago(1h)
    | project AppTimestamp, Logger, CustomLevel, Thread, Message, ExceptionClass, StackTrace, TraceId, SpanId
    
  4. 将返回应用程序日志,如下图所示:Application logs return as shown in the following image:

Json 日志显示

显示包含错误的日志条目Show log entries containing errors

若要查看包含错误的日志条目,请运行以下查询:To review log entries that have an error, run the following query:

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

使用此查询查找错误,或修改查询词以查找特定的异常类或错误代码。Use this query to find errors, or modify the query terms to find specific exception class or error code.

显示特定 traceId 的日志条目Show log entries for a specific traceId

若要查看特定跟踪 ID“trace_id”的日志条目,请运行以下查询:To review log entries for a specific tracing ID "trace_id", run the following query:

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

后续步骤Next Steps