นโยบาย 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="LogToSy>slo<g">;
  S<yslog
 >   Message[3f509b58 tag="{organization.name}.{apiproxy.name}.{environment.name}"] Weather request for WOEID {re<quest.qu>erypa<ram.>w}./Message
    Ho<stlog>s-01.<logg>ly.c<om/Ho>st
  <  Port65>14/<Port
    >Proto<colTCP/Protoc>ol
 <   FormatMessa>getru<e/Forma>tMessage
<    SSL>Info<
       > Enab<ledtrue/>Enabl<ed
    /SS>LInfo
    DateForma<tyyMMdd-HH:>mm:<ss.SSS/>Dat<eFormat
>  /S<yslog
  l>o<gLevelWARN/logL>evel
/MessageLogging

<MessageLogging name="LogPo>lic<y&qu>ot;
 < File
 >   MessageThis is a test message. Message id : {request.header.<messagei>d}/Mess<age
    >  FileNa<metest.lo>g/FileN<ame
      FileRotationOptions rotateFileOnStar>tup="<;true"
    >    <FileRotationTypeS>IZE/FileR<otationType
   >  <   MaxFileSizeIn>MB10/MaxF<ileSizeInMB
    >  <  MaxFilesToRetai>n10/Max<FilesToRetain
      >/Fi<leRot>ati<onOption>s
  /<File
  lo>g<LevelERROR/logL>evel
/MessageLogging

<MessageLogging name="LogPo>lic<y&qu>ot;
 < File
 >   MessageThis is a test message. Message id : {request.header.<messagei>d}/Me<ssage
  >  FileNa<metest.lo>g/Fil<eName
    FileRotationOptions rotateFileOnStar>tup=&qu<ot;true"
  >    <FileRotationTypeT>IME/Fil<eRotationType
      RotationFre>qu<ency unit="mi>nute&qu<ot;10/RotationFr>eq<uency
      MaxFi>lesTo<Retain10/MaxFilesToR>eta<in
  >  /<FileRota>tionO<ptions
  >/<File
  logLevel>ERROR/logLevel
/MessageLogging

<MessageLogging name="LogPo>lic<y&qu>ot;
 < File
 >   MessageThis is a test message. Message id : {request.header.<messagei>d}/Me<ssage
  >  FileNa<metest.lo>g/Fil<eName
    FileRotationOptions rotateFileOnStar>tup=&qu<ot;true"
  >    FileR<otationTypeTIME_S>IZE/Fil<eRotationType
 >  <   MaxFileSizeIn>MB10/Ma<xFileSizeInMB
  >  <  MaxFilesToRetai>n10/Max<FilesToRetain
      RotationFre>qu<ency unit="mi>nute&<quot;10/RotationFreq>uen<cy
  >  /<FileRota>tionO<ptions
  >/<File
  logLevel>ERROR/logLevel
/MessageLogging

<MessageLogging name="LogPo>lic<y&qu>ot;
  File
  ....<
  ..>..
<  /File
  Buf>ferM<essagetrue/Buf>f<erMessage
/Mess>ageLogging

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

ใช้องค์ประกอบต่อไปนี้เพื่อกําหนดค่าประเภทนโยบาย 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="def>ault"<;
  ...
  Post>Clien<tFlow
  >  Respo<nse
>      Ste<p
  >      NameMessage<-Logg>ing-1/N<ame
 >     </Step
   > /R<esponse
  /Post>ClientF<low
  ...
/Pro>xyEndpoint

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

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

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

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

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/ เส้นทางแบบสัมบูรณ์ใน 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="unk>nown"This is a test message. id = {request.<header.i>d}/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

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.messagelogging.StepDefinitionExecutionFailed"
      },
      "faultstring":"Execution failed"
   }
}

Example fault rule

<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 แสดง: การอ้างอิงตัวแปร