httplog 技术文档

2024-12-26 09:44:47作者：蔡丛锟

1. 安装指南

httplog 是一个用于记录应用程序发出的 HTTP 请求的 Ruby gem。它可以帮助调试 API 错误响应，或者简单地了解应用程序底层的 HTTP 请求情况。

安装步骤

要安装 httplog，请使用以下命令：

gem install httplog

环境要求

httplog 需要 Ruby 2.6 或更高版本。

2. 项目的使用说明

基本使用

在项目中引入 httplog，并确保在引入 HTTP 库之后引入 httplog：

require 'httplog'

默认情况下，httplog 会将所有发出的 HTTP 请求及其响应记录到 $stdout，日志级别为 DEBUG。

内容类型注意事项

二进制数据（由 Content-Type 头指示）不会被记录。
文本数据（如 text/* 和大多数 application/* 类型）会被编码为 UTF-8，无效字符会被替换。

3. 项目 API 使用文档

配置选项

httplog 提供了丰富的配置选项，可以通过以下方式进行配置：

HttpLog.configure do |config|
  # 启用或禁用所有日志记录
  config.enabled = true

  # 指定日志记录器或日志记录方法
  config.logger = Logger.new($stdout)
  config.logger_method = :log

  # 日志级别
  config.severity = Logger::Severity::DEBUG

  # 配置记录哪些 HTTP 请求部分
  config.log_connect   = true
  config.log_request   = true
  config.log_headers   = false
  config.log_data      = true
  config.log_status    = true
  config.log_response  = true
  config.log_benchmark = true

  # 将所有请求记录为单行
  config.compact_log = false

  # 以 JSON 格式记录日志
  config.json_log = false

  # 美化输出
  config.color = false

  # 根据 URL 模式限制日志记录
  config.url_whitelist_pattern = nil
  config.url_blacklist_pattern = nil

  # 屏蔽请求和响应 JSON 数据中的敏感信息
  config.url_masked_body_pattern = nil

  # 指定自定义的 JSON 解析器
  config.json_parser = JSON

  # Graylog 日志格式配置
  config.graylog_formatter = nil

  # 屏蔽敏感请求参数
  config.filter_parameters = %w[password]

  # 自定义日志前缀
  config.prefix = ->{ "[httplog] #{Time.now} " }
end

Rails 应用中的配置

在 Rails 应用中，建议根据环境进行配置。不要在全局初始化器中配置 httplog，因为在生产环境中 HttpLog 可能未定义。

# config/environments/development.rb

HttpLog.configure do |config|
  config.logger = Rails.logger
end

颜色化输出

你可以通过以下方式为日志输出添加颜色：

HttpLog.configure do |config|
  config.color = :red
end

或者为文本和背景指定颜色：

HttpLog.configure do |config|
  config.color = {color: :black, background: :yellow}
end

Graylog 日志记录

如果你使用 Graylog，可以通过以下配置使用其搜索功能：

FORMATTER = Lograge::Formatters::KeyValue.new

HttpLog.configure do |config|
  config.logger            = <your GELF::Logger>
  config.logger_method     = :add
  config.severity          = GELF::Levels::DEBUG
  config.graylog_formatter = FORMATTER
end

紧凑日志记录

如果你觉得日志过于冗长，可以启用紧凑日志记录：

HttpLog.configure do |config|
  config.compact_log = true
end

JSON 日志记录

如果你希望以 JSON 格式记录日志，可以启用 JSON 日志记录：

HttpLog.configure do |config|
  config.json_log = true
end

参数过滤

你可以通过以下方式过滤敏感参数：

HttpLog.configure do |config|
  config.filter_parameters = %w[password]
end

4. 项目安装方式

通过 Gemfile 安装

如果你使用 Bundler 管理依赖，可以在 Gemfile 中添加以下内容：

gem 'httplog'

然后运行 bundle install 安装 gem。

直接安装

你也可以通过以下命令直接安装 httplog：

gem install httplog

5. 示例

以下是一个使用默认配置的日志输出示例：

[httplog] Connecting: localhost:80
[httplog] Sending: GET http://localhost:9292/index.html
[httplog] Status: 200
[httplog] Benchmark: 0.00057 seconds
[httplog] Response:
<html>
  <head>
    <title>Test Page</title>
  </head>
  <body>
    <h1>This is the test page.</h1>
  </body>
</html>