From 0ade5aaa9f295e22de8bd9194d19ff81b411c1bb Mon Sep 17 00:00:00 2001 From: Edwin Kempin Date: Fri, 10 Aug 2018 08:49:32 +0200 Subject: [PATCH] Add documentation for request tracing Change-Id: If2d57ae451abeb0f0040b5960c7f7a930247328a Signed-off-by: Edwin Kempin --- Documentation/cmd-index.txt | 21 +++++++++++++ Documentation/index.txt | 1 + Documentation/rest-api.txt | 29 ++++++++++++++++++ Documentation/user-request-tracing.txt | 41 ++++++++++++++++++++++++++ Documentation/user-upload.txt | 22 ++++++++++++++ 5 files changed, 114 insertions(+) create mode 100644 Documentation/user-request-tracing.txt diff --git a/Documentation/cmd-index.txt b/Documentation/cmd-index.txt index 236240115f..a7b4650c29 100644 --- a/Documentation/cmd-index.txt +++ b/Documentation/cmd-index.txt @@ -205,6 +205,27 @@ link:cmd-show-queue.html[ps]:: link:cmd-suexec.html[suexec]:: Execute a command as any registered user account. +=== [[trace]]Trace + +For executing SSH commands tracing can be enabled by setting the +`--trace` option. + +---- + $ ssh -p 29418 review.example.com gerrit create-project --trace foo/bar +---- + +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 printed +to the stderr command output: + +---- + TRACE_ID: 1534174322774-7edf2a7b +---- + +Given the trace ID an administrator can find the corresponding logs and +investigate issues more easily. + GERRIT ------ Part of link:index.html[Gerrit Code Review] diff --git a/Documentation/index.txt b/Documentation/index.txt index 84925f4f98..6011158542 100644 --- a/Documentation/index.txt +++ b/Documentation/index.txt @@ -67,6 +67,7 @@ . link:config-reverseproxy.html[Reverse Proxy] . link:config-auto-site-initialization.html[Automatic Site Initialization on Startup] . link:pgm-index.html[Server Side Administrative Tools] +. link:user-request-tracing.html[Request Tracing] . link:note-db.html[NoteDb] . link:config-accounts.html[Accounts on NoteDb] . link:config-groups.html[Groups on NoteDb] diff --git a/Documentation/rest-api.txt b/Documentation/rest-api.txt index 0957d32c52..a9c1ca69fa 100644 --- a/Documentation/rest-api.txt +++ b/Documentation/rest-api.txt @@ -191,6 +191,35 @@ Preconditions] section. "`422 Unprocessable Entity`" is returned if the ID of a resource that is specified in the request body cannot be resolved. +[[tracing]] +=== Request Tracing +For each REST endpoint tracing can be enabled by setting the `trace` +request parameter. + +.Example Request +---- + GET /changes/myProject~master~I8473b95934b5732ac55d26311a706c9c2bde9940/suggest_reviewers?trace&q=J +---- + +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 with the REST response in the `X-Gerrit-Trace` header. + +.Example Response +---- +HTTP/1.1 200 OK + Content-Disposition: attachment + Content-Type: application/json; charset=UTF-8 + X-Gerrit-Trace: 1533885943749-8257c498 + + )]}' + ... ... +---- + +Given the trace ID an administrator can find the corresponding logs and +investigate issues more easily. + GERRIT ------ Part of link:index.html[Gerrit Code Review] diff --git a/Documentation/user-request-tracing.txt b/Documentation/user-request-tracing.txt new file mode 100644 index 0000000000..7d98b25364 --- /dev/null +++ b/Documentation/user-request-tracing.txt @@ -0,0 +1,41 @@ += 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, 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. + +== 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. diff --git a/Documentation/user-upload.txt b/Documentation/user-upload.txt index 31a32addfa..62f7eb6231 100644 --- a/Documentation/user-upload.txt +++ b/Documentation/user-upload.txt @@ -421,6 +421,28 @@ branches, consider adding a custom remote block to your project's $ git push exp ---- +[[trace]] +==== Trace + +When pushing to Gerrit tracing can be enabled by setting the `trace` +push option. + +---- + git push -o trace=true 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: + +---- + remote: TRACE_ID: 1534174322774-7edf2a7b +---- + +Given the trace ID an administrator can find the corresponding logs and +investigate issues more easily. + [[push_replace]] === Replace Changes