MessageLogging 정책

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

Apigee Edge 문서 보기

정책 아이콘

제목

MessageLogging 정책을 사용하여 커스텀 메시지를 Cloud Logging 또는 syslog에 로깅할 수 있습니다. 로그의 정보를 API 런타임 환경에서 문제 추적과 같은 다양한 태스크에 사용할 수 있습니다.

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

MessageLogging 정책을 사용하는 방법은 두 가지입니다.

  • <CloudLogging> 요소는 메시지를 Cloud Logging에 로깅합니다. 이 방법을 사용하려면 Google Cloud 프로젝트에 Cloud Logging API를 사용 설정해야 합니다. Google Cloud 프로젝트에 API를 사용 설정하는 방법에 대한 자세한 내용은 서비스 사용 설정 및 중지를 참조하세요.
  • <Syslog> 요소는 시스템 로그 또는 이벤트 메시지를 특정 서버로 전송하기 위한 표준 프로토콜인 syslog에 메시지를 로깅합니다. 이 방법을 사용하려면 시스템로그 서버가 있어야 합니다. 없는 경우 Splunk, Sumo Logic, Loggly와 같은 공개 로그 관리 서비스를 사용할 수 있습니다. 제3자 로그 관리 서비스 구성을 참조하세요.

참고: 동일한 정책에서 <CloudLogging> 요소와 <Syslog> 요소를 모두 사용할 수는 없습니다.

<MessageLogging> 요소

<MessageLogging> 정책을 정의합니다.

기본값 아래의 기본 정책 탭을 참조하세요.
필수 여부 필수
유형 유형
상위 요소 해당 사항 없음
하위 요소 <CloudLogging>
<Syslog>
<logLevel>

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MessageLogging continueOnError="false" enabled="true" name="Message-Logging-1">
    <DisplayName>Message Logging-1</DisplayName>
    <Syslog>
<!-- Note: You cannot use both the <Syslog> element and the <CloudLogging> element in the same policy. -->
        <Message>Some message for syslog</Message>
        <Host>localhost</Host>
        <Port>514</Port>
    </Syslog>
    <CloudLogging>
<!-- Note: You cannot use both the <CloudLogging> and the <Syslog> element in the same policy. -->
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>gce_instance</ResourceType>
    </CloudLogging>
    <logLevel>ALERT</logLevel>
</MessageLogging>

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

속성 기본 필수 여부 설명
name 해당 없음 필수

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.
continueOnError false 선택 정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조:
enabled true 선택 정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.
async   false 지원 중단됨 이 속성은 지원이 중단되었습니다.

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

필드 이름 필드 설명
CloudLogging

Cloud Logging에 로깅되도록 메시지를 구성합니다.
Syslog

syslog에 로깅되도록 메시지를 구성합니다.

샘플

CloudLogging

<MessageLogging name="LogToCloudLogging">
    <CloudLogging>
        <LogName>projects/{organization.name}/logs/{log.id}</LogName>
        <Message contentType="application/json">{"{message.queryparam.key}": "{message.queryparam.value}"}</Message>
        <Labels>
            <Label>
                <Key>key1</Key>
                <Value>value1</Value>
            </Label>
            <Label>
                <Key>key2</Key>
                <Value>value2</Value>
            </Label>
        </Labels>
        <ResourceType>gce_instance</ResourceType>
    </CloudLogging>
</MessageLogging>

이 예시에서는 메시지 템플릿을 사용하는 방법을 보여줍니다. Message 요소에 흐름 변수가 포함되어 있으므로

{"{message.queryparam.key}": "{message.queryparam.value}"}

누군가 message.queryparam.key = "fruit" 및 message.queryparam.value = "apple" 값을 사용하여 프록시를 호출하면 결과로 생성되는 로그 항목은 {"fruit": "apple"}이 됩니다.

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>yyMMdd-HH:mm:ss.SSS</DateFormat>
  </Syslog>
  <logLevel>ALERT</logLevel>
</MessageLogging>

이 예시에서는 API가 소비자 앱에서 수신하는 각 요청 메시지에 대한 정보를 로깅해야 한다고 가정합니다. 3f509b58 값은 loggly 서비스와 관련된 키 값을 나타냅니다. loggly 계정이 있으면 loggly 키를 바꾸세요. 생성되는 로그 메시지에는 트랜잭션과 관련된 조직, API 프록시, 환경 이름 같은 4개 값과 요청 메시지의 쿼리 매개변수 값이 채워집니다. 타임스탬프 형식은 DateFormat 요소에 지정된 형식과 같이 230704-13:42:17.376과 유사합니다.

TLS/SSL을 통한 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>6514</Port>
    <Protocol>TCP</Protocol>
    <FormatMessage>true</FormatMessage>
    <SSLInfo>
        <Enabled>true</Enabled>
    </SSLInfo>
  </Syslog>
  <logLevel>WARN</logLevel>
</MessageLogging>

<SSLInfo> 블록을 추가하여 TLS/SSL을 통해 제3자 메시지 로깅 제공업체에 메시지를 보낼 수 있습니다.

하위 요소 참조

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

<CloudLogging>

<CloudLogging> 요소를 사용하여 메시지를 Cloud Logging에 로깅합니다.

필드 이름 필수 여부 설명
LogName 예 로그의 이름입니다. 로그 이름은 projects/{PROJECT_ID}/logs/{LOG_ID} 형식이어야 합니다. {PROJECT_ID} 및 {LOG_ID} 대신 변수를 사용할 수 있습니다.
Message 예

로깅할 메시지입니다. 메시지에는 속성 contentType이 있으며 값은 각각 텍스트 및 JSON 메시지에 대해 text/plain 또는 application/json일 수 있습니다. 샘플을 참조하세요.
Label 아니요 로그 메시지에 첨부할 라벨입니다(있는 경우). 이는 다음과 같이 키-값 쌍의 형식입니다. 
<Label>
    <Key>key1</Key>
    <Value>value1</Value>
</Label>
ResourceType 아니요(기본값: 전역) 로그를 생성하는 모니터링 리소스를 나타냅니다.

Cloud Logging 인증

<CloudLogging> 요소를 사용하려면 Google 인증을 사용하도록 API 프록시를 배포해야 합니다. Apigee는 Cloud Logging에 대한 아웃바운드 요청에서 지정한 서비스 계정의 ID에 해당하는 사용자 인증 정보를 사용합니다. 자세한 내용은 Google 인증 사용을 참조하세요. 배포할 때 API 프록시에 연결하는 서비스 계정에는 logging.logEntries.create 권한이 있는 역할이 있어야 합니다. <CloudLogging>의 Identity and Access Management(IAM) 역할에 대한 자세한 내용은 액세스 제어 가이드를 참조하세요.

<Syslog>

<Syslog> 요소를 사용하여 syslog에 로깅되도록 메시지를 구성합니다. <Syslog>를 사용하면 API 프록시가 로그 메시지를 Apigee에서 원격 시스템로그 서버로 전달합니다. 이 방법을 사용하려면 시스템로그 서버가 있어야 합니다. 없는 경우 Splunk, Sumo Logic, Loggly와 같은 공개 로그 관리 서비스를 사용할 수 있습니다. 타사 로그 관리 서비스 구성을 참조하세요.

필드 이름 필수 여부 필드 설명
Message 예

로깅할 메시지입니다. 메시지에는 속성 contentType이 있으며 값은 각각 텍스트 및 JSON 메시지에 대해 text/plain 또는 application/json일 수 있습니다. 샘플을 참조하세요.
Host 아니요 syslog를 전송해야 하는 서버의 호스트 이름 또는 IP 주소입니다. 이 요소를 포함하지 않는 경우 기본값은 localhost입니다.
Port 아니요 syslog가 실행되는 포트입니다. 이 요소를 포함하지 않는 경우 기본값은 514입니다.
Protocol 아니요 TCP 또는 UDP(기본값)입니다. UDP 성능이 더 좋지만 TCP 프로토콜은 메시지 로그가 시스템로그 서버로 전송되도록 보장합니다. TLS/SSL을 통해 syslog 메시지를 보내는 경우 TCP만 지원됩니다.
FormatMessage 아니요. 그러나 Loggly와 함께 사용하려면 <FormatMessage>true</FormatMessage>가 필요합니다.

true 또는 false(기본)

이 요소를 사용하면 메시지에 추가된 Apigee에서 생성한 콘텐츠의 형식을 제어할 수 있습니다. true로 설정되면 syslog 메시지에 고정된 수의 문자가 추가되어 메시지에서 해당 정보를 필터링할 수 있습니다. 다음은 고정 형식의 예시입니다.

<14>1 2023-03-20T09:24:39.039+0000 e49cd3a9-4cf6-48a7-abb9-7ftfe4d97d00 Apigee - - - Message starts here

Apigee에서 생성한 정보에는 다음이 포함됩니다.

  • <14> - 메시지의 로그 수준 및 시설 수준을 기반으로 한 우선순위 점수(Syslog 프로토콜 참조)
  • 1 - 현재 syslog 버전
  • UTC 오프셋 날짜 (UTC = +0000)
  • 메시지 프로세서 UUID
  • "Apigee - - - "

false(기본)로 설정하면 메시지가 이러한 고정된 문자로 표현되지 않습니다.
PayloadOnly 아니요

true 또는 false(기본)

이 요소는 FormatMessage에서 지정한 추가 문자 없이 syslog 메시지의 본문만 포함하도록 Apigee에서 생성된 메시지의 형식을 설정합니다.

이 요소를 포함하지 않거나 비워 둘 경우 기본값은 false입니다.

FormatMessage를 참조하세요.
DateFormat 아니요

각 로그 메시지의 타임스탬프 형식을 지정하는 데 사용할 형식 템플릿 문자열입니다. 기본적으로 Apigee는 yyyy-MM-dd'T'HH:mm:ss.SSSZ를 사용합니다. 이 템플릿의 동작은 Java의 SimpleDateFormat 클래스 문서에 설명되어 있습니다. 이 정의에 따라 형식 문자열의 yyyy는 4자리 연도로, MM은 2자리 월 숫자로 바뀝니다.

SSLInfo 아니요

SSL/TLS를 통해 메시지를 로깅할 수 있습니다. 하위 요소 <Enabled>true</Enabled>와 함께 사용합니다.

이 요소를 포함하지 않거나 비워 두면 기본값은 false(TLS/SSL 없음)입니다.

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

API 프록시 구성 참조에 설명된 대로 양방향 TLS/SSL 사용 설정을 포함하여 TargetEndpoint에서와 마찬가지로 <SSLInfo> 태그를 구성할 수 있습니다. TCP 프로토콜만 지원됩니다.

<logLevel>

유효한 <logLevel> 요소 값은 INFO(기본값), ALERT, WARN, ERROR입니다.

메시지 로그에 포함할 특정 수준의 정보를 설정합니다.

FormatMessage 요소(true로 설정)를 사용하면 <logLevel> 설정은 메시지에 추가된 Apigee 생성 정보에서 집계된 우선순위 점수(꺾쇠괄호 안의 숫자)에 영향을 미칩니다.

사용 참고사항

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

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

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

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

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

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

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

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

Apigee는 메시지를 단순 텍스트로 로깅하고, 요청 또는 응답이 수신된 날짜와 시간, 요청의 사용자 ID, 소스 요청이 전송된 소스 IP 주소와 같은 변수를 포함하도록 로깅을 구성할 수 있습니다.

Apigee는 메시지를 비동기식으로 로깅합니다. 로그가 계속 작성되는 동안 응답이 반환됩니다. 따라서 콜아웃을 차단하여 API에 지연 시간이 발생하지 않습니다. 오류가 반환되지 않고 로그가 작성되지 않는 경우가 있지만 이러한 이벤트는 드뭅니다.

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

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

  • <CloudLoggingg> 사용: 
    steps.messagelogging.TooManyPendingLoggingRequest
  • <Syslog> 사용: 
    Log message size exceeded. Increase the max message size setting

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

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

메시지 템플릿의 각 변수에 기본값을 별도로 지정할 수 있습니다. 예를 들어 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자 로그 관리 구성은 다음 문서를 참조하세요.

오류 참조

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

런타임 오류

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

오류 코드 HTTP 상태 원인
steps.messagelogging.StepDefinitionExecutionFailed 500 오류 문자열을 참조하세요.
steps.messagelogging.InvalidGoogleCloudLogName 500 이 오류는 LogName이 projects/{project}/logs/{logid}의 유효한 형식으로 평가되지 않을 때 발생합니다.
steps.messagelogging.InvalidJsonMessage 500 이 오류는 contentType 속성 값이 application/json으로 선택되었지만 실제 메시지 값이 유효한 JSON 문자열이 아닌 경우 발생합니다.
steps.messagelogging.TooManyPendingLoggingRequest 500 이 오류는 아직 Cloud Logging에 기록 대기 중인 요청이 2,500개를 초과하면 발생합니다. 2,500개의 한도는 각 Apigee 런타임 포드마다 적용됩니다. 예를 들어 트래픽이 Apigee 런타임 포드의 두 인스턴스에 분산되는 경우 유효 한도는 5,000개의 요청입니다.
-

배포 오류

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

오류 이름 원인 수정
InvalidProtocol <Protocol> 요소 내에서 지정된 프로토콜이 유효하지 않은 경우 MessageLogging 정책의 배포가 이 오류와 함께 실패할 수 있습니다. 유효한 프로토콜은 TCP 및 UDP입니다. TLS/SSL을 통해 syslog 메시지를 보내는 경우 TCP만 지원됩니다.
InvalidPort 포트 번호가 <Port> 요소 내에 지정되지 않았거나 유효하지 않은 경우 MessageLogging 정책의 배포가 이 오류와 함께 실패할 수 있습니다. 포트 번호는 0보다 큰 정수여야 합니다.

오류 변수

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

변수 장소 예
fault.name="fault_name" fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name Matches "StepDefinitionExecutionFailed"
messagelogging.policy_name.failed policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. messagelogging.ML-LogMessages.failed = true

오류 응답 예시

{  
   "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

관련 주제