Apigee 및 Apigee Hybrid 문서입니다.
Apigee Edge 문서 보기
Apigee의 MessageLogging 정책을 통해 API 프록시 개발자는 커스텀 메시지를 Cloud Logging 또는 syslog 엔드포인트에 로깅할 수 있습니다. 입력 매개변수, 요청 페이로드, 응답 코드, 오류 메시지(있는 경우) 등 API 요청과 관련된 중요한 정보는 추후 참조용으로 또는 디버깅을 위해 로깅할 수 있습니다. 정책은 백그라운드 프로세스를 사용하여 로깅을 수행하지만 정책 사용에 대한 주의사항이 있습니다.
안티패턴
MessageLogging 정책은 API 요청에 대한 자세한 정보를 얻고 API 요청에서 발생하는 문제를 디버깅하는 효율적인 방법을 제공합니다. 그러나 동일한 MessageLogging 정책을 두 번 이상 사용하거나 PostClientFlow 이외의 흐름에서 동일한 API 프록시의 청크에 여러 MessageLogging 정책이 데이터를 로그하면 부정적인 영향을 미칠 수 있습니다. 이는 Apigee에서 MessageLogging 정책용 외부 엔드포인트에 대한 연결을 열기 때문입니다. 정책에서 TCP를 통해 TLS를 사용하는 경우 syslog 엔드포인트와 마찬가지로 TLS 연결을 설정하는 추가 오버헤드가 있습니다.
API 프록시 예시의 도움을 받아 설명해 봅시다.
API 프록시
다음 예시에서는 'LogRequestInfo'라는 MessageLogging 정책이 요청 흐름에 배치되고 'LogResponseInfo'라는 다른 MessageLogging 정책이 응답 흐름에 추가됩니다. 둘 다 ProxyEndpoint PreFlow에 있습니다. LogRequestInfo 정책은 API 프록시가 요청을 받는 즉시 백그라운드에서 실행되며 LogResponseInfo 정책은 프록시가 대상 서버로부터 응답을 받은 후, 그러나 프록시가 API 클라이언트에 응답을 반환하기 전에 실행됩니다. 2개의 TLS 연결이 잠재적으로 설정되므로 이 작업은 추가 시스템 리소스가 소비됩니다.
또한 API 프록시 실행 중에 오류가 발생한 경우에만 실행되는 'LogErrorInfo'라는 MessageLogging 정책이 있습니다.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ProxyEndpoint name="default"> ... <FaultRules> <FaultRule name="fault-logging"> <Step> <Name>LogErrorInfo</Name> </Step> </FaultRule> </FaultRules> <PreFlow name="PreFlow"> <Request> <Step> <Name>LogRequestInfo</Name> </Step> </Request> </PreFlow> <PreFlow name="PreFlow"> <Response> <Step> <Name>LogResponseInfo</Name> </Step> </Response> </PreFlow> ... </ProxyEndpoint>
메시지 로깅 정책
다음 정책 구성 예시에서는 데이터가 TCP를 통한 TLS를 사용하여 타사 로그 서버에 로깅됩니다. 동일한 API 프록시에서 이러한 정책 중 둘 이상이 사용되는 경우 TLS 연결 설정 및 관리 오버헤드에 추가 시스템 메모리 및 CPU 주기가 적용되어 대규모 성능 문제가 발생할 수 있습니다. MessageLogging을 사용하여 Cloud Logging 엔드포인트에 로깅하는 경우에도 유사한 부정적인 효과가 발생합니다.
LogRequestInfo 정책
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <MessageLogging name="LogRequestInfo"> <Syslog> <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {request.queryparam.w}.</Message> <Host>logs-01.loggly.com</Host> <Port>6514</Port> <Protocol>TCP</Protocol> <FormatMessage>true</FormatMessage> <SSLInfo> <Enabled>true</Enabled> </SSLInfo> </Syslog> <logLevel>INFO</logLevel> </MessageLogging>
LogResponseInfo 정책
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <MessageLogging name="LogResponseInfo"> <Syslog> <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Status: {response.status.code}, Response {response.content}.</Message> <Host>logs-01.loggly.com</Host> <Port>6514</Port> <Protocol>TCP</Protocol> <FormatMessage>true</FormatMessage> <SSLInfo> <Enabled>true</Enabled> </SSLInfo> </Syslog> <logLevel>INFO</logLevel> </MessageLogging>
LogErrorInfo 정책
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <MessageLogging name="LogErrorInfo"> <Syslog> <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Fault name: {fault.name}.</Message> <Host>logs-01.loggly.com</Host> <Port>6514</Port> <Protocol>TCP</Protocol> <FormatMessage>true</FormatMessage> <SSLInfo> <Enabled>true</Enabled> </SSLInfo> </Syslog> <logLevel>ERROR</logLevel> </MessageLogging>
영향
- API 프록시 흐름 중에 로그 엔드포인트에 연결을 여러 번 설정하여 네트워킹 오버헤드가 증가합니다.
- 시스템로그 서버가 느리거나 여러 syslog 호출로 인해 발생하는 대용량 작업을 처리할 수 없으면 메시지 프로세서의 압력이 가중되어 요청 처리가 느려져서 시간이 많이 지연되거나 504 게이트웨이 시간 초과 오류가 발생할 수 있습니다.
MessageLogging 정책이 PostClient 흐름 이외의 다른 흐름에 배치된 경우 이 정책을 실행하기 전에 오류가 발생하면 MessageLogging 정책이 실행되지 않으므로 정보가 로깅되지 않을 수 있습니다.
앞의 ProxyEndpoint 예시에서는 다음 상황에서 정보가 로깅되지 않습니다.
- 요청 흐름의 LogRequestInfo 정책보다 먼저 배치된 정책이 실패하는 경우
또는 - 대상 서버가 오류와 함께 실패한 경우(HTTP 4XX, 5XX). 이 경우 성공적인 응답이 반환되지 않으면 LogResponseInfo 정책이 실행되지 않습니다.
두 경우 모두 LogErrorInfo 정책이 실행되고 오류 관련 정보만 로깅됩니다.
- 요청 흐름의 LogRequestInfo 정책보다 먼저 배치된 정책이 실패하는 경우
권장사항
- 프록시 흐름 내에서 ExtractVariables 정책 또는 JavaScript 정책의 인스턴스 하나 이상을 사용하여 로깅할 모든 흐름 변수를 컨텍스트 변수로 설정합니다. 이렇게 하면 나중에 실행되는 MessageLogging 정책에서 사용할 수 있습니다.
- 단일 MessageLogging 정책을 사용하여 무조건 실행되는 PostClientFlow에서 필요한 모든 데이터를 로깅합니다.
- syslog를 사용하는 경우 시스템로그 서버에 메시지를 전달할 필요가 없고 TLS/SSL이 필수가 아닌 경우 UDP 프로토콜을 사용합니다.
MessageLogging 정책은 오류 처리를 포함하여 실제 API 기능과 분리되도록 설계되었습니다. 따라서 요청/응답 처리의 외부에 있는 PostClientFlow에서 호출해도 API의 성공 여부에 관계없이 항상 데이터가 로깅됩니다.
다음은 PostClientFlow에서 MessageLogging 정책을 호출하는 예시입니다.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> ... <PostClientFlow> <Request/> <Response> <Step> <Name>LogInfo</Name> </Step> </Response> </PostClientFlow> ...
다음은 모든 데이터를 로깅하는 MessageLogging 정책인 LogInfo의 예시입니다.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <MessageLogging name="LogInfo"> <Syslog> <Message>[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {woeid} Status: {weather.response.code}, Response {weather.response}, Fault: {fault.name:None}.</Message> <Host>logs-01.loggly.com</Host> <Port>6514</Port> <Protocol>TCP</Protocol> <FormatMessage>true</FormatMessage> <SSLInfo> <Enabled>true</Enabled> </SSLInfo> </Syslog> <logLevel>INFO</logLevel> </MessageLogging>
응답 변수는 오류 흐름 이후의 PostClientFlow에서 사용할 수 없으므로 ExtractVariables 또는 자바스크립트 정책을 사용하여 woeid
및 weather.response*
변수를 명시적으로 설정하는 것이 중요합니다.
추가 자료
- 자바스크립트 정책
- ExtractVariables 정책
- PostClientFlow를 사용하여 오류가 발생한 경우를 포함해 프록시 처리 후 코드 실행