Configuration¶
DatadogLogsConfig 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 the API key and the application key.
Datadog settings¶
| Setting | Default | Environment variables (in order) |
|---|---|---|
apiKey — header DD-API-KEY (secret, required) |
none | GROW_DATADOG_LOGS_API_KEY, DD_API_KEY |
appKey — header DD-APPLICATION-KEY, query API only (secret) |
none | GROW_DATADOG_LOGS_APP_KEY, DD_APP_KEY, DD_APPLICATION_KEY |
site — Datadog site |
datadoghq.com |
GROW_DATADOG_LOGS_SITE, DD_SITE |
url — one base URL for intake and API (proxy, fakeintake) |
derived from site |
GROW_DATADOG_LOGS_URL |
intakeUrl — logs intake base URL |
url, else https://http-intake.logs.<site> |
GROW_DATADOG_LOGS_INTAKE_URL |
apiUrl — API base URL (validate, search, aggregate, indexes) |
url, else https://api.<site> |
GROW_DATADOG_LOGS_API_URL |
service — service of every log without a service.name resource |
none | GROW_DATADOG_LOGS_SERVICE, DD_SERVICE |
env — tag env:<value> without a deployment.environment resource |
none | GROW_DATADOG_LOGS_ENV, DD_ENV |
version — tag version:<value> without a service.version resource |
none | GROW_DATADOG_LOGS_VERSION, DD_VERSION |
tags — extra key:value tags |
none | GROW_DATADOG_LOGS_TAGS, DD_TAGS |
hostname — hostname without a host.name resource |
none | GROW_DATADOG_LOGS_HOSTNAME, DD_HOSTNAME |
source — ddsource (selects Datadog integration pipelines) |
grow-sdk |
GROW_DATADOG_LOGS_SOURCE |
Rules (identical in every language):
- Sites:
datadoghq.com,us3.datadoghq.com,us5.datadoghq.com,ap1.datadoghq.com,ap2.datadoghq.com,uk1.datadoghq.com,datadoghq.eu,ddog-gov.com,us2.ddog-gov.com(trimmed, case-insensitive). Use the API site, not the UI host (app.datadoghq.com). An unknown site is aCONFIGerror unlessurlor bothintakeUrlandapiUrlare set. - Keys:
apiKeyis required by every call, includinghealth().appKeyis only needed forclient.query()(which raisesCONFIGwithout it) and is never sent to the intake. A blank key is aCONFIGerror. - Tags:
DD_TAGS/tagsas one string are split on commas and whitespace (the Datadog Agent convention), empty items and duplicates dropped.ddtagson the wire isenv:<env>,version:<version>, thentags; whitespace or commas inside one tag become_.
Common settings¶
| Setting | Default | Environment variable |
|---|---|---|
connectTimeout — connection setup |
10 s | GROW_DATADOG_LOGS_CONNECT_TIMEOUT |
requestTimeout — per attempt (headers + body) |
30 s | GROW_DATADOG_LOGS_REQUEST_TIMEOUT |
totalTimeout — whole call incl. retries and backoff |
120 s | GROW_DATADOG_LOGS_TOTAL_TIMEOUT |
retry — retry policy (below) |
3 retries | GROW_DATADOG_LOGS_MAX_RETRIES |
tls.caCertPath / tls.caCertPem — extra CA |
none | GROW_DATADOG_LOGS_CA_CERT (path) |
tls.clientCertPath + tls.clientKeyPath — mutual TLS |
none | GROW_DATADOG_LOGS_CLIENT_CERT, GROW_DATADOG_LOGS_CLIENT_KEY |
tls.insecureSkipVerify — tests only, logs a warning once |
false |
GROW_DATADOG_LOGS_INSECURE_SKIP_VERIFY |
proxy — proxy URL |
none (environment proxies are ignored) | GROW_DATADOG_LOGS_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-datadog-logs/<version> (<language>).
From the environment¶
fromEnv resolves each setting with this precedence:
- the value passed in code (overrides),
GROW_DATADOG_LOGS_<NAME>,- the Datadog variables (
DD_API_KEY,DD_SITE, …) in the order of the table above, - 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 { DatadogLogsClient, DatadogLogsConfig } from "@grow-codes/datadog-logs";
// Environment only
const client = DatadogLogsClient.fromEnv();
// Environment with explicit overrides (explicit values win)
const config = DatadogLogsConfig.fromEnv({ service: "checkout", requestTimeoutMs: 5_000 });
// Everything in code
const explicit = new DatadogLogsConfig({
apiKey: process.env.MY_DD_API_KEY,
appKey: process.env.MY_DD_APP_KEY, // only for client.query()
site: "datadoghq.eu",
service: "checkout",
env: "prod",
version: "1.4.0",
tags: ["team:payments"],
totalTimeoutMs: 60_000,
retry: { maxRetries: 5, initialBackoffMs: 200 },
proxy: "http://proxy.internal:3128",
userAgentSuffix: "my-app/1.4",
});
const custom = new DatadogLogsClient(explicit);
console.log(String(explicit)); // keys shown as [REDACTED]
use std::time::Duration;
use grow_datadog_logs::{DatadogLogsClient, DatadogLogsConfig};
// Environment only
let client = DatadogLogsClient::from_env()?;
// Environment with explicit overrides (explicit values win)
let config = DatadogLogsConfig::builder()
.service("checkout")
.request_timeout(Duration::from_secs(5))
.build_from_env()?;
// Everything in code
let explicit = DatadogLogsConfig::builder()
.api_key(std::env::var("MY_DD_API_KEY").unwrap_or_default())
.app_key(std::env::var("MY_DD_APP_KEY").unwrap_or_default()) // only for client.query()
.site("datadoghq.eu")
.service("checkout")
.env("prod")
.version("1.4.0")
.tags(["team:payments"])
.total_timeout(Duration::from_secs(60))
.max_retries(5)
.proxy("http://proxy.internal:3128")
.user_agent_suffix("my-app/1.4")
.build()?;
let custom = DatadogLogsClient::new(explicit)?;
println!("{:?}", custom.config()); // keys shown as [REDACTED]
// Environment only
client, err := datadoglogs.NewClientFromEnv()
// Everything in code: zero values mean "use the default"
cfg := datadoglogs.Config{
CommonConfig: datadoglogs.CommonConfig{
TotalTimeout: time.Minute,
Retry: &datadoglogs.RetryPolicy{MaxRetries: 5, InitialBackoff: 200 * time.Millisecond},
Proxy: "http://proxy.internal:3128",
UserAgentSuffix: "my-app/1.4",
},
APIKey: datadoglogs.NewSecret(os.Getenv("MY_DD_API_KEY")),
AppKey: datadoglogs.NewSecret(os.Getenv("MY_DD_APP_KEY")), // only for client.Query()
Site: "datadoghq.eu",
Service: "checkout",
Env: "prod",
Version: "1.4.0",
Tags: []string{"team:payments"},
}
if err := cfg.Validate(); err != nil {
log.Fatal(err) // errors.Is(err, datadoglogs.ErrConfig)
}
custom, err := datadoglogs.NewClient(cfg)
// Environment with explicit overrides (explicit values win; nil env = process environment)
merged, err := datadoglogs.ConfigFromEnvWith(datadoglogs.Config{Service: "checkout"}, nil)
fmt.Println(merged) // keys shown as [REDACTED]
import os
from grow_datadog_logs import DatadogLogsClient, DatadogLogsConfig, RetryPolicy
# Environment only
client = DatadogLogsClient.from_env()
# Environment with explicit overrides (explicit values win)
config = DatadogLogsConfig.from_env(service="checkout", request_timeout=5.0)
# a test environment instead of os.environ (positional-only, see Compatibility)
test_config = DatadogLogsConfig.from_env({"DD_API_KEY": "test"}, env="ci")
# Everything in code: durations are float seconds (datetime.timedelta also works)
explicit = DatadogLogsConfig(
api_key=os.environ["MY_DD_API_KEY"],
app_key=os.environ.get("MY_DD_APP_KEY"), # only for client.query()
site="datadoghq.eu",
service="checkout",
env="prod",
version="1.4.0",
tags=("team:payments",),
total_timeout=60.0,
retry=RetryPolicy(max_retries=5, initial_backoff=0.2),
proxy="http://proxy.internal:3128",
user_agent_suffix="my-app/1.4",
)
custom = DatadogLogsClient(explicit)
print(repr(explicit)) # keys shown as [REDACTED]
import java.time.Duration;
import java.util.List;
import codes.grow.packages.datadoglogs.DatadogLogsClient;
import codes.grow.packages.datadoglogs.DatadogLogsConfig;
import codes.grow.packages.datadoglogs.core.RetryPolicy;
// Environment only
DatadogLogsClient client = DatadogLogsClient.fromEnv();
// Everything in code
DatadogLogsConfig config = DatadogLogsConfig.builder()
.apiKey(System.getenv("MY_DD_API_KEY"))
.appKey(System.getenv("MY_DD_APP_KEY")) // only for client.query()
.site("datadoghq.eu")
.service("checkout")
.env("prod")
.version("1.4.0")
.tags(List.of("team:payments"))
.totalTimeout(Duration.ofMinutes(1))
.retry(RetryPolicy.builder().maxRetries(5).initialBackoff(Duration.ofMillis(200)).build())
.proxy("http://proxy.internal:3128")
.userAgentSuffix("my-app/1.4")
.build();
DatadogLogsClient custom = DatadogLogsClient.create(config);
System.out.println(config); // keys shown as [REDACTED]
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 wait the client accepts |
Backoff for retry n (0-based) is full jitter: a random wait between 0 and
min(maxBackoff, initialBackoff × multiplier^n).
Datadog rules on top of the shared transport:
- Every Datadog request is retried on HTTP 429, 408, 500, 502, 503, 504 and on network errors. This
includes the intake
POSTand the read-only search/aggregatePOSTs: Datadog has no idempotency key, so a retried intake request can store a batch twice when the first answer was lost. - On 429 and 503 the client honours
Retry-After; when it is missing,X-RateLimit-Reset(seconds until the rate-limit window resets) is the hint. It waitsmax(hint, backoff). When the hint exceedsmaxRetryAfteror the remainingtotalTimeout, it stops at once withRATE_LIMITED/UNAVAILABLEand setsretryAfteron the error. - Every 403 from Datadog (missing or invalid key, or a key without the needed permission, which
Datadog does not tell apart) becomes
AUTHENTICATIONwithhttpStatus403.
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)). - Every call on a closed client raises
CANCELLED.
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 keys never leave through an unexpected proxy. Setproxy(orGROW_DATADOG_LOGS_PROXY) to use one.