spotflow_logger/lib.rs
1//! An unofficial [Spotflow Observability Platform](https://spotflow.io) client.
2//!
3//! # Overview
4//!
5//! This crate provides a simple API for logging messages to the Spotflow Observability Platform.
6//! It could be used directly or as an integration with [tracing](https://docs.rs/tracing) crate.
7//! For tracing it provides a [tracing-subscriber](https://docs.rs/tracing-subscriber) `Layer`.
8//!
9//! Current implementation is `std` and requires `async` environment.
10//!
11//! # Examples
12//!
13//! ```rust
14//! let (spotflow_logger, spotflow_task, spotflow_stopper) = SpotflowLogger::builder()
15//! // name of device to be displayed in Spotflow Observability Platform
16//! .set_device_id("test1")
17//! // spotflow ingest key from https://app.spotflow.io/ingest-keys
18//! .set_password(mqtt_password)
19//! .build();
20//!
21//! // spawn task handling MQTT communication with spotflow platform
22//! let spotflow_task = task::spawn(spotflow_task);
23//!
24//! // register client with tracing-subscriber
25//! tracing_subscriber::registry()
26//! .with(LevelFilter::INFO)
27//! .with(spotflow_logger)
28//! .init();
29//!
30//! tracing::info!("test message");
31//!
32//! // send a request to finish `spotflow_task`
33//! spotflow_stopper.stop().unwrap();
34//! // join the `spotflow_task`
35//! _ = spotflow_task.await;
36//! ```
37//!
38//! # API
39//!
40//! The entry point to this crate is [`SpotflowLogger::builder`], which creates a
41//! [`SpotflowLoggerBuilder`] instance.
42//!
43//! # Unresolved Issues
44//!
45//! Currently there are following issues:
46//!
47//! - Errors during log line send or processing are suppressed.
48//!
49//! - MQTT QoS is forced to be `AtMostOnce`.
50//!
51//! - `TRACE` log level is mapped to `DEBUG` since spotflow does not support `TRACE`.
52//!
53//! - Some large integral types like `u128` are not supported for `cbor`.
54//!
55//! - Tracing `span` and `instrument` are not supported.
56//!
57//! - `no_std` environment is not supported.
58//!
59//! # Feature Flags
60//!
61//! Following features are supported:
62//!
63//! - `cbor` (on by default). Uses [CBOR](https://cbor.io) object representation for log messages.
64//! This feature flag is mutually exclusive with `json`.
65//!
66//! - `json`. Uses [JSON](https://www.json.org) format for log messages. This feature flag is mutually
67//! exclusive with `cbor`.
68//!
69//! - `tracing`. Provides additianal API for [tracing](https://docs.rs/tracing) crate integration.
70//!
71
72mod builder;
73#[cfg(feature = "cbor")]
74mod cbor;
75mod error;
76#[cfg(feature = "json")]
77mod json;
78mod logger;
79mod logline;
80
81pub use crate::{
82 builder::SpotflowLoggerBuilder,
83 error::SpotflowError,
84 logger::SpotflowLogger,
85 logline::{LabelName, LabelValue, LogLine, Severity},
86};
87
88#[cfg(all(feature = "cbor", feature = "json"))]
89compile_error!("Features \"cbor\" and \"json\" are mutually exclusive.");