MessageLogging 정책

<ph type="x-smartling-placeholder"></ph> 현재 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 로그 메시지 비동기식으로 작동합니다. 즉, 차단 콜아웃으로 인해 발생할 수 있는 지연 시간이 발생하지 않습니다. 추가할 수 있습니다

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

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

Log message size exceeded. Increase the max message size setting

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

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

Private Cloud용 Edge 4.16.01 이상의 경우 /opt/apigee/customer/application/message-processor.properties 파일에서 conf/message-logging.properties+max. log.message.size.in.kb 속성을 설정하고 메시지 프로세서를 다시 시작하세요. 이 속성은 처음에는 기본적으로 주석 처리됩니다.

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

로그 메시지 제어 프라이빗 클라우드용 에지의 타임스탬프

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

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

이러한 시스템 전체 기본값은 다음을 사용하여 syslog 대상에 대해 재정의할 수 있습니다. DateFormat 요소 이 템플릿의 동작은 Java의 SimpleDateFormat 클래스에 대한 문서를 참조하세요. 이 정의에 따라 yyyy이(가) 대체됩니다. 4자리 연도가 있는 경우 MM는 두 자리 숫자 월 번호로 대체됩니다. 위 형식에서는 다음과 같은 문자열이 생성될 수 있습니다.

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 파일을 엽니다. 있습니다 파일이 존재하지 않으면 다음과 같이 만듭니다.
   &gt; 베트남어 /opt/apigee/customer/application/message-processor.properties
2. 속성을 원하는 대로 설정합니다.
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd&#39;T&#39;HH:mm:ss.SSSZ
3. 변경사항을 저장합니다.
4. 속성 파일이 'Apigee'의 소유인지 확인하세요. 사용자:
   &gt; chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. 다음과 같이 에지 메시지 프로세서를 다시 시작합니다.
   &gt; /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor 재시작

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로 참조해야 한다는 점에 유의하세요. 기본적으로 주석 처리됩니다. 자세한 내용은 토큰을 제공합니다.

로그 파일을 플랫 파일 구조로 저장하여 모든 로그 파일이 동일한 디렉터리에서 conf/message-logging.properties+enable.flat.directory.structure를 설정하면 됩니다. true를 반환합니다. 메일은 파일 이름은 {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}

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

1. message-processor.properties 파일을 엽니다. 있습니다 파일이 존재하지 않으면 다음과 같이 만듭니다.
   &gt; 베트남어 /opt/apigee/customer/application/message-processor.properties
2. 속성을 원하는 대로 설정합니다.
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. 변경사항을 저장합니다.
4. 속성 파일이 'Apigee'의 소유인지 확인하세요. 사용자:
   &gt; chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Edge 구성요소를 다시 시작합니다.
   &gt; /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor 재시작

Private Cloud 4.15.07 이하용 Edge

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

/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보다 우선합니다.

로그 파일을 플랫 파일 구조로 저장하여 모든 로그 파일이 동일한 디렉터리에서 enable.flat.directory.structure 속성을 Message의 message-logging.properties 파일에서 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 Logic
  • 이 Apigee 커뮤니티 게시물도 참조하세요. https://community.apigee.com/questions/5226/setting-up-logging-with-sumo-logic-which-host-shou.html
  • Sumo Logic을 로깅 서비스로 사용하는 전체 예시는 다음 Apigee 커뮤니티 게시물을 참조하세요. 이 솔루션은 단일 JavaScript 정책을 사용하여 HTTP POST를 수행합니다. Sumo Logic HTTP Source Collector에 대한 요청: 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에서 노출된 변수: 변수 참조