Skip to main content

grow_better_stack_logs/
client.rs

1// Skeleton created by sdk-kit 0.1.0; owned by this repository (edit freely).
2//! `BetterStackClient`: entry point of the SDK (SPEC §2.4, API.md §6, DECISIONS 4 and 5).
3
4use std::sync::{Arc, Once};
5use std::time::{Duration, Instant};
6
7use futures::future::BoxFuture;
8
9use crate::config::BetterStackConfig;
10use crate::core::lifecycle::CloseGroup;
11use crate::core::{Error, HealthStatus, HttpTransport, Result};
12use crate::exporter::{BetterStackLogExporter, IngestExporterOptions, MAX_REQUEST_BYTES};
13use crate::logging::{
14    Attributes, BatchOptions, BatchingLogClient, LogClient, LogExporter, RedactionProcessor,
15    Severity,
16};
17use crate::otlp::{BetterStackOtlpLogExporter, OtlpExporterOptions};
18use crate::query::BetterStackQuery;
19
20/// The batching [`LogClient`] returned by [`BetterStackClient::log_client`].
21pub type BetterStackLogClient = BatchingLogClient;
22
23static PLAIN_HTTP_WARNING: Once = Once::new();
24
25/// Wire protocol of [`BetterStackClient::log_client`].
26#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
27pub enum LogProtocol {
28    /// Better Stack HTTP ingest API (`POST /`, JSON / NDJSON / MessagePack). Default.
29    #[default]
30    Http,
31    /// OTLP/HTTP (`POST /v1/logs`).
32    Otlp,
33}
34
35/// Options of [`BetterStackClient::log_client`].
36#[derive(Clone)]
37pub struct LogClientOptions {
38    /// Batch options; `max_batch_bytes` is capped at the 10 MiB request limit.
39    pub batch: BatchOptions,
40    /// Resource attributes added to every record (`service.name`, …).
41    pub resource: Attributes,
42    /// Redaction applied to every record (default [`RedactionProcessor::default`]); `None`
43    /// disables it.
44    pub redaction: Option<RedactionProcessor>,
45    /// Minimum severity of loggers made by [`LogClient::logger`] (default `Info`).
46    pub min_severity: Severity,
47    /// HTTP ingest (default) or OTLP.
48    pub protocol: LogProtocol,
49    /// Encoding and limits of the HTTP exporter (protocol `Http`); default: the client's
50    /// shared exporter.
51    pub exporter: Option<IngestExporterOptions>,
52    /// Options of the OTLP exporter (protocol `Otlp`); default: the client's shared exporter.
53    pub otlp: Option<OtlpExporterOptions>,
54}
55
56impl Default for LogClientOptions {
57    fn default() -> Self {
58        LogClientOptions {
59            batch: BatchOptions::default(),
60            resource: Attributes::new(),
61            redaction: Some(RedactionProcessor::default()),
62            min_severity: Severity::Info,
63            protocol: LogProtocol::Http,
64            exporter: None,
65            otlp: None,
66        }
67    }
68}
69
70impl std::fmt::Debug for LogClientOptions {
71    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
72        f.debug_struct("LogClientOptions")
73            .field("batch", &self.batch)
74            .field("resource", &self.resource)
75            .field("redaction", &self.redaction.is_some())
76            .field("min_severity", &self.min_severity)
77            .field("protocol", &self.protocol)
78            .field("exporter", &self.exporter)
79            .field("otlp", &self.otlp)
80            .finish()
81    }
82}
83
84impl LogClientOptions {
85    /// Sets the batch options.
86    pub fn batch(mut self, batch: BatchOptions) -> Self {
87        self.batch = batch;
88        self
89    }
90    /// Adds one resource attribute.
91    pub fn resource_attribute(
92        mut self,
93        key: impl Into<String>,
94        value: impl Into<crate::logging::AttrValue>,
95    ) -> Self {
96        self.resource.insert(key.into(), value.into());
97        self
98    }
99    /// Sets the protocol.
100    pub fn protocol(mut self, protocol: LogProtocol) -> Self {
101        self.protocol = protocol;
102        self
103    }
104    /// Sets the HTTP exporter options.
105    pub fn exporter(mut self, opts: IngestExporterOptions) -> Self {
106        self.exporter = Some(opts);
107        self
108    }
109    /// Sets the OTLP exporter options (and selects OTLP).
110    pub fn otlp(mut self, opts: OtlpExporterOptions) -> Self {
111        self.protocol = LogProtocol::Otlp;
112        self.otlp = Some(opts);
113        self
114    }
115}
116
117/// Async client for Better Stack Logs. Cheap to clone (clones share the connections).
118///
119/// It talks to two hosts with separate credentials and transports: the source's ingesting host
120/// ([`log_client`](Self::log_client), [`exporter`](Self::exporter),
121/// [`otlp_exporter`](Self::otlp_exporter)) and the SQL query host ([`query`](Self::query)). A
122/// source token is never sent to the query host and SQL credentials never to the ingest host.
123///
124/// ```no_run
125/// # async fn demo() -> grow_better_stack_logs::Result<()> {
126/// use grow_better_stack_logs::logging::{attrs, LogClient};
127/// use grow_better_stack_logs::{BetterStackClient, LogClientOptions};
128///
129/// let client = BetterStackClient::from_env()?;
130/// let logs = client.log_client(LogClientOptions::default().resource_attribute("service.name", "checkout"))?;
131/// logs.logger(None, attrs! {}).info("order placed", attrs! { "order_id" => 42 });
132/// client.close().await;
133/// # Ok(()) }
134/// ```
135#[derive(Debug, Clone)]
136pub struct BetterStackClient {
137    inner: Arc<Inner>,
138}
139
140#[derive(Debug)]
141pub(crate) struct Inner {
142    pub(crate) config: BetterStackConfig,
143    pub(crate) ingest: Option<HttpTransport>,
144    pub(crate) query: Option<HttpTransport>,
145    pub(crate) on_close: CloseGroup,
146}
147
148impl Inner {
149    pub(crate) fn ingest_transport(&self, operation: &str) -> Result<&HttpTransport> {
150        self.ingest.as_ref().ok_or_else(|| {
151            Error::config(format!(
152                "{operation}: url (the source's ingesting host) and source_token are required for ingestion"
153            ))
154        })
155    }
156
157    pub(crate) fn query_transport(&self, operation: &str) -> Result<&HttpTransport> {
158        self.query.as_ref().ok_or_else(|| {
159            Error::config(format!(
160                "{operation}: query_url, query_username and query_password are required for SQL queries"
161            ))
162        })
163    }
164}
165
166impl BetterStackClient {
167    /// Creates a client from a configuration (`CONFIG` when invalid).
168    pub fn new(config: BetterStackConfig) -> Result<Self> {
169        config.validate()?;
170        let secrets = config.known_secrets();
171        let make = |common: Option<&crate::core::CommonConfig>| -> Result<Option<HttpTransport>> {
172            let Some(common) = common else {
173                return Ok(None);
174            };
175            let t = HttpTransport::new(common)?;
176            for s in &secrets {
177                t.add_known_secret(s);
178            }
179            Ok(Some(t))
180        };
181        let ingest = if config.has_ingest() {
182            make(config.ingest_common())?
183        } else {
184            None
185        };
186        let query = if config.has_query() {
187            make(config.query_common())?
188        } else {
189            None
190        };
191        if [config.url(), config.query_url()]
192            .iter()
193            .flatten()
194            .any(|u| u.scheme() == "http")
195        {
196            PLAIN_HTTP_WARNING.call_once(|| {
197                tracing::warn!(
198                    target: "grow_better_stack_logs",
199                    "a Better Stack endpoint uses plain http; credentials travel unencrypted (use only for local test services)"
200                );
201            });
202        }
203        Ok(BetterStackClient {
204            inner: Arc::new(Inner {
205                config,
206                ingest,
207                query,
208                on_close: CloseGroup::new(),
209            }),
210        })
211    }
212
213    /// Creates a client from `GROW_BETTER_STACK_LOGS_*`, `BETTERSTACK_SOURCE_TOKEN`,
214    /// `BETTERSTACK_INGESTING_HOST`, `BETTERSTACK_QUERY_*` … environment variables.
215    pub fn from_env() -> Result<Self> {
216        Self::new(BetterStackConfig::from_env()?)
217    }
218
219    /// The configuration in use.
220    pub fn config(&self) -> &BetterStackConfig {
221        &self.inner.config
222    }
223
224    /// The ingest transport (`None` without ingest credentials).
225    pub fn ingest_transport(&self) -> Option<&HttpTransport> {
226        self.inner.ingest.as_ref()
227    }
228
229    /// The SQL query transport (`None` without query credentials).
230    pub fn query_transport(&self) -> Option<&HttpTransport> {
231        self.inner.query.as_ref()
232    }
233
234    /// Registers work that [`BetterStackClient::close`] runs (flush, stop tails, …).
235    pub fn on_close<F>(&self, f: F)
236    where
237        F: FnOnce() -> BoxFuture<'static, ()> + Send + 'static,
238    {
239        self.inner.on_close.register(f);
240    }
241
242    /// Unauthenticated liveness, without sending data. With a query host:
243    /// `GET {query_url}/ping` (`Ok.` → `ok`). Ingest-only: `GET {url}/` without credentials;
244    /// any answer below 500 proves the host is reachable. `details.endpoint` is `query` or
245    /// `ingest`. Never fails except for `CANCELLED` and `CONFIG`.
246    pub async fn health(&self) -> Result<HealthStatus> {
247        let (transport, path, endpoint) = match (&self.inner.query, &self.inner.ingest) {
248            (Some(q), _) => (q, "/ping", "query"),
249            (None, Some(i)) => (i, "/", "ingest"),
250            (None, None) => return Err(Error::config("health: no endpoint configured")),
251        };
252        let req = (400..600).fold(
253            transport.get(path).operation("health").idempotent(false),
254            |r, s| r.ok_status(s),
255        );
256        let resp = match req.send().await {
257            Ok(resp) => resp,
258            Err(err) => {
259                return HealthStatus::from_error(err).map(|h| h.with_detail("endpoint", endpoint))
260            }
261        };
262        let status = resp.status();
263        let hs = if endpoint == "query" && status < 300 {
264            let word = resp.text().unwrap_or_default();
265            let word = word.trim().trim_end_matches('.').to_ascii_lowercase();
266            HealthStatus::healthy(if word.is_empty() {
267                "ok".to_owned()
268            } else {
269                word
270            })
271        } else if (endpoint == "ingest" && status < 500) || status < 300 {
272            HealthStatus::healthy("ok")
273        } else {
274            HealthStatus::unhealthy("unhealthy")
275        };
276        Ok(hs
277            .with_detail("endpoint", endpoint)
278            .with_detail("httpStatus", status.to_string()))
279    }
280
281    /// Authenticated round trip; returns the latency. With query credentials:
282    /// `SELECT count() AS c FROM remote(<source_table>_logs) WHERE 1 = 0` (or `SELECT 1`
283    /// without a `source_table`). Ingest-only: posts an empty batch `[]` (no event is stored).
284    /// Bad credentials → `AUTHENTICATION`.
285    pub async fn ping(&self) -> Result<Duration> {
286        let started = Instant::now();
287        if self.inner.query.is_some() {
288            let sql = match self.config().source_table() {
289                Some(t) => format!("SELECT count() AS c FROM remote({t}_logs) WHERE 1 = 0"),
290                None => "SELECT 1 AS ok".to_owned(),
291            };
292            self.query()?
293                .query(&sql, &Default::default(), &Default::default())
294                .await?;
295        } else {
296            self.inner
297                .post_ingest("ping", "/", b"[]".to_vec(), "application/json", false)
298                .await?;
299        }
300        Ok(started.elapsed().max(Duration::from_nanos(1)))
301    }
302
303    /// Always `UNSUPPORTED`: Better Stack is a SaaS and exposes no service version (the query
304    /// host's ClickHouse version is not one).
305    pub async fn server_version(&self) -> Result<String> {
306        Err(Error::unsupported(
307            "serverVersion: Better Stack does not report a server version",
308        ))
309    }
310
311    /// The HTTP ingest exporter with the configured encoding and default limits. `CONFIG`
312    /// without ingest credentials. Most users call [`log_client`](Self::log_client) instead.
313    pub fn exporter(&self) -> Result<BetterStackLogExporter> {
314        self.new_exporter(IngestExporterOptions::default())
315    }
316
317    /// An HTTP ingest exporter with its own encoding and limits (use it with
318    /// [`log_client_with`](Self::log_client_with)). `CONFIG` without ingest credentials,
319    /// `VALIDATION` for limits outside 1..=10 MiB.
320    pub fn new_exporter(&self, opts: IngestExporterOptions) -> Result<BetterStackLogExporter> {
321        self.inner.ingest_transport("logs.exporter")?;
322        BetterStackLogExporter::new(Arc::clone(&self.inner), opts)
323    }
324
325    /// The OTLP/HTTP logs exporter (protobuf). `CONFIG` without ingest credentials.
326    pub fn otlp_exporter(&self) -> Result<BetterStackOtlpLogExporter> {
327        self.new_otlp_exporter(OtlpExporterOptions::default())
328    }
329
330    /// An OTLP/HTTP logs exporter with its own protocol (protobuf or JSON), scope and limit.
331    pub fn new_otlp_exporter(
332        &self,
333        opts: OtlpExporterOptions,
334    ) -> Result<BetterStackOtlpLogExporter> {
335        self.inner.ingest_transport("logs.otlpExporter")?;
336        BetterStackOtlpLogExporter::new(Arc::clone(&self.inner), opts)
337    }
338
339    /// A batching [`BetterStackLogClient`] over the HTTP ingest API (default) or OTLP;
340    /// [`close`](Self::close) flushes and closes it. Must be called inside a tokio runtime.
341    /// `CONFIG` without ingest credentials, `CANCELLED` after `close`.
342    pub fn log_client(&self, opts: LogClientOptions) -> Result<BetterStackLogClient> {
343        let exporter: Arc<dyn LogExporter> = match opts.protocol {
344            LogProtocol::Http => Arc::new(self.new_exporter(opts.exporter.unwrap_or_default())?),
345            LogProtocol::Otlp => {
346                Arc::new(self.new_otlp_exporter(opts.otlp.clone().unwrap_or_default())?)
347            }
348        };
349        self.log_client_with(exporter, opts)
350    }
351
352    /// A batching [`BetterStackLogClient`] over any exporter (for example
353    /// [`otlp_exporter`](Self::otlp_exporter)); [`close`](Self::close) flushes and closes it.
354    pub fn log_client_with(
355        &self,
356        exporter: Arc<dyn LogExporter>,
357        opts: LogClientOptions,
358    ) -> Result<BetterStackLogClient> {
359        if self.inner.on_close.is_closed() {
360            return Err(Error::cancelled("logClient: client is closed"));
361        }
362        let mut batch = opts.batch;
363        batch.max_batch_bytes = batch.max_batch_bytes.min(MAX_REQUEST_BYTES);
364        let client = BatchingLogClient::builder(exporter)
365            .batch_options(batch)
366            .resource(opts.resource)
367            .redaction(opts.redaction)
368            .min_severity(opts.min_severity)
369            .build()?;
370        let c = client.clone();
371        self.inner.on_close.register(move || {
372            Box::pin(async move {
373                let _ = c.close().await;
374            })
375        });
376        Ok(client)
377    }
378
379    /// The SQL query client. `CONFIG` without query credentials.
380    pub fn query(&self) -> Result<BetterStackQuery> {
381        self.inner.query_transport("query")?;
382        Ok(BetterStackQuery::new(Arc::clone(&self.inner)))
383    }
384
385    /// Flushes and closes every log client, stops running tails, then releases both
386    /// transports. Idempotent.
387    pub async fn close(&self) {
388        self.inner.on_close.close().await;
389        if let Some(t) = &self.inner.ingest {
390            t.close();
391        }
392        if let Some(t) = &self.inner.query {
393            t.close();
394        }
395    }
396
397    /// Whether [`BetterStackClient::close`] was called.
398    pub fn is_closed(&self) -> bool {
399        self.inner.on_close.is_closed()
400    }
401}