mirror of https://github.com/istio/istio.io.git
Add docs for experimental tracing configuration (#7122)
* Add docs for customizing tracing configuration * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Frank Budinsky <frankb@ca.ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Frank Budinsky <frankb@ca.ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Frank Budinsky <frankb@ca.ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Frank Budinsky <frankb@ca.ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Frank Budinsky <frankb@ca.ibm.com> * Fix linting error * Caution the use custom_tags and gateways * Spelling fixes; change to active voice * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Rachael Graham <rachael.graham@ibm.com> * Update based on comments * Remove MeshConfig from ignored spelling * Fix links * Remove gateways warning * Update content/en/docs/tasks/observability/distributed-tracing/configurability/index.md Co-Authored-By: Douglas Reid <douglas-reid@users.noreply.github.com> * Review comments * Address nit in doc; link to jaeger * Trace sampling is beta; other features are experimental * Fix whitespace Co-authored-by: Frank Budinsky <frankb@ca.ibm.com> Co-authored-by: Rachael Graham <rachael.graham@ibm.com> Co-authored-by: Douglas Reid <douglas-reid@users.noreply.github.com>
This commit is contained in:
jacob-delgado
GitHub
parent
a937dec53c
commit
988cc4606d
|
|
@ -63,7 +63,8 @@ Below is our list of existing features and their current phases. This informatio
|
|||
| [Stackdriver Integration](/docs/reference/config/policy-and-telemetry/adapters/stackdriver/) | Beta
|
||||
| [Distributed Tracing to Zipkin / Jaeger](/docs/tasks/observability/distributed-tracing/) | Beta
|
||||
| [Logging with Fluentd](/docs/tasks/observability/mixer/logs/fluentd/) | Beta
|
||||
| [Trace Sampling](/docs/tasks/observability/distributed-tracing/overview/#trace-sampling) | Beta
|
||||
| [Trace Sampling](/docs/tasks/observability/distributed-tracing/configurability/#trace-sampling) | Beta
|
||||
| [Trace Configurability](/docs/tasks/observability/distributed-tracing/configurability/) | Experimental
|
||||
|
||||
### Security and policy enforcement
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,143 @@
|
|||
---
|
||||
title: Configurability (Beta/Experimental)
|
||||
description: How to configure tracing options (beta/experimental).
|
||||
weight: 60
|
||||
keywords: [telemetry,tracing]
|
||||
---
|
||||
|
||||
Istio provides the ability to configure advanced tracing options,
|
||||
including sampling rates and span tags. Sampling is a beta feature, but
|
||||
custom tags and tracing tag length are considered experimental for this release.
|
||||
|
||||
## Create a `MeshConfig` with trace settings
|
||||
|
||||
All tracing options are configured by using `MeshConfig` during Istio *installation*.
|
||||
To simplify configuration, create a single YAML file to pass to `istioctl`.
|
||||
|
||||
{{< text yaml >}}
|
||||
cat <<'EOF' > tracing.yaml
|
||||
apiVersion: install.istio.io/v1alpha1
|
||||
kind: IstioOperator
|
||||
spec:
|
||||
meshConfig:
|
||||
defaultConfig:
|
||||
tracing:
|
||||
EOF
|
||||
{{< /text >}}
|
||||
|
||||
Then, you can append any configuration options to the `tracing.yaml` file.
|
||||
|
||||
## Trace sampling
|
||||
|
||||
Istio captures a trace for all requests by default when installing with the demo profile.
|
||||
For example, when using the Bookinfo sample application, every time you access
|
||||
`/productpage` you see a corresponding trace in the
|
||||
[dashboard](../jaeger/). 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:
|
||||
|
||||
{{< warning >}}
|
||||
Previously, the recommended method was to change the `values.pilot.traceSampling` setting during the mesh setup
|
||||
or to change the `PILOT_TRACE_SAMPLE` environment variable in the pilot or istiod deployment.
|
||||
While this method to alter sampling continues to work, the following method
|
||||
is strongly recommended instead.
|
||||
|
||||
In the event that both are specified, the value specified in the `MeshConfig` will override any other setting.
|
||||
{{< /warning >}}
|
||||
|
||||
To modify the default random sampling, which is defaulted to a value of 100 in the demo profile
|
||||
and 1 for the default profile, add the following to your `tracing.yaml` file.
|
||||
|
||||
{{< text yaml >}}
|
||||
apiVersion: install.istio.io/v1alpha1
|
||||
kind: IstioOperator
|
||||
spec:
|
||||
meshConfig:
|
||||
defaultConfig:
|
||||
tracing:
|
||||
sampling: <VALUE>
|
||||
{{< /text >}}
|
||||
|
||||
Where the `<VALUE>` should be in the range of 0.0 to 100.0 with a precision of 0.01.
|
||||
For example, to trace 5 requests out of every 10000, use 0.05 as the value here.
|
||||
|
||||
## Customizing tracing tags
|
||||
|
||||
The ability to add custom tracing tags to spans has also been implemented.
|
||||
|
||||
Tags can be added to spans based on literals, environmental variables and
|
||||
client request headers.
|
||||
|
||||
{{< warning >}}
|
||||
There is no limit on the number of custom tags that you can add, but tag names must be unique.
|
||||
{{< /warning >}}
|
||||
|
||||
To add custom tags to your spans, add the following to your `tracing.yaml` file.
|
||||
|
||||
Literals:
|
||||
|
||||
{{< text yaml >}}
|
||||
apiVersion: install.istio.io/v1alpha1
|
||||
kind: IstioOperator
|
||||
spec:
|
||||
meshConfig:
|
||||
defaultConfig:
|
||||
tracing:
|
||||
custom_tags:
|
||||
tag_literal: # user-defined name
|
||||
literal:
|
||||
value: <VALUE>
|
||||
{{< /text >}}
|
||||
|
||||
Environmental variables:
|
||||
|
||||
{{< text yaml >}}
|
||||
apiVersion: install.istio.io/v1alpha1
|
||||
kind: IstioOperator
|
||||
spec:
|
||||
meshConfig:
|
||||
defaultConfig:
|
||||
tracing:
|
||||
custom_tags:
|
||||
tag_env:
|
||||
environment: # user-defined name
|
||||
name: <ENV_VARIABLE_NAME>
|
||||
defaultValue: <VALUE> # optional
|
||||
{{< /text >}}
|
||||
|
||||
{{< warning >}}
|
||||
In order to add custom tags based on environmental variables, you must
|
||||
modify the `istio-sidecar-injector` ConfigMap in your root Istio system namespace.
|
||||
{{< /warning >}}
|
||||
|
||||
Client request headers:
|
||||
|
||||
{{< text yaml >}}
|
||||
apiVersion: install.istio.io/v1alpha1
|
||||
kind: IstioOperator
|
||||
spec:
|
||||
meshConfig:
|
||||
defaultConfig:
|
||||
tracing:
|
||||
custom_tags:
|
||||
tag_header: # user-defined name
|
||||
header:
|
||||
name: <CLIENT-HEADER>
|
||||
defaultValue: <VALUE> # optional
|
||||
{{< /text >}}
|
||||
|
||||
## Customizing tracing tag length
|
||||
|
||||
By default, the maximum length for the request path included as part of the `HttpUrl` span tag is 256.
|
||||
|
||||
To modify this maximum length, add the following to your `tracing.yaml` file.
|
||||
|
||||
{{< text yaml >}}
|
||||
apiVersion: install.istio.io/v1alpha1
|
||||
kind: IstioOperator
|
||||
spec:
|
||||
meshConfig:
|
||||
defaultConfig:
|
||||
tracing:
|
||||
max_path_tag_length: <VALUE>
|
||||
{{< /text >}}
|
||||
|
|
@ -124,7 +124,7 @@ The LightStep integration does not currently capture spans generated by Istio's
|
|||
## Trace sampling
|
||||
|
||||
Istio captures traces at a configurable trace sampling percentage. To learn how to modify the trace sampling percentage,
|
||||
visit the [Distributed Tracing trace sampling section](../overview/#trace-sampling).
|
||||
visit the [Distributed Tracing trace sampling section](../configurability/#trace-sampling).
|
||||
When using LightStep, 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -90,32 +90,3 @@ public Response bookReviewsById(@PathParam("productId") int productId,
|
|||
|
||||
When you make downstream calls in your applications, make sure to include these headers.
|
||||
|
||||
## Trace sampling
|
||||
|
||||
Istio captures a trace for all requests by default when installing with the demo profile.
|
||||
For example, when using the Bookinfo sample application above, every time you access
|
||||
`/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:
|
||||
|
||||
* During the mesh setup, use the option `values.pilot.traceSampling` to
|
||||
set the percentage of trace sampling. See the
|
||||
[Installing with {{< istioctl >}}](/docs/setup/install/istioctl/) documentation for
|
||||
details on setting options.
|
||||
* In a running mesh, edit the `istio-pilot` deployment and
|
||||
change the environment variable with the following steps:
|
||||
|
||||
1. To open your text editor with the deployment configuration file
|
||||
loaded, run the following command:
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl -n istio-system edit deploy istio-pilot
|
||||
{{< /text >}}
|
||||
|
||||
1. Find the `PILOT_TRACE_SAMPLING` environment variable, and change
|
||||
the `value:` to your desired percentage.
|
||||
|
||||
In both cases, valid values are from 0.0 to 100.0 with a precision of 0.01.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -4,4 +4,4 @@ weight: 40
|
|||
---
|
||||
|
||||
Istio, via Envoy, currently supports a percentage-based sampling strategy for trace generation.
|
||||
Please see [this section](/docs/tasks/observability/distributed-tracing/overview/#trace-sampling) for more information on how to set this sampling rate.
|
||||
Please see [this section](/docs/tasks/observability/distributed-tracing/configurability/#trace-sampling) for more information on how to set this sampling rate.
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Since Istio 1.0.3, the sampling rate for tracing has been reduced to 1% in the `
|
|||
[configuration profile](/docs/setup/additional-setup/config-profiles/).
|
||||
This means that only 1 out of 100 trace instances captured by Istio will be reported to the tracing backend.
|
||||
The sampling rate in the `demo` profile is still set to 100%. See
|
||||
[this section](/docs/tasks/observability/distributed-tracing/overview/#trace-sampling)
|
||||
[this section](/docs/tasks/observability/distributed-tracing/configurability/#trace-sampling)
|
||||
for more information on how to set the sampling rate.
|
||||
|
||||
If you still do not see any trace data, please confirm that your ports conform to the Istio [port naming conventions](/faq/traffic-management/#naming-port-convention) and that the appropriate container port is exposed (via pod spec, for example) to enable
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ We're pleased to announce the availability of Istio 1.0.3. Please see below for
|
|||
|
||||
- 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/observability/distributed-tracing/overview/#trace-sampling) is set to 1%.
|
||||
- Default [trace sampling](/docs/tasks/observability/distributed-tracing/configurability/#trace-sampling) is set to 1%.
|
||||
|
||||
## Policy and telemetry
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue