第18章 Logging 日志.md · Gradle 2 用戶指南

日志是構建工具的主要"UI"。如果日志太多，真正的警告和問題容易被隱藏。另一方面，如果出了錯，你需要找出相關的信息。Gradle 定義了6個日志級別，如表 Table 18.1, “Log levels” 所示。除了那些您通過可能會平常看到的日志級別之外，有兩個 Gradle 特定日志級別。這兩個級別分別是?`QUIET`?和?`LIFECYCLE`。默認使用后面的這個日志級別，用于報告構建進度。 Table 18.1\. Log levels | 級別 | 用途 | | --- | --- | | ERROR | Error 錯誤信息 | | QUIET | 重要信息 | | WARNING | Warning 警告信息 | | LIFECYCLE | 過程信息 | | INFO | 信息 | | DEBUG | Debug 調試信息 | ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2018.%20Logging%20%E6%97%A5%E5%BF%97.md#181-choosing-a-log-level-選擇級別)18.1\. Choosing a log level 選擇級別在 Table 18.2, “Log level command-line options” 中命令行，是用來選擇不同的級別的選項。 Table 18.3, “Stacktrace command-line options” 中的是影響堆棧跟蹤日志 Table 18.2\. Log level command-line options | 選項 | 輸出日志的級別 | | --- | --- | | no logging options | LIFECYCLE 及更高 | | `-q`?or?`--quiet` | QUIET 及更高 | | `-i`?or?`--info` | INFO 及更高 | | `-d`?or?`--debug` | DEBUG 及更高 (所有的日志信息) | Table 18.3\. Stacktrace command-line options | 選項 | 含義 | | --- | --- | | No stacktrace options | 構建錯誤（如編譯錯誤）時沒有棧跟蹤打印到控制臺。只有在內部異常的情況下才打印棧跟蹤。如果選擇 DEBUG 日志級別，則總是輸出截取后的棧跟蹤信息。 | | `-s`?or?`--stacktrace` | 輸出截斷的棧跟蹤。我們推薦使用這一個選項而不是打印全棧的跟蹤信息。Groovy 的全棧跟蹤非常冗長（由于其潛在的動態調用機制，然而他們通常不包含你的的代碼中哪里錯了的相關信息。） | | `-S`?or?`--full-stacktrace` | 打印全棧的跟蹤信息。 | ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2018.%20Logging%20%E6%97%A5%E5%BF%97.md#182-writing-your-own-log-messages-編寫自己的日志消息)18.2\. Writing your own log messages 編寫自己的日志消息在構建文件，打印日志的一個簡單方法是把消息寫到標準輸出中。Gradle 會把寫到標準輸出的所有內容重定向到它的日志系統的 QUIET 級別中。 Example 18.1\. Using stdout to write log messages build.gradle ~~~ println 'A message which is logged at QUIET level' ~~~ Gradle 還提供了一個 logger 屬性給構建腳本，它是一個 Logger 實例。該接口擴展自 SLF4J 的 Logger接口，并添加了幾個 Gradle 的特有方法。下面是關于如何在構建腳本中使用它的示例： Example 18.2\. Writing your own log messages build.gradle ~~~ logger.quiet('An info log message which is always logged.') logger.error('An error log message.') logger.warn('A warning log message.') logger.lifecycle('A lifecycle info log message.') logger.info('An info log message.') logger.debug('A debug log message.') logger.trace('A trace log message.') ~~~ 您也可以在構建腳本中通過其他使用的類掛鉤到 Gradle 的日志系統中（例如 buildSrc 目錄中的類）。只需使用一個 SLF4J 的logger對象。你可以在構建腳本中，用與內置的logger同樣的方式使用這個logger。 Example 18.3\. Using SLF4J to write log messages build.gradle ~~~ import org.slf4j.Logger import org.slf4j.LoggerFactory Logger slf4jLogger = LoggerFactory.getLogger('some-logger') slf4jLogger.info('An info log message logged using SLF4j') ~~~ ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2018.%20Logging%20%E6%97%A5%E5%BF%97.md#183-logging-from-external-tools-and-libraries-使用外部工具和庫記錄日志)18.3\. Logging from external tools and libraries 使用外部工具和庫記錄日志 Gradle 內部使用 Ant 和 Ivy。它們都有自己的日志系統。Gradle 將他們日志輸出重定向到 Gradle 的日志系統。從 Ant/Ivy 的日志級別到 Gradle 的日志級別是一對一的映射，除了 Ant/Ivy 的 TRACE 級別，它是映射到 Gradle 的 DEBUG 級別的。這意味著默認情況下， Gradle 日志級別將不會顯示任何 Ant/Ivy 的輸出，除非是錯誤或警告信息。有很多的工具仍然在使用標準輸出日志記錄。默認情況下，Gradle 將標準輸出重定向到 QUIET日志級別，把標準錯誤輸出重寫向到 ERROR 級別。這種行為是可配置的。Project 對象提供了一個?[LoggingManager](http://www.gradle.org/docs/current/javadoc/org/gradle/api/logging/LoggingManager.html)，它允許您在計算構建腳本時，修改標準輸出和錯誤重定向的日志級別。 Example 18.4\. Configuring standard output capture build.gradle ~~~ logging.captureStandardOutput LogLevel.INFO println 'A message which is logged at INFO level' ~~~ 為能在任務執行過程中更改標準輸出或錯誤的日志級別，task也提供了一個 LoggingManager。 Example 18.5\. Configuring standard output capture for a task build.gradle ~~~ task logInfo { logging.captureStandardOutput LogLevel.INFO doFirst { println 'A task message which is logged at INFO level' } } ~~~ Gradle 還提供了對 Java Util Logging，Jakarta Commons Logging 和 Log4j 的日志工具的集成。你生成的類使用這些日志記錄工具輸出的任何日志消息，都將被重定向到 Gradle 的日志系統。 ## [](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2018.%20Logging%20%E6%97%A5%E5%BF%97.md#184-changing-what-gradle-logs-改變-gradle-日志)18.4\. Changing what Gradle logs 改變 Gradle 日志您可以用您自己的 logging UI 大量地替換 Gradle 的。你可以這樣做，例如，如果您想要以某種方式自定義 UI ——以輸出更多或更少的信息，或修改日志格式您可以使用 Gradle.useLogger() 方法替換這個 logging。它可以在構建腳本，或 init 腳本，或通過內嵌的 API 訪問。請注意它完全禁用 Gradle 的默認輸出。下面是一個示例，在 init 腳本中修改任務執行和構建完成的日志打印。 Example 18.6\. Customizing what Gradle logs init.gradle ~~~ useLogger(new CustomEventLogger()) class CustomEventLogger extends BuildAdapter implements TaskExecutionListener { public void beforeExecute(Task task) { println "[$task.name]" } public void afterExecute(Task task, TaskState state) { println() } public void buildFinished(BuildResult result) { println 'build completed' if (result.failure != null) { result.failure.printStackTrace() } } } ~~~ 執行 gradle -I init.gradle build ~~~ > gradle -I init.gradle build [compile] compiling source [testCompile] compiling test source [test] running unit tests [build] build completed ~~~ 你的 logger 可以實現下面列出的任何監聽器接口。當你注冊一個 logger時，只能替換它實現的接口的日志記錄。其他接口的日志記錄是不變的。你可以在?[The Build Lifecycle 構建生命周期](https://github.com/waylau/Gradle-2-User-Guide/blob/master/Chapter%2056.%20The%20Build%20Lifecycle%20%E6%9E%84%E5%BB%BA%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F.md)中的 55.6 節 “在構建腳本中響應生命周期”查看相關信息。 * [BuildListener](http://www.gradle.org/docs/current/javadoc/org/gradle/BuildListener.html) * [ProjectEvaluationListener](http://www.gradle.org/docs/current/javadoc/org/gradle/api/ProjectEvaluationListener.html) * [TaskExecutionGraphListener](http://www.gradle.org/docs/current/javadoc/org/gradle/api/execution/TaskExecutionGraphListener.html) * [TaskExecutionListener](http://www.gradle.org/docs/current/javadoc/org/gradle/api/execution/TaskExecutionListener.html) * [TaskActionListener](http://www.gradle.org/docs/current/javadoc/org/gradle/api/execution/TaskActionListener.html)