นโยบาย MessageLogging

คุณกำลังดูเอกสารประกอบของ Apigee Edge
ไปที่เอกสารประกอบของ Apigee X info

อะไร

วิธีที่ดีที่สุดวิธีหนึ่งในการติดตามปัญหาในสภาพแวดล้อมรันไทม์ของ API คือการบันทึกข้อความ คุณสามารถแนบและกำหนดค่านโยบาย MessageLogging ใน API เพื่อบันทึกข้อความที่กำหนดเองไปยัง ฮาร์ดดิสก์ในเครื่อง (Edge for Private Cloud เท่านั้น) หรือไปยัง 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

<FileName>/opt/apigee/var/log/messages/mylog.log</FileName>

<FileName>mylog.log</FileName>

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

สคีมา

หมายเหตุการใช้งาน

เมื่อแนบนโยบาย MessageLogging ไปยังโฟลว์พร็อกซี API ให้พิจารณาวางไว้ใน การตอบกลับ ProxyEndpoint ในโฟลว์พิเศษที่เรียกว่า PostClientFlow PostClientFlow จะทำงาน หลังจากส่งการตอบกลับไปยังไคลเอ็นต์ที่ขอ ซึ่งจะช่วยให้มั่นใจได้ว่าเมตริกทั้งหมดพร้อมใช้งาน สำหรับการบันทึก ดูรายละเอียดเกี่ยวกับการใช้ PostClientFlow ได้ที่เอกสารอ้างอิงการกำหนดค่าพร็อกซี API

PostClientFlow มีความพิเศษ 2 อย่างดังนี้

1. โดยจะดำเนินการเป็นส่วนหนึ่งของขั้นตอนการตอบกลับเท่านั้น
2. ซึ่งเป็นโฟลว์เดียวที่ดำเนินการหลังจากที่พร็อกซีเข้าสู่สถานะข้อผิดพลาด

เนื่องจากมีการดำเนินการไม่ว่าพร็อกซีจะสำเร็จหรือไม่ก็ตาม คุณจึงวางนโยบาย MessageLogging ไว้ใน PostClientFlow และมั่นใจได้ว่าจะมีการดำเนินการเสมอ

รูปภาพการติดตามต่อไปนี้แสดงนโยบาย MessageLogging ที่ดำเนินการเป็นส่วนหนึ่งของ PostClientFlow หลังจากที่ DefaultFaultRule ดำเนินการ

ในตัวอย่างนี้ นโยบาย "ยืนยันคีย์ API" ทำให้เกิดข้อผิดพลาดเนื่องจากคีย์ไม่ถูกต้อง

ด้านล่างนี้คือคำจำกัดความของ ProxyEndpoint ที่มี PostClientFlow

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

Edge จะบันทึกข้อความเป็นข้อความธรรมดา และคุณสามารถกำหนดค่าการบันทึกเพื่อรวมตัวแปรต่างๆ เช่น วันที่และเวลาที่ได้รับคำขอหรือการตอบกลับ ข้อมูลประจำตัวผู้ใช้ในคำขอ ที่อยู่ IP ต้นทางที่ส่งคำขอ และอื่นๆ บันทึกขอบจะส่งข้อความแบบอะซิงโครนัส ซึ่งหมายความว่า API จะไม่มีเวลาในการตอบสนองที่อาจเกิดจากการบล็อกการเรียกออก

นโยบาย MessageLogging จะเขียนข้อความที่บันทึกไว้ในหน่วยความจำไปยังบัฟเฟอร์ เครื่องมือบันทึกข้อความ จะอ่านข้อความจากบัฟเฟอร์ แล้วเขียนไปยังปลายทางที่คุณกำหนดค่า ปลายทางแต่ละแห่ง จะมีบัฟเฟอร์ของตัวเอง

ผู้ใช้อาจได้รับข้อความบันทึกที่ส่งไปยังปลายทาง Syslog ใหม่ล่าช้า ซึ่งเป็นผลมาจากลักษณะการทำงาน "cold start" ที่ตั้งใจไว้ในนโยบาย เมื่อกำหนดค่าปลายทางการบันทึกใหม่ นอกเหนือจากปลายทางการบันทึกที่มีอยู่ ตัวประมวลผลข้อความ (MP) อาจจัดคิวข้อความบันทึก 1,000 รายการในหน่วยความจำก่อนที่จะส่ง ซึ่งอาจส่งผลให้เกิดความล่าช้าในตอนแรก ในสภาพแวดล้อมที่มีการเข้าชมต่ำ ความล่าช้าเริ่มต้นนี้จะไม่สังเกตเห็นได้สำหรับภาระงานการผลิตทั่วไป เนื่องจากข้อความควรสะสมอย่างรวดเร็ว เมื่อถึงเกณฑ์แล้ว ระบบจะส่งข้อความบันทึก ตามที่คาดไว้ การรีสตาร์ท Message Processor อย่างราบรื่นยังสามารถทริกเกอร์ การนำส่งข้อความที่อยู่ในคิวเมื่อข้อความเหล่านั้นออกจากคิวได้ด้วย

หากอัตราการเขียนไปยังบัฟเฟอร์เพิ่มขึ้นเกินกว่าอัตราการอ่าน บัฟเฟอร์จะล้นและ การบันทึกจะล้มเหลว หากเกิดกรณีนี้ คุณอาจเห็นข้อความที่มีข้อมูลต่อไปนี้ในไฟล์บันทึก

Log message size exceeded. Increase the max message size setting

หากพบปัญหานี้ใน Edge for Private Cloud 4.15.07 และเวอร์ชันก่อนหน้า ให้ค้นหาไฟล์ message-logging.properties แล้วใช้โซลูชันนี้

เพิ่มพร็อพเพอร์ตี้ max.log.message.size.in.kb (ค่าเริ่มต้น = 128 KB) ในไฟล์ message-logging.properties

สําหรับ Edge for Private Cloud 4.16.01 ขึ้นไป ให้ตั้งค่าพร็อพเพอร์ตี้ conf/message-logging.properties+max. log.message.size.in.kb ในไฟล์ /opt/apigee/customer/application/message-processor.properties แล้วรีสตาร์ท Message Processor โปรดทราบว่าพร็อพเพอร์ตี้นี้จะถูกแสดงความคิดเห็นไว้โดยค่าเริ่มต้น

หมายเหตุ: ตัวแปรข้อความตอบกลับใน Edge จะไม่พร้อมใช้งานจากโฟลว์ข้อผิดพลาด ตัวแปรเหล่านี้จะใช้ไม่ได้ใน PostClientFlow หากโฟลว์ก่อนหน้าเป็นโฟลว์ข้อผิดพลาด หากต้องการบันทึกข้อมูลการตอบกลับ จาก PostClientFlow ให้ใช้ออบเจ็กต์ message คุณ ใช้ออบเจ็กต์นี้เพื่อรับส่วนหัวและข้อมูลอื่นๆ จากการตอบกลับได้ ไม่ว่าจะมีข้อผิดพลาดหรือไม่ก็ตาม ดูข้อมูลเพิ่มเติมและตัวอย่างได้ที่ตัวแปรข้อความ

การควบคุมการประทับเวลาของข้อความบันทึก ใน Edge สำหรับ Private Cloud

โดยค่าเริ่มต้น การประทับเวลาในข้อความบันทึกทั้งหมดจะมีรูปแบบดังนี้

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

ค่าเริ่มต้นทั่วทั้งระบบนี้สามารถลบล้างได้สำหรับปลายทาง Syslog โดยใช้ องค์ประกอบ DateFormat ลักษณะการทำงานของเทมเพลตนี้อธิบายไว้ใน เอกสารประกอบสำหรับคลาส SimpleDateFormat ของ Java ตามคำนิยามนั้น yyyy จะถูกแทนที่ ด้วยปี 4 หลัก MM จะถูกแทนที่ด้วยหมายเลขเดือน 2 หลัก และอื่นๆ รูปแบบข้างต้นอาจส่งผลให้เกิดสตริงในรูปแบบต่อไปนี้

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

คุณใช้พร็อพเพอร์ตี้ conf_system_apigee.syslogger.dateFormat ในตัวประมวลผลข้อความ Edge เพื่อควบคุมรูปแบบดังกล่าวได้ เช่น การเปลี่ยนรูปแบบข้อความ เป็น

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. รีสตาร์ท Edge Message Processor:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

ตำแหน่งไฟล์บันทึกใน Edge สำหรับ Private Cloud

Edge สำหรับ Private Cloud 4.16.01 ขึ้นไป

โดยค่าเริ่มต้น บันทึกข้อความ Private Cloud จะอยู่ในไดเรกทอรีต่อไปนี้ในโหนด Message Processor

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

คุณเปลี่ยนตำแหน่งบันทึกเริ่มต้นได้โดยแก้ไขพร็อพเพอร์ตี้ในไฟล์ message-logging.properties ใน Message Processor ดังนี้

• 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 ในไฟล์ message-logging.properties ระบบจะจัดเก็บข้อความไว้ในไดเรกทอรีที่ระบุโดย พร็อพเพอร์ตี้ด้านบน และชื่อไฟล์จะมีรูปแบบเป็น {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-service edge-message-processor restart

Edge สำหรับ Private Cloud 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

ตัวอย่างเช่น การรวมพร็อพเพอร์ตี้ทั้ง 2 รายการจะตั้งค่าไดเรกทอรีการบันทึกที่ /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 เป็น true ในไฟล์ message-logging.properties ใน Message Processors ข้อความจะจัดเก็บไว้ในไดเรกทอรีที่ระบุโดยพร็อพเพอร์ตี้ด้านบน และชื่อไฟล์จะอยู่ในรูปแบบ {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>

คุณระบุค่าเริ่มต้นทั่วไปสำหรับตัวแปรที่ยังไม่ได้รับการแก้ไขทั้งหมดได้โดยการตั้งค่าแอตทริบิวต์ defaultVariableValue ในองค์ประกอบ Message ดังนี้

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

การกำหนดค่าบริการจัดการบันทึกของบุคคลที่สาม

นโยบายการบันทึกข้อความช่วยให้คุณส่งข้อความ Syslog ไปยังบริการจัดการบันทึกของบุคคลที่สาม เช่น Splunk, Sumo Logic และ Loggly ได้ หากต้องการส่ง Syslog ไปยังบริการใดบริการหนึ่ง โปรดดูเอกสารประกอบของบริการนั้นเพื่อกำหนดค่าโฮสต์ พอร์ต และโปรโตคอลของบริการ จากนั้นตั้งค่าองค์ประกอบ Syslog ในนโยบายนี้ตามนั้น

ดูเอกสารประกอบต่อไปนี้สำหรับการกำหนดค่าการจัดการบันทึกของบุคคลที่สาม

• Splunk (เลือกเวอร์ชันผลิตภัณฑ์)
  ดูโพสต์ชุมชน Apigee นี้ด้วย: บันทึกข้อความลงใน Splunk
• Sumo Logic
  • ดูโพสต์ในชุมชน Apigee นี้ด้วย Setting up logging with Sumo Logic, which host should I use?
  • ดูตัวอย่างที่สมบูรณ์โดยใช้ Sumo Logic เป็นบริการบันทึกได้ในโพสต์ชุมชน Apigee ต่อไปนี้ โซลูชันใช้นโยบาย JavaScript เดียวเพื่อส่งคำขอ HTTP POST ไปยังตัวรวบรวมแหล่งที่มาของ HTTP ของ Sumo Logic: การบันทึกไปยัง Sumo Logic โดยใช้ JavaScript และ HTTP
• Loggly
  เมื่อใช้ Loggly คุณต้องระบุ <FormatMessage>true</FormatMessage> ในนโยบายเป็นองค์ประกอบย่อยขององค์ประกอบ <Syslog>
  ดูข้อมูลเพิ่มเติมเกี่ยวกับการบันทึกข้อความไปยัง Loggly ได้ในโพสต์ชุมชน Apigee นี้ บันทึกข้อความลงใน Loggly

ข้อมูลอ้างอิงข้อผิดพลาด

ส่วนนี้จะอธิบายรหัสข้อผิดพลาดและข้อความแสดงข้อผิดพลาดที่แสดงกลับมา และตัวแปรข้อผิดพลาดที่ 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 แสดง: การอ้างอิงตัวแปร