99ccd92b10
At the moment request tracing for REST calls is enabled by setting the 'trace' or 'trace=<trace-id>' request parameter. This is good for manual use since adding the request parameter to the URL is very easy and can be done quickly. For providing copy-pastable examples for how to do tracing this is not ideal, since it depends on the concrete URL how the request parameter would need to be set, e.g. it can be that '?trace' or '&trace' needs to be appended depending on whether the URL already contains request parameters or not. With this change we now support enabling request tracing for REST calls also by setting a 'X-Gerrit-Trace' header in the request. For manual use this is less easy but it makes providing copy-pastable examples for how to do tracing easier as one can now do: curl -D /tmp/gerrit -H X-Gerrit-Trace URL grep X-Gerrit-Trace /tmp/gerrit Change-Id: I793ca9fff83ef23f5720390931599a9a85e868c7 Signed-off-by: Edwin Kempin <ekempin@google.com>
73 lines
3.4 KiB
Plaintext
73 lines
3.4 KiB
Plaintext
= Request Tracing
|
|
|
|
Gerrit supports on-demand tracing of single requests that results in
|
|
additional logs with debug information that are written to the
|
|
`error_log`. The logs that correspond to a traced request are
|
|
associated with a unique trace ID. This trace ID is returned with the
|
|
response and can be used by an administrator to find the matching log
|
|
entries.
|
|
|
|
How tracing is enabled and how the trace ID is returned depends on the
|
|
request type:
|
|
|
|
* REST API: For REST calls tracing can be enabled by setting the
|
|
`trace` request parameter or the `X-Gerrit-Trace` header, the trace
|
|
ID is returned as `X-Gerrit-Trace` header. More information about
|
|
this can be found in the link:rest-api.html#tracing[Request Tracing]
|
|
section of the link:rest-api.html[REST API documentation].
|
|
* SSH API: For SSH calls tracing can be enabled by setting the
|
|
`--trace` option. More information about this can be found in
|
|
the link:cmd-index.html#trace[Trace] section of the
|
|
link:cmd-index.html[SSH command documentation].
|
|
* Git: For Git pushes tracing can be enabled by setting the
|
|
`trace` push option, the trace ID is returned in the command output.
|
|
More information about this can be found in
|
|
the link:user-upload.html#trace[Trace] section of the
|
|
link:user-upload.html[upload documentation]. Tracing for Git requests
|
|
other than Git push is not supported.
|
|
|
|
When request tracing is enabled it is possible to provide an ID that
|
|
should be used as trace ID. If a trace ID is not provided a trace ID is
|
|
automatically generated. The trace ID must be provided to the support
|
|
team so that they can find the trace.
|
|
|
|
When doing traces it is recommended to specify the ID of the issue
|
|
that is being investigated as trace ID so that the traces of the issue
|
|
can be found more easily. When the issue ID is used as trace ID there
|
|
is no need to find the generated trace ID and report it in the issue.
|
|
|
|
Since tracing consumes additional server resources tracing should only
|
|
be enabled for single requests if there is a concrete need for
|
|
debugging. In particular bots should never enable tracing for all their
|
|
requests by default.
|
|
|
|
== Find log entries for a trace ID
|
|
|
|
If tracing is enabled all log messages that correspond to the traced
|
|
request have a `TRACE_ID` tag set, e.g.:
|
|
|
|
----
|
|
[2018-08-13 15:28:08,913] [HTTP-76] TRACE com.google.gerrit.httpd.restapi.RestApiServlet : Received REST request: GET /a/accounts/self (parameters: [trace]) [CONTEXT forced=true TRACE_ID="1534166888910-3985dfba" ]
|
|
[2018-08-13 15:28:08,914] [HTTP-76] TRACE com.google.gerrit.httpd.restapi.RestApiServlet : Calling user: admin [CONTEXT forced=true TRACE_ID="1534166888910-3985dfba" ]
|
|
[2018-08-13 15:28:08,942] [HTTP-76] TRACE com.google.gerrit.httpd.restapi.RestApiServlet : REST call succeeded: 200 [CONTEXT forced=true TRACE_ID="1534166888910-3985dfba" ]
|
|
----
|
|
|
|
By doing a grep with the trace ID over the error log the log entries
|
|
that correspond to the request can be found.
|
|
|
|
== Which information is captured in a trace?
|
|
|
|
* request details
|
|
** REST API: request URL, request parameter names, calling user,
|
|
response code, response body on errors
|
|
** SSH API: parameter names
|
|
** Git API: push options, magic branch parameter names
|
|
* cache misses, cache evictions
|
|
* reads from NoteDb, writes to NoteDb
|
|
* reads of meta data files, writes of meta data files
|
|
* index queries (with parameters and matches)
|
|
* reindex events
|
|
* permission checks (e.g. which rule is responsible for a deny)
|
|
* timer metrics
|
|
* all other logs
|