Configuration¶
GraylogConfig holds every setting of a client. It is immutable after construction,
validated when it is built (invalid values raise a CONFIG error) and its string/debug form
redacts every credential. The Graylog fields (credentials, GELF and OTLP endpoints) are listed
under Graylog settings.
Common settings¶
| Setting | Default | Environment variable |
|---|---|---|
url — endpoint base URL |
http://127.0.0.1:9000 |
GROW_GRAYLOG_URL |
connectTimeout — connection setup |
10 s | GROW_GRAYLOG_CONNECT_TIMEOUT |
requestTimeout — per attempt (headers + body) |
30 s | GROW_GRAYLOG_REQUEST_TIMEOUT |
totalTimeout — whole call incl. retries and backoff |
120 s | GROW_GRAYLOG_TOTAL_TIMEOUT |
retry — retry policy (below) |
3 retries | GROW_GRAYLOG_MAX_RETRIES |
tls.caCertPath / tls.caCertPem — extra CA |
none | GROW_GRAYLOG_CA_CERT (path) |
tls.clientCertPath + tls.clientKeyPath — mutual TLS |
none | GROW_GRAYLOG_CLIENT_CERT, GROW_GRAYLOG_CLIENT_KEY |
tls.insecureSkipVerify — tests only, logs a warning once |
false |
GROW_GRAYLOG_INSECURE_SKIP_VERIFY |
proxy — proxy URL |
none (environment proxies are ignored) | GROW_GRAYLOG_PROXY |
headers — extra request headers |
{} |
— |
userAgentSuffix — appended to the User-Agent |
none | — |
hooks — request/response callbacks (Hooks) |
none | — |
logger — diagnostic logger (Hooks) |
silent | — |
Every request sends User-Agent: grow-codes-graylog/<version> (<language>).
From the environment¶
fromEnv resolves each setting with this precedence:
- the value passed in code (overrides),
GROW_GRAYLOG_<NAME>,- the vendor variables
GRAYLOG_*(Graylog settings), - the platform stack aliases
GRAYLOG_HOST,GRAYLOG_PORT,GRAYLOG_TRANSPORT, - the default.
Parsing rules:
- Durations accept integer milliseconds (
1500) or Go-style units:500ms,10s,2m,1h, combinations such as1m30s. - Booleans accept
true/false,1/0,yes/no,on/off(any case). - An empty variable counts as unset.
- A present but invalid value raises a
CONFIGerror that names the variable, never its value.
import { GraylogClient, GraylogConfig } from "@grow-codes/graylog";
// Environment only
const client = GraylogClient.fromEnv();
// Environment with explicit overrides (explicit values win)
const config = GraylogConfig.fromEnv({ requestTimeoutMs: 5_000 });
// Everything in code
const explicit = new GraylogConfig({
url: "https://graylog.example.com",
apiToken: process.env.MY_GRAYLOG_TOKEN,
gelfHost: "graylog.example.com",
gelfProtocol: "http",
connectTimeoutMs: 5_000,
requestTimeoutMs: 15_000,
totalTimeoutMs: 60_000,
retry: { maxRetries: 5, initialBackoffMs: 200 },
tls: { caCertPath: "/etc/ssl/internal-ca.pem" },
proxy: "http://proxy.internal:3128",
headers: { "x-team": "payments" },
userAgentSuffix: "my-app/1.4",
});
const custom = new GraylogClient(explicit);
console.log(String(explicit)); // apiToken shown as [REDACTED]
use std::time::Duration;
use grow_graylog::{GelfProtocol, GraylogClient, GraylogConfig, RetryPolicy};
// Environment only
let client = GraylogClient::from_env()?;
// Environment with explicit overrides (explicit values win)
let config = GraylogConfig::builder()
.request_timeout(Duration::from_secs(5))
.build_from_env()?;
// Everything in code
let explicit = GraylogConfig::builder()
.url("https://graylog.example.com")
.api_token(std::env::var("MY_GRAYLOG_TOKEN").unwrap_or_default())
.gelf_host("graylog.example.com")
.gelf_protocol(GelfProtocol::Http)
.connect_timeout(Duration::from_secs(5))
.request_timeout(Duration::from_secs(15))
.total_timeout(Duration::from_secs(60))
.retry(RetryPolicy::default().with_max_retries(5))
.ca_cert_path("/etc/ssl/internal-ca.pem")
.proxy("http://proxy.internal:3128")
.header("x-team", "payments")
.user_agent_suffix("my-app/1.4")
.build()?;
let custom = GraylogClient::new(explicit)?;
println!("{:?}", custom.config()); // api_token shown as [REDACTED]
// Environment only
client, err := graylog.NewClientFromEnv()
// Everything in code: zero values mean "use the default"
cfg := graylog.Config{
CommonConfig: graylog.CommonConfig{
URL: "https://graylog.example.com",
ConnectTimeout: 5 * time.Second,
RequestTimeout: 15 * time.Second,
TotalTimeout: time.Minute,
Retry: &graylog.RetryPolicy{MaxRetries: 5, InitialBackoff: 200 * time.Millisecond},
TLS: graylog.TLSConfig{CACertPath: "/etc/ssl/internal-ca.pem"},
Proxy: "http://proxy.internal:3128",
Headers: map[string]string{"x-team": "payments"},
UserAgentSuffix: "my-app/1.4",
},
APIToken: graylog.NewSecret(os.Getenv("MY_GRAYLOG_TOKEN")),
GelfHost: "graylog.example.com",
GelfProtocol: graylog.GelfHTTP,
}
if err := cfg.Validate(); err != nil {
log.Fatal(err) // errors.Is(err, graylog.ErrConfig)
}
custom, err := graylog.NewClient(cfg)
// Environment with explicit overrides (explicit values win; nil env = process environment)
merged, err := graylog.ConfigFromEnvWith(graylog.Config{
CommonConfig: graylog.CommonConfig{RequestTimeout: 5 * time.Second},
}, nil)
fmt.Println(merged) // APIToken shown as [REDACTED]
import os
from grow_graylog import RetryPolicy, TlsConfig, GraylogClient, GraylogConfig
# Environment only
client = GraylogClient.from_env()
# Environment with explicit overrides (explicit values win)
config = GraylogConfig.from_env(request_timeout=5.0)
# Everything in code: durations are float seconds (datetime.timedelta also works)
explicit = GraylogConfig(
url="https://graylog.example.com",
api_token=os.environ.get("MY_GRAYLOG_TOKEN"),
gelf_host="graylog.example.com",
gelf_protocol="http",
connect_timeout=5.0,
request_timeout=15.0,
total_timeout=60.0,
retry=RetryPolicy(max_retries=5, initial_backoff=0.2),
tls=TlsConfig(ca_cert_path="/etc/ssl/internal-ca.pem"),
proxy="http://proxy.internal:3128",
headers={"x-team": "payments"},
user_agent_suffix="my-app/1.4",
)
custom = GraylogClient(explicit)
print(repr(explicit)) # api_token shown as [REDACTED]
import java.time.Duration;
import codes.grow.packages.graylog.GelfProtocol;
import codes.grow.packages.graylog.GraylogClient;
import codes.grow.packages.graylog.GraylogConfig;
import codes.grow.packages.graylog.core.RetryPolicy;
// Environment only
GraylogClient client = GraylogClient.fromEnv();
// Everything in code
GraylogConfig config = GraylogConfig.builder()
.url("https://graylog.example.com")
.apiToken(System.getenv("MY_GRAYLOG_TOKEN"))
.gelfHost("graylog.example.com")
.gelfProtocol(GelfProtocol.HTTP)
.connectTimeout(Duration.ofSeconds(5))
.requestTimeout(Duration.ofSeconds(15))
.totalTimeout(Duration.ofMinutes(1))
.retry(RetryPolicy.builder().maxRetries(5).initialBackoff(Duration.ofMillis(200)).build())
.proxy("http://proxy.internal:3128")
.header("x-team", "payments")
.userAgentSuffix("my-app/1.4")
.build();
GraylogClient custom = GraylogClient.create(config);
System.out.println(config); // apiToken shown as [REDACTED]
Graylog settings¶
| Setting | Default | Environment variables (precedence order) |
|---|---|---|
apiToken (secret) — REST API token, sent as HTTP Basic <token>:token; wins over user/password |
none | GROW_GRAYLOG_API_TOKEN, GRAYLOG_API_TOKEN |
username + password (secret) — REST HTTP Basic credentials |
none | GROW_GRAYLOG_USER / GROW_GRAYLOG_PASSWORD, GRAYLOG_USER / GRAYLOG_PASSWORD |
url — REST base URL (paths start with /api) |
http://127.0.0.1:9000 |
GROW_GRAYLOG_URL, GRAYLOG_URL |
gelfHost — GELF host |
host of url |
GROW_GRAYLOG_GELF_HOST, GRAYLOG_GELF_HOST, platform GRAYLOG_HOST |
gelfPort — GELF port |
12202 for http, 12201 otherwise |
GROW_GRAYLOG_GELF_PORT, GRAYLOG_GELF_PORT, platform GRAYLOG_PORT |
gelfProtocol — default GELF transport udp, tcp or http |
tcp |
GROW_GRAYLOG_GELF_PROTOCOL, GRAYLOG_GELF_PROTOCOL, platform GRAYLOG_TRANSPORT |
gelfHttpUrl — full GELF HTTP endpoint |
http(s)://<gelfHost>:<gelfPort>/gelf |
GROW_GRAYLOG_GELF_HTTP_URL, GRAYLOG_GELF_HTTP_URL |
gelfTls — TLS for GELF TCP (and https for the default GELF HTTP URL), with the tls settings |
false |
GROW_GRAYLOG_GELF_TLS |
otlpEndpoint — OTLP/gRPC endpoint of a Graylog OpenTelemetry (gRPC) input |
http://<gelfHost>:4317 |
GROW_GRAYLOG_OTLP_ENDPOINT, GRAYLOG_OTLP_GRPC_ENDPOINT |
requestedBy — X-Requested-By header on non-GET requests (Graylog's CSRF guard) |
grow-codes-graylog |
— |
Names per language: TypeScript apiToken, gelfHttpUrl; Rust api_token, gelf_http_url; Go
APIToken, GelfHTTPURL, GelfTLS, OTLPEndpoint; Python api_token, gelf_http_url; Java
apiToken(…), basicAuth(user, password), gelfHttpUrl(…).
The platform aliases GRAYLOG_HOST, GRAYLOG_PORT and GRAYLOG_TRANSPORT are the variables that
Grow Codes stacks set for their Graylog service (TCP and UDP on 12201); they have the lowest
priority. validate() raises CONFIG for an invalid URL, a blank API token, a username without a password
(or the reverse), a port outside 1–65535, an unknown GELF protocol (otlp is a log client
protocol, not a gelfProtocol), a non-HTTP(S) gelfHttpUrl/otlpEndpoint or a blank
requestedBy.
Retry policy¶
| Field | Default | Meaning |
|---|---|---|
maxRetries |
3 | retries after the first attempt (so up to 4 attempts) |
initialBackoff |
100 ms | backoff cap of the first retry |
maxBackoff |
10 s | cap of every backoff |
multiplier |
2 | growth of the cap per retry |
maxRetryAfter |
60 s | longest server-requested Retry-After the client waits for |
Backoff for retry n (0-based) is full jitter: a random wait between 0 and
min(maxBackoff, initialBackoff × multiplier^n).
Requests are retried on HTTP 429, 408, 502, 503, 504 and on network errors. Idempotent
requests (GET HEAD OPTIONS PUT DELETE, or marked idempotent) are also retried on HTTP 500.
Other requests (for example POST) are retried only on 429 and on connection errors that happened
before the request was sent, never after an uncertain send.
On 429 and 503 the client honours Retry-After (seconds or HTTP date) and waits
max(retryAfter, backoff). When that wait exceeds maxRetryAfter or the remaining
totalTimeout, it stops at once with RATE_LIMITED/UNAVAILABLE and sets retryAfter on the
error. Set maxRetries to 0 to turn retries off.
Timeouts and cancellation¶
connectTimeoutbounds connection setup,requestTimeouteach attempt,totalTimeoutthe whole call including backoff sleeps. An exhausted timeout raisesTIMEOUT.- Cancellation is honoured during requests and backoff sleeps and raises
CANCELLED: TypeScript{ signal }(AbortSignal), Rust dropping the future, Goctx, Pythoncancel=(CancelToken) or task cancellation, Java…Asyncfutures (cancel(true)).
TLS and proxies¶
- Add a private CA with
tls.caCertPath(or the PEM text intls.caCertPem). - Mutual TLS needs
tls.clientCertPathandtls.clientKeyPathtogether. tls.insecureSkipVerifydisables certificate checks. Use it for local tests only; the client logs a warning once.HTTP_PROXY/HTTPS_PROXYare ignored so that credentials never leave through an unexpected proxy. Setproxy(orGROW_GRAYLOG_PROXY) to use one.