Permalink
Browse files

update logging howto

  • Loading branch information...
1 parent 208118c commit 43056746bc2da1311f6a88010919fbacad332c34 @harrah harrah committed Aug 1, 2012
Showing with 158 additions and 14 deletions.
  1. +158 −14 src/jekyll/howto/logging.md
View
@@ -8,24 +8,18 @@ sections:
- id: tasklast
name: view the previous logging output of a specific task
command: last compile
- - id: lastgrep
- name: search the logging output of the previously executed command
- command: last-grep *Test.jar
- - id: tasklastgrep
- name: search the previous logging output of a specific task
- command: last-grep *Test.jar run
+ - id: printwarnings
+ name: show warnings from the previous compilation
+ command: print-warnings
- id: level
name: change the logging level globally
command: set every logLevel := Level.Debug
- id: tasklevel
name: change the logging level for a specific task, configuration, or project
setting: logLevel in compile := Level.Debug
- id: trace
- name: configure printing of stack traces globally
+ name: configure printing of stack traces
command: set every traceLevel := 5`
- - id: tasktrace
- name: configure printing of stack traces for a specific task, configuration, or project
- setting: traceLevel := 5
- id: nobuffer
name: print the output of tests immediately instead of buffering
setting: logBuffered := false
@@ -35,6 +29,10 @@ sections:
name: log messages from a task
---
+[print-warnings]: #printwarnings
+[previous output]: #last
+[Streams]: http://harrah.github.com/xsbt/latest/api/#sbt.std.Streams
+
<h4 id="last">View logging output of the previously executed command</h4>
When a command is run, more detailed logging output is sent to a file than to the screen (by default).
@@ -89,22 +87,168 @@ Configuration of the logging level for the console and for the backing file are
<h4 id="tasklast">View the logging output of a specific task</h4>
-<h4 id="lastgrep">Search the logging output of the previously executed command</h4>
+When a task is run, more detailed logging output is sent to a file than to the screen (by default).
+This output can be recalled for a specific task by running `last <task>`.
+For example, the first time `compile` is run, output might look like:
+
+{% highlight console %}
+> compile
+[info] Updating {file:/.../demo/}example...
+[info] Resolving org.scala-lang#scala-library;2.9.2 ...
+[info] Done updating.
+[info] Compiling 1 Scala source to .../demo/target/scala-2.9.2/classes...
+[success] Total time: 0 s, completed Jun 1, 2012 1:11:11 PM
+{% endhighlight %}
+
+The output indicates that both dependency resolution and compilation were performed.
+The detailed output of each of these may be recalled individually.
+For example,
+
+{% highlight console %}
+> last compile
+[debug]
+[debug] Initial source changes:
+[debug] removed:Set()
+[debug] added: Set(/home/mark/tmp/a/b/A.scala)
+[debug] modified: Set()
+...
+{% endhighlight %}
-<h4 id="tasklastgrep">Search the logging output of a specific task</h4>
+and:
+
+{% highlight console %}
+> last update
+[info] Updating {file:/.../demo/}example...
+[debug] post 1.3 ivy file: using exact as default matcher
+[debug] :: resolving dependencies :: example#example_2.9.2;0.1-SNAPSHOT
+[debug] confs: [compile, runtime, test, provided, optional, compile-internal, runtime-internal, test-internal, plugin, sources, docs, pom]
+[debug] validate = true
+[debug] refresh = false
+[debug] resolving dependencies for configuration 'compile'
+...
+{% endhighlight %}
+
+
+<h4 id="printwarnings">Display warnings from the previous compilation</h4>
+
+The Scala compiler does not print the full details of warnings by default.
+Compiling code that uses the deprecated `error` method from Predef might generate the following output:
+
+{% highlight console %}
+> compile
+[info] Compiling 1 Scala source to <...>/classes...
+[warn] there were 1 deprecation warnings; re-run with -deprecation for details
+[warn] one warning found
+{% endhighlight %}
+
+The details aren't provided, so it is necessary to add `-deprecation` to the options passed to the compiler (`scalacOptions`) and recompile.
+An alternative when using Scala 2.10 and later is to run `print-warnings`.
+This task will display all warnings from the previous compilation.
+For example,
+
+{% highlight console %}
+> print-warnings
+[warn] A.scala:2: method error in object Predef is deprecated: Use sys.error(message) instead
+[warn] def x = error("Failed.")
+[warn] ^
+{% endhighlight %}
<h4 id="level">Change the logging level globally</h4>
+The amount of logging is controlled by the `logLevel` setting, which takes values from the `Level` enumeration.
+Valid values are `Error`, `Warn`, `Info`, and `Debug` in order of increasing verbosity.
+To change the global logging level, set `logLevel in Global`.
+For example, to set it temporarily from the sbt prompt,
+
+{% highlight console %}
+> set logLevel in Global := Level.Warn
+{% endhighlight %}
+
<h4 id="tasklevel">Change the logging level for a specific task, configuration, or project</h4>
-<h4 id="trace">Configure printing of stack traces globally</h4>
+The amount of logging is controlled by the `logLevel` setting, which takes values from the `Level` enumeration.
+Valid values are `Error`, `Warn`, `Info`, and `Debug` in order of increasing verbosity.
+The logging level may be configured globally, as described in the previous section, or it may be applied to a specific project, configuration, or task.
+For example, to change the logging level for compilation to only show warnings and errors:
+
+{% highlight console %}
+> set logLevel in compile := Level.Warn
+{% endhighlight %}
+
+To enable debug logging for all tasks in the current project,
+
+{% highlight console %}
+> set logLevel := Level.Warn
+{% endhighlight %}
+
+A common scenario is that after running a task, you notice that you need more information than was shown by default.
+A `logLevel` based solution typically requires changing the logging level and running a task again.
+However, there are two cases where this is unnecessary.
+First, warnings from a previous compilation may be displayed using `print-warnings` for the main sources or `test:print-warnings` for test sources.
+Second, output from the previous execution is available either for a single task or for in its entirety.
+See the section on [print-warnings] and the sections on [previous output].
+
+<h4 id="trace">Configure printing of stack traces</h4>
-<h4 id="tasktrace">Configure printing of stack traces for a specific task, configuration, or project</h4>
+By default, sbt hides the stack trace of most exceptions thrown during execution.
+It prints a message that indicates how to display the exception.
+However, you may want to show more of stack traces by default.
+
+The setting to configure is `traceLevel`, which is a setting with an Int value.
+When `traceLevel` is set to a negative value, no stack traces are shown.
+When it is zero, the stack trace is displayed up to the first sbt stack frame.
+When positive, the stack trace is shown up to that many stack frames.
+
+For example, the following configures sbt to show stack traces up to the first sbt frame:
+
+{% highlight console %}
+> set every traceLevel := 0
+{% endhighlight %}
+
+The `every` part means to override the setting in all scopes.
+To change the trace printing behavior for a single project, configuration, or task, scope `traceLevel` appropriately:
+
+{% highlight console %}
+> set traceLevel in Test := 5
+> set traceLevel in update := 0
+> set traceLevel in ThisProject := -1
+{% endhighlight %}
<h4 id="nobuffer">Print the output of tests immediately instead of buffering</h4>
+By default, sbt buffers the logging output of a test until the whole class finishes.
+This is so that output does not get mixed up when executing in parallel.
+To disable buffering, set the `logBuffered` setting to false:
+
+{% highlight scala %}
+logBuffered := false
+{% endhighlight %}
+
<h4 id="custom">Add a custom logger</h4>
+The setting `extraLoggers` can be used to add custom loggers.
+A custom logger should implement [AbstractLogger].
+`extraLoggers` is a function `ScopedKey[_] => Seq[AbstractLogger]`.
+This means that it can provide different logging based on the task that requests the logger.
+
+{% highlight scala %}
+extraLoggers ~= { currentFunction =>
+ (key: ScopedKey[_]) => {
+ myCustomLogger(key) +: currentFunction(key)
+ }
+}
+{% endhighlight %}
+
+Here, we take the current function for the setting `currentFunction` and provide a new function.
+The new function prepends our custom logger to the ones provided by the old function.
+
<h4 id="log">Log messages in a task</h4>
+The special task `streams` provides per-task logging and I/O via a [Streams] instance.
+To log, a task maps the `streams` task and uses its `log` member:
+{% highlight scala %}
+myTask <<= (..., streams) map { (..., s) =>
+ s.log.warn("A warning.")
+}
+{% endhighlight %}

0 comments on commit 4305674

Please sign in to comment.