Skip to main content

Crate grow_better_stack_logs

Crate grow_better_stack_logs 

Source
Expand description

§grow-better-stack-logs

Rust SDK for Better Stack Logs by Grow Codes. Not affiliated with Better Stack, Inc.

Better Stack has two hosts with separate credentials: the source’s ingesting host (source token, POST / with JSON / NDJSON / MessagePack, or OTLP /v1/logs) and the SQL query host (ClickHouse HTTP interface with a connection’s username and password).

use grow_better_stack_logs::logging::{attrs, LogClient};
use grow_better_stack_logs::{BetterStackClient, LogClientOptions, SearchLogsOptions};

let client = BetterStackClient::from_env()?;
let logs = client.log_client(LogClientOptions::default())?;
logs.logger(None, attrs! {}).info("order placed", attrs! { "order_id" => 42 });
logs.flush(None).await?;

let found = client
    .query()?
    .search_logs(SearchLogsOptions::default().contains("order placed"))
    .await?;
println!("{} records", found.records.len());
client.close().await;

Features: blocking (a blocking client), testing (in-memory fakes and the conformance runner), tracing-layer and log-bridge (logging adapters, on by default).

Re-exports§

pub use crate::core::Error;
pub use crate::core::ErrorCode;
pub use crate::core::HealthStatus;
pub use crate::core::Result;
pub use crate::core::RetryPolicy;
pub use crate::core::Secret;

Modules§

blockingblocking
Blocking wrapper (feature blocking). Each client owns a small tokio runtime (one worker thread, so batching log clients export in the background).
core
Shared core: errors, configuration, secrets in config, redaction, retries and transport.
logging
Logging category (SPEC §4): records, batching, redaction, the Logger facade, the query model and framework adapters.
testingtesting
Test support (feature testing): in-memory fakes and the conformance runner (SPEC §6).

Macros§

attrs
Builds an Attributes map: attrs! { "user" => "ada", "n" => 3 }.
query_params
Builds QueryParams: query_params! { "needle" => "x", "n" => 3 }.

Structs§

BetterStackClient
Async client for Better Stack Logs. Cheap to clone (clones share the connections).
BetterStackConfig
Immutable client configuration; build it with BetterStackConfig::builder or BetterStackConfig::from_env. Debug output redacts every credential.
BetterStackConfigBuilder
Builder for BetterStackConfig. Values set here win over the environment.
BetterStackLogExporter
LogExporter for Better Stack’s HTTP ingest API: maps records to events (to_better_stack_event), splits batches so no request exceeds 10 MiB, encodes them as JSON, NDJSON or MessagePack, gzips when asked and posts with Authorization: Bearer <source token>. Exports are retried like idempotent calls (429, 5xx, network errors); Better Stack does not deduplicate, so an ambiguous failure may store a record twice.
BetterStackOtlpLogExporter
LogExporter that sends OTLP/HTTP logs to the source’s ingesting host (POST {url}/v1/logs) with the source token. Records are grouped by resource; batches are split so no request exceeds the request limit; partial_success in the response counts as rejected records. Retried like idempotent calls (duplicates possible after an ambiguous failure).
BetterStackQuery
SQL query client for Better Stack Logs (ClickHouse HTTP interface with the connection’s own Basic credentials). Implements LogQueryClient: search runs search_logs on the configured source_table, tail polls search, list_streams returns the configured collection and list_labels is UNSUPPORTED (Better Stack has no labels). Cheap to clone.
IngestExporterOptions
Options of BetterStackClient::new_exporter.
LogClientOptions
Options of BetterStackClient::log_client.
OtlpExporterOptions
Options of BetterStackClient::new_otlp_exporter.
OtlpPartialSuccess
Partial success reported by an OTLP response.
QueryOptions
Options of BetterStackQuery::query and BetterStackQuery::query_raw.
SearchLogsOptions
Options of BetterStackQuery::search_logs.
SendEventsOptions
Options of BetterStackLogExporter::send_events.

Enums§

Encoding
Wire encoding of ingest requests (POST / on the ingesting host).
LogProtocol
Wire protocol of BetterStackClient::log_client.
OtlpProtocol
OTLP/HTTP payload format.
QueryParam
Value of a bound query parameter ({name:Type} placeholder + param_<name> URL parameter). QueryParam::Null is sent as \N (use a Nullable(…) type).

Constants§

DEFAULT_SCOPE_NAME
Default instrumentation scope name.
DEFAULT_SEARCH_LIMIT
Default limit of one search page.
DEFAULT_URL
Empty on purpose: Better Stack has no global ingest host. Every source has its own ingesting host (for example https://s1234.eu-nbg-2.betterstackdata.com), so the ingest URL must be set whenever logs are sent (DECISIONS 4).
MAX_RECORD_BYTES
Better Stack limit for one record (10 MiB uncompressed).
MAX_REQUEST_BYTES
Better Stack limit for one request body (10 MiB, measured compressed). The exporter never builds a larger uncompressed body, so the limit always holds.
MAX_SEARCH_LIMIT
Largest limit of one search page.
OTLP_LOGS_PATH
OTLP logs path on the ingesting host.
VENDOR_QUERY_PASSWORD_VARS
Vendor variables checked after GROW_BETTER_STACK_LOGS_QUERY_PASSWORD.
VENDOR_QUERY_URL_VARS
Vendor variables checked (in order) after GROW_BETTER_STACK_LOGS_QUERY_URL.
VENDOR_QUERY_USERNAME_VARS
Vendor variables checked after GROW_BETTER_STACK_LOGS_QUERY_USERNAME.
VENDOR_SOURCE_TABLE_VARS
Vendor variables checked after GROW_BETTER_STACK_LOGS_SOURCE_TABLE.
VENDOR_SOURCE_TOKEN_VARS
Vendor variables checked after GROW_BETTER_STACK_LOGS_SOURCE_TOKEN.
VENDOR_URL_VARS
Vendor variables checked (in order) after GROW_BETTER_STACK_LOGS_URL.

Functions§

clickhouse_code
Extracts the ClickHouse exception code from an error text (Code: 60. DB::Exception: …).
code_for_clickhouse
The SDK error code for a ClickHouse exception code (API.md §5.1), or None when the code has no special mapping (the HTTP status mapping applies then).
encode_event
Encodes one raw event (a JSON object) for encoding. VALIDATION when it is not an object.
encode_msgpack
Encodes a JSON value as MessagePack.
encode_otlp_protobuf
Encodes an OTLP ExportLogsServiceRequest (collector/logs/v1) as protobuf; records are grouped by resource, the scope is scope_name with the SDK version.
encode_record
Encodes one record as an event for encoding: the JSON object for JSON/NDJSON, the MessagePack map (with dt / observed_dt as timestamp extensions) for MessagePack.
error_for_clickhouse
Builds the SDK error for a ClickHouse exception code, or None without a special mapping. 241 (memory limit) gets a hint; 202 (too many simultaneous queries) is retryable.
escape_param_value
Escapes a param_<name> value for ClickHouse, which parses query parameter values in the escaped (TabSeparated) text format: backslash → \\, tab → \t, newline → \n, carriage return → \r (DECISIONS 12). Without it the server would unescape a bound backslash.
format_datetime64
YYYY-MM-DD HH:MM:SS.ffffff (UTC), the DateTime64(6) text form. Times before the epoch are clamped to it.
format_event_time
RFC 3339 UTC with nanoseconds (2026-11-18T21:00:00.123456789Z), the dt form for JSON and NDJSON. Times before the epoch are clamped to it.
frame
Joins encoded events into one request body.
is_valid_identifier
Whether s is a safe ClickHouse identifier (^[A-Za-z_][A-Za-z0-9_]*$), the rule for source tables (collections), which cannot be bound as SQL parameters.
json_escape
JSON string escaping without the surrounding quotes, as in the raw event JSON.
log_record_from_row
Normalizes a {dt, raw} row into a LogRecord (API.md §5.3): body = message (else msg, else the raw text), severity from severity_number / level / severity, trace ids from span.trace_id / span.span_id (or top-level trace_id / span_id), resource from resource, and every other field plus attributes into attributes.
map_ingest_error
Maps ingest-host errors: 403 (invalid or missing source token) → AUTHENTICATION, 402 (quota or spending limit) → RATE_LIMITED with retryable = false. Other errors pass through (406/413 are already VALIDATION, 429/5xx follow SPEC §2.1).
map_query_error
Maps SQL-host errors by their ClickHouse code (found in the message), else keeps the error.
normalize_base_url
Normalizes a host or URL: a value containing :// is used as given, a bare host[:port] becomes https://host[:port]; trailing slashes are removed. Blank input gives None.
otlp_json_request
Builds the OTLP/JSON ExportLogsServiceRequest object.
parse_datetime
Parses a ClickHouse DateTime64 text (2026-11-18 21:00:00.123456, UTC, 0–9 fraction digits), an RFC 3339 string (Z or numeric offset) or UNIX seconds / milliseconds.
parse_partial_success
Reads partial_success from an ExportLogsServiceResponse (protobuf or OTLP/JSON bytes). Returns None when nothing was rejected or the body cannot be read.
parse_rows
Parses a JSON-family response body (JSONEachRow, JSON, JSONEachRow with output_format_json_array_of_rows) into rows. A ClickHouse exception appended to the body is returned as the mapped error.
sql_string
Escapes a value as a ClickHouse single-quoted string literal (\, ' and control characters escaped with a backslash).
to_better_stack_event
Maps a record to the Better Stack event object (the JSON stored in the raw column): {dt, message, level, severity_number, span: {trace_id, span_id}, trace_flags, resource, attributes, observed_dt}. span.trace_id / span.span_id are Better Stack’s log ↔ trace correlation fields. Empty resource / attributes are left out.

Type Aliases§

BetterStackError
Service-prefixed alias of Error.
BetterStackLogClient
The batching LogClient returned by BetterStackClient::log_client.
QueryParams
Bound parameters of BetterStackQuery::query: name → value.
QueryRow
One result row (JSON object; ClickHouse quotes 64-bit integers as strings).