Add sampling info to Tracing tasks (#3397)

* Add sampling info to Tracing tasks

* Address review comments and add boilerplate

* Add link to OpenTracing

* Address review comments

* Wording changes

.spelling

@@ -326,6 +326,7 @@ OpenID_Connect
 OpenShift
 OpenSSL
 openssl
+OpenTracing
 OS-level
 Ostrowski
 p50

content/boilerplates/trace-generation.md

@@ -0,0 +1,7 @@
+To see trace data, you must send requests to your service. The number of requests depends on Istio's sampling rate.
+You set this rate when you install Istio. The default sampling rate is 1%. You need to send at least 100 requests before the first trace is visible.
+To send a 100 requests to the `productpage` service, use the following command:
+
+{{< text bash >}}
+$ for i in `seq 1 100`; do curl -s -o /dev/null http://$GATEWAY_URL/productpage; done
+{{< /text >}}

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

@@ -9,9 +9,13 @@ 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/).
+1.  To set up Istio, follow the instructions in the [Installation guide](/docs/setup/kubernetes/install/helm)
+    and use the `--set tracing.enabled=true`  Helm install options to enable tracing.
 
-    Use the Helm chart with tracing enabled to set the `--set tracing.enabled=true` option.
+    {{< warning >}}
+    When you enable tracing, you can set the sampling rate that Istio uses for tracing.
+    Use the `pilot.traceSampling` option to set the sampling rate. The default sampling rate is 1%.
+    {{< /warning >}}
 
 1.  Deploy the [Bookinfo](/docs/examples/bookinfo/#deploying-the-application) sample application.
 
@@ -32,6 +36,8 @@ To learn how Istio handles tracing, visit this task's [overview](../overview/).
 1.  When the Bookinfo application is up and running, access `http://$GATEWAY_URL/productpage` one or more times
     to generate trace information.
 
+    {{< boilerplate trace-generation >}}
+
 1.  From the left-hand pane of the dashboard, select `productpage` from the **Service** drop-down list and click
     **Find Traces**:
 

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

@@ -26,29 +26,34 @@ To do this, an application needs to collect and propagate the following headers
 * `x-b3-flags`
 * `x-ot-span-context`
 
-If you look in the sample services, you can see that the `productpage` service (Python) extracts the required headers from an HTTP request:
+If you look at the sample Python `productpage` service, for example,
+you see that the application extracts the required headers from an HTTP request
+using [OpenTracing](https://opentracing.io/) libraries:
 
 {{< text python >}}
 def getForwardHeaders(request):
     headers = {}
 
-    if 'user' in session:
-        headers['end-user'] = session['user']
+    # x-b3-*** headers can be populated using the opentracing span
+    span = get_current_span()
+    carrier = {}
+    tracer.inject(
+        span_context=span.context,
+        format=Format.HTTP_HEADERS,
+        carrier=carrier)
 
-    incoming_headers = [ 'x-request-id',
-                         'x-b3-traceid',
-                         'x-b3-spanid',
-                         'x-b3-parentspanid',
-                         'x-b3-sampled',
-                         'x-b3-flags',
-                         'x-ot-span-context'
-    ]
+    headers.update(carrier)
+
+    # ...
+
+    incoming_headers = ['x-request-id']
+
+    # ...
 
     for ihdr in incoming_headers:
         val = request.headers.get(ihdr)
         if val is not None:
             headers[ihdr] = val
-            #print "incoming: "+ihdr+":"+val
 
     return headers
 {{< /text >}}
@@ -67,8 +72,6 @@ public Response bookReviewsById(@PathParam("productId") int productId,
                             @HeaderParam("x-b3-sampled") String xsampled,
                             @HeaderParam("x-b3-flags") String xflags,
                             @HeaderParam("x-ot-span-context") String xotspan) {
-  int starsReviewer1 = -1;
-  int starsReviewer2 = -1;
 
   if (ratings_enabled) {
     JsonObject ratingsResponse = getRatings(Integer.toString(productId), user, xreq, xtraceid, xspanid, xparentspanid, xsampled, xflags, xotspan);

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

@@ -11,10 +11,16 @@ 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/).
+1.  To set up Istio, follow the instructions in the [Installation guide](/docs/setup/kubernetes/install/helm).
 
-    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`.
+    Use the following Helm install options to enable tracing and to select the `zipkin` tracing provider:
+    * `--set tracing.enabled=true`
+    * `--set tracing.provider=zipkin`
+
+    {{< warning >}}
+    When you enable tracing, you can set the sampling rate that Istio uses for tracing.
+    Use the `pilot.traceSampling` option to set the sampling rate. The default sampling rate is 1%.
+    {{< /warning >}}
 
 1.  Deploy the [Bookinfo](/docs/examples/bookinfo/#deploying-the-application) sample application.
 
@@ -35,6 +41,8 @@ To learn how Istio handles tracing, visit this task's [overview](../overview/).
 1.  When the Bookinfo application is up and running, access `http://$GATEWAY_URL/productpage` one or more times
     to generate trace information.
 
+    {{< boilerplate trace-generation >}}
+
 1.  From the top panel, select a service of interest (or 'all') from the **Service Name** drop-down list and click
     **Find Traces**: