분산 trace 사용 설정

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 페이지에서는 Apigee 런타임에 분산 추적을 구성하는 데 필요한 단계를 보여줍니다. 분산 추적 시스템을 처음 사용하고 자세한 정보가 필요한 경우 분산 추적 이해를 참조하세요.

소개

분산 trace 시스템을 사용하면 프록시와 같은 중개자뿐만 아니라 여러 애플리케이션, 서비스, 데이터베이스 간에 분산된 소프트웨어 시스템에서 요청을 추적할 수 있습니다. 이러한 추적 시스템은 각 단계의 요청에 걸린 시간을 보여주는 보고서를 생성합니다. 또한 추적 보고서를 통해 요청 중에 호출된 다양한 서비스를 상세하게 확인할 수 있으므로 소프트웨어 시스템의 각 단계에 발생한 변경사항을 더 자세히 이해할 수 있습니다.

Apigee Edge의 trace 도구와 Apigee의 디버그 도구는 API 프록시 문제를 해결하고 모니터링하는 데 유용합니다. 그러나 이러한 도구는 Cloud Trace 또는 Jaeger와 같은 분산 추적 서버에 데이터를 전송하지 않습니다. 분산 추적 보고서에서 Apigee 런타임 데이터를 보려면 Apigee 런타임에서 분산 추적을 명시적으로 사용 설정해야 합니다. 추적이 사용 설정되면 런타임은 trace 데이터를 추적 서버로 보내고 기존 trace에 참여할 수 있습니다. 따라서 단일 위치에서 Apigee 생태계 내부와 외부의 데이터를 볼 수 있습니다.

분산 추적 보고서에서 다음 정보를 확인할 수 있습니다.

• 전체 흐름의 실행 시간
• 요청이 수신된 시간
• 요청이 대상으로 전송된 시간
• 대상에서 응답이 수신된 시간
• 흐름에서 각 정책의 실행 시간
• 서비스 콜아웃 및 대상 흐름의 실행 시간
• 응답이 클라이언트로 전송된 시간

분산 추적 보고서에서는 흐름의 실행 세부정보를 스팬으로 확인할 수 있습니다. 스팬은 trace에서 흐름에 걸린 시간을 나타냅니다. 흐름을 실행하는 데 걸린 시간은 흐름에서 각 정책을 실행하는 데 필요한 시간의 집계로 표시됩니다. 각각의 다음 흐름을 개별 스팬으로 확인 수 있습니다.

• 요청
  • 프록시
    • Preflow
    • PostFlow
  • 대상
    • Preflow
    • PostFlow
• 응답
  • 프록시
    • Preflow
    • PostFlow
  • 대상
    • Preflow
    • PostFlow

분산 추적을 사용 설정하면 Apigee 런타임이 기본적으로 사전 정의된 변수 집합을 추적합니다. 자세한 내용은 trace 보고서의 기본 trace 변수를 참조하세요. TraceCapture 정책을 사용하여 기본 런타임 동작을 확장하고 추가 흐름, 정책 또는 커스텀 변수를 추적할 수 있습니다. 자세한 내용은 TraceCapture 정책을 사용하세요.

Apigee에 대한 수신 API 호출은 호출이 기존 trace의 일부이므로 trace 헤더를 포함할 수 있습니다. 이 경우 Apigee가 기존 trace에 참여하여 헤더를 나가는 API 호출로 전달합니다. Apigee 런타임은 Zipkin B3 헤더 형식을 이해합니다. 따라서 기존 trace에 참여할 때 x-b3-traceid, x-b3-spanid, x-b3-sampled 헤더를 인식합니다. 하지만 수신 API 호출에 trace 헤더가 없으면 Apigee가 해당 trace 헤더를 추가하고 이를 송신 API 호출에 전달합니다. 다른 서비스는 필요에 따라 헤더에 액세스하고 trace에 참여할 수 있습니다.

trace 보고서의 기본 trace 변수

분산 추적이 사용 설정되면 추적 보고서에서 다음과 같은 사전 정의된 변수 집합을 볼 수 있습니다. 이러한 변수는 다음 스팬에서 볼 수 있습니다.

• POST_RESP_SENT: 이 스팬은 대상 서버에서 응답이 수신된 후에 추가됩니다.
• POST_CLIENT_RESP_SENT: 이 스팬은 프록시 응답이 클라이언트로 전송된 후에 추가됩니다.

POST_RESP_SENT 스팬의 변수

다음 변수가 POST_RESP_SENT 스팬에 표시됩니다.

• REQUEST_URL(request.url)
• REQUEST_VERB(request.verb)
• RESPONSE_STATUS_CODE(response.status.code)
• ROUTE_NAME(route.name)
• ROUTE_TARGET(route.target)
• TARGET_BASE_PATH(target.basepath)
• TARGET_HOST(target.host)
• TARGET_IP(target.ip)
• TARGET_NAME(target.name)
• TARGET_PORT(target.port)
• TARGET_RECEIVED_END_TIMESTAMP(target.received.end.timestamp)
• TARGET_RECEIVED_START_TIMESTAMP(target.received.start.timestamp)
• TARGET_SENT_END_TIMESTAMP(target.sent.end.timestamp)
• TARGET_SENT_START_TIMESTAMP(target.sent.start.timestamp)
• TARGET_SSL_ENABLED(target.ssl.enabled)
• TARGET_URL(target.url)

POST_CLIENT_RESP_SENT 스팬의 변수

다음 변수가 POST_CLIENT_RESP_SENT 스팬에 표시됩니다.

• API_PROXY_REVISION(apiproxy.revision)
• APIPROXY_NAME(apiproxy.name)
• CLIENT_RECEIVED_END_TIMESTAMP(client.received.end.timestamp)
• CLIENT_RECEIVED_START_TIMESTAMP(client.received.start.timestamp)
• CLIENT_SENT_END_TIMESTAMP(client.sent.end.timestamp)
• CLIENT_SENT_START_TIMESTAMP(client.sent.start.timestamp)
• ENVIRONMENT_NAME(environment.name)
• FAULT_SOURCE(message.header + InternalHeaders.FAULT_SOURCE)
• IS_ERROR(is.error)
• MESSAGE_ID(message.id)
• MESSAGE_STATUS_CODE(message.status.code)
• PROXY_BASE_PATH(proxy.basepath)
• PROXY_CLIENT_IP(proxy.client.ip)
• PROXY_NAME(proxy.name)
• PROXY_PATH_SUFFIX(proxy.pathsuffix)
• PROXY_URL(proxy.url)

지원되는 분산 trace 시스템

Apigee 런타임은 다음과 같은 분산 trace 시스템을 지원합니다.

• Cloud Trace
• Jaeger

trace 데이터를 Cloud Trace 또는 Jaeger 시스템으로 전송하도록 Apigee 런타임을 구성할 수 있습니다.

Apigee 런타임에서 모든 API 호출을 추적하면 성능에 영향을 미치므로 Apigee에서 확률적 샘플링 레이트를 구성할 수 있습니다. 샘플링 레이트를 사용하여 분산 추적을 위해 전송되는 API 호출 수를 지정할 수 있습니다. 예를 들어 샘플링 레이트를 0.4로 지정하면 API 호출의 40%가 trace용으로 전송됩니다. 자세한 내용은 성능 고려사항을 참조하세요.

구성 가능한 최대 샘플링 레이트는 0.5입니다.

Cloud Trace를 위한 Apigee 런타임 구성

Apigee 런타임과 Apigee Hybrid 런타임 모두 Cloud Trace를 사용한 분산 추적을 지원합니다. Jaeger를 사용하는 경우에는 이 섹션을 건너뛰고 Jeger에 분산 추적 사용 설정을 진행합니다.

Cloud Trace를 위한 Apigee 런타임 구성

Apigee 런타임에서 Cloud Trace를 사용하려면 Google Cloud 프로젝트에 Cloud Trace API가 사용 설정되어 있어야 합니다. 이 설정을 사용하면 Google Cloud 프로젝트가 인증된 소스에서 trace 데이터를 수신할 수 있습니다.

Cloud Trace API가 사용 설정되어 있는지 확인하려면 다음 안내를 따르세요.

1. Google Cloud Console에서 API 및 서비스로 이동합니다.

   API 및 서비스로 이동

2. API 및 서비스 사용 설정을 클릭합니다.
3. 검색창에 Trace API를 입력합니다.
4. API 사용 설정됨이 표시된 경우는 이 API가 이미 사용 설정되어 있으므로 수행할 작업이 없습니다. 그렇지 않은 경우에는 사용 설정을 클릭합니다.

Cloud Trace를 위한 Apigee Hybrid 런타임 구성

Apigee Hybrid 런타임에서 Cloud Trace를 사용하려면 Cloud Trace API를 사용 설정해야 합니다. Cloud Trace API가 사용 설정되어 있는지 확인하려면 Cloud Trace에 Apigee 런타임 구성의 단계를 수행합니다.

Cloud Trace API를 사용 설정하는 것 외에도 iam.gserviceaccount.com 서비스 계정을 추가해야 Hybrid 런타임에서 Cloud Trace를 사용할 수 있습니다. 서비스 계정과 필수 역할 및 키를 추가하려면 다음 단계를 수행합니다.

1. 새 서비스 계정을 만듭니다.

   gcloud iam service-accounts create \
       apigee-runtime --display-name "Service Account Apigee hybrid runtime" \
       --project PROJECT_ID

2. 서비스 계정에 IAM 정책 바인딩을 추가합니다.

   gcloud projects add-iam-policy-binding \
       PROJECT_ID --member "serviceAccount:apigee-runtime@PROJECT_ID.iam.gserviceaccount.com" \
       --role=roles/cloudtrace.agent --project PROJECT_ID

3. 서비스 계정 키를 만듭니다.

   gcloud iam service-accounts keys \
       create ~/apigee-runtime.json --iam-account apigee-runtime@PROJECT_ID.iam.gserviceaccount.com

   서비스 계정 키를 올바르게 관리하지 않으면 보안 위험을 초래할 수 있습니다. 비공개 키의 보안 및 서비스 계정 키 관리 권장사항에 설명된 다른 작업의 책임은 사용자에게 있습니다. 서비스 계정 키를 만들 수 없는 경우 조직 수준에서 서비스 계정 키 생성이 사용 중지된 것일 수 있습니다. 자세한 내용은 기본 보안별 조직 리소스 관리를 참조하세요.
4. overrides.yaml 파일에 대해 서비스 계정을 추가합니다.

envs:
 - name: ENV_NAME
   serviceAccountPaths:
   runtime: apigee-runtime.json
   synchronizer: apigee-sync.json
   udca: apigee-udca.json

5. 런타임에 변경사항을 적용합니다.

apigeectl apply -f overrides.yaml --env=ENV_NAME

Apigee Hybrid 환경에서 Cloud Trace와 함께 Anthos Service Mesh를 사용할 수 있습니다. 서비스 메시에서 Cloud Trace 사용 설정에 대한 자세한 내용은 Cloud Trace에서 trace 액세스를 참조하세요.

분산 추적 사용 설정

Cloud Trace 또는 Jaeger에 분산 추적을 사용 설정하기 전에 다음 환경 변수를 만듭니다.

TOKEN="Authorization: Bearer $(gcloud auth print-access-token)"
ENV_NAME=YOUR_ENVIRONMENT_NAME
PROJECT_ID=YOUR_GOOGLE_CLOUD_PROJECT_ID

각 항목의 의미는 다음과 같습니다.

• TOKEN는 Bearer 토큰이 있는 인증 헤더를 정의합니다. Apigee API를 호출할 때 이 헤더를 사용합니다. 자세한 내용은 print-access-token 명령어의 참조 페이지를 확인하세요.
• ENV_NAME은 조직의 환경 이름입니다.
• PROJECT_ID는 Google Cloud 프로젝트의 ID입니다.

Cloud Trace에 분산 추적 사용 설정

다음 예시는 Cloud Trace에 대해 분산 trace를 사용 설정하는 방법을 보여줍니다.

1. 다음 Apigee API 호출을 실행합니다.

   curl -H "$TOKEN" \
       -H "Content-Type: application/json" \
       https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
       -X PATCH \
       -d '{"exporter":"CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'",
       "samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

   요청 본문 예시는 다음 요소로 구성됩니다.

   • samplingRate는 0.1로 설정되어 있습니다. 즉, API 호출 중 약 10%가 분산 추적으로 전송됩니다. 런타임 환경에 samplingRate를 설정하는 방법에 대한 자세한 내용은 성능 고려사항을 참조하세요.
   • exporter 매개변수가 CLOUD_TRACE로 설정됩니다.
   • 엔드포인트는 trace를 전송할 Google Cloud 프로젝트로 설정됩니다. 참고: 구성 단계에서 수행된 서비스 계정과 일치해야 합니다.

   성공적인 응답은 다음과 유사하게 표시됩니다.

   {
     "exporter": "CLOUD_TRACE",
     "endpoint": "staging",
     "samplingConfig": {
       "sampler": "PROBABILITY",
       "samplingRate": 0.1
     }
   }

Jaeger에 분산 추적 사용 설정

다음 예시는 Jaeger에 대해 분산 trace를 사용 설정하는 방법을 보여줍니다.

curl -s -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig' \
    -X PATCH \
    -H "content-type:application/json" -d '{
    "samplingConfig": {
    "samplingRate": 0.4,
    "sampler": "PROBABILITY"},
    "endpoint": "http://DOMAIN:9411/api/v2/spans",
    "exporter": "JAEGER"
    }'

예를 들면 다음과 같습니다.

• samplingRate가 0.4로 설정됩니다. 즉, API 호출 중 약 40%가 분산 추적으로 전송됩니다.
• exporter 매개변수가 JAEGER로 설정됩니다.
• 엔드포인트는 Jaeger가 설치되고 구성된 위치로 설정됩니다.

명령어를 실행하면 다음과 비슷한 응답이 표시될 수 있습니다.

{
  "exporter": "JAEGER",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.4
  }
}

분산 추적 구성 보기

런타임에서 기존 분산 추적 구성을 보려면 런타임에 로그인하고 다음 명령어를 실행합니다.

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig

명령어를 실행하면 다음과 비슷한 응답이 표시될 수 있습니다.

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.1
  }
}

분산 추적 구성 업데이트

다음 명령어는 Cloud Trace에 대해 기존 분산 trace 구성을 업데이트하는 방법을 보여줍니다.

curl -s \
    -H "$TOKEN" \
    'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig?updateMask=endpoint,samplingConfig,exporter' \
    -X PATCH -H "content-type:application/json" \
    -d '{"samplingConfig": {"samplingRate": 0.05, "sampler":"PROBABILITY"},
    "endpoint":"staging", exporter:"CLOUD_TRACE"}'

명령어를 실행하면 다음과 비슷한 응답이 표시될 수 있습니다.

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "PROBABILITY",
    "samplingRate": 0.05
  }
}

이 예시에서는 샘플링 레이트가 0.05로 업데이트됩니다.

Jaeger에 대해 구성을 업데이트하려면 요청에서 exporter 필드를 JAEGER로 설정합니다.

분산 추적 구성 중지

다음 예시는 Cloud Trace에 대해 구성된 분산 추적을 중지하는 방법을 보여줍니다.

curl -H "$TOKEN" \
    -H "Content-Type: application/json" \
    https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig \
    -X PATCH -d '{"exporter": "CLOUD_TRACE","endpoint": "'"$PROJECT_ID"'","samplingConfig":
    {"sampler": "OFF","samplingRate": 0.1}}'

명령어를 실행하면 다음과 비슷한 응답이 표시될 수 있습니다.

{
  "exporter": "CLOUD_TRACE",
  "endpoint": "staging",
  "samplingConfig": {
    "sampler": "OFF",
    "samplingRate": 0.1
  }
}

API 프록시에 대한 trace 설정 재정의

Apigee 런타임에서 분산 trace를 사용 설정한 후에는 런타임의 모든 API 프록시가 trace에 대해 동일한 구성을 사용합니다. 하지만 API 프록시 또는 API 프록시 그룹에 대해 분산 trace 구성을 재정의할 수 있습니다. 이렇게 하면 trace 구성을 더 세부적으로 제어할 수 있습니다.

다음 예시는 hello-world API 프록시에 대해 분산 trace 구성을 재정의합니다.

curl -s -H "$TOKEN" \
     'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/ENV_NAME/traceConfig/overrides' \
     -X POST \
     -H "content-type:application/json" \
     -d '{"apiProxy": "hello-world","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.1}}'

모든 API 프록시의 구성을 변경할 필요 없이 API 프록시 관련 문제를 해결하도록 구성을 재정의할 수 있습니다.

trace 설정 재정의 업데이트

API 프록시나 API 프록시 그룹의 추적 구성 재정의를 삭제하려면 다음 단계를 수행합니다.

1. 다음 명령어를 사용하여 추적 구성의 기존 재정의를 검색합니다.

   curl -s -H "$TOKEN" \
       'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
       -X GET 

   이 명령어는 재정의를 통해 적용되는 프록시를 식별하는 '이름' 필드가 포함된 다음과 같은 응답을 반환합니다.

   {
     "traceConfigOverrides": [
       {
         "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
         "apiProxy": "proxy1",
         "samplingConfig": {
           "sampler": "PROBABILITY",
           "samplingRate": 0.25
         }
       }
     ]
   }

2. 프록시를 업데이트하려면 '이름' 필드의 값을 사용하여 업데이트된 필드 값과 함께 해당 프록시의 재정의 구성에 POST 요청을 전송합니다. 예를 들면 다음과 같습니다.

   curl -s -H "$TOKEN" \
       'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
       -X POST \
       -H "content-type:application/json" \
       -d '{"apiProxy": "proxy1","samplingConfig": {"sampler": "PROBABILITY","samplingRate": 0.05}}'

trace 설정 재정의 삭제

API 프록시 또는 API 프록시 그룹의 추적 구성 재정의를 삭제하려면 다음 단계를 수행합니다.

1. 다음 명령어를 사용하여 추적 구성의 기존 재정의를 검색합니다.

   curl -s -H "$TOKEN" \
       'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides' \
       -X GET 

   이 명령어는 재정의를 통해 적용되는 프록시를 식별하는 '이름' 필드가 포함된 다음과 같은 응답을 반환합니다.

   {
     "traceConfigOverrides": [
       {
         "name": "dc8437ea-4faa-4b57-a14f-4b8d3a15fec1",
         "apiProxy": "proxy1",
         "samplingConfig": {
           "sampler": "PROBABILITY",
           "samplingRate": 0.25
         }
       }
     ]
   }

2. 프록시를 삭제하려면 '이름' 필드의 값을 사용하여 업데이트된 필드 값과 함께 해당 프록시의 재정의 구성에 DELETE 요청을 전송합니다. 예를 들면 다음과 같습니다.

   curl -s -H "$TOKEN" \
       'https://apigee.googleapis.com/v1/organizations/$PROJECT_ID/environments/$ENV_NAME/traceConfig/overrides/dc8437ea-4faa-4b57-a14f-4b8d3a15fec1' \
       -X DELETE \

성능에 대한 고려사항

Apigee 런타임 환경에 분산 추적을 사용 설정하면 성능에 영향을 미칠 수 있습니다. 이로 인해 메모리 사용량이 늘고 CPU 요구사항이 증가하며 지연 시간이 늘어날 수 있습니다. 영향의 정도는 API 프록시의 복잡성(예: 정책 수) 및 확률적 샘플링 레이트(samplingRate로 설정)에 따라 부분적으로 달라집니다. 샘플링 레이트가 높을수록 성능에 많은 영향을 미칩니다. 성능에 미치는 영향은 다양한 요인에 따라 달라지지만 분산 추적을 사용할 경우 10~20%의 성능 저하를 예상할 수 있습니다.

높은 트래픽 및 낮은 지연 시간이 요구되는 환경에서 권장되는 확률적 샘플링 레이트는 10% 이하입니다. 분산 추적을 사용하여 문제를 해결하려면 특정 API 프록시의 확률 샘플링(samplingRate)만 늘리는 것이 좋습니다.