Set up tracing.

Cargo.toml

@@ -36,6 +36,16 @@ tree-sitter-highlight = "0.25.2"
 tree-sitter-nix = "0.0.2"
 tree-sitter-python = "0.23.6"
 url = "2.5.0"
+tracing = { version = "0.1.37", optional = true }
+tracing-opentelemetry = { version = "0.20.0", optional = true }
+tracing-subscriber = { version = "0.3.17", optional = true, features = ["env-filter"] }
+opentelemetry = { version = "0.20.0", optional = true, default-features = false, features = ["trace", "rt-tokio"] }
+opentelemetry-otlp = { version = "0.13.0", optional = true }
+opentelemetry-semantic-conventions = { version = "0.12.0", optional = true }
+
+[features]
+default = ["tracing"]
+tracing = ["dep:opentelemetry", "dep:opentelemetry-otlp", "dep:opentelemetry-semantic-conventions", "dep:tracing", "dep:tracing-opentelemetry", "dep:tracing-subscriber"]
 
 # Optimized build for any sort of release.
 [profile.release-lto]

TODO.org

@@ -1,4 +1,4 @@
-* Things to do [4/14]
+* Things to do [5/14]
 ** DONE If the paragraph only contains an image, text-align center
 ** DONE Syntax highlighting for code blocks
 ** TODO Render gnuplot
@@ -8,7 +8,7 @@
 ** TODO Support references to code block lines
 ** TODO Only include text up to first heading on homepage and include a "read more" link
 ** DONE Make loading language-specific CSS files conditional on the presence of src blocks using those languages
-** TODO Set up tracing so I can use warning and such
+** DONE Set up tracing so I can use warning and such
 ** TODO Make copying of language-specific CSS files conditional on the presence of src blocks using those languages
 ** TODO Switch to an entirely lazily-evaluated output tree
 ** TODO Add highlighting for languages [1/2]

src/init_tracing.rs

@@ -0,0 +1,88 @@
+#[cfg(feature = "tracing")]
+use opentelemetry_otlp::WithExportConfig;
+#[cfg(feature = "tracing")]
+use tracing::warn;
+#[cfg(feature = "tracing")]
+use tracing_subscriber::fmt;
+#[cfg(feature = "tracing")]
+use tracing_subscriber::prelude::__tracing_subscriber_SubscriberExt;
+#[cfg(feature = "tracing")]
+use tracing_subscriber::util::SubscriberInitExt;
+
+const SERVICE_NAME: &str = "natter";
+
+// Despite the obvious verbosity that fully-qualifying everything causes, in these functions I am fully-qualifying everything relating to tracing. This is because the tracing feature involves multiple libraries working together and so I think it is beneficial to see which libraries contribute which bits.
+
+#[cfg(feature = "tracing")]
+pub(crate) fn init_telemetry() -> Result<(), Box<dyn std::error::Error>> {
+    let log_to_console = fmt::layer();
+    let subscriber = tracing_subscriber::Registry::default();
+    let level_filter_layer = tracing_subscriber::EnvFilter::try_from_default_env()
+        .unwrap_or(tracing_subscriber::EnvFilter::new("WARN"));
+
+    // by default it will hit http://localhost:4317 with a gRPC payload
+    // TODO: I think the endpoint can be controlled by the OTEL_EXPORTER_OTLP_TRACES_ENDPOINT env variable instead of hard-coded into this code base. Regardless, I am the only developer right now so I am not too concerned.
+    let exporter = opentelemetry_otlp::new_exporter()
+        .tonic()
+        // Using "localhost" is broken inside the docker container when tracing
+        .with_endpoint("http://127.0.0.1:4317/v1/traces");
+
+    let tracer = opentelemetry_otlp::new_pipeline()
+        .tracing()
+        .with_exporter(exporter)
+        .with_trace_config(opentelemetry::sdk::trace::config().with_resource(
+            opentelemetry::sdk::Resource::new(vec![opentelemetry::KeyValue::new(
+                opentelemetry_semantic_conventions::resource::SERVICE_NAME,
+                SERVICE_NAME.to_string(),
+            )]),
+        ))
+        // If I do install_batch then 1K+ spans will get orphaned off into their own trace and I get the error message "OpenTelemetry trace error occurred. cannot send message to batch processor as the channel is closed"
+        //
+        // If I do install_simple then it only creates 1 trace (which is good!) but my console gets spammed with this concerning log message that makes me think it might be dropping the extra spans on the floor: "OpenTelemetry trace error occurred. Exporter otlp encountered the following error(s): the grpc server returns error (Unknown error): , detailed error message: Service was not ready: transport error"
+        //
+        // I suspect it is related to this bug: https://github.com/open-telemetry/opentelemetry-rust/issues/888
+        //
+        // .install_simple()
+        .install_batch(opentelemetry::runtime::Tokio);
+
+    let tracing_layer = tracer.map(|tracer| tracing_opentelemetry::layer().with_tracer(tracer));
+
+    opentelemetry::global::set_text_map_propagator(
+        opentelemetry::sdk::propagation::TraceContextPropagator::new(),
+    );
+
+    match tracing_layer {
+        Ok(tracing_layer) => {
+            subscriber
+                .with(level_filter_layer)
+                .with(tracing_layer)
+                .with(log_to_console)
+                .try_init()?;
+        }
+        Err(e) => {
+            subscriber
+                .with(level_filter_layer)
+                .with(fmt::layer())
+                .try_init()?;
+            warn!("Failed initialize OpenTelemetry tracing: {}", e);
+        }
+    };
+
+    Ok(())
+}
+
+#[cfg(feature = "tracing")]
+pub(crate) fn shutdown_telemetry() -> Result<(), Box<dyn std::error::Error>> {
+    opentelemetry::global::shutdown_tracer_provider();
+    Ok(())
+}
+
+#[cfg(not(feature = "tracing"))]
+pub(crate) fn init_telemetry() -> Result<(), Box<dyn std::error::Error>> {
+    Ok(())
+}
+
+#[cfg(not(feature = "tracing"))]
+pub(crate) fn shutdown_telemetry() -> Result<(), Box<dyn std::error::Error>> {
+    Ok(())
+}

src/main.rs

@@ -8,11 +8,14 @@ use self::cli::parameters::Commands;
 use self::command::build::build_site;
 use self::command::init::init_natter_folder;
 use self::error::CustomError;
+use self::init_tracing::init_telemetry;
+use self::init_tracing::shutdown_telemetry;
 mod cli;
 mod command;
 mod config;
 mod context;
 mod error;
+mod init_tracing;
 mod intermediate;
 mod render;
 mod walk_fs;
@@ -23,6 +26,7 @@ fn main() -> Result<ExitCode, CustomError> {
 }
 
 async fn main_body() -> Result<ExitCode, CustomError> {
+    init_telemetry().expect("Telemetry should initialize successfully.");
     let args = Cli::parse();
     match args.command {
         Commands::Init(args) => {
@@ -32,5 +36,6 @@ async fn main_body() -> Result<ExitCode, CustomError> {
             build_site(args).await?;
         }
     };
+    shutdown_telemetry().expect("Telemetry should shutdown successfully.");
     Ok(ExitCode::SUCCESS)
 }