Allow clients to provide ID for tracing

This makes it easier for users to communicate the trace ID to the
Gerrit support team. E.g. users can simply use a bug ID as trace ID and
then there is no need to find the generated trace ID and post it in the
bug. This is nice because finding the generated trace ID can be tricky,
e.g. for REST calls it is returned as a response header that is only
visible with curl -v or in the browser network tooling.

This slightly changes the way how tracing is enabled:

1. REST API:
   * old syntax:
     a) ?trace -> enabled trace
     b) ?trace=true -> enabled trace
     c) ?trace=false -> disabled trace
   * new syntax:
     a) ?trace -> enabled trace with generated trace ID
     b) ?trace=foo -> enabled trace with trace ID ‘foo’

2. Git API:
   * old syntax:
     a) -o trace -> enabled trace
     b) -o trace=true -> enabled trace
     c) -o trace=false -> disabled trace
   * new syntax:
     a) -o trace -> enabled trace with generated trace ID
     b) -o trace=foo -> enabled trace with trace ID ‘foo’

3. SSH API:
   * old syntax:
     a) --trace -> enabled trace
   * new syntax:
     a) --trace -> enabled trace with generated trace ID
     b) --trace --traceId=foo -> enabled trace with trace ID ‘foo’
     c) --traceId=foo -> error, cannot use --traceId without --trace

Change-Id: I4f2c3b5748678bbdf8820463d8374b854200743a
Signed-off-by: Edwin Kempin <ekempin@google.com>

Documentation/user-upload.txt

diff --git a/Documentation/user-upload.txt b/Documentation/user-upload.txt
index 78bbe99..751e886 100644
--- a/Documentation/user-upload.txt
+++ b/Documentation/user-upload.txt
@@ -424,17 +424,26 @@
 [[trace]]
 ==== Trace
 
-When pushing to Gerrit tracing can be enabled by setting the `trace`
-push option.
+When pushing to Gerrit tracing can be enabled by setting the
+`trace=<trace-id>` push option. It is recommended to use the ID of the
+issue that is being investigated as trace ID.
 
 ----
+  git push -o trace=issue/123 ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master
+----
+
+It is also possible to omit the trace ID and get a unique trace ID
+generated.
+
+.Example Request
+----
   git push -o trace ssh://john.doe@git.example.com:29418/kernel/common HEAD:refs/for/master
 ----
 
 Enabling tracing results in additional logs with debug information that
 are written to the `error_log`. All logs that correspond to the traced
-request are associated with a unique trace ID. This trace ID is
-returned in the command output:
+request are associated with the trace ID. This trace ID is returned in
+the command output:
 
 ----
   remote: TRACE_ID: 1534174322774-7edf2a7b