นโยบาย MessageLogging

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

อะไร

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

การอ้างอิงองค์ประกอบ

ใช้องค์ประกอบต่อไปนี้เพื่อกำหนดค่าประเภทนโยบาย MessageLนั้นๆ

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

สคีมา

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

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

PostClientFlow มีความพิเศษใน 2 รูปแบบ ดังนี้

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

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

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

ในตัวอย่างนี้ นโยบายคีย์ API "ยืนยัน" เป็นสาเหตุของข้อผิดพลาดเนื่องจากข้อผิดพลาด

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

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

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

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

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

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

หมายเหตุ: ข้อความตอบกลับ ตัวแปรใน 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 ใน Editor หากไม่มีไฟล์ ให้สร้างขึ้นมา:
   > 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 ดังนี้
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor รีสตาร์ท

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

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

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

/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/ Absolute Path มีความสำคัญเหนือ 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 ใน Editor หากไม่มีไฟล์ ให้สร้างขึ้นมา:
   > 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 รีสตาร์ท

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/โฟลเดอร์/ เส้นทางจะต่อท้ายไฟล์ ตำแหน่ง data.dir

เช่น ชุดค่าผสมของพร็อพเพอร์ตี้ทั้ง 2 รายการจะตั้งค่าไดเรกทอรีการบันทึกที่ /opt/apigee4/var/log/custom/โฟลเดอร์/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 ผู้ประมวลผลข้อมูล ข้อความจะจัดเก็บอยู่ในไดเรกทอรีที่พร็อพเพอร์ตี้ข้างต้นระบุไว้ รวมถึงไฟล์ จะอยู่ในรูปแบบ {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 นี้ด้วย 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 โซลูชันนี้ใช้นโยบาย JavaScript เดียวเพื่อสร้าง HTTP POST คำขอไปยังเครื่องมือรวบรวมแหล่งที่มา HTTP ของ Sumo Logic: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  เมื่อใช้ Loggly ต้องใช้ <FormatMessage>true</FormatMessage> ใน นโยบายเป็นองค์ประกอบย่อยขององค์ประกอบ <Syslog>
  ดูข้อมูลเพิ่มเติมเกี่ยวกับการบันทึกข้อความไปยัง 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: ข้อมูลอ้างอิงตัวแปร