Package codes.grow.packages.betterstack
Class BetterStackClient
java.lang.Object
codes.grow.packages.betterstack.BetterStackClient
- All Implemented Interfaces:
AutoCloseable
Client for Better Stack Logs: ingestion through the source's ingesting host (
logClient(), exporter(), otlpExporter()) and the SQL query API (query()), each with its own credentials and transport. A source token is never sent to the
query host and SQL credentials never to the ingesting host.
try (BetterStackClient client = BetterStackClient.fromEnv()) {
BatchingLogClient logs = client.logClient(
BetterStackLogClientOptions.builder().resource(Map.of("service.name", "checkout")).build());
logs.logger().info("order placed", Map.of("orderId", 42));
} // close() flushes every log client
Thread-safe. Every I/O method has a blocking form and an …Async form returning CompletableFuture.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classBuilder that configures and creates a client in one chain. -
Method Summary
Modifier and TypeMethodDescriptionstatic BetterStackClient.Builderbuilder()Starts a client builder.voidclose()Flushes and closes every log client, stops tails, then releases both transports.config()Returns the configuration.static BetterStackClientcreate(BetterStackConfig config) Creates a client.exporter()The HTTP ingest exporter in the configured encoding with the default limits.static BetterStackClientfromEnv()Creates a client fromGROW_BETTER_STACK_LOGS_*and the vendor variables (BETTERSTACK_SOURCE_TOKEN,BETTERSTACK_INGESTING_HOST,BETTERSTACK_QUERY_*, …).health()Unauthenticated liveness check that never sends data.Asynchronoushealth().booleanisClosed()Returns whetherclose()was called.A batching log client over the HTTP ingest API with default options.logClient(BetterStackLogClientOptions options) A batching log client over the HTTP ingest API (LogProtocol.HTTP, default) or OTLP.logClient(LogExporter exporter, BetterStackLogClientOptions options) A batching log client over any exporter (for examplenewExporter(codes.grow.packages.betterstack.BetterStackLogExporterOptions)).newExporter(BetterStackLogExporterOptions options) A new HTTP ingest exporter with its own encoding and limits (use it withlogClient(LogExporter, BetterStackLogClientOptions)).A new OTLP exporter with its own payload format, scope name and request limit.The OTLP/HTTP logs exporter (protobuf,/v1/logs).ping()Authenticated round trip.Asynchronousping().query()The SQL query client (also theLogQueryClient).voidregister(AutoCloseable resource) Registers a resource (log client, tail) closed with the client.Better Stack is a SaaS without a version endpoint (the query host's ClickHouse version is not one).AsynchronousserverVersion(): always fails withUnsupportedException.toString()
-
Method Details
-
create
Creates a client.- Parameters:
config- configuration- Returns:
- a new client
- Throws:
ConfigException- when the configuration, TLS or proxy settings are invalid
-
fromEnv
Creates a client fromGROW_BETTER_STACK_LOGS_*and the vendor variables (BETTERSTACK_SOURCE_TOKEN,BETTERSTACK_INGESTING_HOST,BETTERSTACK_QUERY_*, …).- Returns:
- a new client
-
builder
Starts a client builder.- Returns:
- a new builder
-
config
Returns the configuration.- Returns:
- the configuration
-
register
Registers a resource (log client, tail) closed with the client.- Parameters:
resource- the resource- Throws:
CancelledException- when the client is closed (the resource is closed first)
-
health
Unauthenticated liveness check that never sends data. With a query host:GET {queryUrl}/ping(Ok.). Ingest-only:GET {url}/without credentials; any answer below 500 means the host is reachable.details.endpointisqueryoringest. Never throws for an unhealthy or unreachable service.- Returns:
- the health status
- Throws:
CancelledException- when interrupted or closed
-
healthAsync
Asynchronoushealth().- Returns:
- a future with the health status
-
ping
Authenticated round trip. With query credentials:SELECT count() AS c FROM remote(<sourceTable>_logs) WHERE 1 = 0(orSELECT 1without a source table). Ingest-only: posts an empty batch[](no event is stored).- Returns:
- the latency
- Throws:
AuthenticationException- on bad credentials
-
pingAsync
Asynchronousping().- Returns:
- a future with the latency
-
serverVersion
Better Stack is a SaaS without a version endpoint (the query host's ClickHouse version is not one).- Returns:
- never
- Throws:
UnsupportedException- always
-
serverVersionAsync
AsynchronousserverVersion(): always fails withUnsupportedException.- Returns:
- a failed future
-
exporter
The HTTP ingest exporter in the configured encoding with the default limits.- Returns:
- the exporter
- Throws:
ConfigException- without ingest credentials
-
newExporter
A new HTTP ingest exporter with its own encoding and limits (use it withlogClient(LogExporter, BetterStackLogClientOptions)).- Parameters:
options- encoding and limits- Returns:
- the exporter
- Throws:
ConfigException- without ingest credentialsValidationException- for limits outside 1 to 10 MiB
-
otlpExporter
The OTLP/HTTP logs exporter (protobuf,/v1/logs).- Returns:
- the exporter
- Throws:
ConfigException- without ingest credentials
-
newOtlpExporter
A new OTLP exporter with its own payload format, scope name and request limit.- Parameters:
options- options- Returns:
- the exporter
- Throws:
ConfigException- without ingest credentials
-
logClient
A batching log client over the HTTP ingest API with default options.- Returns:
- the log client
- Throws:
ConfigException- without ingest credentials
-
logClient
A batching log client over the HTTP ingest API (LogProtocol.HTTP, default) or OTLP.close()flushes and closes every log client created here.- Parameters:
options- protocol, exporter options, batching, resource, redaction- Returns:
- the log client
- Throws:
ConfigException- without ingest credentials
-
logClient
A batching log client over any exporter (for examplenewExporter(codes.grow.packages.betterstack.BetterStackLogExporterOptions)). The protocol and exporter options ofoptionsare ignored.close()flushes and closes it.- Parameters:
exporter- the exporteroptions- batching, resource, redaction- Returns:
- the log client
-
query
The SQL query client (also theLogQueryClient).- Returns:
- the query client
- Throws:
ConfigException- without query credentials
-
isClosed
public boolean isClosed()Returns whetherclose()was called.- Returns:
- true once closed
-
close
public void close()Flushes and closes every log client, stops tails, then releases both transports. Idempotent; later calls raiseCancelledException.- Specified by:
closein interfaceAutoCloseable
-
toString
-