Telemetry API

    Telemetry API resources inherit configuration from parent resources in the Istio configuration hierarchy:

    1. root configuration namespace (example: )
    2. local namespace (namespace-scoped resource with no workload selector)
    3. workload (namespace-scoped resource with a workload selector)

    A Telemetry API resource in the root configuration namespace, typically istio-system, provides mesh-wide defaults for behavior. Any workload-specific selector in the root configuration namespace will be ignored/rejected. It is not valid to define multiple mesh-wide Telemetry API resources in the root configuration namespace.

    Namespace-specific overrides for the mesh-wide configuration can be achieved by applying a new Telemetry resource in the desired namespace (without a workload selector). Any fields specified in the namespace configuration will completely override the field from the parent configuration (in the root configuration namespace).

    Workload-specific overrides can be achieved by applying a new Telemetry resource in the desired namespace with a workload selector.

    Workload Selection

    Individual workloads within a namespace are selected via a which allows label-based selection of workloads.

    It is not valid to have two different Telemetry resources select the same workload using selector. Likewise, it is not valid to have two distinct Telemetry resources in a namespace with no selector specified.

    An example set of provider configuration in MeshConfig is:

    For convenience, Istio comes with a few providers configured out of the box with default settings:

    In additional, a can be set which will be used when the Telemetry resources do not specify a provider.

    Examples

    Configuring mesh-wide behavior

    Telemetry API resources inherit from the root configuration namespace for a mesh, typically istio-system. To configure mesh-wide behavior, add a new (or edit the existing) Telemetry resource in the root configuration namespace.

    Here is an example configuration that uses the provider configuration from the prior section:

    This configuration overrides the default provider from MeshConfig, setting the mesh default to be the localtrace provider. It also sets the mesh-wide sampling percentage to be 100, and configures a tag to be added to all trace spans with a name of foo and a value of bar.

    When deployed into a mesh with the prior mesh-wide example configuration, this will result in tracing behavior in the myapp namespace that sends trace spans to the localtrace provider and randomly selects requests for tracing at a rate, but that sets custom tags for each span with a name of userId and a value taken from the userId request header. Importantly, the foo: bar tag from the parent configuration will not be used in the myapp namespace. The custom tags behavior completely overrides the behavior configured in the mesh-default.istio-system resource.

    Any configuration in a Telemetry resource completely overrides configuration of its parent resource in the configuration hierarchy. This includes provider selection.

    Configuring workload-specific behavior

    To tailor the behavior for individual workloads, add a Telemetry resource to the desired namespace and use a selector. Any fields specified in the workload-specific resource will completely override the inherited field configuration from the configuration hierarchy.

    For example:

    In this case, tracing will be disabled for the frontend workload in the myapp namespace. Istio will still forward the tracing headers, but no spans will be reported to the configured tracing provider.

    It is not valid to have two Telemetry resources with workload selectors select the same workload. In those cases, behavior is undefined.