Bug 1406965 - Add docs on enabling trace logs. r=automatedtester
authorAndreas Tolfsen <ato@sny.no>
Mon, 09 Oct 2017 17:56:11 +0100
changeset 385310 529092fc92477be7accc8b604ea9c8812dafa969
parent 385309 d77fd67f3722aeb14c7545fedbbd867b24c6493c
child 385311 3bcd6572f47dcd2960b7046a143dd22bfa58e9d7
push id32652
push userarchaeopteryx@coole-files.de
push dateTue, 10 Oct 2017 21:49:31 +0000
treeherdermozilla-central@f1ecd5c26948 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersautomatedtester
bugs1406965
milestone58.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1406965 - Add docs on enabling trace logs. r=automatedtester DONTBUILD MozReview-Commit-ID: L2uZuPjA2ig
testing/geckodriver/doc/TraceLogs.md
new file mode 100644
--- /dev/null
+++ b/testing/geckodriver/doc/TraceLogs.md
@@ -0,0 +1,159 @@
+Enabling trace logs
+===================
+
+geckodriver provides different bands of logs for different audiences.
+The most important log entries are shown to everyone by default,
+and these include which port geckodriver provides the WebDriver
+API on, as well as informative warnings, errors, and fatal exceptions.
+
+The different log bands are, in ascending bandwidth:
+
+1. `fatal` is reserved for exceptional circumstances when geckodriver
+   or Firefox cannot recover.  This usually entails that either
+   one or both of the processes will exit.
+
+2. `error` messages are mistakes in the program code which it is
+   possible to recover from.
+
+3. `warn` shows warnings of more informative nature that are not
+   necessarily problems in geckodriver.  This could for example happen
+   if you use the legacy `desiredCapabilities`/`requiredCapabilities`
+   objects instead of the new `alwaysMatch`/`firstMatch` structures.
+
+4. `info` (default) contains information about which port geckodriver
+   binds to, but also all messages from the lower-bandwidth levels
+   listed above.
+
+5. `config` additionally shows the negotiated capabilities after
+   matching the `alwaysMatch` capabilities with the sequence of
+   `firstMatch` capabilities.
+
+6. `debug` is reserved for information that is useful when programming.
+
+7. `trace`, where in addition to itself, all previous levels
+   are included.  The trace level shows all HTTP requests received
+   by geckodriver, packets sent to and from the remote protocol in
+   Firefox, and responses sent back to your client.
+
+In other words this means that the configured level will coalesce
+entries from all lower bands including itself.  If you set the log
+level to `error`, you will get log entries for both `fatal` and `error`.
+Similarly for `trace`, you will get all the logs that are offered.
+
+To help debug a problem with geckodriver or Firefox, the trace-level
+output is vital to understand what is going on.  This is why we ask
+that trace logs are included when filing bugs gainst geckodriver.
+It is only under very special circumstances that a trace log is
+not needed, so you will normally find that our first action when
+triaging your issue will be to ask you to include one.  Do yourself
+and us a favour and provide a trace-level log right away.
+
+To silence geckodriver altogether you may for example either redirect
+all output to append to some log files:
+
+	% geckodriver >>geckodriver.log 2>>geckodriver.err.log
+
+Or a black hole somewhere:
+
+	% geckodriver >/dev/null 2>&1
+
+The log level set for geckodriver is propagated to the Marionette
+logger in Firefox.  Marionette is the remote protocol that geckodriver
+uses to implement WebDriver.  This means enabling trace logs for
+geckodriver will also implicitly enable them for Marionette.
+
+The log level is set in different ways.  Either by using the
+`--log <LEVEL>` option, where `LEVEL` is one of the log levels
+from the list above, or by using the `-v` (for debug) or `-vv`
+(for trace) shorthands.  For example, the following command will
+enable trace logs for both geckodriver and Marionette:
+
+	% geckodriver -vv
+
+The second way of setting the log level is through capabilities.
+geckodriver accepts a Mozila-specific configuration object
+in [`moz:firefoxOptions`].  This JSON Object, which is further
+described in the [README] can hold Firefox-specific configuration,
+such as which Firefox binary to use, additional preferences to set,
+and of course which log level to use.
+
+[`moz:firefoxOptions`]: ../README.md#firefox-capabilities
+[README]: ../README.md
+
+Each client has its own way of specifying capabilities, and some clients
+include “helpers” for providing browser-specific configuration.
+It is often advisable to use these helpers instead of encoding the
+JSON Object yourself because it can be difficult to get the exact
+details right, but if you choose to, it should look like this:
+
+	{"moz:firefoxOptions": {"log": {"level": "trace"}}}
+
+Note that most known WebDriver clients, such as those provided by
+the Selenium project, do not expose a way to actually _see_ the logs
+unless you redirect the log output to a particular file (using the
+method shown above) or let the client “inherit” geckodriver’s
+output, for example by redirecting the stdout and stderr streams to
+its own.  The notable exceptions are the Python and Ruby bindings,
+which surface geckodriver logs in a remarkable easy and efficient way.
+
+See the client-specific documentation below for the most idiomatic
+way to enable trace logs in your language.  We want to expand this
+documentation to cover all the best known clients people use with
+geckodriver.  If you find your language missing, please consider
+[submitting a patch].
+
+[submitting a patch]: ../CONTRIBUTING.md
+
+
+Python
+------
+
+The Selenium [Python client] comes with an
+[`selenium.webdriver.firefox.options.Options`] helper that can
+be used programmatically to construct the [`moz:firefoxOptions`]
+capabilities object:
+
+	from selenium.webdriver import Firefox
+	from selenium.webdriver.firefox.options import Options
+
+	opts = Options()
+	opts.log.level = "trace"
+	driver = Firefox(firefox_options=opts)
+
+The log output is stored in a file called _geckodriver.log_ in your
+script’s current working directory.
+
+[Python client]: https://selenium-python.readthedocs.io/
+[`selenium.webdriver.firefox.options.Options`]: https://github.com/SeleniumHQ/selenium/blob/master/py/selenium/webdriver/firefox/options.py
+
+
+Ruby
+----
+
+The Selenium [Ruby client] comes with an [`Options`] helper to
+generate the correct [`moz:firefoxOptions`] capabilities object:
+
+	opts = Selenium::WebDriver::Firefox::Options.new(log_level: :trace)
+	driver = Selenium::WebDriver.for :firefox, options: opts
+
+To show the logs, set the `DEBUG=1` output variable or start your
+Ruby interpreter with the `-d` flag.
+
+[Ruby client]: http://seleniumhq.github.io/selenium/docs/api/rb/
+[`Options`]: http://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/Firefox/Options.html
+
+
+Java
+----
+
+The Selenium [Java client] also comes with
+a [`org.openqa.selenium.firefox.FirefoxOptions`] helper for
+constructing the [`moz:firefoxOptions`] capabilities object:
+
+	FirefoxOptions opts = new FirefoxOptions().setLogLevel(Level.ALL);
+	WebDriver driver = new FirefoxDriver(opts);
+
+The log output is helpfully propagated to stdout.
+
+[Java client]: https://seleniumhq.github.io/selenium/docs/api/java/
+[`org.openqa.selenium.firefox.FirefoxOptions`]: https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/firefox/FirefoxOptions.html