Telemetry API
- 使用 API
- 示例

Telemetry API

此功能针对开发人员/专家用户，被认为是 Alpha.

Istio 提供 Telemetry API，能够灵活地配置指标、访问日志和追踪。

使用 API

作用域、继承和覆盖

在 Istio 配置层次结构中，Telemetry API 资源从父级资源中继承配置：

根配置命名空间（例如 istio-system）
本地命名空间（不带工作负载 selector 的作用于命名空间的资源）
工作负载（带有工作负载 selector 的作用于命名空间的资源）

istio-system 这类根配置命名空间中的 Telemetry API 资源提供了网格范围的默认行为。根配置命名空间中的所有工作负载特定选择算符都将被忽略/拒绝。在根配置命名空间中定义多个网格范围的 Telemetry API 资源是无效的。

通过将新的 Telemetry 资源应用到（不带工作负载选择算符的）目标命名空间中，可以针对网格范围的配置达成特定于命名空间的覆盖。命名空间配置中指定的所有字段都将完全覆盖（根配置命名空间中的）父级配置中的字段。

使用工作负载选择算符 将新的 Telemetry 资源应用到目标命名空间中，可以实现特定于工作负载的覆盖。

工作负载选择

命名空间内的单个工作负载通过 selector 进行选择，这允许基于标签选择工作负载。

使用 selector 让两个不同的 Telemetry 资源选择相同的工作负载是无效的。同样在未指定 selector 时在一个命名空间中设定两个不同的 Telemetry 资源也是无效的。

提供程序选择

Telemetry API 使用提供程序的概念表明要使用的集成协议或类型。可以在 MeshConfig 中配置提供程序。

MeshConfig 中的提供程序配置示例设置如下：

data:
  mesh: |-
      extensionProviders: # The following content defines two example tracing providers.
      - name: "localtrace"
        zipkin:
          service: "zipkin.istio-system.svc.cluster.local"
          port: 9411
          maxTagLength: 56
      - name: "cloudtrace"
        stackdriver:
          maxTagLength: 256

为了方便，Istio 默认设置随附了几个开箱即用的提供程序：

提供程序名称	功能
`prometheus`	指标
`stackdriver`	指标、追踪、访问日志
`envoy`	访问日志

此外，还可以设置默认的提供程序，便于在 Telemetry 资源未指定提供程序时将使用这个默认的提供程序。

如果您正使用 Sidecar 配置，不要忘记添加提供程序的服务。

提供程序不支持 $(HOST_IP)。如果您正以代理（agent）模式运行收集器，您可以使用服务内部流量策略，并将 InternalTrafficPolicy 设置为 Local 以获得更好的性能。

示例

配置网格范围的行为

Telemetry API 资源从网格的根配置命名空间（通常是 istio-system）中进行继承。要配置网格范围的行为，可以在根配置命名空间中添加新的（或编辑现有的）Telemetry 资源。

以下是上一节中使用提供程序配置的示例配置：

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  name: mesh-default
  namespace: istio-system
spec:
  tracing:
  - providers:
    - name: localtrace
    customTags:
      foo:
        literal:
          value: bar
    randomSamplingPercentage: 100

此配置覆盖源于 MeshConfig 的默认提供程序，将网格默认设置为 localtrace 提供程序。它还将网格范围的抽样百分比设置为 100，配置一个标记以名称 foo 和赋值 bar 添加到所有链路 span。

配置作用于命名空间的追踪行为

要定制个别命名空间的行为，添加 Telemetry 资源到目标命名空间。命名空间资源中指定的所有字段将完全覆盖从配置层次结构中继承的字段配置。例如：

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  name: namespace-override
  namespace: myapp
spec:
  tracing:
  - customTags:
      userId:
        header:
          name: userId
          defaultValue: unknown

当用先前网格范围的示例配置部署到网格中时，这将造成 myapp 命名空间中的追踪行为，将链路 span 发送到 localtrace 提供程序并随机以 100% 的比率选择追踪请求，但这会使用名称 userId 和 userId 请求头中获取的值为每个 span 设置自定义标记。重要的是，在 myapp 命名空间中将不会使用来自父级配置的 foo: bar 标记。自定义标记行为将完全覆盖 mesh-default.istio-system 资源中配置的行为。

Telemetry 资源中的所有配置将完全覆盖配置层次结构中其父级资源的配置。这包括提供程序选择。

配置特定于工作负载的行为

要定制个别工作负载的行为，添加 Telemetry 资源到目标命名空间并使用 selector。特定工作负载资源中指定的所有字段将完全覆盖从配置层次结构中继承的字段配置。

例如：

apiVersion: telemetry.istio.io/v1alpha1
kind: Telemetry
metadata:
  name: workload-override
  namespace: myapp
spec:
  selector:
    matchLabels:
      service.istio.io/canonical-name: frontend
  tracing:
  - disableSpanReporting: true

这种情况下，对于 myapp 命名空间中的 frontend 工作负载，追踪将被禁用。 Istio 仍将转发追踪头，但没有 span 将被报告给配置的追踪提供程序。

让带有工作负载选择算符的两个 Telemetry 资源选择相同的工作负载是无效的。这种情况下，此行为属于未定义的状态。

Telemetry API *