마이크로서비스 관측 가능성 참조 정보

구성 데이터

다음 표에는 환경 변수에서 확인할 수 있는 구성 데이터가 정의되어 있습니다.

필드 사양
project_id 문자열

관측 가능한 데이터가 전송되는 프로젝트의 식별자입니다. 비어 있으면 gRPC 관측 가능성 플러그인이 환경 변수 또는 기본 사용자 인증 정보에서 프로젝트 ID를 가져오려고 시도합니다.

찾을 수 없으면 관측 가능성 init 함수가 오류를 반환합니다.
cloud_logging 객체

로깅 옵션은 이 테이블에 분류됩니다.
없으면 로깅이 사용 중지됩니다.
cloud_logging.client_rpc_events[] 목록

라이브러리에서 나가는 RPC에 대한 구성을 보여주는 client_rpc_events 구성 목록입니다.

client_rpc_events 구성은 텍스트 순서로 평가되고 첫 번째 일치 항목이 사용됩니다. RPC가 항목과 일치하지 않으면 목록에서 다음 항목을 계속 평가합니다.
cloud_logging.client_rpc_events[].methods[] 목록[String]

메서드 식별자 목록입니다.

기본적으로는 목록이 비어 있고 일치하는 메서드가 없습니다.

메서드의 값은 [service]/[method] 형식입니다.

*는 다음 항목의 와일드 카드로 허용됩니다.
  • 메서드 이름입니다. 값이 [service]/*이면 지정된 서비스에 있는 모든 메서드와 일치합니다.
  • 모든 [service]/[method]와 일치하는 필드의 전체 값입니다. client_rpc_events[].exclude가 true이면 지원되지 않습니다.
  • * 와일드 카드는 서비스 이름에서 독립적으로 사용할 수 없습니다. */[method]는 지원되지 않습니다.

서비스 이름(지정된 경우)은 패키지 이름을 포함하여 정규화된 서비스 이름이어야 합니다.

예시:
  • goo.Foo/Bar는 goo.Foo 서비스에서 Bar 메서드만 선택합니다. 여기서 goo는 패키지 이름입니다.
  • goo.Foo/*는 goo.Foo 서비스의 모든 메서드를 선택합니다.
  • *은 모든 서비스의 모든 메서드를 선택합니다.
cloud_logging.client_rpc_events[].exclude 불리언

client_rpc_events[].methods[]로 표시된 메서드를 로깅에서 제외할지 여부입니다.

기본값은 false입니다. 즉, client_rpc_events[].methods[]로 표시된 메서드가 로그 레코드에 포함됩니다.

값이 true이면 와일드 카드(*)를 client_rpc_events[].methods[].의 전체 값으로 사용할 수 없습니다.
cloud_logging.client_rpc_events[].max_metadata_bytes Int

로깅할 메타데이터의 최대 바이트 수입니다. 메타데이터 크기가 정의된 한도보다 크면 한도를 초과하는 키-값 쌍이 로깅되지 않습니다.

기본값은 0입니다. 즉, 메타데이터가 로깅되지 않습니다.
cloud_logging.client_rpc_events[].max_message_bytes Int

로깅할 각 메시지의 최대 바이트 수입니다. 메시지 크기가 정의된 한도보다 크면 한도를 초과하는 콘텐츠가 잘립니다.

기본값은 0입니다. 즉, 메시지 페이로드가 로깅되지 않습니다.
cloud_logging.server_rpc_events[] 목록

바이너리로 들어오는 RPC 구성을 나타내는 server_rpc_events 구성 목록입니다.

server_rpc_events 구성은 텍스트 순서로 평가되고 첫 번째 일치 항목이 사용됩니다. RPC가 항목과 일치하지 않으면 목록에서 다음

항목을 계속 평가합니다.
cloud_logging.server_rpc_events[].methods[] 목록 [String]

메서드 그룹을 선택할 수 있는 문자열 목록입니다.

기본적으로는 목록이 비어 있고 일치하는 메서드가 없습니다.

메서드의 값은 [service]/[method] 형식입니다.

*는 다음 항목의 와일드 카드로 허용됩니다.
  • 메서드 이름입니다. 값이 [service]/*이면 지정된 서비스에 있는 모든 메서드와 일치합니다.
  • 모든 [service]/[method]와 일치하는 메서드의 전체 값입니다. server_rpc_events[].exclude가 true이면 지원되지 않습니다.
  • * 와일드 카드는 서비스 이름에서 독립적으로 사용할 수 없습니다. */[method]는 지원되지 않습니다.

서비스 이름(지정된 경우)은 패키지 이름을 포함하여 정규화된 서비스 이름이어야 합니다.

예시:
  • goo.Foo/Bar는 goo.Foo 서비스에서 Bar 메서드만 선택합니다. 여기서 goo는 패키지 이름입니다.
  • goo.Foo/*는 goo.Foo 서비스의 모든 메서드를 선택합니다.
  • *은 모든 서비스의 모든 메서드를 선택합니다.
cloud_logging.server_rpc_events[].exclude 불리언

server_rpc_events[].methods[]로 표시된 메서드를 로깅에서 제외할지 여부입니다.

기본값은 false입니다. 즉, server_rpc_events[].methods[]로 표시된 메서드가 로깅됩니다.

값이 true이면 와일드 카드(*)를 server_rpc_events[].methods[]의 전체 값으로 사용할 수 없습니다.
cloud_logging.server_rpc_events[].max_metadata_bytes Int

로깅할 메타데이터의 최대 바이트 수입니다. 메타데이터 크기가 정의된 한도보다 크면 한도를 초과하는 키-값 쌍이 로깅되지 않습니다.

기본값은 0입니다. 즉, 메타데이터가 로깅되지 않습니다.
cloud_logging.server_rpc_events[].max_message_bytes Int

로깅할 각 메시지의 최대 바이트 수입니다. 메시지 크기가 정의된 한도보다 크면 한도를 넘어서는 콘텐츠가 잘립니다.

기본값은 0입니다. 즉, 메시지 페이로드가 로깅되지 않습니다.
cloud_monitoring 객체

Cloud Monitoring을 사용 설정합니다. 구성 옵션이 없습니다. 비어 있는 구성 객체를 제공하면 모니터링이 사용 설정됩니다. 구성 객체를 제공하지 않으면 모니터링이 사용 중지됩니다.

예를 들어 다른 옵션을 지정하지 않으면 빈 구성 섹션이 모니터링을 사용 설정합니다.

export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_monitoring": {
    }
}'
cloud_trace 객체

빈 구성 섹션은 기본 구성 옵션으로 추적을 사용 설정합니다. 구성 객체를 제공하지 않으면 추적이 사용 중지됩니다.

예를 들어 빈 구성 섹션은 기본 구성 옵션으로 추적을 사용 설정합니다.

export GRPC_GCP_OBSERVABILITY_CONFIG='{
    "project_id": "your-project-here",
    "cloud_trace": {
    }
}'


추적이 사용 설정되었으면 샘플링 레이트가 '0'이더라도 특정 trace를 샘플링하는 결정이 전파됩니다.
cloud_trace.sampling_rate 숫자

추적되는 RPC의 확률을 제어하는 전역 설정입니다. 예를 들면 다음과 같습니다.
  • 값이 0.05면 RPC가 추적될 가능성이 5%입니다.
  • 값이 1.0이면 모든 호출이 추적됩니다.
  • 값이 0이면 새 추적이 시작되지 않습니다.

기본적으로 sample_rate는 0입니다.

이 플러그인은 샘플링 결정을 업스트림에 존중합니다. RPC가 업스트림에서 샘플링되도록 선택된 경우 플러그인은 플러그인의 샘플링 레이트 설정에 관계없이 스팬을 수집하고 백엔드에 데이터를 업로드합니다.
labels 객체

키-값 쌍 집합을 포함하는 JSON 객체입니다. 키와 값은 모두 문자열입니다.

라벨은 Cloud Logging, Cloud Monitoring, Cloud Trace에 함께 적용됩니다.

Trace 정의

이 섹션에서는 추적에 대한 정보를 제공합니다.

추적 컨텍스트 전파

서비스 간 추적이 작동하기 위해서는 서비스 소유자가 업스트림에서 수신된(또는 그 자체로 시작된) 추적 컨텍스트를 다운스트림으로 전파하도록 지원해야 합니다. Trace 컨텍스트는 gRPC 메타데이터를 통해 서비스 간에 전파됩니다. 이 구성의 서비스가 원격 분석 데이터를 적절한 서비스에 보고할 수 있도록 Cloud Monitoring, Cloud Logging, Cloud Trace API, 마이크로서비스 API를 사용 설정해야 합니다.

전파 지원이 없으면 다운스트림 서비스가 Trace에 대해 스팬을 생성할 수 없습니다. 기존 스팬은 영향을 받지 않습니다. 마이크로서비스 관측 가능성 플러그인은 추적 컨텍스트 인코딩을 위해 OpenCensus 바이너리 형식을 지원합니다.

스팬

스팬 이름 형식은 다음과 같이 지정됩니다.

유형 예시 값 용도
RPC 스팬 [Sent|Recv].helloworld.Greeter.SayHello 스팬 이름은 프리픽스 슬래시 없이 점으로 연결된 전체 메서드 이름입니다.
스팬 이름은 CLIENT RPC 스팬의 경우 Sent.가 프리픽스로 지정되고 전체 메서드 이름 앞에 있는 SERVER RPC 스팬의 경우 Recv.가 프리픽스로 지정됩니다.
시도 스팬 Attempt.helloworld.Greeter.SayHello 전체 메서드 이름 앞에 Attempt. 프리픽스를 연결합니다.

스팬 라벨

통합은 다른 스팬 라벨을 제공합니다.

시도 스팬의 경우 2개의 추가 재시도 관련 속성(스팬 라벨)이 연결됩니다.

라벨 예시 값 용도
previous-rpc-attempts 0 이 RPC 이전의 재시도 수입니다.
transparent-retry True/False 이 RPC가 투명한 재시도로 시작되었는지 여부입니다.

측정항목 정의

다음 측정항목이 제공되고 일반적인 사용자 여정에 대해 마이크로서비스(gRPC) 모니터링이라는 대시보드에 표시됩니다.

다음은 gRPC 클라이언트 측 측정항목의 측정항목입니다.

측정항목 이름 설명 종류, 유형, 단위 라벨
custom.googleapis.com/opencensus/grpc.io/client/started_rpcs 완료되지 않은 항목을 포함하여 시작된 클라이언트 RPC 시도 수입니다. 누적, Int64, 1 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/completed_rpcs 서버에서 응답이 수신되거나 전송될 때와 같이 완료된 클라이언트 RPC 수입니다. 누적, Int64, 1 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/roundtrip_latency 하위 채널을 선택하는 데 걸리는 시간을 포함하여 RPC 시도를 완료하는 데 걸리는 엔드 투 엔드 시간입니다. 누적, 분산, 밀리초 grpc_client_method
custom.googleapis.com/opencensus/grpc.io/client/api_latency 애플리케이션의 관점에서 RPC를 완료하기 위해 gRPC 라이브러리에 걸리는 전체 시간입니다. 누적, 분산, 밀리초 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/sent_compressed_message_bytes_per_rpc RPC 시도당 모든 요청 메시지에 전송되는 총 바이트(압축되고, 암호화되지 않음)입니다. 누적, 분포, 기준 grpc_client_method, grpc_client_status
custom.googleapis.com/opencensus/grpc.io/client/received_compressed_message_bytes_per_rpc RPC 시도당 모든 응답 메시지에 수신되는 총 바이트(압축되고 암호화되지 않음)입니다. 누적, 분포, 기준 grpc_client_method, grpc_client_status

다음 gRPC 서버 측 측정항목을 사용할 수 있습니다.

측정항목 이름 설명 종류, 유형, 단위 라벨
custom.googleapis.com/opencensus/grpc.io/server/started_rpcs
완료되지 않은 RPC를 포함하여 서버에서 지금까지 수신된 RPC 수입니다.		 누적, Int64, 1 grpc_server_method
custom.googleapis.com/opencensus/grpc.io/server/completed_rpcs
서버에서 응답이 전송된 경우와 같이 완료된 총 RPC 수입니다.		 누적, Int64, 1 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/sent_compressed_message_bytes_per_rpc
RPC당 모든 응답 메시지에 전송되는 총 바이트(압축되고 암호화되지 않음)입니다.		 누적, 분포, 기준 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/received_compressed_message_bytes_per_rpc
RPC당 모든 요청 메시지에 수신되는 총 바이트(압축되고 암호화되지 않음)입니다.		 누적, 분포, 기준 grpc_server_method, grpc_server_status
custom.googleapis.com/opencensus/grpc.io/server/server_latency
서버 전송(HTTP2/inproc/cronet) 관점에서 RPC에 걸리는 전체 시간입니다.		 누적, 분산, 밀리초 grpc_server_method

위 표에서 각 분포에는 다음과 같은 버킷 히스토그램이 포함됩니다.

  • 바이트 크기: 0, 1024, 2048, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864, 268435456, 1073741824, 4294967296

  • 지연 시간(밀리초): 0, 0.01, 0.05, 0.1, 0.3, 0.6, 0.8, 1, 2, 3, 4, 5, 6, 8, 10, 13, 16, 20, 25, 30, 40, 50, 65, 80, 100, 130, 160, 200, 250, 300, 400, 500, 650, 800, 1000, 2000, 5000, 10000, 20000, 50000, 100000

태그 설명:

  • grpc_client_method: 패키지, 서비스, 메서드를 포함하는 전체 gRPC 메서드 이름(예: google.bigtable.v2.Bigtable/CheckAndMutateRow)
  • grpc_client_status: 수신된 gRPC 서버 상태 코드(예: OK, CANCELLED, DEADLINE_EXCEEDED)
  • grpc_server_method: 패키지, 서비스, 메서드를 포함하는 전체 gRPC 메서드 이름(예: com.exampleapi.v4.BookshelfService/Checkout)
  • grpc_server_status: 반환된 gRPC 서버 상태 코드(예: OK, CANCELLED, DEADLINE_EXCEEDED)

로그 레코드 정의

마이크로서비스 관측 가능성 로그는 로그 이름을 사용하여 Cloud Logging에 업로드됩니다. PROJECT_ID는 프로젝트를 나타내는 문자열의 자리 표시자입니다.

logName=projects/[PROJECT_ID]/logs/microservices.googleapis.com%2Fobservability%2Fgrpc

다음은 생성된 로그 레코드의 JSON 표현입니다.

{
    "authority": string,
    "callId": string,
    "type": string,
    "logger": string,
    "serviceName": string,
    "methodName": string,
    "peer": {
        "type": string,
        "address": string,
        "ipPort": int
    },
    "payload": {
        "timeout": string,
        "metadata":
            {
                string: string,
                string: string
            },
        "statusCode": string,
        "statusMessage": string,
        "statusDetails": string,
        "message": string,
        "messageLength": int,
    },
    "sequenceId": int
}

다음 표에서는 로그 항목의 필드를 설명합니다.

필드 사양
authority 문자열

단일 프로세스를 사용하여 서로 다른 ID로 여러 가상 서버를 실행할 수 있습니다.

authority는 이러한 서버 ID의 이름입니다. 일반적으로 호스트 또는 호스트:포트 형식에서 URI 부분입니다.
callId 문자열

UUID에 해당하는 [클라이언트/서버] 호출을 고유하게 식별합니다. 각 호출에는 여러 로그 항목이 포함될 수 있습니다. 모두 동일한 callId를 사용합니다.
type 문자열

로그 이벤트의 유형입니다.

이벤트 유형:
EVENT_TYPE_UNKNOWN
CLIENT_HEADER
SERVER_HEADER
CLIENT_MESSAGE
SERVER_MESSAGE
CLIENT_HALF_CLOSE
SERVER_TRAILER
CANCEL
logger 문자열

이벤트 로거의 유형입니다.

이벤트 로거 유형:
LOGGER_UNKNOWN, CLIENT, SERVER
serviceName 문자열

서비스의 이름입니다.
methodName 문자열

RPC 메서드의 이름입니다.
peer 객체

피어 주소 정보입니다. 클라이언트 측에서 피어는 서버 헤더 이벤트 및 트레일러 이벤트에 로깅됩니다. 서버 측에서 피어는 항상 클라이언트 헤더 이벤트에 로깅됩니다.
peer.type 문자열

IPv4, IPv6, UNIX 중 하나인 주소 유형입니다.
peer.address 문자열

주소의 콘텐츠입니다.
peer.ip_port Int

주소의 포트 번호입니다. IPv4 및 IPv6 주소에만 사용할 수 있습니다.
payload 객체

페이로드에는 이벤트에 따라 메타데이터, 제한 시간, 메시지, 상태 조합이 포함될 수 있습니다.

  • 메시지 이벤트의 경우 페이로드가 클라이언트/서버 메시지 및 메시지 길이로 전달되는 실제 데이터입니다.
  • 헤더 이벤트의 경우 페이로드에는 헤더 이름과 값이 포함됩니다.
  • 트레일러 이벤트의 경우 페이로드에 트레일러 메타데이터(있는 경우)와 함께 상태 세부정보가 포함됩니다.
  • 클라이언트 헤더 이벤트의 경우 제한 시간이 설정되었으면 페이로드에 제한 시간도 포함됩니다.
payload.timeout 문자열

google.protobuf.Duration을 나타내는 문자열입니다(예: '1.2초').

RPC 제한 시간 값입니다.
payload.metadata 매핑 [String, String]

헤더 이벤트 또는 트레일러 이벤트에 사용됩니다.
payload.message 문자열(바이트)

메시지 페이로드입니다.
payload.messageLength Int

전체 메시지가 로깅되는지 여부에 관계없이 메시지 크기입니다(예: 자르거나 생략 가능한지 여부).
payload.statusCode 문자열

gRPC 상태 코드입니다.
payload.statusMessage 문자열

gRPC 상태 메시지입니다.
payload.statusDetails 문자열

grpc-status-details-bin 메타데이터 키의 값입니다(있는 경우). 항상 인코딩된 google.rpc.Status 메시지입니다.
payloadTruncated 불리언

메시지 또는 메타데이터 필드가 구성 옵션으로 인해 잘렸거나 생략된 경우에는 True입니다.
sequenceId Int

이 호출에 대한 메시지 시퀀스 ID입니다. 첫 번째 메시지는 설정되지 않은 값과 구분을 위해 값이 1입니다. 이 필드의 목적은 내구성 또는 순서가 보장되지 않은 환경에서 누락된 항목을 감지하는 것입니다.

리소스 라벨

리소스 라벨은 관측 가능성 데이터를 생성하는 소스를 식별합니다. 각 리소스 라벨은 키 값 쌍입니다. 여기서 키는 소스 환경(예: GKE 또는 Compute Engine)과 관련된 사전 정의된 값입니다.

GKE 배포의 측정항목 및 추적의 경우 컨테이너 이름 및 네임스페이스 이름을 제외하고 기본적으로 리소스 라벨이 채워집니다. 누락된 값은 다운로드 API를 사용하여 채울 수 있습니다.

다음은 환경 변수 키입니다.

  • CONTAINER_NAME
  • NAMESPACE

예를 들어 다음 중 env 섹션에는 2개의 리소스 라벨이 포함됩니다.

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    run: app1
  name: app1
spec:
  replicas: 2
  selector:
    matchLabels:
      run: app1
  template:
    metadata:
      labels:
        run: app1
    spec:
      containers:
        - image: 'o11y-examples:1.00'
          name: container1
          ports:
            - protocol: TCP
              containerPort: 50051
          env:
            - name: CONTAINER_NAME
              value: container1
            - name: NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace

커스텀 라벨

커스텀 라벨은 관측 가능성 데이터에서 추가적인 사용자 제공 정보를 나타냅니다. 라벨은 키와 값으로 구성됩니다. 키-값 쌍은 추적 데이터에 스팬 라벨로 연결되고 측정항목 데이터에 측정항목 라벨로 연결되고 로깅 데이터에 로그 항목 라벨로 연결됩니다. 모든 커스텀 라벨은 STRING 유형입니다.

labels에 대해 키-값 쌍 목록을 지정하여 구성에 커스텀 라벨을 제공할 수 있습니다. 이 구현은 구성을 읽고 각 키-값 쌍에 대해 개별 라벨을 만든 후 라벨을 관측 가능성 데이터에 연결합니다. 예를 들면 다음과 같습니다.

"labels": {
    "DATACENTER": "SAN_JOSE_DC",
    "APP_ID": "24512"
  }

각 로그 항목에는 다음 추가 라벨이 포함됩니다.

{
   "DATACENTER": "SAN_JOSE_DC"
   "APP_ID": "24512"
}

다음 단계