Trace 라벨

Trace는 스팬에 의미 있는 데이터를 주석으로 추가할 수 있는 메커니즘을 제공합니다. Cloud Trace API V1을 사용하는 경우 Cloud Trace API TraceSpan 객체의 labels 필드를 사용하여 이러한 주석을 만듭니다. Cloud Trace API V2를 사용하는 경우 속성으로 주석을 추가할 수 있습니다. 주석 옵션에 대한 자세한 내용은 스팬 주석 처리를 참조하세요.

대부분의 라벨은 라벨 표에서 Trace 폭포식 뷰가 표시된 경우 표시됩니다.

라벨과 스택 trace가 표시된 Trace 목록 페이지

라벨이 표시되는 다른 위치도 있습니다.

  • 세부정보 창에 가장 일반적인 HTTP 라벨이 나열됩니다.
  • 호출 trace 표에는 stacktrace 라벨의 콘텐츠가 표시됩니다. 이 표는 스팬에 스택 trace가 포함된 경우에만 표시됩니다.
  • GKE 컨테이너 표에는 GKE 컨테이너의 표준 라벨이 표시됩니다. 표의 각 행은 특정 라벨에 대한 값이며 리소스에 대한 정보를 자세히 볼 때 사용할 수 있는 링크입니다.

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 형식의 스택 trace입니다. 스택 trace는 검색을 위해 색인이 생성되지 않습니다.
이 라벨은 호출 스택 표에 표시됩니다.

    "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 컨테이너의 모든 표준 라벨이 나와 있습니다.

라벨
Project ID GKE 클러스터를 호스팅하는 Google Cloud 프로젝트입니다. 프로젝트 이름을 클릭하여 Google Cloud Console의 GKE 대시보드로 이동합니다.
Cluster Name GKE 클러스터를 식별합니다. 클러스터 구성 페이지로 이동하려면 이 값을 클릭합니다.
Namespace 네임스페이스를 식별합니다. GKE 워크로드 페이지로 이동하려면 이 값을 클릭합니다.
Pod Name GKE pod를 식별합니다. Pod 세부정보 대시보드로 이동하려면 이 값을 클릭합니다.
Container Name GKE 컨테이너를 식별합니다. 컨테이너의 세부정보 페이지로 이동하려면 이 값을 클릭합니다.

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

{
  "projectId": "a-sample-project",
  "traceId": "00000000000000004db6dd68e7d37f57",
  "spans": [
    {
      "spanId": "12913864118554233534",
      "kind": "RPC_SERVER",
      "name": "http://xx.xxx.xxx.xxx/",
      "startTime": "2019-04-02T19:37:34.149058Z",
      "endTime": "2019-04-02T19:37:34.151136Z",
      "parentSpanId": "5599906629317525335",
      "labels": {
        "/component": "default",
        "/http/host": "xx.xxx.xxx.xxx",
        "/http/status_code": "200",
        "/http/url": "http://xx.xxx.xxx.xxx/",
        "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 프리픽스

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

라벨 키 샘플 라벨 값
g.co/agent opencensus-go[0.15.0]
g.co/gce/instanceid 12345678900000000

커스텀 라벨

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

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

수백 또는 수천 개의 커스텀 라벨을 만들면 라벨 카디널리티가 증가하여 성능에 영향을 미칠 수 있습니다.

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

OpenCensus 사용

OpenCensus 라이브러리를 사용하는 경우 OpenCensus 속성 이름을 사용해야 합니다. Cloud Trace 사전 정의된 라벨 이름과 함께 OpenCensus 속성 이름을 교차 나열하는 표를 찾으려면 속성을 참조하세요.