Class BetterStackConfig

java.lang.Object
codes.grow.packages.betterstack.BetterStackConfig

public final class BetterStackConfig extends Object
Immutable configuration of a BetterStackClient (SPEC section 2.2).

Better Stack Logs has two hosts with separate credentials:

  • the source's ingesting host (url(), for example s1234.eu-nbg-2.betterstackdata.com) with the source token (Authorization: Bearer)
  • the SQL query host (queryUrl(), ClickHouse HTTP interface, for example eu-nbg-2-connect.betterstackdata.com) with the username and password of a connection (HTTP Basic)

Each set is all-or-nothing and at least one must be complete. A value without :// becomes https://value; trailing slashes are removed. There is no default ingesting host.

Build one with builder() or read it from the environment with fromEnv(). Precedence: explicit builder value > GROW_BETTER_STACK_LOGS_<NAME> > vendor variables (BETTERSTACK_*) > default. toString() never prints credentials.

  • Field Details

    • IDENTIFIER_PATTERN

      public static final Pattern IDENTIFIER_PATTERN
      Collection (table) names are identifiers: they cannot be bound as SQL parameters.
    • URL_VENDOR_VARS

      public static final List<String> URL_VENDOR_VARS
      Vendor variables read for url after GROW_BETTER_STACK_LOGS_URL, in order.
    • SOURCE_TOKEN_VENDOR_VARS

      public static final List<String> SOURCE_TOKEN_VENDOR_VARS
      Vendor variables read for sourceToken.
    • QUERY_URL_VENDOR_VARS

      public static final List<String> QUERY_URL_VENDOR_VARS
      Vendor variables read for queryUrl, in order.
    • QUERY_USERNAME_VENDOR_VARS

      public static final List<String> QUERY_USERNAME_VENDOR_VARS
      Vendor variables read for queryUsername.
    • QUERY_PASSWORD_VENDOR_VARS

      public static final List<String> QUERY_PASSWORD_VENDOR_VARS
      Vendor variables read for queryPassword.
    • SOURCE_TABLE_VENDOR_VARS

      public static final List<String> SOURCE_TABLE_VENDOR_VARS
      Vendor variables read for sourceTable.
  • Method Details

    • normalizeBaseUrl

      public static String normalizeBaseUrl(String value)
      Normalizes a host or URL: a value containing :// is used as given, a bare host[:port] becomes https://host[:port]; trailing slashes are removed.
      Parameters:
      value - host or URL, may be null
      Returns:
      the base URL, or null for blank input
    • isValidIdentifier

      public static boolean isValidIdentifier(String s)
      Whether s is a safe ClickHouse identifier (^[A-Za-z_][A-Za-z0-9_]*$), the rule for collections (source tables).
      Parameters:
      s - text
      Returns:
      true when valid
    • builder

      public static BetterStackConfig.Builder builder()
      Starts an empty builder (every field at its default).
      Returns:
      a new builder
    • fromEnv

      public static BetterStackConfig fromEnv()
      Reads the configuration from the process environment.
      Returns:
      the validated configuration
      Throws:
      ConfigException - when a variable holds an invalid value (the message names the variable, never the value) or neither credential set is complete
    • fromEnv

      public static BetterStackConfig fromEnv(Map<String,String> env)
      Reads the configuration from an explicit variable map (tests).
      Parameters:
      env - variable map
      Returns:
      the validated configuration
    • hasIngest

      public boolean hasIngest()
      Whether the ingest side (url and sourceToken) is configured.
      Returns:
      true with ingest credentials
    • hasQuery

      public boolean hasQuery()
      Whether the SQL query side (queryUrl, queryUsername and queryPassword) is configured.
      Returns:
      true with query credentials
    • validate

      public void validate()
      Checks the credential sets, URLs, the source table, timeouts, TLS and proxy.
      Throws:
      ConfigException - when a rule is violated
    • ingestTransportConfig

      public TransportConfig ingestTransportConfig()
      Transport settings of the ingest side (baseUrl = url()).
      Returns:
      the transport configuration
      Throws:
      ConfigException - without ingest credentials
    • queryTransportConfig

      public TransportConfig queryTransportConfig()
      Transport settings of the SQL query side (baseUrl = queryUrl()).
      Returns:
      the transport configuration
      Throws:
      ConfigException - without query credentials
    • knownSecrets

      public List<String> knownSecrets()
      Credential values to redact from error messages and logs (source token, query password and the Basic credential).
      Returns:
      secret values
    • basicCredentials

      public Optional<String> basicCredentials()
      Returns base64(username:password) for HTTP Basic.
      Returns:
      the credential, or empty without query credentials
    • url

      public Optional<String> url()
      Returns the ingest base URL (the source's ingesting host).
      Returns:
      the URL, or empty for a query-only client
    • sourceToken

      public Optional<Secret> sourceToken()
      Returns the source token.
      Returns:
      the token, or empty
    • queryUrl

      public Optional<String> queryUrl()
      Returns the SQL query base URL.
      Returns:
      the URL, or empty for an ingest-only client
    • queryUsername

      public Optional<String> queryUsername()
      Returns the SQL connection username.
      Returns:
      the username, or empty
    • queryPassword

      public Optional<Secret> queryPassword()
      Returns the SQL connection password.
      Returns:
      the password, or empty
    • sourceTable

      public Optional<String> sourceTable()
      Returns the default collection (t1234_myapp) used by search, searchLogs, tail and ping.
      Returns:
      the collection, or empty
    • encoding

      public IngestEncoding encoding()
      Returns the ingest body encoding (default IngestEncoding.JSON).
      Returns:
      the encoding
    • connectTimeout

      public Duration connectTimeout()
      Returns the connect timeout.
      Returns:
      the timeout
    • requestTimeout

      public Duration requestTimeout()
      Returns the per-attempt timeout.
      Returns:
      the timeout
    • totalTimeout

      public Duration totalTimeout()
      Returns the total timeout per call including retries.
      Returns:
      the timeout
    • retry

      public RetryPolicy retry()
      Returns the retry policy.
      Returns:
      the policy
    • tls

      public TlsOptions tls()
      Returns the TLS options.
      Returns:
      the options
    • proxy

      public Optional<String> proxy()
      Returns the explicit proxy URL.
      Returns:
      the proxy, or empty
    • headers

      public Map<String,String> headers()
      Returns the extra request headers.
      Returns:
      immutable map
    • userAgentSuffix

      public Optional<String> userAgentSuffix()
      Returns the user agent suffix.
      Returns:
      the suffix, or empty
    • hooks

      public Hooks hooks()
      Returns the hooks.
      Returns:
      the hooks
    • logger

      public Logger logger()
      Returns the logger.
      Returns:
      the logger
    • toBuilder

      public BetterStackConfig.Builder toBuilder()
      Returns a builder pre-filled with this configuration.
      Returns:
      a new builder
    • toString

      public String toString()
      Overrides:
      toString in class Object