Chính sách Ghi nhật ký tin nhắn

Bạn đang xem tài liệu về Apigee Edge.
Tham khảo tài liệu về Apigee X. thông tin

Nội dung

Một trong những cách tốt nhất để theo dõi sự cố trong môi trường thời gian chạy API là ghi nhật ký thông điệp. Bạn có thể đính kèm và định cấu hình chính sách MessageLogging trên API của mình để ghi nhật ký các thông báo tuỳ chỉnh vào một ổ đĩa cục bộ (chỉ riêng Edge cho Đám mây riêng tư) hoặc vào nhật ký hệ thống.

Mẫu

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

Tham chiếu phần tử

Dùng các phần tử sau để định cấu hình loại chính sách MessageLogging.

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

Giản đồ

Ghi chú sử dụng

Khi đính kèm chính sách MessageLogging vào luồng proxy API, hãy cân nhắc đặt chính sách này vào phản hồi ProxyEndpoint, trong một quy trình đặc biệt có tên là PostClientFlow. PostClientFlow thực thi sau khi phản hồi được gửi đến ứng dụng yêu cầu. Việc này giúp đảm bảo rằng tất cả chỉ số đều có sẵn để ghi nhật ký. Để biết thông tin chi tiết về cách sử dụng PostClientFlow, hãy xem Tài liệu tham khảo về cấu hình proxy API.

PostClientFlow đặc biệt theo hai cách:

1. Lệnh này chỉ được thực thi trong luồng phản hồi.
2. Đây là luồng duy nhất được thực thi sau khi proxy chuyển sang trạng thái lỗi.

Vì chính sách này được thực thi bất kể proxy thành công hay không thành công, nên bạn có thể đặt các chính sách MessageLogging trong PostClientFlow và được đảm bảo rằng chúng luôn thực thi.

Hình ảnh Theo dõi sau đây cho thấy chính sách MessageLogging thực thi trong khuôn khổ PostClientFlow, sau khi DefaultFaultRule thực thi:

Trong ví dụ này, chính sách Xác minh khoá API đã gây ra lỗi do khoá không hợp lệ.

Dưới đây là định nghĩa ProxyEndpoint bao gồm PostClientFlow:

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

Edge ghi nhật ký các thông báo dưới dạng văn bản đơn giản và bạn có thể định cấu hình nhật ký để thêm các biến vào, chẳng hạn như ngày và giờ nhận được yêu cầu hoặc phản hồi, danh tính người dùng trong yêu cầu, địa chỉ IP nguồn mà từ đó yêu cầu được gửi đi, v.v. Edge ghi lại thông báo một cách không đồng bộ, nghĩa là không có độ trễ nào có thể do việc chặn chú thích được đưa vào API của bạn.

Chính sách MessageLogging ghi các thông điệp đã ghi nhật ký trong bộ nhớ vào vùng đệm. Trình ghi nhật ký thông báo sẽ đọc thông điệp từ vùng đệm, sau đó ghi vào đích đến mà bạn định cấu hình. Mỗi đích đến có vùng đệm riêng.

Nếu tốc độ ghi vào vùng đệm tăng vượt quá tốc độ đọc, thì vùng đệm sẽ bị tràn và không ghi nhật ký được. Nếu việc này xảy ra, bạn có thể thấy một thông báo chứa nội dung sau trong tệp nhật ký:

Log message size exceeded. Increase the max message size setting

Nếu bạn gặp vấn đề này trong Edge for Private Cloud 4.15.07 trở xuống, hãy tìm tệp message-logging.properties và dùng giải pháp sau:

Tăng thuộc tính max.log.message.size.in.kb (giá trị mặc định = 128 KB) trong tệp message-logging.properties.

Đối với Edge dành cho đám mây riêng tư 4.16.01 trở lên, hãy thiết lập thuộc tính conf_message-logging_max.log.message.size.in.kb trong tệp /opt/apigee/customer/application/message-processor.properties rồi khởi động lại Trình xử lý thông báo.

Lưu ý: Các biến thông báo phản hồi trong Edge không có trong Luồng lỗi. Các biến này cũng không có trong PostClientFlow nếu luồng trước đó là Luồng lỗi. Nếu bạn muốn ghi nhật ký thông tin phản hồi từ PostClientFlow, hãy sử dụng đối tượng thông báo. Bạn có thể sử dụng đối tượng này để lấy tiêu đề và các thông tin khác từ phản hồi cho dù có lỗi hay không. Hãy xem phần Biến thông báo để biết thêm thông tin và ví dụ.

Kiểm soát dấu thời gian của thông điệp nhật ký trong Edge cho Đám mây riêng tư

Theo mặc định, dấu thời gian trong tất cả thông điệp nhật ký có định dạng:

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

Bạn có thể ghi đè giá trị mặc định toàn hệ thống này cho các đích đến nhật ký hệ thống bằng cách sử dụng phần tử DateFormat. Hành vi của mẫu này được mô tả trong tài liệu về lớp SimpleDateFormat của Java. Theo định nghĩa đó, yyyy sẽ được thay thế bằng năm gồm 4 chữ số, MM sẽ được thay bằng số tháng gồm 2 chữ số, v.v. Định dạng trên có thể dẫn đến một chuỗi có dạng này:

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

Bạn có thể sử dụng thuộc tính conf_system_apigee.syslogger.dateFormat trên Trình xử lý thông báo Edge để kiểm soát định dạng đó. Ví dụ: thay đổi định dạng thông báo thành:

yy/MM/dd'T'HH:mm:ss.SSSZ

..thay thế dấu gạch ngang bằng dấu gạch chéo và rút ngắn thành năm gồm 2 chữ số, ghi lại dấu thời gian trong biểu mẫu:

22/09/28T22:38:11.721+0000

Cách thay đổi định dạng:

1. Mở tệp message-processor.properties trong trình chỉnh sửa. Nếu tệp chưa tồn tại, hãy tạo tệp:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Đặt các thuộc tính như mong muốn:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Lưu các thay đổi.
4. Đảm bảo tệp thuộc tính thuộc quyền sở hữu của người dùng "apigee":
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Khởi động lại Trình xử lý tin nhắn Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Vị trí tệp nhật ký trong Edge dành cho đám mây riêng tư

Edge dành cho đám mây riêng tư 4.16.01 trở lên

Theo mặc định, nhật ký thông báo Đám mây riêng tư nằm trong thư mục sau đây trên các nút Trình xử lý thư:

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

Bạn có thể thay đổi vị trí mặc định của nhật ký bằng cách sửa đổi các thuộc tính trong tệp message-LOG.properties trên Bộ xử lý thư:

• bin_setenv_data_dir – Đặt đường dẫn gốc để lưu trữ tệp nhật ký. Ví dụ: bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-blog_log.root.dir – Nếu bạn thiết lập thuộc tính này thành một đường dẫn tương đối, chẳng hạn như conf/message-logging.properties+log.root.dir=custom/folder/, the path is appended to the bin_setenv_data_dir location.
  
  Nếu bạn thiết lập đường dẫn này thành một đường dẫn tuyệt đối, chẳng hạn như conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages, thì nhật ký thông báo sẽ được lưu trữ trong /opt/apigee/var/log/messages/messagelog/. Đường dẫn tuyệt đối sẽ được ưu tiên hơn bin_setenv_data_dir.
  
  Xin lưu ý rằng bạn phải tham chiếu thuộc tính này dưới dạng conf/message-reporting.properties+log.root.dir vì thuộc tính này được nhận xét theo mặc định. Hãy xem phần Đặt mã thông báo đang được nhận xét để biết thêm thông tin.

Nếu bạn muốn lưu trữ các tệp nhật ký trong một cấu trúc tệp phẳng để mọi tệp nhật ký được đặt trong cùng một thư mục, hãy đặt giá trị conf/message-LOG.properties+enable.flat.directory.structure thành đúng trong tệp message-LOG.properties. Thông báo được lưu trữ trong thư mục do các thuộc tính ở trên chỉ định và tên tệp có dạng {org}_{environment}_{api_proxy_name}_{revision}_{logging_policy_name}_{filename}.

Cách đặt các thuộc tính này:

1. Mở tệp message-processor.properties trong trình chỉnh sửa. Nếu tệp chưa tồn tại, hãy tạo tệp:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Đặt các thuộc tính như mong muốn:
   conf/message-log.properties+log.root.dir=/opt/apigee/var/log/messages
3. Lưu các thay đổi.
4. Đảm bảo tệp thuộc tính thuộc quyền sở hữu của người dùng "apigee":
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Khởi động lại thành phần Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Edge dành cho đám mây riêng tư 4.15.07 trở xuống

Theo mặc định, nhật ký thông báo nằm ở vị trí sau trên trình xử lý thông báo:

/opt/apigee4/var/log/apigee/message-processor/messagelog/{org}/{environment}/{api_proxy_name}/{revision}/{logging_policy_name}/

Bạn có thể thay đổi vị trí mặc định của nhật ký bằng cách sửa đổi các thuộc tính sau trong tệp message- tín.properties trên trình xử lý thông báo:

• data.dir – Đặt đường dẫn gốc cho bộ nhớ tệp nhật ký. Ví dụ: data.dir=/opt/apigee4/var/log
• log.root.dir – Nếu bạn đặt đường dẫn này thành một đường dẫn tương đối, chẳng hạn như log.root.dir=custom/folder/, thì đường dẫn sẽ được nối vào vị trí data.dir.

Ví dụ: tổ hợp hai thuộc tính sẽ đặt thư mục ghi nhật ký tại /opt/apigee4/var/log/custom/folder/messagelog/ (lưu ý rằng /messagelog được thêm tự động).

Nếu bạn đặt giá trị này thành một đường dẫn tuyệt đối, chẳng hạn như log.root.dir=/opt/apigee4/var/log/messages thì nhật ký thông báo sẽ được lưu trữ trong /opt/apigee4/var/log/messages/messagelog/. Đường dẫn tuyệt đối trong log.root.dir được ưu tiên hơn data.dir.

Nếu bạn muốn lưu trữ các tệp nhật ký trong một cấu trúc tệp phẳng để tất cả các tệp nhật ký đều được đặt trong cùng một thư mục, hãy đặt thuộc tính enable.flat.directory.structure thành true trong tệp message- Thông.properties trên Bộ xử lý thông báo. Tin nhắn được lưu trữ trong thư mục do các thuộc tính nêu trên chỉ định và tên tệp có dạng {org}_{environment}_{api_proxy_name}_{revision}_{ Thông_nhật ký_policy_name}_{filename}.

Giá trị mặc định cho các biến trong mẫu thông báo

Bạn có thể chỉ định giá trị mặc định cho từng biến trong mẫu thông báo riêng. Ví dụ: nếu biến request.header.id không phân giải được, thì giá trị của biến đó sẽ được thay thế bằng giá trị unknown.

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

Bạn có thể chỉ định một giá trị mặc định chung cho mọi biến chưa được giải quyết bằng cách thiết lập thuộc tính defaultVariableValue trên phần tử Message:

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

Định cấu hình dịch vụ quản lý nhật ký của bên thứ ba

Chính sách MessageLogging cho phép bạn gửi thông báo nhật ký hệ thống đến các dịch vụ quản lý nhật ký của bên thứ ba, như Splunk, Sumo Logic và Loggly. Nếu bạn muốn gửi nhật ký hệ thống đến một trong các dịch vụ đó, hãy xem tài liệu của dịch vụ đó để định cấu hình máy chủ lưu trữ, cổng và giao thức của dịch vụ, sau đó đặt phần tử Nhật ký hệ thống trên chính sách này cho phù hợp.

Xem tài liệu sau đây để biết cấu hình quản lý nhật ký của bên thứ ba:

• Splunk (chọn phiên bản của sản phẩm)
  Bạn cũng có thể xem bài đăng này trên thẻ Cộng đồng Apigee: https://community.apigee.com/content/kbentry/13298/log-messages-into-splunk.html
• Logic Sumo
  • Ngoài ra, hãy xem bài đăng này trên thẻ Cộng đồng Apigee: https://community.apigee.com/questions/5226/setting-up- đảm-with-sumo-logic-what-host-shou.html
  • Để tìm hiểu ví dụ đầy đủ về việc sử dụng Sumo Logic làm dịch vụ ghi nhật ký, hãy xem bài đăng sau đây về Apigee trên Cộng đồng. Giải pháp này sử dụng một chính sách JavaScript duy nhất để gửi yêu cầu POST HTTP tới Trình thu thập nguồn HTTP Sumo Logic: https://community.apigee.com/articles/32286/LOG-to-sumo-logic-using-javascript-and-http.html
• Loggly
  Khi sử dụng Loggly, bạn bắt buộc phải sử dụng <FormatMessage>true</FormatMessage> trong chính sách này dưới dạng phần tử con của phần tử <Syslog>.
  Ngoài ra, hãy xem bài đăng này trên thẻ Cộng đồng Apigee để biết thêm thông tin về cách ghi nhật ký tin nhắn vào Loggly: https://community.apigee.com/content/kbentry/14798/log-messages-into-loggly.html

Tham chiếu lỗi

Phần này mô tả mã lỗi và thông báo lỗi được trả về, cũng như các biến lỗi do Edge đặt khi chính sách này kích hoạt lỗi. Thông tin này rất quan trọng để biết bạn có đang phát triển các quy tắc lỗi để xử lý lỗi hay không. Để tìm hiểu thêm, hãy xem phần Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.

Lỗi thời gian chạy

Những lỗi này có thể xảy ra khi thực thi chính sách.

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai một proxy có chứa chính sách này.

Biến lỗi

Các biến này được đặt khi xảy ra lỗi thời gian chạy. Để biết thêm thông tin, hãy xem bài viết Những điều bạn cần biết về lỗi chính sách.

Ví dụ về phản hồi lỗi

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

Ví dụ về quy tắc lỗi

<FaultRule name="MessageLogging">
    <Step>
        <Name>ML-LogMessages</Name>
        <Condition>(fault.name Matches "StepDefinitionExecutionFailed") </Condition>
    </Step>
    <Condition>(messagelogging.ML-LogMessages.failed = true) </Condition>
</FaultRule>

Biến luồng

Các biến sau đây được điền sẵn về lỗi chính sách.

• messagelogging.failed
• messagelogging.{stepdefinition-name}.failed

Chủ đề có liên quan

• Biến do Edge hiển thị: Tham chiếu biến