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

Bạn đang xem tài liệu về Apigee Edge.
Chuyển đến 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 các vấn đề 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 để ghi nhật ký các thông báo tuỳ chỉnh vào một ổ đĩa cục bộ (chỉ Edge dành cho dịch vụ đám mây riêng tư) hoặc 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ử

Sử dụng các thành phần 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 của 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 khách hàng đưa ra yêu cầu. Việc này giúp đảm bảo rằng tất cả các chỉ số đều có sẵn để ghi nhật ký. Để biết 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 ở hai cách:

1. Hoạt động này chỉ được thực thi 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.

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

Hình ảnh theo dõi sau đây cho thấy một chính sách MessageLogging đang được thực thi như một phần của 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 mã 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 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 ghi nhật ký để thêm 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 về nhật ký Edge không đồng bộ, nghĩa là không có độ trễ có thể do việc chặn chú thích được đưa ra cho API của bạn.

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

Nếu tốc độ ghi vào bộ đệm tăng vượt quá tốc độ đọc, bộ đệm sẽ bị tràn và thì việc 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 có chứa nội dung sau trong nhật ký tệp:

Log message size exceeded. Increase the max message size setting

Nếu bạn gặp phải vấn đề này trong Edge dành cho Private Cloud 4.15.07 trở xuống, hãy tìm 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 message-logging.properties.

Đối với Edge dành cho Private Cloud phiên bản 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ư. Xin lưu ý rằng ban đầu, tài sản này được nhận xét theo mặc định.

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

Kiểm soát thông điệp nhật ký dấu thời gian 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 trên toàn hệ thống này cho các đích 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ế có năm gồm 4 chữ số, thì MM sẽ được thay thế 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 sau:

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

Bạn có thể sử dụng conf_system_apigee.syslogger.dateFormat trên Edge Message Processor để kiểm soát định dạng đó. Ví dụ: thay đổi thông điệp định dạng 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 theo 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 chưa tồn tại, hãy tạo tệp:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Đặt 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 rằng tệp thuộc tính thuộc sở hữu của "apigee" người dùng:
   > chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
5. Khởi động lại Trình xử lý thư của Edge:
   > /opt/apigee/apigee-service/bin/apigee-service Edge-message-processor khởi động lại

Vị trí tệp ghi nhật ký trên Edge dành cho Cloud riêng tư

Edge dành cho Private Cloud 4.16.01 trở lên

Theo mặc định, nhật ký thông báo trên Đám mây riêng tư nằm trong thư mục sau trên ứng dụng Tin nhắn Nút đơn vị xử lý:

/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 thuộc tính trong tệp message-logging.properties trên Bộ xử lý thư:

• bin_setenv_data_dir – Thiết lập đườ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-logging_log.root.dir - Nếu bạn thiết lập 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, tin nhắn nhật ký 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.
  
  Lưu ý rằng bạn phải tham chiếu thuộc tính dưới dạng conf/message-logging.properties+log.root.dir vì thì theo mặc định, khung nhìn đó sẽ được nhận xét. Hãy xem phần Cài đặt hiện đã được nhận xét để tìm hiểu 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ý được đặt trong cùng thư mục, hãy đặt conf/message-logging.properties+enable.flat.directory.structure thành true trong tệp message-logging.properties. Thư được lưu trữ trong thư mục được chỉ định bởi các thuộc tính trên 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 chưa tồn tại, hãy tạo tệp:
   > vi /opt/apigee/customer/application/message-processor.properties
2. Đặt thuộc tính như mong muốn:
   conf/message-logging.properties+log.root.dir=/opt/apigee/var/log/messages
3. Lưu các thay đổi.
4. Đảm bảo rằng tệp thuộc tính thuộc sở hữu của "apigee" người dùng:
   > 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 khởi động lại

Edge dành cho 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 thông báo bộ xử lý:

/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 phần tệp message-logging.properties trên trình xử lý thư:

• data.dir – Đặt thư mục 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 URL này dẫn đến một đường dẫn tương đối, chẳng hạn như log.root.dir=custom/folder/, thì đường dẫn này sẽ được thêm vào vị trí data.dir.

Ví dụ: sự kết hợp giữa hai thuộc tính sẽ đặt thư mục ghi nhật ký ở /opt/apigee4/var/log/custom/folder/messagelog/ (lưu ý rằng /messagelog sẽ đượ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, nhật ký tin nhắn 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 cấu trúc tệp phẳng để tất cả các tệp nhật ký được đặt trong cùng 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 thư Bộ xử lý. Thư được lưu trữ trong thư mục do các thuộc tính ở trên chỉ định và tệp tên 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 cho từng biến trong mẫu thông báo một cách riêng biệt. 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ế với 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 giải quyết bằng cách đặt giá trị 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 phần 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 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ụ, rồi đặt phần tử Nhật ký hệ thống 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)
  Ngoài ra, hãy 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
• Sumo Logic
  • 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-logging-with-sumo-logic-which-host-shou.html
  • Để biết ví dụ hoàn chỉnh về cách sử dụng Sumo Logic làm dịch vụ ghi nhật ký, hãy xem phần sau đây Bài đăng trên thẻ Cộng đồng Apigee. Giải pháp này sử dụng một chính sách JavaScript duy nhất để tạo yêu cầu POST qua HTTP yêu cầu đến Trình thu thập nguồn HTTP Sumo Logic: https://community.apigee.com/articles/32286/logging-to-sumo-logic-using-javascript-and-http.html
• Loggly
  Khi sử dụng Loggly, phải có <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ả 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 được điền sẵn khi không tuân thủ chính sách.

• 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