TraceCapture 정책

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

Apigee Edge 문서 보기

미리보기

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

개요

TraceCapture 정책을 사용하면 Apigee 런타임의 trace 데이터에 추가 변수를 추가할 수 있습니다. Apigee 런타임에 대해 분산 trace를 사용 설정했으면 기본적으로 런타임이 사전 정의된 변수 집합을 trace합니다. 자세한 내용은 trace 보고서의 기본 trace 변수를 참조하세요. 하지만 Apigee 런타임이 추가 흐름, 정책, 커스텀 변수를 trace하도록 하려면 TraceCapture 정책을 사용합니다. 이 정책은 요청 또는 응답 흐름에서 사용할 수 있습니다. 분산 추적 보고서에서는 TraceCaptureExecution 스팬에서 TraceCapture 정책으로 추가된 변수를 볼 수 있습니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

<TraceCapture>

TraceCapture 정책을 정의합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	복합 유형
상위 요소	해당 사항 없음
하위 요소	<DisplayName> <IgnoreUnresolvedVariables> <ThrowExceptionOnLimit> <Variables>

<TraceCapture> 요소는 다음 구문을 사용합니다.

구문

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
    <Variables>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
        <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>
</TraceCapture>

예시

다음 예시는 TraceCapture 정책 정의를 보여줍니다.

<?xml version="1.0" encoding="UTF-8"?>
<TraceCapture continueOnError="true" enabled="true" name="DistributedTraceCapture-1">
    <DisplayName>Distributed-Trace-Capture-Policy-1</DisplayName>
    <Variables>
        <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
        <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
    </Variables>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>
</TraceCapture>

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

속성	기본	필수 여부	설명
name	해당 없음	필수	정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.
continueOnError	false	선택	정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조: 오류 규칙이 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 정책 오류 처리
enabled	true	선택	정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
async	false	지원 중단됨	이 속성은 지원이 중단되었습니다.

다음 표에서는 <TraceCapture>의 하위 요소를 간략하게 설명합니다.

하위 요소	필수 여부	설명
<DisplayName>	선택사항	정책의 커스텀 이름을 지정합니다.
<Variables>	선택사항	trace할 변수 목록을 지정합니다.
<IgnoreUnresolvedVariables>	선택사항	해결되지 않은 변수가 발생하면 처리를 중지할지 여부를 지정합니다.
<ThrowExceptionOnLimit>	선택사항	변수 크기가 256바이트 한도를 초과할 경우 변수를 잘라야 하는지 여부를 지정합니다.
기타 하위 요소
<MergeBehavior>	선택사항	응답 메시지의 병합 동작을 지정합니다.

하위 요소 참조

이 섹션에서는 <TraceCapture>의 하위 요소를 설명합니다.

<DisplayName>

name 속성 외에 이 요소를 사용하여 관리 UI 프록시 편집기에서 자연스러운 다른 이름으로 정책의 라벨을 지정합니다.

<DisplayName> 요소는 모든 정책에 공통으로 적용됩니다.

기본값	해당 사항 없음
필수 여부	선택사항. <DisplayName>을 생략하면 정책의 name 속성 값이 사용됩니다.
유형	문자열
상위 요소	<PolicyElement>
하위 요소	없음

<DisplayName> 요소는 다음 구문을 사용합니다.

구문

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

예시

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 요소에 속성 또는 하위 요소가 없습니다.

<Variables>

trace할 변수 목록을 지정합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	복합 유형
상위 요소	<TraceCapture>
하위 요소	<Variable>

<Variables> 요소는 다음 구문을 사용합니다.

구문

<Variables>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
    <Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>
</Variables>

예시

다음 예시는 flow-variable-1 및 flow-variable-2 흐름 변수를 trace합니다.

<Variables>
    <Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>
    <Variable name="trace-variable-2" ref="flow-variable-2">default-val-2</Variable>
</Variables>

참고:

• private 및 policy.secret 변수는 trace할 수 없습니다.
• Apigee에서는 Cloud Trace의 15 변수 최댓값과 Jaegar의 25 변수 최댓값을 구성하도록 권장합니다.

<Variable>

trace 데이터에 추가할 변수를 지정합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	복합 유형
상위 요소	<Variables>
하위 요소	없음

<Variable> 요소는 다음 구문을 사용합니다.

구문

<Variable name="TRACE_VARIABLE_NAME" ref="FLOW_VARIABLE_NAME">DEFAULT_VALUE</Variable>

예시

다음 예시에서는 trace-variable-1 trace 변수를 flow-variable-1 흐름 변수의 값으로 설정합니다.

<Variable name="trace-variable-1" ref="flow-variable-1">default-val-1</Variable>

flow-variable-1 흐름 변수를 사용할 수 없으면 trace-variable-1이 기본값 default-val-1로 설정됩니다.

다음 표는 <Variable>의 속성을 설명합니다.

속성	필수 여부	유형	설명
name	필수	문자열	지정된 변수에 대해 수집되는 데이터를 참조하는 이름입니다. 이 이름은 분산 trace 보고서에 표시됩니다.
ref	필수	문자열	trace 데이터를 수집할 변수입니다. 이 변수는 Apigee에서 사전 정의된 흐름 변수 또는 API 프록시의 커스텀 변수일 수 있습니다.

참고: 변수에 대해 선택적인 기본값을 지정할 수 있습니다. ref에 지정된 변수가 요청 또는 응답에 정의되지 않은 경우 trace 데이터에 해당 변수의 기본값이 포함됩니다.

<IgnoreUnresolvedVariables>

해결되지 않은 변수가 발생하면 처리를 중지할지 여부를 결정합니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	부울
상위 요소	<TraceCapture>
하위 요소	없음

확인되지 않은 변수를 무시하고 계속 처리하려면 true로 설정합니다. 그렇지 않으면 false로 설정합니다. 기본값은 true입니다.

<IgnoreUnresolvedVariables>를 true로 설정하는 것은 <TraceCapture>의 continueOnError를 true로 설정하는 것과 다릅니다. continueOnError를 true로 설정하면 Apigee가 모든 오류를 무시하지만 변수의 오류를 무시하지 않습니다.

<IgnoreUnresolvedVariables> 요소는 다음 구문을 사용합니다.

구문

<IgnoreUnresolvedVariables>BOOLEAN_VALUE</IgnoreUnresolvedVariables>

예시

다음 예시에서는 <IgnoreUnresolvedVariables>를 false로 설정합니다.

<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>

참고: 요소의 기본값은 false입니다.

<ThrowExceptionOnLimit>

변수 크기가 256바이트 한도를 초과할 경우의 정책 동작을 지정합니다.

• true로 설정되었으면 변수 크기가 한도를 초과할 때 정책이 오류를 발생시킵니다.
• false로 설정되었으면 정책이 한도를 초과하는 변수를 자릅니다. 변수는 해당 한도 크기로 잘립니다.

참고: 요소의 기본값은 false입니다.

기본값	해당 사항 없음
필수 여부	선택사항
유형	부울
상위 요소	<TraceCapture>
하위 요소	없음

<ThrowExceptionOnLimit> 요소는 다음 구문을 사용합니다.

구문

<ThrowExceptionOnLimit>BOOLEAN_VALUE</ThrowExceptionOnLimit>

예시

다음 예시에서는 <ThrowExceptionOnLimit> 값을 true로 설정합니다.

<ThrowExceptionOnLimit>false</ThrowExceptionOnLimit>

오류 코드

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드	HTTP 상태	원인
steps.tracecapture.UnresolvedVariable	500	이 오류는 TraceCapture 정책에 지정된 변수가 다음 중 하나인 경우에 발생합니다. 범위를 벗어난 경우(정책이 실행 중인 특정 흐름에서 사용할 수 없음) 또는 확인할 수 없는 경우(정의되지 않음)
steps.tracecapture.VariableValueLimitExceeded	500	<ThrowExceptionOnLimit> 요소가 true로 설정되었고 변수 크기가 256바이트를 초과하면 이 오류가 발생합니다.

오류 변수

정책에 실행 오류가 발생할 때마다 Apigee는 오류 메시지를 생성합니다. 오류 응답에서 이러한 오류 메시지를 볼 수 있습니다. 시스템에서 생성된 오류 메시지가 제품의 컨텍스트와 관련이 없을 경우가 많습니다. 메시지를 보다 의미 있게 만들기 위해 오류 유형에 따라 오류 메시지를 맞춤설정할 수 있습니다.

오류 메시지를 맞춤설정하려면 오류 규칙 또는 RaiseFault 정책을 사용하면 됩니다. 오류 규칙과 RaiseFault 정책의 차이점에 대한 자세한 내용은 FaultRules와 RaiseFault 정책 비교를 참조하세요. 오류 규칙과 RaiseFault 정책 모두에서 Condition 요소를 사용하여 조건을 확인해야 합니다. Apigee는 각 정책에 고유한 오류 변수를 제공하며 정책이 런타임 오류를 트리거할 때 오류 변수 값이 설정됩니다. 이러한 변수를 사용하여 특정 오류 조건을 확인하고 적절한 조치를 취할 수 있습니다. 오류 조건 확인에 대한 자세한 내용은 빌드 조건을 참조하세요.

다음 표에서는 이 정책과 관련된 오류 변수를 설명합니다.

변수	각 항목의 의미는 다음과 같습니다.	예
fault.name	fault.name은 런타임 오류 표에 나열된 오류 중 하나와 일치할 수 있습니다. 오류 이름은 오류 코드의 마지막 부분입니다.	fault.name Matches "UnresolvedVariable"
tracecapture.POLICY_NAME.failed	POLICY_NAME은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	tracecapture.trace-capture-1.failed = true

정책 오류에 대한 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.