Accepts a LokiConfig or plain options.
Optionalshared: LokiClientSharedThe tenant this client sends as X-Scope-OrgID, if any.
Build information: GET /loki/api/v1/status/buildinfo.
Flushes and closes log clients created by logClient, stops open tails and releases connections (children from withTenant leave the shared connections open). Idempotent.
Normalizes a LogQL query on the server (GET /loki/api/v1/format_query).
Readiness: GET /ready. 200 ready → healthy ok; 503 → unhealthy with Loki's text
(e.g. Ingester not ready: waiting for 15s after being ready); network errors →
unreachable. Never throws except for CANCELLED and CONFIG.
Approximate index statistics: GET /loki/api/v1/index/stats. Reads the TSDB index only,
so data still in the ingester counts after the next chunk flush.
Label names: GET /loki/api/v1/labels (an empty result is []).
Values of one label: GET /loki/api/v1/label/{name}/values. The name is validated client
side (Loki answers unknown and invalid names with an empty result).
A batching LogClient that writes to this Loki (and tenant). Records go through
redaction and the cardinality guard; protocol: "otlp" uses /otlp/v1/logs instead.
close flushes and closes every log client created here.
A LogQueryClient (search, tail, listStreams, listLabels, waitForLog) on this Loki.
Authenticated round trip: GET /loki/api/v1/labels?since=5m with auth and tenant headers.
Returns the latency in milliseconds; AuthenticationError without a tenant (multi-tenant
Loki) or with wrong gateway credentials.
Pushes streams with POST /loki/api/v1/push. JSON by default (optionally gzip);
format: "protobuf" sends a Snappy-compressed PushRequest. The cardinality guard moves
labels outside config.allowedLabels to every entry's structured metadata (unless
config.disableLabelGuard), then labels are validated client side. Entries without a
timestamp get "now". Retrying is safe: Loki drops entries identical to stored ones (same labels,
timestamp and line), so the push is marked idempotent and retried on 5xx and network
errors. Status 260 (ingestion blocked by the operator) throws a non-retryable error.
Pushes records as OTLP/JSON to POST /otlp/v1/logs (Loki's OTLP endpoint). Loki promotes
its default resource attributes (service.name, deployment.environment, …) to labels and
stores everything else as structured metadata.
Instant metric query: GET /loki/api/v1/query. A plain log selector ({...} with or
without a pipeline) is rejected with ValidationError, as Loki does not run log queries
as instant queries; use queryRange instead.
Range query (logs or metrics): GET /loki/api/v1/query_range.
true when GET /ready answers 200 (same probe as health).
Series matching any of the selectors: GET /loki/api/v1/series (at least one matcher).
Server version (buildInfo().version, e.g. "3.7.10").
Live tail over WebSocket (/loki/api/v1/tail). Resolves once connected; handshake errors
reject (AuthenticationError, ValidationError, …). onEntries receives the streams of
every frame; dropped entries go to onDropped, later errors to onError. Only log queries
(starting with {) are allowed. Stop with handle.stop() or close().
Proxies are not used for the WebSocket.
Ingested bytes per series or label: GET /loki/api/v1/index/volume (vector result).
Needs limits_config.volume_enabled: true; otherwise Loki returns an empty vector.
Volume over time: GET /loki/api/v1/index/volume_range. Always a matrix: Loki answers
with a vector when every series has a single point, which is converted to one-sample
matrix series.
A client for another tenant: shares this client's connections, sends X-Scope-OrgID: id
on every request and on the tail handshake. This client is unchanged. Closing the child
does not close the shared connections. Throws ValidationError for an invalid id.
StaticfromBuilds a client from GROW_GRAFANA_LOKI_* (and LOKI_*) environment variables.
Client for Grafana Loki: push (JSON, protobuf + Snappy, OTLP), LogQL queries, labels, series, index stats and volume, WebSocket tail, status, multi-tenancy and the logging category (
logClient(),logQueryClient()).