Merge pull request goharbor#251 from ninjadq/add_doc_for_tracing

Add doc for tracing

docs/administration/distributed-tracing/_index.md

@@ -0,0 +1,24 @@
+---
+title: Distributed Tracing
+weight: 37
+---
+
+Observability is a key feature for operating a service in production and using this data you can identify abnormal statuses and make informed decisions to fix issues when an error occurs. The distributed tracing is key element of observability in modern application. Harbor can provide distributed tracing data for operators and administrator to know the current running status and to help  troubleshooting.  Harbor expose tracing data using the [OpenTelemetry]([OpenTelemetry](https://opentelemetry.io/)) sdk, you can eazily export traces via Otel protocol which can comsumed by [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) then expose to almost the on-prem or cloud trace backend. Because of the popularity [Jaeger](https://www.jaegertracing.io), Harbor also can expose tracing data to Jaeger backend directly.
+
+In harbor v2.4 and later you are able to enable distributed tracing in you Harbor [configuration file](../../install-config/configure-yml-file.md). But we only support one exporter at a time( you can not set bosh or none of them if you enabled tracing). You can set otel as exporter and leveraging OpenTelemetry Collector to retransmit to multiple backend if you want to send data to multiple exporter. And similarly, Jaeger exporter  support agent mode and endpoint mode, but only one mode can enabled at a time.
+
+# Exposed data
+
+Tracing data are exposed by serveral Harbor components: `core`, `jobservice`, `registry`. The following sections list the available Harbor trace data.
+
+| Data                     | Component   | Example                                                      |
+| :----------------------- | :---------- | :----------------------------------------------------------- |
+| Received HTTP Request    | Core        | Every HTTP request (like operation on harbor UI, push image, etc. ) |
+| Client Sent HTTP Request | Core        | core access other services via HTTP(like health check, proxy to chartmuseum, call job service API, etc.) |
+| Request ID               | Core        | Every http tracing will added a `X-Request-ID` , which will help to find the log |
+| Database Transaction     | Core        | Every Operation that triggered DB transaction(like create project, push image to harbor, etc) |
+| Received HTTP Request    | Jobservice  | Every HTTP request(like health check, call from core, etc.)  |
+| Client Sent HTTP Request | Jobservice  | jobservice access other services via HTTP(like replication job calling core API to push image, GC job calling registryctl API, etc.) |
+| backend jobs             | Jobservice  | Any job ran by jobservice                                    |
+| Received HTTP Request    | Registryctl | Every HTTP request(like health check from core, call from jobservice, etc.) |
+

docs/install-config/configure-yml-file.md

@@ -342,9 +342,57 @@ The following table lists the additional, optional parameters that you can set t
     <td valign="top"><code>path</code></td>
     <td valign="top">Path metrics are exposed on. Default is <code>/metrics</code></td>
   </tr>
+  <tr>
+    <td valign="top"><code>trace</code></td>
+    <td valign="top">&nbsp;</td>
+    <td valign="top">Configure exposing Distributed tracing data</td>
+  </tr>
+  <tr>
+    <td valign="top">&nbsp;</td>
+    <td valign="top"><code>enabled</code></td>
+    <td valign="top">Enable exposing tracing on your Harbor instance by setting this to <code>true</code>. Default is <code>false</code></td>
+  </tr>
+  <tr>
+    <td valign="top">&nbsp;</td>
+    <td valign="top"><code>sample_rate</code></td>
+    <td valign="top">Set the sample rate of tracing. For example, set sample_rate to <code>1</code> if you wanna sampling 100% of trace data; set <code>0.5</code> if you wanna sampling 50% of trace data, and so forth </td>
+  </tr>
+  <tr>
+    <td valign="top">&nbsp;</td>
+    <td valign="top"><code>namespace</code></td>
+    <td valign="top">Namespace used to differenciate different harbor services, which will set to attribute with key <code>service.namespace</code></td>
+  </tr>
+    <tr>
+    <td valign="top">&nbsp;</td>
+    <td valign="top"><code>attributes</code></td>
+    <td valign="top">The attributes is a key value dict contains user defined customized attributes used to initialize trace provider, and all of these atributes will added to trace data</td>
+  </tr>
+  <tr>
+    <td valign="top">&nbsp;</td>
+    <td valign="top"><code>jaeger</code></td>
+    <td valign="top"><ul>
+      <li><code>endpoint</code>: The url of endpoint(for example <code>http://127.0.0.1:14268/api/traces</code>). set endpoint means export to jaeger collector via http.</li>
+      <li><code>username:</code>: Username used to connect endpoint. Left empty if not needed.</li>
+      <li><code>password:</code>: Password used to connect endpoint. Left empty if not needed.</li>
+      <li><code>agent_host</code>: The host name of jaeger agent. Set agent_host means export data to jaeger agent via udp. </li>
+      <li><code>agent_port:</code>: The port name of jaeger agent.</li>
+    </ul></td>
+  </tr>
+   <tr>
+    <td valign="top">&nbsp;</td>
+    <td valign="top"><code>otel</code></td>
+    <td valign="top"><ul>
+      <li><code>endpoint</code>: The hostname and port for otel compitable backend(for example <code>127.0.0.1:4318</code>).</li>
+      <li><code>url_path:</code>: The url path of endpoint(for example <code>127.0.0.1:4318</code>) </li>
+      <li><code>compression:</code>: If enabling data compression</li>
+      <li><code>insecure</code>: Ignore cert verification for otel backend </li>
+      <li><code>timeout:</code>: The timeout of data transfer</li>
+    </ul></td>
+  </tr>
 </table>
 
 
+
 {{< note >}}
 The `harbor.yml` file includes options to configure a UAA CA certificate. This authentication mode is not recommended and is not documented.
 {{< /note >}}