commit a60c530fd5d0e9fb5de9f151f043fe73bb6ff610 Author: Luca Palmieri Date: Sun Sep 27 16:27:51 2020 +0100 First release. diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..b47106786 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +/target +Cargo.lock +.idea diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..604cb3d10 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at rust@lpalmieri.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 000000000..2c747b654 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,26 @@ +[package] +name = "tracing-actix-web" +version = "0.1.0" +authors = ["Luca Palmieri "] +edition = "2018" + +license = "MIT/Apache-2.0" + +repository = "https://github.com/LukeMathWalker/tracing-actix-web" +documentation = "https://docs.rs/tracing-actix-web/" +readme = "README.md" + +description = "Structured logging middleware for actix-web." + +keywords = ["http", "actix-web", "tracing", "logging"] +categories = ["asynchronous", "web-programming"] + +[dependencies] +actix-web = "2" +tracing = "0.1.19" +tracing-futures = "0.2.4" +futures = "0.3.5" + +[dev-dependencies] +tracing-subscriber = { version = "0.2.12", features = ["registry", "env-filter"] } +tracing-bunyan-formatter = "0.1.6" diff --git a/LICENSE-APACHE b/LICENSE-APACHE new file mode 100644 index 000000000..16fe87b06 --- /dev/null +++ b/LICENSE-APACHE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/LICENSE-MIT b/LICENSE-MIT new file mode 100644 index 000000000..31aa79387 --- /dev/null +++ b/LICENSE-MIT @@ -0,0 +1,23 @@ +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 000000000..f0a921304 --- /dev/null +++ b/README.md @@ -0,0 +1,80 @@ +

tracing-actix-web

+
+ + Structured logging for actix-web applications. + +
+ +`tracing-actix-web` provides [`TracingLogger`], a middleware to log request and response info when using the [`actix-web`] framework. + +[`TracingLogger`] is designed as a drop-in replacement of [`actix-web`]'s [`Logger`]. + +[`Logger`] is built on top of the [`log`] crate: you need to use regular expressions to parse the request information out of the logged message. + +[`TracingLogger`] relies on [`tracing`], a modern instrumentation framework for structured logging: all request information is captured as a machine-parsable set of key-value pairs. +It also enables propagation of context information to children spans. + +## How to install + +Add `tracing-actix-web` to your dependencies: +```toml +[dependencies] +# ... +tracing-actix-web = "0.1" +``` +If you are using [`cargo-edit`](https://github.com/killercup/cargo-edit), run +```bash +cargo add tracing-actix-web +``` + +## Usage example + +Register `TracingLogger` as a middleware for your application using `.wrap` on `App`. +Add a `Subscriber` implementation to output logs to the console. + +```rust +use actix_web::middleware::Logger; +use actix_web::App; +use tracing::{Subscriber, subscriber::set_global_default}; +use tracing_actix_web::TracingLogger; +use tracing_bunyan_formatter::{BunyanFormattingLayer, JsonStorageLayer}; +use tracing_subscriber::{layer::SubscriberExt, EnvFilter, Registry}; + +/// Compose multiple layers into a `tracing`'s subscriber. +pub fn get_subscriber( + name: String, + env_filter: String +) -> impl Subscriber + Send + Sync { + let env_filter = EnvFilter::try_from_default_env() + .unwrap_or(EnvFilter::new(env_filter)); + let formatting_layer = BunyanFormattingLayer::new( + name.into(), + std::io::stdout + ); + Registry::default() + .with(env_filter) + .with(JsonStorageLayer) + .with(formatting_layer) +} + +/// Register a subscriber as global default to process span data. +/// +/// It should only be called once! +pub fn init_subscriber(subscriber: impl Subscriber + Send + Sync) { + LogTracer::init().expect("Failed to set logger"); + set_global_default(subscriber).expect("Failed to set subscriber"); +} + +fn main() { + let subscriber = get_subscriber("app".into(), "info".into()); + init_subscriber(subscriber); + + let app = App::new().wrap(TracingLogger); +} +``` + +[`TracingLogger`]: https://docs.rs/tracing-actix-web/0.1.0/tracing-actix-web/#struct.TracingLogger.html +[`actix-web`]: https://docs.rs/actix-web +[`Logger`]: https://docs.rs/actix-web/2.0.0/actix_web/middleware/struct.Logger.html +[`log`]: https://docs.rs/log +[`tracing`]: https://docs.rs/tracing diff --git a/src/lib.rs b/src/lib.rs new file mode 100644 index 000000000..a5c3b27b7 --- /dev/null +++ b/src/lib.rs @@ -0,0 +1,155 @@ +//! `tracing-actix-web` provides [`TracingLogger`], a middleware to log request and response info +//! when using the [`actix-web`] framework. +//! +//! [`TracingLogger`] is designed as a drop-in replacement of [`actix-web`]'s [`Logger`]. +//! +//! [`Logger`] is built on top of the [`log`] crate: you need to use regular expressions to parse +//! the request information out of the logged message. +//! +//! [`TracingLogger`] relies on [`tracing`], a modern instrumentation framework for structured +//! logging: all request information is captured as a machine-parsable set of key-value pairs. +//! It also enables propagation of context information to children spans. +//! +//! [`TracingLogger`]: #struct.TracingLogger.html +//! [`actix-web`]: https://docs.rs/actix-web +//! [`Logger`]: https://docs.rs/actix-web/2.0.0/actix_web/middleware/struct.Logger.html +//! [`log`]: https://docs.rs/log +//! [`tracing`]: https://docs.rs/tracing +use actix_web::dev::{Service, ServiceRequest, ServiceResponse, Transform}; +use actix_web::Error; +use futures::future::{ok, Ready}; +use futures::task::{Context, Poll}; +use std::future::Future; +use std::pin::Pin; +use tracing::Span; +use tracing_futures::Instrument; + +/// `TracingLogger` is a middleware to log request and response info in a structured format. +/// +/// `TracingLogger` is designed as a drop-in replacement of [`actix-web`]'s [`Logger`]. +/// +/// [`Logger`] is built on top of the [`log`] crate: you need to use regular expressions to parse +/// the request information out of the logged message. +/// +/// `TracingLogger` relies on [`tracing`], a modern instrumentation framework for structured +/// logging: all request information is captured as a machine-parsable set of key-value pairs. +/// It also enables propagation of context information to children spans. +/// +/// ## Usage +/// +/// Register `TracingLogger` as a middleware for your application using `.wrap` on `App`. +/// Add a `Subscriber` implementation to output logs to the console. +/// +/// ```rust +/// use actix_web::middleware::Logger; +/// use actix_web::App; +/// use tracing::{Subscriber, subscriber::set_global_default}; +/// use tracing_actix_web::TracingLogger; +/// use tracing_bunyan_formatter::{BunyanFormattingLayer, JsonStorageLayer}; +/// use tracing_subscriber::{layer::SubscriberExt, EnvFilter, Registry}; +/// +/// /// Compose multiple layers into a `tracing`'s subscriber. +/// pub fn get_subscriber( +/// name: String, +/// env_filter: String +/// ) -> impl Subscriber + Send + Sync { +/// let env_filter = EnvFilter::try_from_default_env() +/// .unwrap_or(EnvFilter::new(env_filter)); +/// let formatting_layer = BunyanFormattingLayer::new( +/// name.into(), +/// std::io::stdout +/// ); +/// Registry::default() +/// .with(env_filter) +/// .with(JsonStorageLayer) +/// .with(formatting_layer) +/// } +/// +/// /// Register a subscriber as global default to process span data. +/// /// +/// /// It should only be called once! +/// pub fn init_subscriber(subscriber: impl Subscriber + Send + Sync) { +/// LogTracer::init().expect("Failed to set logger"); +/// set_global_default(subscriber).expect("Failed to set subscriber"); +/// } +/// +/// fn main() { +/// let subscriber = get_subscriber("app".into(), "info".into()); +/// init_subscriber(subscriber); +/// +/// let app = App::new().wrap(TracingLogger); +/// } +/// ``` +/// +/// [`actix-web`]: https://docs.rs/actix-web +/// [`Logger`]: https://docs.rs/actix-web/2.0.0/actix_web/middleware/struct.Logger.html +/// [`log`]: https://docs.rs/log +/// [`tracing`]: https://docs.rs/tracing +pub struct TracingLogger; + +impl Transform for TracingLogger +where + S: Service, Error = Error>, + S::Future: 'static, + B: 'static, +{ + type Request = ServiceRequest; + type Response = ServiceResponse; + type Error = Error; + type Transform = TracingLoggerMiddleware; + type InitError = (); + type Future = Ready>; + + fn new_transform(&self, service: S) -> Self::Future { + ok(TracingLoggerMiddleware { service }) + } +} + +#[doc(hidden)] +pub struct TracingLoggerMiddleware { + service: S, +} + +impl Service for TracingLoggerMiddleware +where + S: Service, Error = Error>, + S::Future: 'static, + B: 'static, +{ + type Request = ServiceRequest; + type Response = ServiceResponse; + type Error = Error; + type Future = Pin>>>; + + fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll> { + self.service.poll_ready(cx) + } + + fn call(&mut self, req: ServiceRequest) -> Self::Future { + let user_agent = req + .headers() + .get("User-Agent") + .map(|h| h.to_str().unwrap_or("")) + .unwrap_or(""); + let span = tracing::info_span!( + "Request", + request_path = %req.path(), + user_agent = %user_agent, + client_ip_address = %req.connection_info().remote().unwrap_or(""), + status_code = tracing::field::Empty, + ); + let fut = self.service.call(req); + Box::pin( + async move { + let outcome = fut.await; + let status_code = match &outcome { + Ok(response) => response.response().status(), + Err(error) => error.as_response_error().status_code(), + }; + Span::current().record("status_code", &status_code.as_u16()); + outcome + } + .instrument(span), + ) + } +}