<commit_before>---
title: Configurability (Beta/Development)
description: How to configure tracing options (beta/development).
weight: 60
keywords: [telemetry,tracing]
owner: istio/wg-policies-and-telemetry-maintainers
test: no
---

Istio provides the ability to configure advanced tracing options,
such as sampling rate and adding custom tags to reported spans.
Sampling is a beta feature, but adding custom tags and tracing tag length are
considered in-development for this release.

## Before you begin

1.  Ensure that your applications propagate tracing headers as described [here](/docs/tasks/observability/distributed-tracing/overview/).

1.  Follow the tracing installation guide located under [Integrations](/docs/ops/integrations/)
    based on your preferred tracing backend to install the appropriate addon and
    configure your Istio proxies to send traces to the tracing deployment.

## Available tracing configurations

You can configure the following tracing options in Istio:

1.  Random sampling rate for percentage of requests that will be selected for trace
    generation.

1.  Maximum length of the request path after which the path will be truncated for
    reporting. This can be useful in limiting trace data storage specially if you're
    collecting traces at ingress gateways.

1.  Adding custom tags in spans. These tags can be added based on static literal
    values, environment values or fields from request headers. This can be used to
    inject additional information in spans specific to your environment.

There are two ways you can configure tracing options:

1.  Globally via `MeshConfig` options.

1.  Per pod annotations for workload specific customization.

{{< warning >}}
In order for the new tracing configuration to take effect for either of these
options you need to restart pods injected with Istio proxies.
{{< /warning >}}

### Using `MeshConfig` for trace settings

All tracing options can be configured globally via `MeshConfig`.
To simplify configuration, it is recommended to create a single YAML file
which you can pass to the `istioctl install -f` command.

{{< text yaml >}}
cat <<'EOF' > tracing.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      tracing:
        sampling: 10
        custom_tags:
          my_tag_header:
            header:
              name: host
EOF
{{< /text >}}

### Using `proxy.istio.io/config` annotation for trace settings

You can add the `proxy.istio.io/config` annotation to your Pod metadata
specification to override any mesh-wide tracing settings.
For instance, to modify the `sleep` deployment shipped with Istio you would add
the following to `samples/sleep/sleep.yaml`:
<commit_msg>Explain pod annotation overrides for tracing (#7923)<commit_after>---
title: Configurability (Beta/Development)
description: How to configure tracing options (beta/development).
weight: 60
keywords: [telemetry,tracing]
owner: istio/wg-policies-and-telemetry-maintainers
test: no
---

Istio provides the ability to configure advanced tracing options,
such as sampling rate and adding custom tags to reported spans.
Sampling is a beta feature, but adding custom tags and tracing tag length are
considered in-development for this release.

## Before you begin

1.  Ensure that your applications propagate tracing headers as described [here](/docs/tasks/observability/distributed-tracing/overview/).

1.  Follow the tracing installation guide located under [Integrations](/docs/ops/integrations/)
    based on your preferred tracing backend to install the appropriate addon and
    configure your Istio proxies to send traces to the tracing deployment.

## Available tracing configurations

You can configure the following tracing options in Istio:

1.  Random sampling rate for percentage of requests that will be selected for trace
    generation.

1.  Maximum length of the request path after which the path will be truncated for
    reporting. This can be useful in limiting trace data storage specially if you're
    collecting traces at ingress gateways.

1.  Adding custom tags in spans. These tags can be added based on static literal
    values, environment values or fields from request headers. This can be used to
    inject additional information in spans specific to your environment.

There are two ways you can configure tracing options:

1.  Globally via `MeshConfig` options.

1.  Per pod annotations for workload specific customization.

{{< warning >}}
In order for the new tracing configuration to take effect for either of these
options you need to restart pods injected with Istio proxies.
{{< /warning >}}

Note that any pod annotations added for tracing configuration overrides global settings.
In order to preserve any global settings you should copy them from
global mesh config to pod annotations along with workload specific
customization. In particular, make sure that the tracing backend address is
always provided in the annotations to ensure that the traces are reported
correctly for the workload.

### Using `MeshConfig` for trace settings

All tracing options can be configured globally via `MeshConfig`.
To simplify configuration, it is recommended to create a single YAML file
which you can pass to the `istioctl install -f` command.

{{< text yaml >}}
cat <<'EOF' > tracing.yaml
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      tracing:
        sampling: 10
        custom_tags:
          my_tag_header:
            header:
              name: host
EOF
{{< /text >}}

### Using `proxy.istio.io/config` annotation for trace settings

You can add the `proxy.istio.io/config` annotation to your Pod metadata
specification to override any mesh-wide tracing settings.
For instance, to modify the `sleep` deployment shipped with Istio you would add
the following to `samples/sleep/sleep.yaml`:

{'fraction_non_alphanumeric': 0.056993066125486214, 'fraction_numerical': 0.0050735667174023336, 'mean_word_length': 4.098275862068966, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2500659', 'n_tokens_mistral': 1514, 'n_tokens_neox': 1449, 'n_words': 761}