1use 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
20pub type BetterStackLogClient = BatchingLogClient;
22
23static PLAIN_HTTP_WARNING: Once = Once::new();
24
25#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
27pub enum LogProtocol {
28 #[default]
30 Http,
31 Otlp,
33}
34
35#[derive(Clone)]
37pub struct LogClientOptions {
38 pub batch: BatchOptions,
40 pub resource: Attributes,
42 pub redaction: Option<RedactionProcessor>,
45 pub min_severity: Severity,
47 pub protocol: LogProtocol,
49 pub exporter: Option<IngestExporterOptions>,
52 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 pub fn batch(mut self, batch: BatchOptions) -> Self {
87 self.batch = batch;
88 self
89 }
90 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 pub fn protocol(mut self, protocol: LogProtocol) -> Self {
101 self.protocol = protocol;
102 self
103 }
104 pub fn exporter(mut self, opts: IngestExporterOptions) -> Self {
106 self.exporter = Some(opts);
107 self
108 }
109 pub fn otlp(mut self, opts: OtlpExporterOptions) -> Self {
111 self.protocol = LogProtocol::Otlp;
112 self.otlp = Some(opts);
113 self
114 }
115}
116
117#[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 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 pub fn from_env() -> Result<Self> {
216 Self::new(BetterStackConfig::from_env()?)
217 }
218
219 pub fn config(&self) -> &BetterStackConfig {
221 &self.inner.config
222 }
223
224 pub fn ingest_transport(&self) -> Option<&HttpTransport> {
226 self.inner.ingest.as_ref()
227 }
228
229 pub fn query_transport(&self) -> Option<&HttpTransport> {
231 self.inner.query.as_ref()
232 }
233
234 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 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 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 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 pub fn exporter(&self) -> Result<BetterStackLogExporter> {
314 self.new_exporter(IngestExporterOptions::default())
315 }
316
317 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 pub fn otlp_exporter(&self) -> Result<BetterStackOtlpLogExporter> {
327 self.new_otlp_exporter(OtlpExporterOptions::default())
328 }
329
330 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 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 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 pub fn query(&self) -> Result<BetterStackQuery> {
381 self.inner.query_transport("query")?;
382 Ok(BetterStackQuery::new(Arc::clone(&self.inner)))
383 }
384
385 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 pub fn is_closed(&self) -> bool {
399 self.inner.on_close.is_closed()
400 }
401}