diff options
Diffstat (limited to 'doc/development/distributed_tracing.md')
-rw-r--r-- | doc/development/distributed_tracing.md | 24 |
1 files changed, 12 insertions, 12 deletions
diff --git a/doc/development/distributed_tracing.md b/doc/development/distributed_tracing.md index 6d277f9ae99..9228609aae9 100644 --- a/doc/development/distributed_tracing.md +++ b/doc/development/distributed_tracing.md @@ -1,7 +1,7 @@ --- stage: Monitor group: Health -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Distributed Tracing - development guidelines @@ -49,7 +49,7 @@ all subsystems at GitLab: - Correlation IDs should never be used to pass context (for example, a username or an IP address). - Correlation IDs should never be _parsed_, or manipulated in other ways (for example, split). -The [LabKit library](https://gitlab.com/gitlab-org/labkit) provides a standardized interface for working with GitLab's +The [LabKit library](https://gitlab.com/gitlab-org/labkit) provides a standardized interface for working with GitLab correlation IDs in the Go programming language. LabKit can be used as a reference implementation for developers working with tracing and correlation IDs on non-Go GitLab subsystems. @@ -59,7 +59,7 @@ on non-Go GitLab subsystems. GitLab uses the `GITLAB_TRACING` environment variable to configure distributed tracing. The same configuration is used for all components (e.g., Workhorse, Rails, etc). -When `GITLAB_TRACING` is not set, the application will not be instrumented, meaning that there is +When `GITLAB_TRACING` is not set, the application isn't instrumented, meaning that there is no overhead at all. To enable `GITLAB_TRACING`, a valid _"configuration-string"_ value should be set, with a URL-like @@ -94,8 +94,8 @@ by typing `p` `b` in the browser window. Once the performance bar is enabled, click on the **Trace** link in the performance bar to go to the Jaeger UI. -The Jaeger search UI will return a query for the `Correlation-ID` of the current request. Normally, -this search should return a single trace result. Clicking this result will show the detail of the +The Jaeger search UI returns a query for the `Correlation-ID` of the current request. Normally, +this search should return a single trace result. Clicking this result shows the detail of the trace in a hierarchical time-line. ![Jaeger Search UI](img/distributed_tracing_jaeger_ui.png) @@ -154,7 +154,7 @@ This should start the process with the default listening ports. ### 2. Configure the `GITLAB_TRACING` environment variable -Once you have Jaeger running, you'll need to configure the `GITLAB_TRACING` variable with the +Once you have Jaeger running, configure the `GITLAB_TRACING` variable with the appropriate configuration string. **TL;DR:** If you are running everything on the same host, use the following value: @@ -178,9 +178,9 @@ This configuration string uses the Jaeger driver `opentracing://jaeger` with the | `udp_endpoint` | `localhost:6831` | This is the default. Configures Jaeger to send trace information to the UDP listener on port `6831` using compact thrift protocol. Note that we've experienced some issues with the [Jaeger Client for Ruby](https://github.com/salemove/jaeger-client-ruby) when using this protocol. | | `sampler` | `probabalistic` | Configures Jaeger to use a probabilistic random sampler. The rate of samples is configured by the `sampler_param` value. | | `sampler_param` | `0.01` | Use a ratio of `0.01` to configure the `probabalistic` sampler to randomly sample _1%_ of traces. | -| `service_name` | `api` | Override the service name used by the Jaeger backend. This parameter will take precedence over the application-supplied value. | +| `service_name` | `api` | Override the service name used by the Jaeger backend. This parameter takes precedence over the application-supplied value. | -NOTE: **Note:** +NOTE: The same `GITLAB_TRACING` value should to be configured in the environment variables for all GitLab processes, including Workhorse, Gitaly, Rails, and Sidekiq. @@ -189,7 +189,7 @@ variables for all GitLab processes, including Workhorse, Gitaly, Rails, and Side After the `GITLAB_TRACING` environment variable is exported to all GitLab services, start the application. -When `GITLAB_TRACING` is configured properly, the application will log this on startup: +When `GITLAB_TRACING` is configured properly, the application logs this on startup: ```shell 13:41:53 gitlab-workhorse.1 | 2019/02/12 13:41:53 Tracing enabled @@ -198,7 +198,7 @@ When `GITLAB_TRACING` is configured properly, the application will log this on s ... ``` -If `GITLAB_TRACING` is not configured correctly, this will also be logged: +If `GITLAB_TRACING` is not configured correctly, this issue is logged: ```shell 13:43:45 gitaly.1 | 2019/02/12 13:43:45 skipping tracing configuration step: tracer: unable to load driver mytracer @@ -215,6 +215,6 @@ not set. By default, the Jaeger search UI is available at <http://localhost:16686/search>. -TIP: **Tip:** -Don't forget that you will need to generate traces by using the application before +NOTE: +Don't forget that you must generate traces by using the application before they appear in the Jaeger UI. |