นโยบาย MessageLogging

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

อะไร

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

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

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

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

<FileName>mylog.log</FileName>

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

สคีมา

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

เมื่อแนบนโยบายการบันทึกข้อความไปยังเวิร์กโฟลว์พร็อกซี 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 ต้นทางที่ส่งคำขอ และอื่นๆ Edge จะบันทึกข้อความแบบไม่พร้อมกัน ซึ่งหมายความว่า API ของคุณจะไม่เกิดความล่าช้าที่อาจเกิดจากการบล็อกข้อความไฮไลต์

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

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

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 หากขั้นตอนก่อนหน้าคือ Error Flow หากต้องการบันทึกข้อมูลการตอบกลับจาก 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 Message Processor เพื่อควบคุมรูปแบบดังกล่าว เช่น การเปลี่ยนรูปแบบข้อความเป็น

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 for 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 ในโปรแกรมประมวลผลข้อความ ดังนี้

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