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
|