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

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. Thông tin

Nội dung

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

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ử

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

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

<FileName>mylog.log</FileName>

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

Giản đồ

Ghi chú về cách sử dụng

Khi đính kèm chính sách MessageLogging vào một luồng proxy API, hãy cân nhắc việc đặt chính sách đó trong phản hồi ProxyEndpoint, trong một luồng đặ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 khách yêu cầu, điều này đảm bảo rằng tất cả cá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. Thao tác này chỉ được thực hiện trong quy trình 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 có thành công hay không, bạn có thể đặt các chính sách MessageLogging trong PostClientFlow và đảm bảo rằng các chính sách này luôn được thực thi.

Hình ảnh Dấu vết sau đây cho thấy chính sách MessageLogging đang thực thi trong 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 lại 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 tính năng ghi nhật ký để đưa vào các biến, 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à yêu cầu được gửi từ đó, v.v. Thông báo nhật ký Edge không đồng bộ, nghĩa là không có độ trễ nào có thể do các lệnh gọi chặn được giới thiệu đến API của bạn.

Chính sách MessageLogging ghi các thông báo đã ghi vào bộ nhớ vào một vùng đệm. Trình ghi thông báo đọc thông báo từ vùng đệm rồi ghi vào đích đến mà bạn định cấu hình. Mỗi đích đến đều có vùng đệm riêng.

Người dùng có thể gặp phải tình trạng chậm trễ khi nhận được thông báo nhật ký gửi đến một điểm cuối syslog mới. Điều này là do hành vi "khởi động nguội" dự kiến trong chính sách. Khi một đích ghi nhật ký mới được định cấu hình, ngoài(các) đích ghi nhật ký hiện có, Trình xử lý thông báo (MP) có thể xếp hàng 1.000 thông báo nhật ký trong bộ nhớ trước khi gửi. Điều này có thể dẫn đến sự chậm trễ ban đầu trong môi trường có lưu lượng truy cập thấp. Độ trễ ban đầu này không thể quan sát được đối với các khối lượng công việc sản xuất thông thường, vì các thông báo sẽ tích luỹ nhanh chóng. Sau khi đạt đến ngưỡng này, các thông báo nhật ký sẽ được gửi như dự kiến. Việc thực hiện quy trình khởi động lại Message Processor (Bộ xử lý tin nhắn) một cách suôn sẻ cũng có thể kích hoạt việc gửi các tin nhắn trong hàng đợi khi chúng được rút ra khỏi hàng đợi.

Nếu tốc độ ghi vào vùng đệm tăng vượt quá tốc độ đọc, thì vùng đệm sẽ tràn và quá trình ghi nhật ký sẽ không thành công. Nếu điều 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 phải 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à sử dụng giải pháp này:

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 cho Đám mây riêng tư 4.16.01 trở lên, hãy đặt thuộc tính conf/message-logging.properties+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. Xin lưu ý rằng theo mặc định, thuộc tính này ban đầu sẽ được nhận xét.

Lưu ý: Bạn không thể sử dụng các biến thông báo phản hồi trong Edge từ Luồng lỗi. Những biến này cũng không có trong PostClientFlow nếu luồng trước đó là Error Flow. Nếu bạn muốn ghi lại thông tin phản hồi từ PostClientFlow, hãy sử dụng đối tượng message. Bạn có thể sử dụng đối tượng này để lấy tiêu đề và thông tin khác từ phản hồi, bất kể 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 báo nhật ký trong Edge for Private Cloud

Theo mặc định, dấu thời gian trong tất cả thông báo 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 trên toàn hệ thống này cho các đích đến syslog 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 có 4 chữ số, MM sẽ được thay thế bằng số tháng có 2 chữ số, v.v. Định dạng ở trên có thể dẫn đến một chuỗi có dạng như sau:

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 có 2 chữ số, ghi lại dấu thời gian ở dạng:

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

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

1. Mở tệp message-processor.properties trong một trình chỉnh sửa. Nếu tệp không 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 theo ý muốn:
   conf_system_apigee.syslogger.dateFormat=yy/MM/dd'T'HH:mm:ss.SSSZ
3. Lưu 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ý thông báo Edge:
   > /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Vị trí tệp nhật ký trong Edge cho Private Cloud

Edge for Private Cloud 4.16.01 trở lên

Theo mặc định, nhật ký tin nhắn của Đám mây riêng tư nằm trong thư mục sau trên các nút Bộ xử lý tin nhắn:

/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í nhật ký mặc định bằng cách sửa đổi các thuộc tính trong tệp message-logging.properties trên Bộ xử lý thông báo:

• bin_setenv_data_dir – Đặt đường dẫn gốc cho bộ nhớ tệp nhật ký. Ví dụ: bin_setenv_data_dir=/opt/apigee/var/log
• conf_message-logging_log.root.dir – Nếu bạn đặt giá trị 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 đặt giá trị 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, 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 đượ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-logging.properties+log.root.dir vì theo mặc định, thuộc tính này sẽ bị bình luận. Xem phần Đặt một mã thông báo hiện đang được bình luận để biết thêm.

Nếu bạn muốn lưu trữ các tệp nhật ký trong 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 conf/message-logging.properties+enable.flat.directory.structure thành true trong tệp message-logging.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 một trình chỉnh sửa. Nếu tệp không 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 theo ý muốn:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Lưu 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 for Private Cloud 4.15.07 trở xuống

Theo mặc định, nhật ký thông báo nằm ở vị trí sau trên các 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í nhật ký mặc định bằng cách sửa đổi các thuộc tính sau trong tệp message-logging.properties trên các trình xử lý thông báo:

• data.dir – Đặt đường dẫn gốc để lưu trữ tệp nhật ký. Ví dụ: data.dir=/opt/apigee4/var/log
• log.root.dir – Nếu bạn đặt giá trị 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 thêm vào vị trí data.dir.

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

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, 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 sẽ được ưu tiên hơn data.dir.

Nếu bạn muốn lưu trữ tệp nhật ký trong cấu trúc tệp phẳng để tất cả tệp nhật ký đượ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-logging.properties trên Bộ xử lý thông báo. Các 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}.

Giá trị mặc định cho các biến trong mẫu tin nhắn

Bạn có thể chỉ định giá trị mặc định riêng cho từng biến trong mẫu tin nhắn. Ví dụ: nếu không thể phân giải biến request.header.id, 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 tất cả các biến chưa được phân giải bằng cách đặt 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 các 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 syslog đến các dịch vụ quản lý nhật ký của bên thứ ba, chẳng hạn như Splunk, Sumo Logic và Loggly. Nếu bạn muốn gửi syslog đế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ử Syslog trên chính sách này cho phù hợp.

Hãy 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 sản phẩm)
  Xem thêm bài đăng này trên Cộng đồng Apigee: Ghi thông báo vào nhật ký trong Splunk
• Sumo Logic
  • Ngoài ra, hãy xem bài đăng này trên Cộng đồng Apigee: Thiết lập tính năng ghi nhật ký bằng Sumo Logic, tôi nên dùng máy chủ lưu trữ nào?
  • Để xem ví dụ đầy đủ về cách sử dụng Sumo Logic làm dịch vụ ghi nhật ký, hãy xem bài đăng sau đây trên Cộng đồng Apigee. Giải pháp này sử dụng một chính sách JavaScript duy nhất để đưa ra các yêu cầu HTTP POST cho Sumo Logic HTTP Source Collector: Ghi nhật ký vào Sumo Logic bằng JavaScript và HTTP
• Loggly
  Khi sử dụng Loggly, bạn phải có <FormatMessage>true</FormatMessage> trong chính sách dưới dạng phần tử con của phần tử <Syslog>.
  Bạn cũng có thể xem bài đăng này trên Cộng đồng Apigee để biết thêm thông tin về việc ghi nhật ký thông báo vào Loggly: Ghi nhật ký thông báo vào Loggly

Tham chiếu lỗi

Phần này mô tả các 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 nếu bạn đang phát triển các quy tắc lỗi để xử lý lỗi. Để tìm hiểu thêm, 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à Xử lý lỗi.

Lỗi thời gian chạy

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

Lỗi triển khai

Những lỗi này có thể xảy ra khi bạn triển khai 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 khi gặp 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 khi chính sách không được tuân thủ.

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

Chủ đề có liên quan

• Các biến do Edge hiển thị: Tham chiếu biến