Trace 라벨

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

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

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

라벨이 표시되는 위치는 두 곳입니다. 세부정보 창에는 가장 일반적인 HTTP 라벨이 나열되고 호출 trace 표에는 stacktrace 라벨의 콘텐츠가 나열됩니다.

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 세부정보 뷰에 포함된 세부정보 표에 표시됩니다.

다음은 여러 라벨을 포함하는 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 속성 이름을 교차 나열하는 표를 찾으려면 속성을 참조하세요.