개요

1.22 버전 이후 메이저로 승격된 관측 가능성 관련 리소스.^[1]
원래 이스티오에서는 이스티오 전역 설정이나, 워크로드에 어노테이션을 다는 방식으로 관측 가능성 세팅을 지원했다.
이런 방식을 사용성이 너무 제한됐기 때문에 아예 새로운 리소스를 만들어버린 것.

로깅, 메트릭, 트레이싱 등의 설정을 지원한다.
라벨 셀렉팅을 하면 워크로드 단위, 하지 않으면 네임스페이스 단위, 이스티오 루트 네임스페이스에 만들면 전역 설정이 된다.
설정법에 따라서 여러 텔레메트리가 겹치게 되는 경우가 있을 텐데, 이럴 때는 겹치는 설정 부분에 대해서 가장 작은 단위의 설정값이 덮어쓰기한다.

양식 작성법

apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: foo-tracing-alternate
  namespace: baz
spec:
  selector:
    matchLabels:
      service.istio.io/canonical-name: foo
  tracing:
  - providers:
    - name: "zipkin-alternate"
    randomSamplingPercentage: 10.00
  metrics:
  - providers:
    - name: prometheus
    overrides:
    - match:
        metric: ALL_METRICS
        mode: SERVER
      disabled: true
  accessLogging:
  - providers:
    - name: envoy

라벨 셀렉터로 고르고, 트레이싱이나 메트릭, 로깅 설정을 하면 된다.
라벨을 쓰지 않고 targetRefs로 명시적으로 리소스들을 지정하는 것도 가능하다(waypoint 프록시라면 무조건 이걸 써야 한다).

tracing

spec:
  tracing:
  - randomSamplingPercentage: 10.00
    customTags:
      foo1:
		# 그냥 문자열 넣기
        literal:
          value: "foo"
      foo2:
	    # 해당 컨테이너 환경의 환경변수 넣기.
        environment:
          name: "OS_ARCH"
          defaultValue: "linux"
      foo3:
	    # 요청의 헤더 넣기
        header:
          name: "User-Agent"
          defaultValue: "curl"

• randomSamplingPercentage - 몇 퍼센트마다 스팬을 생성할 것인지 지정한다. 0으로 설정 시 모든 요청에 스팬이 붙는다.
• disableSpanReporting - true로 설정 시 스팬 보고를 하지 않는다.
  • 보고를 하지 않을 뿐, 스팬 생성도 하고, 스팬 전파도 그대로 한다.
• enableIstioTags - false로 설정 시 엔보이는 이스티오 전역 설정 태그 값을 스팬에 추가하지 않는다.
• customTags - 원하는 태그를 추가할 수 있다.

메트릭이나 로깅 쪽에도 같은 뜻으로 사용할 수 있는 필드들이 몇 개 있다.

• match - SERVER, CLIENT, CLIENT_AND_SERVER로 세 가지로 대상이 될 트래픽을 지정할 수 있다.
• providers - 스팬을 보고할 대상 툴을 지정한다.
  • 설정하지 않으면 이스티오 설정 시 세팅된 기본 프로바이더가 사용된다.

metrics

  metrics:
  - providers:
    - name: prometheus
    reportingInterval: 5s
    overrides:
	# 서버 쪽 메트릭 비활성화
	- match:
        metric: ALL_METRICS
        mode: SERVER
      disabled: true
	# request_method, request_host 추가(혹은 변경)
    - tagOverrides:
        request_method:
          value: "request.method"
        request_host:
          value: "request.host" # CEL 표현식으로 써야 한다.
    # REQUEST_COUNT 메트릭 제거
    - match:
        metric: REQUEST_COUNT
      tagOverrides:
        response_code:
          operation: REMOVE # REMOVE, UPSERT 가능

overides 필드를 통해 덮어쓰기할 메트릭을 정한다.
메트릭 쪽은 match를 쓸 때 어떤 메트릭을 할 것인지도 세부적으로 지정할 수 있다.
어떤 메트릭 값을 넣을 수 있는지는 서비스 레벨 메트릭 참고.^[2]
그래서 그 값에 대해 tagOverrides 필드를 통해 라벨 커스텀을 할 수 있게 되는 것이다.
(근데 왜 헷갈리게 attribute라 했다, tag라 했다, label이라 했다 하는 건지 모르겠음..)
value 부분은 CEL 표현식으로 작성해야 하는데, 엔보이에서 노출하는 모든 변수를 사용할 수 있다.^[3]
이때 서비스 레벨 메트릭 관련해서 노출하고 싶은 정보가 있다면 엔보이 변수 중 filter_state를 이용해주면 된다.
예를 들어 app 라벨을 이용한 메트릭을 커스텀한다면 filter_state.downstream_peer.app, filter_stat.upstream_peer.app를 설정하는 식이다.^[4]

accessLogging

accessLogging:
  filter:
    expression: "response.code >= 400"

위에서 봤던 disabled, match providers 필드를 사용할 수 있다.
여기에 추가적으로 filter 필드가 있는데, 어떤 것들을 로그로 남길지 CEL 표현식으로 작성하면 된다.
조금 의외라고 생각하는데, 로그 포맷을 커스텀하는 필드는 없다.
문서를 보니까 기능 개발이 이뤄지면서 나중에 filter 필드에 더 자세한 기능들을 넣을 거라는 듯.

관련 문서

참고