--- title: istio.telemetry.v1alpha1 layout: protoc-gen-docs generator: protoc-gen-docs number_of_entries: 7 ---

Telemetry

Telemetry defines how the telemetry is generated for workloads within a mesh.

For mesh level configuration, put the resource in root configuration namespace for your Istio installation without a workload selector.

For any namespace, including the root configuration namespace, it is only valid to have a single workload selector-less Telemetry resource.

For resources with a workload selector, it is only valid to have one resource selecting any given workload.

Telemetry configuration will use a “shallow merge” semantic for configuration override for each telemetry type (Tracing, Metrics, AccessLogging). For example, Tracing configuration will support overrides of the fields providers, random_sampling_percentage, disable_span_reporting, and custom_tags at each level in the configuration hierarchy, with missing values filled in from parent resources. However, when specified, fields like custom_tags will fully replace any values provided by parent configuration.

The hierarchy of Telemetry configuration is as follows: 1. Workload-specific configuration 1. Namespace-specific configuration 1. Root namespace configuration

WARNING: Support for Telemetry policies is under active development and is not stable or supported by Istio at this time.

Examples:

Policy to enable random sampling for 10% of traffic:

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  name: mesh-default
  namespace: istio-system
spec:
  tracing:
  - randomSamplingPercentage: 10.00

Policy to disable trace reporting for the “foo” workload (note: tracing context will still be propagated):

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  name: foo-tracing
  namespace: bar
spec:
  selector:
    labels:
      service.istio.io/canonical-name: foo
  tracing:
  - disableSpanReporting: true

Policy to select the alternate zipkin provider for trace reporting:

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  name: foo-tracing-alternate
  namespace: baz
spec:
  selector:
    labels:
      service.istio.io/canonical-name: foo
  tracing:
  - providers:
    - name: "zipkin-alternate"
    randomSamplingPercentage: 10.00

Policy to add a custom tag from a literal value:

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  name: mesh-default
  namespace: istio-system
spec:
  tracing:
  - randomSamplingPercentage: 10.00
    customTags:
      my_new_foo_tag:
        literal:
          value: "foo"
Field Type Description Required
selector WorkloadSelector

Optional. The selector decides where to apply the Telemetry policy. If not set, the Telemetry policy will be applied to all workloads in the same namespace as the Telemetry policy.

No
tracing Tracing[]

Optional. Tracing configures the tracing behavior for all selected workloads.

No

Tracing

Tracing configures tracing behavior for workloads within a mesh. It can be used to enable/disable tracing, as well as to set sampling rates and custom tag extraction.

Field Type Description Required
providers ProviderRef[]

Optional. Name of provider(s) to use for span reporting. If a provider is not specified, the default tracing provider will be used. NOTE: At the moment, only a single provider can be specified in a given Tracing rule.

No
randomSamplingPercentage DoubleValue

Controls the rate at which traffic will be selected for tracing if no prior sampling decision has been made. If a prior sampling decision has been made, that decision will be respected. However, if no sampling decision has been made (example: no x-b3-sampled tracing header was present in the requests), the traffic will be selected for telemetry generation at the percentage specified.

Defaults to 0%. Valid values [0.00-100.00]. Can be specified in 0.01% increments.

No
disableSpanReporting BoolValue

Controls span reporting. If set to true, no spans will be reported for impacted workloads. This does NOT impact context propagation or trace sampling behavior.

No
customTags map<string, CustomTag>

Optional. Configures additional custom tags to the generated trace spans.

No

ProviderRef

Used to bind Telemetry configuration to specific providers for targeted customization.

Field Type Description Required
name string

Required. Name of Telemetry provider in MeshConfig.

No

Tracing.CustomTag

CustomTag defines a tag to be added to a trace span that is based on an operator-supplied value. This value can either be a hard-coded value, a value taken from an environment variable known to the sidecar proxy, or from a request header.

Field Type Description Required
literal Literal (oneof)

Literal adds the same, hard-coded value to each span.

No
environment Environment (oneof)

Environment adds the value of an environment variable to each span.

No
header RequestHeader (oneof)

RequestHeader adds the value of an header from the request to each span.

No

Tracing.Literal

Field Type Description Required
value string

The tag value to use.

No

Tracing.Environment

Field Type Description Required
name string

Name of the environment variable from which to extract the tag value.

No
defaultValue string

Optional. If the environment variable is not found, this value will be used instead.

No

Tracing.RequestHeader

Field Type Description Required
name string

Name of the header from which to extract the tag value.

No
defaultValue string

Optional. If the header is not found, this value will be used instead.

No