Client¶
BetterStackClient is the entry point. Create one per process (or per set of credentials), share
it between threads/tasks and close it on shutdown. It holds two transports: one for the
source's ingesting host (Bearer source token) and one for the SQL host (HTTP Basic); a client with
only one side configured is valid, and calls that need the other side raise CONFIG.
| Function | Returns | Notes |
|---|---|---|
constructor / create / new |
client | validates the config (CONFIG error) |
fromEnv() |
client | config from GROW_BETTER_STACK_LOGS_* and BETTERSTACK_* (Configuration) |
health() |
HealthStatus { healthy, status, details } |
unauthenticated; with a SQL host GET {queryUrl}/ping (Ok.), otherwise GET {url}/ on the ingesting host (any answer below 500 means reachable; no data is sent). details.endpoint is query or ingest. Never throws for an unhealthy or unreachable service, only for CANCELLED and CONFIG |
ping() |
latency | authenticated: SELECT count() AS c FROM remote(<sourceTable>_logs) WHERE 1 = 0 (or SELECT 1 without a sourceTable); ingest-only clients post an empty batch [] (no event is stored). AUTHENTICATION on bad credentials |
serverVersion() |
— | always UNSUPPORTED: Better Stack is a SaaS without a version (the SQL host's ClickHouse version is not a Better Stack version) |
close() |
— | idempotent; flushes every log client created by this client, stops tails, closes both transports. Later calls on the client, its exporters and its query client raise CANCELLED |
exporter, newExporter, otlpExporter, newOtlpExporter |
exporters | Ingest |
logClient(options) |
BetterStackLogClient |
Log client and search |
query() |
BetterStackQuery |
SQL query |
status is ok, unhealthy, unreachable (network error) or ClickHouse's word.
Create, use and close¶
import { BetterStackClient, BetterStackConfig } from "@grow-codes/better-stack-logs";
const client = new BetterStackClient(
new BetterStackConfig({
url: "s1234.eu-nbg-2.betterstackdata.com", // bare host → https://
sourceToken: process.env.BETTERSTACK_SOURCE_TOKEN,
queryUrl: "eu-nbg-2-connect.betterstackdata.com",
queryUsername: process.env.BETTERSTACK_QUERY_USERNAME,
queryPassword: process.env.BETTERSTACK_QUERY_PASSWORD,
sourceTable: "t1234_myapp",
}),
);
const health = await client.health(); // { healthy, status, details: { endpoint: "query" } }
const latencyMs = await client.ping(); // number (ms)
await client.serverVersion().catch((e) => console.log(e.code)); // "UNSUPPORTED"
await client.close(); // safe to call twice; later calls → CANCELLED
// Cancellation and per-call deadline: every I/O method accepts { signal }
const status = await BetterStackClient.fromEnv().health({ signal: AbortSignal.timeout(2_000) });
use grow_better_stack_logs::{BetterStackClient, BetterStackConfig};
let config = BetterStackConfig::builder()
.url("s1234.eu-nbg-2.betterstackdata.com")
.source_token(std::env::var("BETTERSTACK_SOURCE_TOKEN").unwrap_or_default())
.query_url("eu-nbg-2-connect.betterstackdata.com")
.query_username(std::env::var("BETTERSTACK_QUERY_USERNAME").unwrap_or_default())
.query_password(std::env::var("BETTERSTACK_QUERY_PASSWORD").unwrap_or_default())
.source_table("t1234_myapp")
.build()?;
let client = BetterStackClient::new(config)?;
let health = client.health().await?; // HealthStatus
let latency = client.ping().await?; // Duration
assert!(client.server_version().await.is_err()); // UNSUPPORTED
client.close().await; // safe to call twice
// Without an async runtime, enable the `blocking` feature:
let blocking = grow_better_stack_logs::blocking::BetterStackClient::from_env()?;
let health = blocking.health()?;
client, err := betterstack.NewClient(betterstack.Config{
CommonConfig: betterstack.CommonConfig{URL: "s1234.eu-nbg-2.betterstackdata.com"},
SourceToken: betterstack.NewSecret(os.Getenv("BETTERSTACK_SOURCE_TOKEN")),
QueryURL: "eu-nbg-2-connect.betterstackdata.com",
QueryUsername: os.Getenv("BETTERSTACK_QUERY_USERNAME"),
QueryPassword: betterstack.NewSecret(os.Getenv("BETTERSTACK_QUERY_PASSWORD")),
SourceTable: "t1234_myapp",
})
if err != nil {
return err
}
defer client.Close() // safe to call twice
health, err := client.Health(ctx) // HealthStatus
latency, err := client.Ping(ctx) // time.Duration
_, err = client.ServerVersion(ctx) // errors.Is(err, betterstack.ErrUnsupported)
// Cancellation and deadlines come from ctx
ctx2, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
health, err = client.Health(ctx2)
import os
from grow_better_stack_logs import BetterStackClient, BetterStackConfig, CancelToken, UnsupportedError
config = BetterStackConfig(
url="s1234.eu-nbg-2.betterstackdata.com",
source_token=os.environ["BETTERSTACK_SOURCE_TOKEN"],
query_url="eu-nbg-2-connect.betterstackdata.com",
query_username=os.environ["BETTERSTACK_QUERY_USERNAME"],
query_password=os.environ["BETTERSTACK_QUERY_PASSWORD"],
source_table="t1234_myapp",
)
with BetterStackClient(config) as client:
health = client.health() # HealthStatus
latency_ms = client.ping() # float (ms)
try:
client.server_version()
except UnsupportedError:
pass
health = client.health(cancel=CancelToken()) # cancel from another thread
# close() ran; calling it again is safe, other calls raise CancelledError
BetterStackConfig config = BetterStackConfig.builder()
.url("s1234.eu-nbg-2.betterstackdata.com")
.sourceToken(System.getenv("BETTERSTACK_SOURCE_TOKEN"))
.queryUrl("eu-nbg-2-connect.betterstackdata.com")
.queryUsername(System.getenv("BETTERSTACK_QUERY_USERNAME"))
.queryPassword(System.getenv("BETTERSTACK_QUERY_PASSWORD"))
.sourceTable("t1234_myapp")
.build();
try (BetterStackClient client = BetterStackClient.create(config)) {
HealthStatus health = client.health();
Duration latency = client.ping();
// client.serverVersion() throws UnsupportedException
// Async variants return CompletableFuture
client.healthAsync().orTimeout(2, TimeUnit.SECONDS).join();
} // close() is idempotent; later calls throw CancelledException
AsyncBetterStackClient (Python) has the same methods as coroutines (await client.health(),
await client.aclose(), async with) and honours task cancellation.
Lifecycle rules¶
- The client is safe for concurrent use. Reuse it: it keeps a connection pool per host.
close()flushes queued log batches within the configured deadline, stops polling tails and is safe to call more than once. Calls afterclose()raiseCANCELLEDin every language.- Each language also offers its idiomatic scope: TypeScript
try/finally, Rustclose().await(plus best-effortDrop), Godefer client.Close(), Pythonwith/async with, Java try-with-resources.