Trace 라벨

trace는 스팬에 의미 있는 데이터를 추가할 수 있는 메커니즘을 제공합니다. Cloud Trace API V1을 사용하는 경우 Cloud Trace API TraceSpan 객체에서 labels 필드를 사용하여 키-값 쌍인 라벨을 추가할 수 있습니다. Cloud Trace API V2를 사용하는 경우 Attributes 객체로 정보를 추가할 수 있습니다.

스팬을 탐색할 때는 해당 스팬의 라벨이 속성 탭에 표시됩니다. 예를 들어 다음 스크린샷은 이 탭을 보여줍니다.

Cloud Trace 속성 테이블의 예시

이 정보에 액세스하는 방법은 trace 찾기 및 탐색을 참조하세요.

labels 필드는 키-값 쌍의 매핑입니다. 키와 값은 문자열로 저장됩니다. 문자열 길이 제한은 labels에 대한 API 참조를 확인하세요.

스팬당 32개의 라벨로 제한됩니다.

사전 정의된 키

표준 라벨

다음 표는 지원되는 사전 정의된 키를 설명을 포함하여 나열하고 경우에 따라 예시를 포함합니다.

라벨 키설명
예시
/agent Trace 에이전트 식별자입니다.
"node@google-cloud/trace-agent v3.0.0"
/component 구성요소 식별자입니다.
"grpc"
/error/message 오류 메시지입니다.
"Rendezvous of RPC that terminated with:
status = StatusCode.UNAVAILABLE details = OS Error."
/error/name 오류의 표시 이름입니다.
/http/client_city 클라이언트의 도시입니다.
"NYC"
/http/client_country 클라이언트의 국가입니다.
"US"
/http/client_protocol HTTP 프로토콜 식별자입니다.
"1.0"
/http/client_region 클라이언트의 리전입니다.
"us-east4"
/http/host 호스트 헤더의 값입니다.
"default.example.com"
/http/method† HTTP 요청 메서드로 설정합니다.
HTTP가 아닌 요청에는 이 키를 포함하지 않습니다.
"GET"
/http/path† 요청 URL 경로입니다.
"/cart/checkout"
/http/redirected_url 리디렉션 전의 URL입니다.
이 경우 키 HTTL URL 라벨을 사용하여 최종 도착 URL을 저장합니다.
/http/request/size 요청의 바이트 수입니다.
/http/response/size 응답의 바이트 수입니다.
/http/route† 일치하는 경로입니다.
"/cart/checkout/:item_id"
/http/status_code† HTTP 응답 상태 코드
"200"
/http/url 전체 HTTP 요청 URL입니다.
"http://example.com"
/http/user_agent 요청이 시작된 HTTP 사용자 에이전트에 대한 정보입니다.
"python-requests/2.19.1"
/stacktrace JSON 형식의 스택 트레이스입니다. 스택 트레이스는 검색을 위해 색인이 생성되지 않습니다.
이 라벨은 호출 스택 표에 표시됩니다.
/stacktrace 라벨은 V1 API에만 사용됩니다.
V2 API의 경우 span에 stackTrace 필드가 포함됩니다. 
    "stackTrace": {
      "stackFrames": {
        "frame": [
          {
            "functionName": {
              "value": "serverMethodTrace [as func]"
            },
            "fileName": {
              "value":
              "/usr/src/app/node_modules/@google-cloud/trace-agent/build/src/plugins/plugin-grpc.js"
            },
            "lineNumber": "249",
            "columnNumber": "28"
          },
          {
            "functionName": {
              "value": "anonymous function"
            },
            "fileName": {
              "value": "/usr/src/app/node_modules/grpc/src/server.js"
            },
            "lineNumber": "592",
            "columnNumber": "13"
          }
        ]
      }
    },

†이 라벨과 라벨 값은 trace 세부정보 뷰에 포함된 세부정보 표에 표시됩니다.

GKE의 표준 라벨

다음 표에는 GKE 컨테이너의 모든 표준 라벨이 나와 있습니다.

GKE 컨테이너 표의 표시 이름
라벨 키		 설명
프로젝트 ID
g.co/r/k8s_container/project_id		 GKE 클러스터를 호스팅하는 Google Cloud 프로젝트입니다. 프로젝트 이름을 클릭하여 Google Cloud 콘솔의 GKE 대시보드로 이동합니다.
위치
g.co/r/k8s_container/location		 GKE 클러스터의 물리적 위치입니다.
클러스터 이름
g.co/r/k8s_container/cluster_name 		GKE 클러스터를 식별합니다. 클러스터 구성 페이지로 이동하려면 이 값을 클릭합니다.
네임스페이스
g.co/r/k8s_container/namespace 		네임스페이스를 식별합니다. GKE 워크로드 페이지로 이동하려면 이 값을 클릭합니다.
Pod 이름
g.co/r/k8s_container/pod_name 		GKE pod를 식별합니다. Pod 세부정보 대시보드로 이동하려면 이 값을 클릭합니다.
컨테이너 이름
g.co/r/k8s_container/container_name 		GKE 컨테이너를 식별합니다. 컨테이너의 세부정보 페이지로 이동하려면 이 값을 클릭합니다.

예

다음은 여러 라벨을 포함하는 Trace 객체의 부분 JSON 표현입니다.

{
  "projectId": "a-sample-project",
  "traceId": "00000000000000004db6dd68e7d37f57",
  "spans": [
    {
      "spanId": "12913864118554233534",
      "kind": "RPC_SERVER",
      "name": "http://192.0.2.0/",
      "startTime": "2024-04-02T19:37:34.149058Z",
      "endTime": "2025-04-02T19:37:34.151136Z",
      "parentSpanId": "5599906629317525335",
      "labels": {
        "/component": "default",
        "/http/host": "192.0.2.0",
        "/http/status_code": "200",
        "/http/url": "http://192.0.2.0/",
        "zipkin.io/http.route": "/**",
        "/http/method": "GET",
        "zipkin.io/endpoint.ipv4": "10.16.1.6",
        "zipkin.io/http.path": "/",
        "zipkin.io/mvc.controller.class": "ResourceHttpRequestHandler"
      }
    }
  ]
}

앞의 trace는 Zipkin 수집기를 사용하는 시스템에서 가져왔습니다. 이 경우에는 zipkin.io 키가 있는 라벨이 해당 수집기에 의해 추가되었습니다.

g.co 프리픽스

일부 경우에는 표시된 라벨에 g.co 프리픽스가 포함됩니다. g.co 프리픽스는 이 라벨이 Google 서비스에 의해 생성되었음을 나타냅니다. App Engine 또는 다른 Google Cloud 인프라에서 서비스를 실행하는 경우 다음과 같은 라벨이 표시될 수 있습니다.

라벨 키 샘플 라벨 값
g.co/agent opentelemetry-js 1.18.1; google-cloud-trace-exporter 2.1.0
g.co/r/generic_node/location global

커스텀 라벨

커스텀 라벨을 만들 수 있습니다. 커스텀 라벨을 만드는 경우 다음 형식을 사용하는 것이 좋습니다.

  • /category/product/key: 잘 알려진 제품 에이전트의 경우 예: /db/mongodb/read_size
  • short_host/path/key: 도메인별 키의 경우 예를 들면 g.co/agent입니다.

많은 커스텀 라벨을 만들면 라벨 카디널리티가 증가하여 성능에 영향을 미칠 수 있습니다.

예시 섹션에 설명된 대로 Zipkin 수집기, 또는 OpenTelemetry와 같은 라이브러리를 사용하는 경우 추적 스팬에 라벨이 추가될 수 있습니다.

OpenTelemetry 사용

OpenTelemetry 라이브러리를 사용하는 경우 스팬을 만들 때 OpenTelemetry 시맨틱 규칙을 사용해야 합니다.