Functions¶
The Grafana Loki API of this SDK. Every function exists in all five languages with the same behaviour, defaults and error codes; names follow each language's convention. Each module page shows every function with an example per language.
| Module | Page | What it covers |
|---|---|---|
| Client and status | Client and status | fromEnv, health, ready, ping, buildInfo, serverVersion, withTenant, close |
| Push | Push | push (JSON, gzip, protobuf + Snappy), structured metadata, label validation, cardinality guard, pushOtlp |
| Query | Query | query, queryRange, labels, labelValues, series, indexStats, volume, volumeRange, formatQuery |
| Tail | Tail | tail (WebSocket live tail) |
| LogQL builder | LogQL builder | LogQL.selector(...).lineContains(...).json().where(...) with escaping |
| Logging category | Loki log client and search | logClient / OTLP log client, logQueryClient (search, tail, listStreams, listLabels, waitForLog) |
Names per language¶
| Function | TypeScript | Rust | Go | Python | Java |
|---|---|---|---|---|---|
| from environment | LokiClient.fromEnv() |
LokiClient::from_env() |
loki.NewClientFromEnv() |
LokiClient.from_env() |
LokiClient.fromEnv() |
| health | health() |
health() |
Health(ctx) |
health() |
health() |
| ready | ready() |
ready() |
Ready(ctx) |
ready() |
ready() |
| ping | ping() → ms |
ping() → Duration |
Ping(ctx) → time.Duration |
ping() → ms |
ping() → Duration |
| build info | buildInfo() |
build_info() |
BuildInfo(ctx) |
build_info() |
buildInfo() |
| server version | serverVersion() |
server_version() |
ServerVersion(ctx) |
server_version() |
serverVersion() |
| tenant | withTenant(id) |
with_tenant(id) |
WithTenant(id) |
with_tenant(id) |
withTenant(id) |
| push | push(streams, opts) |
push(&streams, opts) |
Push(ctx, streams, opts) |
push(streams, ...) |
push(streams, opts) |
| OTLP push | pushOtlp(records) |
push_otlp(&records, gzip) |
PushOTLP(ctx, records, opts) |
push_otlp(records) |
pushOtlp(records) |
| instant query | query(logql) |
query(logql, opts) |
Query(ctx, logql, opts) |
query(logql) |
query(logql) |
| range query | queryRange(logql) |
query_range(logql, opts) |
QueryRange(ctx, logql, opts) |
query_range(logql) |
queryRange(logql) |
| label names | labels() |
labels(opts) |
Labels(ctx, opts) |
labels() |
labels() |
| label values | labelValues(name) |
label_values(name, opts) |
LabelValues(ctx, name, opts) |
label_values(name) |
labelValues(name) |
| series | series(matchers) |
series(&matchers, opts) |
Series(ctx, matchers, opts) |
series(matchers) |
series(matchers) |
| index stats | indexStats(q) |
index_stats(q, opts) |
IndexStats(ctx, q, opts) |
index_stats(q) |
indexStats(q) |
| volume | volume(q) |
volume(q, opts) |
Volume(ctx, q, opts) |
volume(q) |
volume(q) |
| volume over time | volumeRange(q) |
volume_range(q, opts) |
VolumeRange(ctx, q, opts) |
volume_range(q) |
volumeRange(q) |
| format LogQL | formatQuery(q) |
format_query(q) |
FormatQuery(ctx, q) |
format_query(q) |
formatQuery(q) |
| live tail | tail(q, onEntries, opts) |
tail(q, on_entries, opts) |
Tail(ctx, q, onEntries, opts) |
tail(q, on_entries) |
tail(q, onFrame, opts) |
| log client | logClient(opts) |
new_log_client(opts) |
NewLogClient(opts) |
log_client() |
logClient(opts) |
| OTLP log client | logClient({ protocol: "otlp" }) |
new_otlp_log_client(opts) |
NewOTLPLogClient(opts) |
otlp_log_client() |
logClient(…protocol(OTLP)) |
| log query client | logQueryClient() |
log_query() |
LogQuery() |
log_query() |
logQueryClient() |
| close | await close() |
close().await |
Close() |
close() / with |
close() / try-with-resources |
Async variants: TypeScript and Rust are async throughout; Python has AsyncLokiClient with the
same methods; Java has a …Async variant (CompletableFuture) of every I/O method; Go takes a
context.Context. Rust also has a blocking client (feature blocking).
Behaviour shared by every function¶
- Every request carries the configured
Authorization(Basic or Bearer) andX-Scope-OrgIDheaders; query calls also sendX-Loki-Response-Encoding-Flags: categorize-labels, so results separate index labels, structured metadata and parsed labels. - Errors map to the canonical codes (Error handling): 400/405/422 →
VALIDATION, 401 (no org id, gateway) →AUTHENTICATION, 403 →PERMISSION_DENIED, 404 →NOT_FOUND, 429 →RATE_LIMITED(withRetry-After), 500/502/503 →UNAVAILABLE(retryable), 504 →TIMEOUT. A 500/503 saying "Ingester is shutting down" (WAL disk at least 90 % full) is a retryableUNAVAILABLEwith a hint about the cause. Push status 260 (ingestion blocked by the operator) is a non-retryableUNAVAILABLE. - Timestamps are Unix nanoseconds on the wire and lossless in every language (TypeScript keeps
timestampNsstrings next toDatevalues).
Settings such as the tenant, credentials and the cardinality guard are described in Configuration.