Rocket Slogger

为 Rocket Web 框架提供结构化日志记录中间件。

当此公平处理程序（中间件）附加到 Rocket 实例时，将自动为每个接收到的请求和每个发送的响应生成详细的日志消息。记录器还可以注入到单个路由中，以在请求时生成额外的自定义日志。

启动时，所有配置都会显示为初始日志消息。这不仅列出了当前配置，还可以作为 Web 服务器已启动/重启的某种信号。接下来是有关可用路由的日志消息，然后是错误状态捕获器之一，然后是服务器正在监听的主机和端口。

设置

需要 Rust 工具链。有关安装说明，请参阅 https://rustup.rs/。

将此 crate 添加到您的 Rust 项目

rocket-slogger = "0.1.0"

快速入门

使用兼容 slog 的 Logger 实例化公平处理程序（中间件），然后将其添加到您的 Rocket 服务器

// Wrap your `slog`-compatible Logger with the fairing
let fairing = Slogger::from_logger(logger);

// Load config from the usual places, such as Rocket.toml and the environment
let mut config = Config::from(Config::figment());

// The fairing does not turn off Rocket's pretty print logs by default
config.log_level = LogLevel::Off;

rocket::custom(config)
    .attach(fairing)
    ...

当启用 terminal 功能时

辅助函数 Slogger::new_terminal_logger() 将设置记录器以输出如下所示的纯文本日志消息

Mar 15 04:32:00.815 INFO Request, method: GET, path: /, content-type: None, user-agent: vscode-restclient

Mar 15 04:32:00.815 INFO Response, size: 11, method: GET, path: /, route: always_greet, rank: -9, code: 200, reason: OK, content-type: text/plain; charset=utf-8

当启用 bunyan 功能时

辅助函数 Slogger::new_bunyan_logger() 将设置记录器以输出如下所示的 bunyan-style JSON 对象

{"msg":"Request","v":0,"name":"My App","level":30,"time":"2023-03-15T04:29:35.865466064Z","hostname":"my-computer","pid":810142,"method":"GET","path":"/","content-type":null,"user-agent":"vscode-restclient"}

{"msg":"Response","v":0,"name":"My App","level":30,"time":"2023-03-15T04:29:35.867971878Z","hostname":"my-computer","pid":810142,"method":"GET","path":"/","route":"always_greet","rank":-9,"code":200,"reason":"OK","content-type":"text/plain; charset=utf-8","size":11}

否则，可以使用 Slogger 公平处理程序与任何兼容 slog 的 Logger 构建公平处理程序，使用 Slogger::from_logger(logger)。

示例

在./examples文件夹中，有各种配置下附加了此日志中间件的Rocket网络服务器的最小实现。

请注意，某些示例需要启用功能。

例如，运行bunyan-callbacks-features的命令是：cargo run --example bunyan-callbacks-features --features bunyan,callbacks。

详细信息

对于收到的每个请求，都会生成包含以下信息的日志消息

• HTTP方法（例如get、post、put等）
• URL路径（例如/path/to/route?query=string）
• 请求的Content-Type头
• 用户代理

对于发送的每个响应，都会生成包含以下信息的日志消息

• HTTP方法
• URL路径
• 响应的Content-Type头
• 状态码和原因
• 响应体大小

当启用transactions功能时

对于收到的每个请求，除了上述信息外，还会生成以下信息

• 中间件接收到请求时的精确UTC日期和时间以及时区。
• 一个唯一的UUID，它将在关联日志时对所有由单个请求生成的日志相同。

对于发送的每个响应，除了上述信息外，还会生成以下信息

• 中间件最初接收到请求时的相同时间。
• 相同的唯一UUID，将响应日志关联到请求日志。
• 中间件接收到请求到接收到响应的总耗时（纳秒）。

当启用local_time功能时

中间件接收到请求时的精确日期和时间以及时区显示为系统本地时区。

但是请注意，日志创建时的time字段仍然在UTC时区。

当启用callbacks功能时

可以在请求或响应上附加到公平（fairing）函数。

这些回调函数可以访问包含所有上述字段以及响应和/或请求引用的slog::Logger。这使得回调函数可以在生成日志消息之前返回具有任何新属性的相同或新的slog::Logger实例。

    Slogger::new_bunyan_logger(env!("CARGO_PKG_NAME"))
        .on_request(|logger, _request| {
            // currently requires a pinned box to have an async context
            Box::pin(async move {
                // here any async function calls or server state can be fetched
                // so that it can be added to the logger that will form the response log
                let new_logger = logger.new(rocket_slogger::log_fields!(
                    "field:from-closure" => "some dynamic data derived at request time",
                    "in:request" => "more dynamic metrics",
                ));

                // the new logger must be returned in an Option<Arc<Logger>>
                Some(Arc::new(new_logger))
            })
        })
        .on_response(|logger, _request, _response| {
            // currently requires a pinned box to have an async context
            Box::pin(async move {
                // here any async function calls or server state can be fetched
                // so that it can be added to the logger that will form the response log
                let new_logger = logger.new(rocket_slogger::log_fields!(
                    "field:from-closure" => "some dynamic data derived at response time",
                    "in:response" => "more dynamic metrics",
                ));

                // the new logger must be returned in an Option<Arc<Logger>>
                Some(Arc::new(new_logger))
            })
        })

Box::pin( async move { ... } )结构允许调用异步函数，例如执行数据库查询。

如果您知道提供更简洁或更简单的异步回调函数的方法，欢迎提出建议！