[istio] 액세스 로그 accessLogFormat 설정

들어가기 앞서

istio proxy 의 access log 를 활성화 하였다. 크게 Telemetry API 를 사용하는 방법과 Mesh Config 를 사용하는 방법이 있는데, 필자의 경우 후자(Mesh Config)를 이용해 활성화 하였다.

https://hyukops.tistory.com/140

[istio] istio 의 Access Log 활성화

IstioOperator 를 이용해 적용하였으며 이를 적용하는 방법에 대한 YAML 은 아래와 같다

kubectl apply -f - <<EOF
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
metadata:
  namespace: istio-system
  name: istiocontrolplane
spec:
  profile: demo
  meshConfig:                   # 지정
    accessLogFile: /dev/stdout  # 지정
...
--- (생략) ---

하지만, 해당 로그에서 원하는 정보만 출력하여 확인하고자 한다.

공식문서에 따르면

Istio에서 accessLogFormat 값을 별도로 지정하지 않으면 다음과 같은 기본 포맷을 사용한다.

[%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %RESPONSE_FLAGS% %RESPONSE_CODE_DETAILS% %CONNECTION_TERMINATION_DETAILS%
"%UPSTREAM_TRANSPORT_FAILURE_REASON%" %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%"
"%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%" %UPSTREAM_CLUSTER_RAW% %UPSTREAM_LOCAL_ADDRESS% %DOWNSTREAM_LOCAL_ADDRESS% %DOWNSTREAM_REMOTE_ADDRESS% %REQUESTED_SERVER_NAME% %ROUTE_NAME%

이 포맷은 요청이 들어와서 응답되기까지의 전 과정을 세부적으로 기록한다. 예를 들어, curl로 httpbin 서비스에 요청을 보냈을 때 다음과 같은 로그가 출력된다. 아래의 표는 필드 예시 (curl 측 로그) 예시 (httpbin 측 로그)

[%START_TIME%]	[2020-11-25T21:26:18.409Z]	[2020-11-25T21:26:18.409Z]
"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%"	"GET /status/418 HTTP/1.1"	"GET /status/418 HTTP/1.1"
%RESPONSE_CODE%	418	418
%RESPONSE_FLAGS%	-	-
%RESPONSE_CODE_DETAILS%	via_upstream	via_upstream
%CONNECTION_TERMINATION_DETAILS%	-	-
"%UPSTREAM_TRANSPORT_FAILURE_REASON%"	"-"	"-"
%BYTES_RECEIVED%	0	0
%BYTES_SENT%	135	135
%DURATION%	4	3
%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%	4	1
"%REQ(X-FORWARDED-FOR)%"	"-"	"-"
"%REQ(USER-AGENT)%"	"curl/7.73.0-DEV"	"curl/7.73.0-DEV"
"%REQ(X-REQUEST-ID)%"	"84961386-6d84-929d-98bd-c5aee93b5c88"	"84961386-6d84-929d-98bd-c5aee93b5c88"
"%REQ(:AUTHORITY)%"	"httpbin:8000"	"httpbin:8000"
"%UPSTREAM_HOST%"	"10.44.1.27:80"	"127.0.0.1:80"
%UPSTREAM_CLUSTER_RAW%	outbound|8000||httpbin.foo.svc.cluster.local	inbound|8000||
%UPSTREAM_LOCAL_ADDRESS%	10.44.1.23:37652	127.0.0.1:41854
%DOWNSTREAM_LOCAL_ADDRESS%	10.0.45.184:8000	10.44.1.27:80
%DOWNSTREAM_REMOTE_ADDRESS%	10.44.1.23:46520	10.44.1.23:37652
%REQUESTED_SERVER_NAME%	-	outbound_.8000_._.httpbin.foo.svc.cluster.local
%ROUTE_NAME%	default	default

access log format 을 설정하는 방법

액세스 로그를 포맷팅하는 방법은 매우 간단하다. 아래의 공식 문서를 살펴보면,

https://istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/#MeshConfig

Global Mesh Options

Mesh Config 에 설정할 수 있는 옵션들이 많은데, accessLogFile, accessLogFormat 및 accessLogEncoding 를 확인하면 된다. 

• accessLogFile : 프록시 Access Log를 기록할 파일 경로(예: /dev/stdout)이며, 값이 비어 있으면 Access Log가 비활성화
• accessLogFormat : 프록시 Access Log의 출력 형식을 지정하며, 값이 비어 있으면 프록시의 기본 로그 포맷을 사용
• accessLogEncoding : 프록시 Access Log의 인코딩 방식을 지정하고 TEXT 또는 JSON 중 선택할 수 있으며, 기본값은 TEXT

예를 들어, 아래와 같이 istioOperator 를 지정하여 배포하면 된다.

spec:
  meshConfig:
    accessLogFile: /dev/stdout
    accessLogEncoding: JSON
    accessLogFormat: |
      {
        "start_time": "%START_TIME%",
        "method": "%REQ(:METHOD)%",
        "path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%",
        "protocol": "%PROTOCOL%",
        "response_code": "%RESPONSE_CODE%",
        "duration": "%DURATION%",
        "upstream_host": "%UPSTREAM_HOST%",
      }

AccessLogFormat 세부 사항

아래의 Envoy 공식 문서를 확인하면, AccessLogFormat 에 지정할 수 있는 커맨드 옵션을 확인할 수 있다.

Envoy는 오픈 소스 프로젝트인 envoyproxy.io에서 개발된 고성능 프록시로, Istio에서 데이터 플레인(proxy) 역할을 수행

https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage?utm_source=chatgpt.com

Access logging — envoy 1.37.0-dev-2d3176 documentation

Istio의 Access Log는 워크로드로 들어오거나 나가는 트래픽의 흐름을 기록한다. 이를 통해 서비스 내부에서 요청이 어떻게 전달되는지, 어느 지점에서 처리되는지를 추적할 수 있다.

• Inbound 트래픽: 외부나 다른 서비스에서 워크로드로 들어오는 요청이다. 예를 들어, 클라이언트가 API 서버에 요청을 보내면 이 요청은 워크로드 입장에서는 inbound 트래픽으로 기록된다.
• Outbound 트래픽: 워크로드에서 외부나 다른 서비스로 나가는 요청이다. 워크로드 내부에서 다른 마이크로서비스로 요청을 보낼 때 기록된다.

Access Log에서 자주 등장하는 upstream과 downstream은 Envoy의 용어이다.

• Upstream: Envoy 사이드카가 요청을 전달하는 대상 호스트이다. 즉, 워크로드 내부의 실제 애플리케이션 컨테이너가 upstream 역할을 한다. Upstream 정보는 요청이 어디로 전달되었는지 확인할 때 유용하다.
• Downstream: Envoy 사이드카로 요청을 보내고 응답을 받는 클라이언트 호스트이다. 일반적으로 요청을 시작한 쪽, 즉 사용자 혹은 다른 서비스가 downstream이 된다.

Access Log는 요청에 대한 다양한 메타데이터를 기록한다. 이를 통해 요청이 어떤 방식으로 전달되고 처리되는지 분석할 수 있다.

• Method & Path: 요청의 HTTP 메서드와 경로. 예: GET /hello HTTP/1.1
• X-ENVOY-UPSTREAM-SERVICE-TIME: Envoy가 요청을 받은 후 업스트림 서비스에서 처리 완료되어 돌아오기까지 걸린 시간(밀리초 단위).
• X-FORWARDED-FOR (XFF 헤더): 요청이 프록시나 로드 밸런서를 거칠 때 원래 클라이언트 IP를 보존하기 위해 사용
• User-Agent: 요청을 보낸 클라이언트 프로그램 정보. 예: curl/8.6.0
• X-REQUEST-ID: 요청 식별용 고유 ID. 요청 간 추적과 디버깅을 위해 사용
• Authority: 요청 대상 호스트와 포트 정보. HTTP/1.x의 Host 헤더와 유사하며, 서버가 여러 도메인을 서비스할 때 어떤 도메인으로 요청이 들어왔는지 구분

Access Log는 요청 처리 후의 결과 정보도 기록한다.

• Response Code: HTTP 상태 코드(예: 200, 418)
• Response Code Details: 응답 코드가 생성된 구체적인 이유나 조건. 디버깅 용도로 사용.
• Response Flag: 요청이 어떻게 처리되었는지를 나타낸다. 예: via_upstream은 응답 코드가 업스트림에서 설정되었음을 의미

Envoy Access Log는 요청의 Header와 Body 내용을 직접 기록하지 않는다. 다만 일부 중요한 헤더는 기본적으로 기록된다.

• X-FORWARDED-FOR
• X-REQUEST-ID
• AUTHORITY

최종 AccessLogFormat (주의 사항 포함)

accessLogFormat에 지정한 내용은 기존 로그를 덮어씁니다. 모든 default access log 필드를 반드시 재작성해야 합니다. 

spec:
  meshConfig:
    accessLogFile: /dev/stdout
    accessLogEncoding: JSON
    accessLogFormat: |
      {
        "start_time": "%START_TIME(%Y-%m-%dT%H:%M:%S.%3fZ)%",                # 요청 시작 시각 
        "method": "%REQ(:METHOD)%",                                          # HTTP 메서드
        "path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%",                        # 원본 요청 URI 또는 경로
        "authority": "%REQ(:AUTHORITY)%",                                    # 요청 대상 호스트
        "protocol": "%PROTOCOL%",                                            # HTTP 프로토콜 버전
        "status": "%RESPONSE_CODE%",                                         # 응답 상태 코드
        "response_flags": "%RESPONSE_FLAGS%",                                # Envoy 응답 플래그
        "duration_ms": "%DURATION%",                                         # 요청 처리 시간(ms)
        "upstream_service_time_ms": "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%", # Upstream 처리 시간
        "upstream_host": "%UPSTREAM_HOST%",                                  # Upstream 호스트(ip:port)
        "downstream_remote_address": "%DOWNSTREAM_REMOTE_ADDRESS%",          # 클라이언트 IP:포트
        "request_headers": {
          "user_agent": "%REQ(USER-AGENT)%",                                 # User-Agent 확인용
          "x_forwarded_for": "%REQ(X-FORWARDED-FOR)%",                       # 헤더 전파 확인용
          "x_request_id": "%REQ(X-REQUEST-ID)%"                              # 요청 고유 ID 확인용
        },
        "response_headers": {
          "content_type": "%RESP(CONTENT-TYPE)%",                            # 응답 Content-Type
          "content_length": "%RESP(CONTENT-LENGTH)?"                         # 응답 Content-Length (있을 경우)
        },
        "route_name": "%ROUTE_NAME%",                                        # 매칭된 라우트 이름
      }

해당 istioOperator 를 적용한 뒤, istio proxy 컨테이너가 포함된 모든 파드를 모두 재기동해야 적용된다.