Description of Telemetry fields - Alibaba Cloud Service Mesh

The Telemetry CustomResourceDefinition (CRD) is used to define and configure policies and behaviors related to observing and collecting data in a Service Mesh (ASM) instance. It allows you to manage the telemetry features provided by Istio at fine-grained levels, such as logging, metrics, and tracing. With the Telemetry CRD, you can customize and adjust the methods for collecting and processing telemetry data based on your business requirements. This topic describes how to configure a Telemetry CRD and describes the fields in the CRD.

Configuration examples

Istio supports observability configurations at three different levels, which correspond to the following observability configurations in the ASM console:

Global configurations (the Global tab in the ASM console)
Namespace-specific configurations (the Namespace tab in the ASM console)
Workload-specific configurations (the Custom tab in the ASM console)

The following sample Telemetry YAML files demonstrate how to configure observability at different levels:

Global configurations

Show the YAML file

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  labels:
    provider: asm
  # When the name is default and the namespace is istio-system, the configurations take effect globally.
  name: default
  namespace: istio-system
spec:
  accessLogging:
  - disabled: false
    # This is the default configuration of ASM and cannot be modified.
    providers:
    - name: envoy
  metrics:
  # You need to configure each metric of the client and 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: {}
    # This is the default configuration of ASM and cannot be modified.
    providers:
    - name: prometheus
  tracing:
  - customTags:
    foo:
      literal:
        value: bar
    randomSamplingPercentage: 10

Namespace-specific configurations

Show the YAML file

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  labels:
    provider: asm
  # When the name is default, the configurations take effect for the entire namespace.
  name: default
  # The configurations take 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 configurations

Show the YAML file

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  labels:
    provider: asm
  # When the name is not set to default, the configurations take effect only for workloads whose label matches the one specified in the selector field.
  name: test
  # The configurations take effect for specified workloads 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
  # This field specifies the workloads for which the configurations take effect
  selector:
    matchLabels:
      foo: bar

Field description

Telemetry

Field	Type	Required	Description
selector	WorkloadSelector	No	Specifies the workloads for which the Telemetry policy is to be configured.
tracing	Tracing[]	No	Specifies the tracing behavior for all selected workloads.
metrics	Metrics[]	No	Specifies the metrics behavior for all selected workloads.
accessLogging	AccessLogging[]	No	Specifies the access logging behavior for all selected workloads.

Tracing

Field	Type	Required	Description
randomSamplingPercentage	double	No	Specifies the rate at which traffic will be selected for tracing. The value 0 indicates that no sampling is performed.
customTags	map<string, CustomTag>	No	Specifies additional custom tags added to the generated trace spans.

Metrics

Field	Type	Required	Description
overrides	MetricsOverrides[]	No	Defines the custom generation method and presentation for a specific metric or all preset standard metrics.
providers	ProviderRef[]	No	Specifies the name of providers to which the configuration applies. The value must be set to prometheus.

AccessLogging

Field	Type	Required	Description
disabled	bool	No	Specifies the logging behavior.
providers	ProviderRef[]	No	Specifies the name of providers to which the configuration applies. The value must be set to envoy.

WorkloadSelector

Field	Type	Required	Description
matchLabels	map<string, string>	No	Specifies one or more labels that indicate the set of pods or virtual machines (VMs) to which the policy applies. The scope of label search is limited to the configuration namespace in which the resource is present.

CustomTag

Field	Type	Required	Description
literal	Tracing.Literal	No	This field adds the same, hard-coded value to each span.
environment	Tracing.Environment	No	This field adds the value of an environment variable to each span.
header	Tracing.RequestHeader	No	This field adds the value of a header from the request to each span.

MetricsOverrides

Field	Type	Required	Description
match	WorkloadSelector	No	Matches the metrics to be overridden. You need to add and configure all client and server metrics.
disabled	bool	No	Specifies whether to disable metric reporting. If this parameter is set to true, metric reporting is disabled.
tagOverrides	map<string, MetricsOverrides>	No	Specifies a collection of tag names and tag expressions to override in the selected metric.

MetricSelector

Field	Type	Required	Description
metric	MetricSelector.IstioMetric	No	Specifies a metric.
mode	WorkloadMode	No	Specifies the mode of metrics generation. Valid values: CLIENT and SERVER.

ProviderRef

Field	Type	Required	Description
name	string	Yes	Specifies the name of the Telemetry provider in MeshConfig.

Tracing.Literal

Field	Type	Required	Description
value	string	Yes	The tag value to be used.

Tracing.Environment

Field	Type	Required	Description
name	string	Yes	Specifies the name of the environment variable from which the tag value is extracted.
defaultValue	string	No	Specifies the default value that is used if the environment variable is not found.

Tracing.RequestHeader

Field	Type	Required	Description
name	string	Yes	Specifies the name of the header from which the tag value is extracted.
defaultValue	string	No	Specifies the default value that is used if the header is not found.

MetricsOverrides.TagOverride

Field	Type	Required	Description
operation	MetricsOverrides.TagOverride.Operation	No	Specifies whether to update, add, or remove a tag.
value	string	No	Specifies the tag value, which is used only when `operation` is set to `UPSERT`.

MetricSelector.IstioMetric

Name	Description
REQUEST_COUNT	Counter of HTTP, HTTP/2, and gRPC requests to or from an application
REQUEST_DURATION	Duration of HTTP, HTTP/2, and gRPC requests
REQUEST_SIZE	Body size of HTTP, HTTP/2, and gRPC requests
RESPONSE_SIZE	Body size of HTTP, HTTP/2, and gRPC responses
TCP_OPENED_CONNECTIONS	Counter of TCP connections opened over the lifetime of a workload
TCP_CLOSED_CONNECTIONS	Counter of TCP connections closed over the lifetime of a workload
TCP_SENT_BYTES	Counter of bytes that are sent during a response over a TCP connection
TCP_RECEIVED_BYTES	Counter of bytes that are received during a response over a TCP connection
GRPC_REQUEST_MESSAGES	Counter of gRPC messages sent from a client
GRPC_RESPONSE_MESSAGES	Counter of gRPC messages sent from a server

MetricsOverrides.TagOverride.Operation

Name	Description
UPSERT	Specifies that the tag should be inserted or updated.
REMOVE	Specifies that the tag should not be included in the metric during the metric generation.

WorkloadMode

Name	Description
CLIENT	Select this value for scenarios when the workload is the source of the network traffic.
SERVER	Select this value for scenarios when the workload is the destination of the network traffic.

Precautions

In principle, fields that are not described in this topic are compatible between ASM and Istio of the corresponding version. The ASM console does not support editing of these fields. Therefore, if you want to use these fields, you can directly update the fields in the corresponding Telemetry custom resource (CR) by using kubectl or other methods. For more information about the fields of the Telemetry CRD, see Telemetry.