cleanup docs and enable DEBUG logs for debug builds

Dockerfile

@@ -47,9 +47,6 @@ RUN cargo build --release --features ${FEATURES} --bin heartbeat
 
 FROM scratch
 
-# Log level for tracing-subscriber
-ARG RUST_LOG=info
-
 # Labels
 # Reference: https://github.com/opencontainers/image-spec/blob/main/annotations.md
 LABEL org.opencontainers.image.source "https://github.com/lmaotrigine/heartbeat"
@@ -62,7 +59,6 @@ COPY --from=build /usr/src/app/target/release/heartbeat /usr/local/bin/heartbeat
 COPY --from=build /usr/src/app/static /usr/local/share/heartbeat/static
 
 WORKDIR /usr/local/share/heartbeat
-ENV RUST_LOG=${RUST_LOG}
 
 # test if the binary works
 RUN [ "/usr/local/bin/heartbeat", "--version" ]

clippy.toml

@@ -15,3 +15,7 @@ reason = "LinkedList is slow and almost never the right choice."
 [[disallowed-types]]
 path = "ring::digest::SHA1_FOR_LEGACY_USE_ONLY"
 reason = "SHA-1 is cryptographically broken"
+
+[[disallowed-methods]]
+path = "tracing_subscriber::fmt::init"
+reason = "Use heartbeat::init_logging instead."

docs/server.md

@@ -76,6 +76,12 @@ docs](https://github.com/launchbadge/sqlx/blob/v0.7.1/sqlx-cli/README.md).
 For starting fresh, you can simple use the [`init.sql`](/docker-entrypoint-initdb.d/init.sql) script to create the
 necessary tables and indexes in your database.
 
+## Logging
+
+By default, the library emits `tracing` spans with `INFO` and lower verbosity on release builds and `DEBUG` and lower on
+debug builds. This can be configured using the `RUST_LOG` environment variable. See the
+[documentation](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/fmt/index.html#filtering-events-with-environment-variables)
+for more information.
 
 ## Running in production
 

docs/usage.md

@@ -45,7 +45,7 @@ You can open `localhost:6060` in a browser to see the webpage.
 - Can't connect when running the binary directly
 
   If running the binary is not throwing any errors, make sure you are connecting to the correct address and port as
-  configured in Rocket.toml.
+  configured.
 
 - Can't read the config file in Docker
 

src/bin/migrate_db.rs

@@ -24,7 +24,7 @@ struct Config {
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    tracing_subscriber::fmt::init();
+    heartbeat::init_logging();
     color_eyre::install()?;
     let conf = Config::parse();
     let dsn = if let Some(dsn) = conf.database_dsn {

src/bin/web.rs

@@ -26,7 +26,7 @@ use heartbeat::{handle_errors, routes::router, AppState, Config};
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    tracing_subscriber::fmt::init();
+    heartbeat::init_logging();
     color_eyre::install()?;
     let config = Config::try_new()?;
     info!(config = ?config, "Loaded config");

src/lib.rs

@@ -16,6 +16,8 @@ use parking_lot::Mutex;
 use sqlx::{postgres::PgPoolOptions, PgPool};
 use stats::Stats;
 use std::sync::Arc;
+use tracing::Level;
+use tracing_subscriber::util::SubscriberInitExt;
 use traits::PoolExt;
 
 mod auth;
@@ -35,6 +37,22 @@ pub use error::handle_errors;
 /// Crate version and git commit hash.
 pub const VERSION: &str = env!("HB_VERSION");
 
+/// Like [`tracing_subscriber::fmt::init`], but defaults to DEBUG on
+/// debug builds.
+pub fn init_logging() {
+    let level = std::env::var("RUST_LOG")
+        .map_err(|_| ())
+        .and_then(|s| s.parse().map_err(|_| ()))
+        .unwrap_or({
+            if cfg!(debug_assertions) {
+                Level::DEBUG
+            } else {
+                Level::INFO
+            }
+        });
+    tracing_subscriber::fmt().with_max_level(level).finish().init();
+}
+
 /// Global application state.
 #[derive(Debug, Clone, FromRef)]
 pub struct AppState {