Telemetry CRD - Alibaba Cloud Service Mesh - Alibaba Cloud Documentation Center

The Telemetry resource lets you define and configure policies and behaviors for observing and collecting data in a service mesh. This resource provides granular control over Istio telemetry features, such as logs, metrics, and tracing. The Telemetry Custom Resource Definition (CRD) lets you customize how telemetry data is collected and processed to meet your specific needs. This topic describes the configuration examples and field definitions for the Telemetry CRD.

Configuration examples

ASM supports four scopes for observability configurations. These scopes correspond to the following observability settings in the ASM console:

Global configuration (Global)
Namespace-specific configuration (Namespace)
Workload-specific configuration (Custom)
(Ambient Waypoint)

The following sections provide Telemetry YAML file examples for different configuration scopes.

Global configuration

Click to view the YAML content

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  labels:
    provider: asm
  # Takes effect globally when the name is 'default' and the namespace is 'istio-system'.
  name: default
  namespace: istio-system
spec:
  accessLogging:
  - disabled: false
    # ASM default configuration. Cannot be modified.
    providers:
    - name: envoy
  metrics:
  # You must configure each metric for both the client and the server.
  - overrides:
    - disabled: false
      match:
        metric: REQUEST_COUNT
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_COUNT
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_DURATION
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_DURATION
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_SIZE
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_SIZE
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: RESPONSE_SIZE
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: RESPONSE_SIZE
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_REQUEST_MESSAGES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_REQUEST_MESSAGES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_RESPONSE_MESSAGES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_RESPONSE_MESSAGES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_SENT_BYTES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_SENT_BYTES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_RECEIVED_BYTES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_RECEIVED_BYTES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_OPENED_CONNECTIONS
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_OPENED_CONNECTIONS
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_CLOSED_CONNECTIONS
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_CLOSED_CONNECTIONS
        mode: SERVER
      tagOverrides: {}
    # ASM default configuration. Cannot be modified.
    providers:
    - name: prometheus
  tracing:
  - customTags:
    foo:
      literal:
        value: bar
    randomSamplingPercentage: 10

Namespace-specific configuration

Click to view the YAML content

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  labels:
    provider: asm
  # Takes effect for the entire namespace when the name is 'default'.
  name: default
  # Takes effect for the 'default' namespace.
  namespace: default
spec:
  accessLogging:
  - disabled: false
    providers:
    - name: accesslogging.default.default
  metrics:
  - overrides:
    - disabled: false
      match:
        metric: REQUEST_COUNT
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_COUNT
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_DURATION
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_DURATION
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_SIZE
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_SIZE
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: RESPONSE_SIZE
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: RESPONSE_SIZE
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_REQUEST_MESSAGES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_REQUEST_MESSAGES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_RESPONSE_MESSAGES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_RESPONSE_MESSAGES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_SENT_BYTES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_SENT_BYTES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_RECEIVED_BYTES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_RECEIVED_BYTES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_OPENED_CONNECTIONS
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_OPENED_CONNECTIONS
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_CLOSED_CONNECTIONS
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_CLOSED_CONNECTIONS
        mode: SERVER
      tagOverrides: {}
    providers:
    - name: prometheus

Workload-specific configuration

Click to view the YAML content

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  labels:
    provider: asm
  # Takes effect only for workloads with labels specified in the selector field when the name is not 'default'.
  name: test
  # Takes effect for the specified workload in the 'default' namespace.
  namespace: default
spec:
  accessLogging:
  - disabled: false
    providers:
    - name: accesslogging.default.test
  metrics:
  - overrides:
    - disabled: false
      match:
        metric: REQUEST_COUNT
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_COUNT
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_DURATION
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_DURATION
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_SIZE
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: REQUEST_SIZE
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: RESPONSE_SIZE
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: RESPONSE_SIZE
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_REQUEST_MESSAGES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_REQUEST_MESSAGES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_RESPONSE_MESSAGES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: GRPC_RESPONSE_MESSAGES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_SENT_BYTES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_SENT_BYTES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_RECEIVED_BYTES
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_RECEIVED_BYTES
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_OPENED_CONNECTIONS
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_OPENED_CONNECTIONS
        mode: SERVER
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_CLOSED_CONNECTIONS
        mode: CLIENT
      tagOverrides: {}
    - disabled: false
      match:
        metric: TCP_CLOSED_CONNECTIONS
        mode: SERVER
      tagOverrides: {}
    providers:
    - name: prometheus
  # Specifies the workloads to which this configuration applies.
  selector:
    matchLabels:
      foo: bar

Waypoint configuration

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: waypoint
  namespace: default
spec:
  targetRefs:
  - kind: Gateway
    name: bookinfo-gateway
    group: gateway.networking.k8s.io
  accessLogging:
  - disabled: false
    providers:
    - name: accesslogging.default.default

Field descriptions

Telemetry

Property	Type	Required	Description
selector	WorkloadSelector	No	A selector that specifies the workloads to which the Telemetry policy applies.
tracing	Tracing[]	No	Configures the tracing behavior for all selected workloads.
metrics	Metrics[]	No	Configures the metrics monitoring behavior for all selected workloads.
accessLogging	AccessLogging[]	No	Configures the access logging behavior for all selected workloads.

Tracing

Property	Type	Required	Description
randomSamplingPercentage	double	No	Controls the traffic sampling rate for tracing. A value of 0 disables sampling.
customTags	map<string, CustomTag>	No	Adds custom tags to traces.

Metrics

Property	Type	Required	Description
overrides	MetricsOverrides[]	No	Customizes how specific or all standard metrics are generated and displayed.
providers	ProviderRef[]	No	Specifies the names of the providers to apply. Currently, only Prometheus is supported.

AccessLogging

Property	Type	Required	Description
disabled	bool	No	Controls the logging behavior.
providers	ProviderRef[]	No	Specifies the names of the providers to apply. Currently, only Envoy is supported.

WorkloadSelector

Property	Type	Required	Description
matchLabels	map<string, string>	No	One or more labels that identify the set of pods or virtual machines (VMs) to which the policy applies. The label search is scoped to the namespace where the resource is configured.

CustomTag

Property	Type	Required	Description
literal	Tracing.Literal	No	Adds the same hard-coded value to every span.
environment	Tracing.Environment	No	Adds the value of an environment variable to every span.
header	Tracing.RequestHeader	No	Fetches a specific header from the request and adds its value to every span.

MetricsOverrides

Property	Type	Required	Description
match	WorkloadSelector	No	Matches the metrics to overwrite. You must add and configure all client-side and server-side metrics.
disabled	bool	No	Specifies whether to disable metric monitoring. Set to `true` to disable.
tagOverrides	map<string, MetricsOverrides>	No	A collection of dimension names and expressions used to overwrite dimensions in a selected metric.

MetricSelector

Property	Type	Required	Description
metric	MetricSelector.IstioMetric	No	Controls the metric.
mode	WorkloadMode	No	Controls the mode in which the metric is generated. Valid values are CLIENT and SERVER.

ProviderRef

Property	Type	Required	Description
name	string	Yes	The Telemetry provider included in the MeshConfig.

TargetRef

Property

Type

Required

Description

targetRefs

PolicyTargetReference

targetRefs specifies a list of resources to which the policy is applied. The specified target resources determine the workloads to which the policy applies. Currently, the following resource attachment types are supported:

kind: Gateway with the API group gateway.networking.k8s.io in the same namespace.
kind: GatewayClass with the API group gateway.networking.k8s.io in the root namespace.
kind: Service with the API group "" or group: "core" in the same namespace. This type is supported only for Waypoint.
kind: ServiceEntry with the API group networking.istio.io in the same namespace. This type is supported only for Waypoint.

If this field is not set, the policy is applied based on the selector definition. You can set either the selector or targetRefs, but not both.

Important

For Waypoint proxies, you must use this field for configuration instead of WorkloadSelector.

PolicyTargetReference

Property	Type	Required	Description
group	string	No	The API group of the target resource.
kind	string	Yes	The API kind of the target resource.
name	string	Yes	The name of the target resource.
namespace	string	No	The namespace of the target resource. If not specified, the namespace is the same as the Telemetry namespace.

Tracing.Literal

Property	Type	Required	Description
value	string	Yes	The tag value to use.

Tracing.Environment

Property	Type	Required	Description
name	string	Yes	The name of the environment variable from which to fetch the tag value.
defaultValue	string	No	The default value to use if the environment variable does not exist.

Tracing.RequestHeader

Property	Type	Required	Description
name	string	Yes	The name of the header from which to fetch the tag value.
defaultValue	string	No	The default value to use if the header does not exist.

MetricsOverrides.TagOverride

Property	Type	Required	Description
operation	MetricsOverrides.TagOverride.Operation	No	Controls whether to update, add, or remove a dimension.
value	string	No	The specified tag value. This is used only when `operation` is `UPSERT`.

MetricSelector.IstioMetric

Name	Description
REQUEST_COUNT	The count of requests initiated by an application, including HTTP, HTTP/2, and gRPC traffic.
REQUEST_DURATION	The duration of requests for HTTP, HTTP/2, and gRPC traffic.
REQUEST_SIZE	The size of the request body for HTTP, HTTP/2, and gRPC traffic.
RESPONSE_SIZE	The size of the response body for HTTP, HTTP/2, and gRPC traffic.
TCP_OPENED_CONNECTIONS	The count of TCP connections opened during the workload lifecycle.
TCP_CLOSED_CONNECTIONS	The count of TCP connections closed during the workload lifecycle.
TCP_SENT_BYTES	The number of bytes sent during a response over a TCP connection.
TCP_RECEIVED_BYTES	The number of bytes received during a request over a TCP connection.
GRPC_REQUEST_MESSAGES	The number of gRPC messages sent by the client.
GRPC_RESPONSE_MESSAGES	The number of gRPC messages sent by the server.

MetricsOverrides.TagOverride.Operation

Name	Description
UPSERT	Specifies that the dimension must be added.
REMOVE	Specifies that the dimension must be removed.

WorkloadMode

Name	Description
CLIENT	The workload is a client that originates network traffic.
SERVER	The workload is a server that terminates network traffic.

Notes

ASM is compatible with the corresponding Istio version for fields not listed in this topic. These fields cannot be edited in the ASM console. If you want to use these fields, you must manage the corresponding Telemetry CR directly using tools such as kubectl. For more information about the fields of the Telemetry resource, see Telemetry.