MessageLogging 정책

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

내용

API 런타임 환경에서 문제를 추적하는 가장 좋은 방법 중 하나는 메시지를 로깅하는 것입니다. API에서 MessageLogging 정책을 연결하고 구성하여 로컬 디스크 (Private Cloud용 Edge만 해당) 또는 syslog에 커스텀 메시지를 로깅할 수 있습니다.

샘플

<MessageLogging name="LogToSyslog">
  <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>514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <DateFormat>yyyy-MM-dd'T'HH:mm:ss.SSSZ</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

<MessageLogging name="LogToSyslog">
  <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>
    <DateFormat>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
      <FileName>test.log</FileName>
      <FileRotationOptions rotateFileOnStartup="true">
        <FileRotationType>SIZE</FileRotationType>
        <MaxFileSizeInMB>10</MaxFileSizeInMB>
        <MaxFilesToRetain>10</MaxFilesToRetain>
      </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME</FileRotationType>
      <RotationFrequency unit="minute">10</RotationFrequency>
      <MaxFilesToRetain>10</MaxFilesToRetain>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
    <Message>This is a test message. Message id : {request.header.messageid}</Message>
    <FileName>test.log</FileName>
    <FileRotationOptions rotateFileOnStartup="true">
      <FileRotationType>TIME_SIZE</FileRotationType>
      <MaxFileSizeInMB>10</MaxFileSizeInMB>
      <MaxFilesToRetain>10</MaxFilesToRetain>
      <RotationFrequency unit="minute">10</RotationFrequency>
    </FileRotationOptions>
  </File>
  <logLevel>ERROR</logLevel>
</MessageLogging>

<MessageLogging name="LogPolicy">
  <File>
  ....
  ....
  </File>
  <BufferMessage>true</BufferMessage>
</MessageLogging>

요소 참조

다음 요소를 사용하여 MessageLogging 정책 유형을 구성합니다.

<SSLInfo>
    <Enabled>true</Enabled>
</SSLInfo>

스키마

사용 참고사항

MessageLogging 정책을 API 프록시 흐름에 연결할 때 PostClientFlow라는 특수 흐름의 ProxyEndpoint 응답에 이를 배치하는 것이 좋습니다. PostClientFlow는 응답이 요청 클라이언트로 전송된 후에 실행되어 모든 측정항목을 로깅에 사용할 수 있습니다. PostClientFlow 사용에 대한 자세한 내용은 API 프록시 구성 참조를 참고하세요.

PostClientFlow는 다음 두 가지 측면에서 특수합니다.

1. 응답 흐름의 일부로만 실행됩니다.
2. 프록시가 오류 상태로 전환된 후 실행되는 유일한 흐름입니다.

프록시 성공 여부와 관계없이 실행되므로 PostClientFlow에 Message Logging 정책을 적용하고 항상 실행되도록 보장할 수 있습니다.

다음 Trace 이미지는 DefaultFaultRule이 실행된 후 PostClientFlow의 일부로 실행되는 MessageLogging 정책을 보여줍니다.

이 예시에서는 잘못된 키로 인해 API 키 인증 정책에서 오류가 발생했습니다.

다음은 PostClientFlow를 포함하는 ProxyEndpoint 정의입니다.

<ProxyEndpoint name="default">
  ...
  <PostClientFlow>
    <Response>
      <Step>
        <Name>Message-Logging-1</Name>
      </Step>
    </Response>
  </PostClientFlow>
  ...
</ProxyEndpoint>

Edge는 메시지를 간단한 텍스트로 로깅하며, 사용자는 요청이나 응답이 수신된 날짜 및 시간, 요청의 사용자 ID, 요청이 전송된 소스 IP 주소 등의 변수를 포함하도록 로깅을 구성할 수 있습니다. Edge는 메시지를 비동기식으로 로깅합니다. 즉, 차단 콜아웃으로 인해 발생할 수 있는 지연 시간이 API에 도입되지 않습니다.

MessageLogging 정책은 메모리의 로깅된 메시지를 버퍼에 기록합니다. 메시지 로거는 버퍼에서 메시지를 읽은 다음 구성할 대상에 기록합니다. 각 대상에는 자체 버퍼가 있습니다.

버퍼의 쓰기 속도가 읽기 속도보다 빠르면 버퍼가 오버플로되고 로깅이 실패합니다. 이 경우 로그 파일에 다음 요소가 포함된 메시지가 표시될 수 있습니다.

Log message size exceeded. Increase the max message size setting

Edge for Private Cloud 4.15.07 이하에서 이 문제가 발생하면 message-logging.properties 파일을 찾아 다음 솔루션을 사용합니다.

message-logging.properties 파일에서 max.log.message.size.in.kb 속성(기본값 = 128KB)을 늘립니다.

Edge for Private Cloud 4.16.01 이상의 경우 /opt/apigee/customer/application/message-processor.properties 파일에서 conf_message-logging_max.log.message.size.in.kb 속성을 설정하고 메시지 프로세서를 다시 시작합니다.

참고: Edge의 응답 메시지 변수는 오류 흐름에서 사용할 수 없습니다. 또한 이전 흐름이 오류 흐름인 경우 PostClientFlow에서 이러한 변수를 사용할 수 없습니다. PostClientFlow의 응답 정보를 로깅하려면 message 객체를 사용합니다. 오류가 있는지 여부에 관계없이 이 객체를 사용하여 응답의 헤더 및 기타 정보를 가져올 수 있습니다. 자세한 내용과 예는 메시지 변수를 참조하세요.

Private Cloud용 에지에서 로그 메시지 타임스탬프 제어

기본적으로 모든 로그 메시지의 타임스탬프는 다음과 같은 형식입니다.

yyyy-MM-dd'T'HH:mm:ss.SSSZ

이 시스템 전체 기본값은 DateFormat 요소를 사용하여 syslog 대상에 대해 재정의할 수 있습니다. 이 템플릿의 동작은 Java의 SimpleDateFormat 클래스 문서에 설명되어 있습니다. 이 정의에 따라 yyyy는 4자리 연도로, MM는 2자리 월 번호로 대체됩니다. 위의 형식을 사용하면 다음 형식의 문자열이 생성될 수 있습니다.

2022-09-28T22:38:11.721+0000

에지 메시지 프로세서의 conf_system_apigee.syslogger.dateFormat 속성을 사용하여 해당 형식을 제어할 수 있습니다. 예를 들어 메시지 형식을 다음과 같이 변경합니다.

yy/MM/dd'T'HH:mm:ss.SSSZ

대시를 슬래시로 대체하고 2자리 연도로 줄여 다음 형식으로 타임스탬프를 기록합니다.

22/09/28T22:38:11.721+0000

형식을 변경하려면 다음 단계를 따르세요.

1. 편집기에서 message-processor.properties 파일을 엽니다. 파일이 존재하지 않으면 만듭니다.
   > vi /opt/apigee/customer/application/message-processor.properties
2. 원하는 대로 속성을 설정합니다.
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. 변경사항을 저장합니다.
4. 속성 파일을 'apigee' 사용자가 소유해야 합니다.
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. 에지 메시지 프로세서를 다시 시작합니다.
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor restart

Private Cloud용 Edge의 로그 파일 위치

Private Cloud용 Edge 4.16.01 이상

기본적으로 프라이빗 클라우드 메시지 로그는 메시지 프로세서 노드의 다음 디렉터리에 있습니다.

/opt/apigee/var/log/edge-message-processor/messagelogging/org_name/environment/api_proxy_name/revision/logging_policy_name/

메시지 프로세서의 message-logging.properties 파일에 있는 속성을 수정하여 기본 로그 위치를 변경할 수 있습니다.

• bin_setenv_data_dir - 로그 파일 저장소의 루트 경로를 설정합니다. 예를 들면 bin_setenv_data_dir=/opt/apigee/var/log입니다.
• conf_message-logging_log.root.dir - conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.와 같은 상대 경로로 설정하는 경우
  
  
  이 값을 절대 경로(예: conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages)로 설정하면 메시지 로그가 /opt/apigee/var/log/messages/messagelog/에 저장됩니다. 절대 경로는 bin_setenv_data_dir보다 우선합니다.
  
  이 속성은 기본적으로 주석 처리되므로 conf/message-logging.properties+log.root.dir로 참조해야 합니다. 자세한 내용은 현재 주석 처리된 토큰 설정을 참조하세요.

모든 로그 파일이 동일한 디렉터리에 배치되도록 로그 파일을 플랫 파일 구조에 저장하려면 message-logging.properties 파일에서 conf/message-logging.properties+enable.flat.directory.structure를 true로 설정하세요. 메시지는 위의 속성으로 지정된 디렉터리에 저장되며 파일 이름은 {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename} 형식을 취합니다.

이러한 속성을 설정하는 방법은 다음과 같습니다.

1. 편집기에서 message-processor.properties 파일을 엽니다. 파일이 존재하지 않으면 만듭니다.
   > vi /opt/apigee/customer/application/message-processor.properties
2. 원하는 대로 속성을 설정합니다.
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. 변경사항을 저장합니다.
4. 속성 파일을 'apigee' 사용자가 소유해야 합니다.
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Edge 구성요소를 다시 시작합니다.
   > /opt/apigee/apigee-service/bin/apigee-serviceedge-message-processor restart

Private Cloud용 Edge 4.15.07 이하

기본적으로 메시지 로그는 메시지 프로세서의 다음 위치에 있습니다.

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

메시지 프로세서의 message-logging.properties 파일에서 다음 속성을 수정하여 기본 로그 위치를 변경할 수 있습니다.

• data.dir - 로그 파일 저장소의 루트 경로를 설정합니다. 예: data.dir=/opt/apigee4/var/log
• log.root.dir - 이를 log.root.dir=custom/folder/와 같은 상대 경로로 설정하면 경로가 data.dir 위치에 추가됩니다.

예를 들어 두 속성의 조합은 로깅 디렉터리를 /opt/apigee4/var/log/custom/folder/messagelog/에 설정합니다(/messagelog는 자동으로 추가됨).

이 값을 절대 경로(예: log.root.dir=/opt/apigee4/var/log/messages)로 설정하면 메시지 로그가 /opt/apigee4/var/log/messages/messagelog/에 저장됩니다. log.root.dir의 절대 경로가 data.dir보다 우선합니다.

로그 파일을 플랫 파일 구조로 저장하여 모든 로그 파일이 동일한 디렉터리에 배치되도록 하려면 메시지 프로세서의 message-logging.properties 파일에서 enable.flat.directory.structure 속성을 true로 설정하세요. 메시지는 위의 속성으로 지정된 디렉터리에 저장되며, 파일 이름은 {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}의 형식을 취합니다.

메시지 템플릿의 변수 기본값

메시지 템플릿의 각 변수에 기본값을 별도로 지정할 수 있습니다. 예를 들어 request.header.id 변수를 확인할 수 없는 경우 해당 값이 unknown 값으로 바뀝니다.

<Message>This is a test message. id = {request.header.id:unknown}</Message>

Message 요소에서 defaultVariableValue 속성을 설정하여 모든 확인되지 않은 변수에 공통 기본값을 지정할 수 있습니다.

<Message defaultVariableValue="unknown">This is a test message. id = {request.header.id}</Message>

제3자 로그 관리 서비스 구성

MessageLogging 정책을 사용하여 syslog 메시지를 Splunk, Sumo Logic, Loggly와 같은 제3자 로그 관리 서비스에 보낼 수 있습니다. 이러한 서비스 중 하나로 syslog를 전송하려면 서비스의 문서를 참조하여 서비스의 호스트, 포트, 프로토콜을 구성한 다음 이 정책에 따라 Syslog 요소를 설정하세요.

제3자 로그 관리 구성은 다음 문서를 참조하세요.

• Splunk(제품 버전 선택)
  또한 이 Apigee 커뮤니티 게시물을 참조하세요(https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html).
• Sumo 로직
  • 이 Apigee 커뮤니티 게시물도 참조하세요. https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • Sumo Logic을 로깅 서비스로 사용하는 전체 예시는 다음 Apigee 커뮤니티 게시물을 참조하세요. 이 솔루션은 단일 자바스크립트 정책을 사용하여 Sumo Logic HTTP Source Collector에 HTTP POST 요청을 수행합니다. https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  Loggly를 사용할 때는 정책에 <Syslog> 요소의 하위 요소로 <FormatMessage>true</FormatMessage>가 필요합니다.
  또한 Loggly 메시지 로깅에 대한 자세한 내용은 Apigee 커뮤니티 게시물(https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html)을 참조하세요.

오류 참조

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

런타임 오류

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

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

오류 응답 예시

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

오류 규칙 예시

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>

흐름 변수

정책 실패 시 다음 변수가 채워집니다.

• messagelogging.failed
• messagelogging.{stepdefinition-name}.failed

관련 주제

• Edge에서 노출된 변수: 변수 참조