Telemetry API

Telemetry API (Telemetry API)

Istio는 메트릭, 액세스 로그, 추적을 유연하게 구성할 수 있는 Telemetry API를 제공해요. 이를 통해 메시 전역부터 개별 워크로드까지 세밀하게 텔레메트리 동작을 제어할 수 있어요.

출처: Istio 문서

본문

Istio는 메트릭, 액세스 로그, 추적을 유연하게 구성할 수 있는 Telemetry API를 제공해요.

API 사용하기 (Using the API)

범위, 상속, 오버라이드 (Scope, Inheritance, and Overrides)

Telemetry API 리소스는 Istio 구성 계층의 상위 리소스에서 구성을 상속해요.

루트 구성 네임스페이스 (예: istio-system)
로컬 네임스페이스 (워크로드 selector가 없는 네임스페이스 범위 리소스)
워크로드 (워크로드 selector가 있는 네임스페이스 범위 리소스) 루트 구성 네임스페이스, 보통 istio-system에 있는 Telemetry API 리소스는 메시 전체의 기본 동작을 제공해요. 루트 구성 네임스페이스의 워크로드별 selector는 무시/거부돼요. 루트 구성 네임스페이스에 여러 개의 메시 전역 Telemetry API 리소스를 정의하는 것은 유효하지 않아요. 메시 전역 구성에 대한 네임스페이스별 오버라이드는 원하는 네임스페이스에 (워크로드 selector 없이) 새 Telemetry 리소스를 적용해서 달성할 수 있어요. 네임스페이스 구성에 지정된 필드는 상위 구성(루트 구성 네임스페이스)의 필드를 완전히 오버라이드해요. 워크로드별 오버라이드는 원하는 네임스페이스에 워크로드 selector가 있는 새 Telemetry 리소스를 적용해서 달성할 수 있어요.

워크로드 선택 (Workload Selection)

네임스페이스 안의 개별 워크로드는 selector를 통해 선택되며, 이를 통해 레이블 기반의 워크로드 선택을 할 수 있어요. 서로 다른 두 Telemetry 리소스가 selector를 사용해서 같은 워크로드를 선택하는 것은 유효하지 않아요. 마찬가지로, selector가 지정되지 않은 두 개의 서로 다른 Telemetry 리소스가 한 네임스페이스에 있는 것도 유효하지 않아요.

프로바이더 선택 (Provider Selection)

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

[!note] Sidecar 구성을 사용한다면 프로바이더의 서비스를 추가하는 것을 잊지 마세요. [!note] 프로바이더는 $(HOST_IP)를 지원하지 않아요. 수집기를 에이전트 모드로 실행한다면 서비스 내부 트래픽 정책을 사용하고, 더 나은 성능을 위해 InternalTrafficPolicy를 Local로 설정할 수 있어요.

예시 (Examples)

메시 전역 동작 구성하기 (Configuring mesh-wide behavior)

Telemetry API 리소스는 메시의 루트 구성 네임스페이스, 보통 istio-system에서 상속돼요. 메시 전역 동작을 구성하려면 루트 구성 네임스페이스에 새 Telemetry 리소스를 추가(또는 기존 것 편집)하세요. 다음은 이전 섹션의 프로바이더 구성을 사용하는 예시 구성이에요.

apiVersion: telemetry.istio.io/v1
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인 태그가 모든 추적 스팬에 추가되도록 구성해요.

네임스페이스 범위 추적 동작 구성하기 (Configuring namespace-scoped tracing behavior)

개별 네임스페이스의 동작을 맞추려면 원하는 네임스페이스에 Telemetry 리소스를 추가하세요. 네임스페이스 리소스에 지정된 필드는 구성 계층의 상속된 필드 구성을 완전히 오버라이드해요. 예를 들어:

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

이전의 메시 전역 예시 구성이 있는 메시에 배포하면, myapp 네임스페이스의 추적 동작은 localtrace 프로바이더로 추적 스팬을 보내고 100% 비율로 요청을 무작위 선택하지만, 각 스팬에 이름이 userId이고 값이 userId 요청 헤더에서 가져온 커스텀 태그를 설정하게 돼요. 중요한 점은 상위 구성의 foo: bar 태그는 myapp 네임스페이스에서 사용되지 않는다는 거예요. 커스텀 태그 동작은 mesh-default.istio-system 리소스에 구성된 동작을 완전히 오버라이드해요.

[!note] Telemetry 리소스의 모든 구성은 구성 계층의 상위 리소스 구성을 완전히 오버라이드해요. 여기에는 프로바이더 선택도 포함돼요.

워크로드별 동작 구성하기 (Configuring workload-specific behavior)

개별 워크로드의 동작을 맞추려면 원하는 네임스페이스에 Telemetry 리소스를 추가하고 selector를 사용하세요. 워크로드별 리소스에 지정된 필드는 구성 계층의 상속된 필드 구성을 완전히 오버라이드해요. 예를 들어:

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

이 경우 myapp 네임스페이스의 frontend 워크로드에 대해 추적이 비활성화돼요. Istio는 추적 헤더를 계속 전달하지만, 구성된 추적 프로바이더에는 스팬이 보고되지 않아요.

[!note] 워크로드 selector가 있는 두 Telemetry 리소스가 같은 워크로드를 선택하는 것은 유효하지 않아요. 그런 경우 동작이 정의되지 않아요.

더 알아보기 (Learn more)

Telemetry API 전체 참조는 Telemetry API 참조 문서를 확인하세요.
프로바이더와 확장 프로바이더 구성에 대해서는 MeshConfig 문서를 참고하세요.