Add initial doc changes related to tracing provider and support for z… (#2884)

* Add initial doc changes related to tracing provider and support for zipkin backend

* Suggestion for way to incorporate more tracing backends - using text from lightstep PR #2844

* Update based on review comments. Moved lightstep content (from #2844 to subfolder

* Add more zipkin content and images

* Remove jaeger from dt page

* Updates following comments

* Updates to address comments

content/about/feature-stages/index.md

@@ -54,7 +54,7 @@ Below is our list of existing features and their current phases. This informatio
 | [Distributed Tracing to Zipkin / Jaeger](/docs/tasks/telemetry/distributed-tracing/) | Alpha
 | [Service Tracing](/docs/tasks/telemetry/distributed-tracing/) | Alpha
 | [Logging with Fluentd](/docs/tasks/telemetry/fluentd/) | Alpha
-| [Trace Sampling](/docs/tasks/telemetry/distributed-tracing/#trace-sampling) | Alpha
+| [Trace Sampling](/docs/tasks/telemetry/distributed-tracing/overview/#trace-sampling) | Alpha
 
 ### Security and Policy Enforcement
 

content/about/notes/1.0.3/index.md

@@ -23,7 +23,7 @@ This release note describes what's different between Istio 1.0.2 and Istio 1.0.3
 
 - Pilot performance and scalability has been greatly enhanced. Pilot now delivers endpoint updates to 500 sidecars in under 1 second.
 
-- Default [trace sampling](/docs/tasks/telemetry/distributed-tracing/#trace-sampling) is set to 1%.
+- Default [trace sampling](/docs/tasks/telemetry/distributed-tracing/overview/#trace-sampling) is set to 1%.
 
 ## Policy and telemetry
 

content/docs/concepts/what-is-istio/index.md

@@ -32,7 +32,7 @@ Istio provides behavioral insights and operational control over the service mesh
 
 ## Why use Istio?
 
-Istio makes it easy to create a network of deployed services with load balancing, service-to-service authentication, monitoring, and more, with [few](/docs/tasks/telemetry/distributed-tracing/#understanding-what-happened) or no code changes
+Istio makes it easy to create a network of deployed services with load balancing, service-to-service authentication, monitoring, and more, with [few](/docs/tasks/telemetry/distributed-tracing/overview/#understanding-what-happened) or no code changes
 in service code. You add Istio support to services by deploying a special sidecar proxy throughout your environment that intercepts all network communication
 between microservices, then configure and manage Istio using its control plane functionality, which includes:
 

content/docs/setup/kubernetes/quick-start-gke-dm/index.md

@@ -221,7 +221,7 @@ You should see the trace statistics sent earlier on [http://localhost:16686](htt
     caption="Tracing Dashboard"
     >}}
 
-For more details on tracing see [Understanding what happened](/docs/tasks/telemetry/distributed-tracing/#understanding-what-happened).
+For more details on tracing see [Understanding what happened](/docs/tasks/telemetry/distributed-tracing/overview/#understanding-what-happened).
 
 ## Uninstalling
 

content/docs/tasks/telemetry/distributed-tracing/_index.md

@@ -0,0 +1,6 @@
+---
+title: Distributed Tracing
+description: This task shows you how to configure Istio-enabled applications to collect trace spans.
+weight: 10
+keywords: [telemetry,tracing]
+---

content/docs/tasks/telemetry/distributed-tracing/jaeger/index.md

@@ -0,0 +1,66 @@
+---
+title: Jaeger
+description: Learn how to configure the proxies to send tracing requests to Jaeger.
+weight: 10
+keywords: [telemetry,tracing,jaeger,span,port forwarding]
+---
+
+To learn how Istio handles tracing, visit this task's [overview](../overview/).
+
+## Before you begin
+
+1.  To set up Istio, follow the instructions in the [Installation guide](/docs/setup/).
+
+    Use the Helm chart with tracing enabled to set the `--set tracing.enabled=true` option.
+
+1.  Deploy the [Bookinfo](/docs/examples/bookinfo/#deploying-the-application) sample application.
+
+## Accessing the dashboard
+
+1.  To setup access to the tracing dashboard, use port forwarding:
+
+    {{< text bash >}}
+    $ kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=istio-ingressgateway -o jsonpath='{.items[0].metadata.name}') 15032:15032 &
+    {{< /text >}}
+
+    Open your browser to [http://localhost:15032](http://localhost:15032).
+
+1.  To use a Kubernetes ingress, specify the Helm chart option `--set tracing.ingress.enabled=true`.
+
+## Generating traces using the Bookinfo sample
+
+1.  When the Bookinfo application is up and running, access `http://$GATEWAY_URL/productpage` one or more times
+    to generate trace information.
+
+1.  From the left-hand pane of the dashboard, select `productpage` from the **Service** drop-down list and click
+    **Find Traces**:
+
+    {{< image width="100%" ratio="52.68%"
+    link="./istio-tracing-list.png"
+    caption="Tracing Dashboard"
+    >}}
+
+1.  Click on the most recent trace at the top to see the details corresponding to the
+    latest request to the `/productpage`:
+
+    {{< image width="100%" ratio="36.32%"
+    link="./istio-tracing-details.png"
+    caption="Detailed Trace View"
+    >}}
+
+1.  The trace is comprised of a set of spans,
+    where each span corresponds to a Bookinfo service, invoked during the execution of a `/productpage` request, or
+    internal Istio component, for example: `istio-ingressgateway`, `istio-mixer`, `istio-policy`.
+
+## Cleanup
+
+1.  Remove any `kubectl port-forward` processes that may still be running:
+
+    {{< text bash >}}
+    $ killall kubectl
+    {{< /text >}}
+
+1.  If you are not planning to explore any follow-on tasks, refer to the
+    [Bookinfo cleanup](/docs/examples/bookinfo/#cleanup) instructions
+    to shutdown the application.
+

content/docs/tasks/telemetry/distributed-tracing/lightstep/index.md

@@ -1,5 +1,5 @@
 ---
-title: Distributed Tracing With LightStep [𝑥]PM
+title: LightStep [𝑥]PM
 description: How to configure the proxies to send tracing requests to LightStep [𝑥]PM.
 weight: 11
 keywords: [telemetry,tracing,lightstep]
@@ -123,7 +123,7 @@ server-side span of the call. The screenshot shows that the call took 14.60 ms.
 ## Trace sampling
 
 Istio captures traces at a configurable trace sampling percentage. To learn how to modify the trace sampling percentage,
-visit the [Distributed Tracing With Jaeger trace sampling section](../distributed-tracing/#trace-sampling).
+visit the [Distributed Tracing trace sampling section](../overview/#trace-sampling).
 When using LightStep [𝑥]PM, we do not recommend reducing the trace sampling percentage below 100%. To handle a high traffic mesh,
 consider scaling up the size of your satellite pool.
 
@@ -139,3 +139,4 @@ from your cluster.
 {{< text bash >}}
 $ kubectl delete secret lightstep.cacert
 {{< /text >}}
+

content/docs/tasks/telemetry/distributed-tracing/overview/index.md

@@ -1,72 +1,14 @@
 ---
-title: Distributed Tracing With Jaeger
-description: How to configure the proxies to send tracing requests to Zipkin or Jaeger.
-weight: 10
+title: Overview
+description: Overview of distributed tracing in Istio.
+weight: 1
 keywords: [telemetry,tracing]
-aliases:
-    - /docs/tasks/zipkin-tracing.html
 ---
 
-This task shows you how Istio-enabled applications can be configured to collect trace spans.
-After completing this task, you should understand all of the assumptions about your
-application and how to have it participate in tracing, regardless of what
-language/framework/platform you use to build your application.
+After completing this task, you understand how to have your application participate in tracing,
+regardless of the language, framework, or platform you use to build your application.
 
-The [Bookinfo](/docs/examples/bookinfo/) sample is used as the
-example application for this task.
-
-## Before you begin
-
-*   Setup Istio by following the instructions in the [Installation guide](/docs/setup/).
-
-    Either use the `istio-demo.yaml` or `istio-demo-auth.yaml` template, which includes tracing support, or
-    use the Helm chart with tracing enabled by setting the `--set tracing.enabled=true` option.
-
-* Deploy the [Bookinfo](/docs/examples/bookinfo/) sample application.
-
-## Accessing the dashboard
-
-Setup access to the Jaeger dashboard by using port-forwarding:
-
-{{< text bash >}}
-$ kubectl port-forward -n istio-system $(kubectl get pod -n istio-system -l app=jaeger -o jsonpath='{.items[0].metadata.name}') 16686:16686 &
-{{< /text >}}
-
-Access the Jaeger dashboard by opening your browser to [http://localhost:16686](http://localhost:16686).
-
-## Generating traces using the Bookinfo sample
-
-With the Bookinfo application up and running, generate trace information by accessing
-`http://$GATEWAY_URL/productpage` one or more times.
-
-From the left-hand pane of the Jaeger dashboard, select `productpage` from the Service drop-down list and click
-Find Traces. You should see something similar to the following:
-
-{{< image width="100%" ratio="52.68%"
-    link="./istio-tracing-list.png"
-    caption="Tracing Dashboard"
-    >}}
-
-If you click on the top (most recent) trace, you should see the details corresponding to your
-latest refresh of the `/productpage`.
-The page should look something like this:
-
-{{< image width="100%" ratio="36.32%"
-    link="./istio-tracing-details.png"
-    caption="Detailed Trace View"
-    >}}
-
-As you can see, the trace is comprised of a set of spans,
-where each span corresponds to a Bookinfo service invoked during the execution of a `/productpage` request.
-
-Every RPC is represented by two spans in the trace. For example, the call from `productpage` to `reviews` starts
-with the span labeled `productpage reviews.default.svc.cluster.local:9080/`, which represents the client-side
-span for the call. It took 24.13 ms. The second span (labeled `reviews reviews.default.svc.cluster.local:9080/`)
-is a child of the first span and represents the server-side span for the call. It took 22.99 ms.
-
-The trace for the call to the `reviews` services reveals two subsequent RPC's in the trace. The first is to the `istio-policy`
-service, reflecting the server-side Check call made for the service to authorize access. The second is the call out to
-the `ratings` service.
+This task uses the [Bookinfo](/docs/examples/bookinfo/) sample as the example application.
 
 ## Understanding what happened
 
@@ -138,7 +80,7 @@ When you make downstream calls in your applications, make sure to include these
 
 Istio captures a trace for all requests by default. For example, when
 using the Bookinfo sample application above, every time you access
-`/productpage` you see a corresponding trace in the Jaeger
+`/productpage` you see a corresponding trace in the
 dashboard. This sampling rate is suitable for a test or low traffic
 mesh. For a high traffic mesh you can lower the trace sampling
 percentage in one of two ways:
@@ -162,14 +104,4 @@ percentage in one of two ways:
 
 In both cases, valid values are from 0.0 to 100.0 with a precision of 0.01.
 
-## Cleanup
 
-*   Remove any `kubectl port-forward` processes that may still be running:
-
-    {{< text bash >}}
-    $ killall kubectl
-    {{< /text >}}
-
-*   If you are not planning to explore any follow-on tasks, refer to the
-    [Bookinfo cleanup](/docs/examples/bookinfo/#cleanup) instructions
-    to shutdown the application.

content/docs/tasks/telemetry/distributed-tracing/zipkin/index.md

@@ -0,0 +1,69 @@
+---
+title: Zipkin
+description: Learn how to configure the proxies to send tracing requests to Zipkin.
+weight: 10
+keywords: [telemetry,tracing,zipkin,span,port forwarding]
+aliases:
+    - /docs/tasks/zipkin-tracing.html
+---
+
+To learn how Istio handles tracing, visit this task's [overview](../overview/).
+
+## Before you begin
+
+1.  To set up Istio, follow the instructions in the [Installation guide](/docs/setup/).
+
+    Use the Helm chart with tracing enabled to set the `--set tracing.enabled=true` option and
+    select the `zipkin` tracing provider with `--set tracing.provider=zipkin`.
+
+1.  Deploy the [Bookinfo](/docs/examples/bookinfo/#deploying-the-application) sample application.
+
+## Accessing the dashboard
+
+1.  To setup access to the tracing dashboard, use port forwarding:
+
+    {{< text bash >}}
+    $ kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=istio-ingressgateway -o jsonpath='{.items[0].metadata.name}') 15032:15032 &
+    {{< /text >}}
+
+    Open your browser to [http://localhost:15032](http://localhost:15032).
+
+1.  To use a Kubernetes ingress, specify the Helm chart option `--set tracing.ingress.enabled=true`.
+
+## Generating traces using the Bookinfo sample
+
+1.  When the Bookinfo application is up and running, access `http://$GATEWAY_URL/productpage` one or more times
+    to generate trace information.
+
+1.  From the top panel, select a service of interest (or 'all') from the **Service Name** drop-down list and click
+    **Find Traces**:
+
+    {{< image width="100%" ratio="52.68%"
+    link="./istio-tracing-list-zipkin.png"
+    caption="Tracing Dashboard"
+    >}}
+
+1.  Click on the most recent trace at the top to see the details corresponding to the
+    latest request to the `/productpage`:
+
+    {{< image width="100%" ratio="36.32%"
+    link="./istio-tracing-details-zipkin.png"
+    caption="Detailed Trace View"
+    >}}
+
+1.  The trace is comprised of a set of spans,
+    where each span corresponds to a Bookinfo service, invoked during the execution of a `/productpage` request, or
+    internal Istio component, for example: `istio-ingressgateway`, `istio-mixer`, `istio-policy`.
+
+## Cleanup
+
+1.  Remove any `kubectl port-forward` processes that may still be running:
+
+    {{< text bash >}}
+    $ killall kubectl
+    {{< /text >}}
+
+1.  If you are not planning to explore any follow-on tasks, refer to the
+    [Bookinfo cleanup](/docs/examples/bookinfo/#cleanup) instructions
+    to shutdown the application.
+

content_zh/docs/tasks/telemetry/distributed-tracing/index.md

@@ -34,14 +34,14 @@ $ kubectl port-forward -n istio-system $(kubectl get pod -n istio-system -l app=
 在 Jaeger dashboard 左侧版面中，从 Service 下拉列表中选择 `productpage`，点击 `Find Traces` 按钮，就会看到类似下图的内容：
 
 {{< image width="100%" ratio="42.35%"
-    link="/docs/tasks/telemetry/distributed-tracing/istio-tracing-list.png"
+    link="/docs/tasks/telemetry/distributed-tracing/jaeger/istio-tracing-list.png"
     caption="跟踪 Dashboard"
     >}}
 
 如果点击顶部（`most recent`）的跟踪信息，会看到最后一次刷新 `/productpage` 页面的信息。显示的内容会跟下图类似：
 
 {{< image width="100%" ratio="42.35%"
-    link="/docs/tasks/telemetry/distributed-tracing//istio-tracing-details.png"
+    link="/docs/tasks/telemetry/distributed-tracing/jaeger/istio-tracing-details.png"
     caption="跟踪信息详细视图"
     >}}