Skip to content

Client and status

Create one client per process, reuse it everywhere and close it on shutdown. close() is idempotent: it flushes the log clients created from this client and stops open tails. Calls on a closed client fail with CANCELLED.

Function Loki API Result
fromEnv() — client configured from GROW_GRAFANA_LOKI_* / LOKI_* (Configuration)
health() GET /ready HealthStatus{healthy, status, details}; never throws for an unhealthy or unreachable server (status is Loki's text, e.g. Ingester not ready: waiting for 15s after being ready, or unreachable)
ready() GET /ready true when Loki answers 200
ping() GET /loki/api/v1/labels?since=5m latency of an authenticated call; AUTHENTICATION when the tenant or gateway credentials are missing or wrong
buildInfo() GET /loki/api/v1/status/buildinfo version, revision, branch, buildUser, buildDate, goVersion
serverVersion() same the version string, e.g. 3.7.10
withTenant(id) — a client for another tenant (X-Scope-OrgID: id on every request and the tail handshake) that shares the connections; the original client is unchanged; VALIDATION for an invalid id
close() — flushes log clients, stops tails, releases connections (children from withTenant leave the shared connections open)
import { LokiClient } from "@grow-codes/grafana-loki";

const client = LokiClient.fromEnv();
try {
  const health = await client.health(); // { healthy, status, details }
  if (!health.healthy) console.warn("Loki is not ready:", health.status);
  console.log(await client.ready(), await client.ping(), "ms");
  const info = await client.buildInfo();
  console.log(info.version === (await client.serverVersion()));

  const teamA = client.withTenant("team-a"); // X-Scope-OrgID: team-a
  console.log(await teamA.labels());
} finally {
  await client.close();
}
use grow_grafana_loki::{LabelsOptions, LokiClient};

let client = LokiClient::from_env()?;
let health = client.health().await?;
if !health.healthy {
    eprintln!("Loki is not ready: {}", health.status);
}
println!("{} {:?}", client.ready().await?, client.ping().await?);
let info = client.build_info().await?;
assert_eq!(info.version, client.server_version().await?);

let team_a = client.with_tenant("team-a")?;
println!("{:?}", team_a.labels(LabelsOptions::default()).await?);
client.close().await;
client, err := loki.NewClientFromEnv()
if err != nil {
    return err
}
defer client.Close()

health, err := client.Health(ctx)
if err != nil {
    return err
}
if !health.Healthy {
    log.Println("Loki is not ready:", health.Status)
}
latency, err := client.Ping(ctx) // errors.Is(err, loki.ErrAuthentication)
info, err := client.BuildInfo(ctx)
version, err := client.ServerVersion(ctx)

teamA, err := client.WithTenant("team-a")
labels, err := teamA.Labels(ctx, loki.LabelsOptions{})
from grow_grafana_loki import LokiClient

with LokiClient.from_env() as client:
    health = client.health()
    if not health.healthy:
        print("Loki is not ready:", health.status)
    print(client.ready(), client.ping(), "ms")
    info = client.build_info()
    assert info.version == client.server_version()

    team_a = client.with_tenant("team-a")
    print(team_a.labels())

AsyncLokiClient has the same methods (async with AsyncLokiClient.from_env() as client:, await client.health(), await client.aclose()).

import codes.grow.packages.loki.LokiClient;

try (LokiClient client = LokiClient.fromEnv()) {
    var health = client.health();
    if (!health.healthy()) {
        System.err.println("Loki is not ready: " + health.status());
    }
    System.out.println(client.ready() + " " + client.ping());
    var info = client.buildInfo();
    System.out.println(info.version().equals(client.serverVersion()));

    LokiClient teamA = client.withTenant("team-a");
    System.out.println(teamA.labels());
}

Every I/O method has a …Async variant returning CompletableFuture (client.healthAsync(), client.pingAsync(), …).

Multi-tenancy

With auth_enabled: true Loki requires X-Scope-OrgID on every data API and answers 401 no org id without it (AUTHENTICATION). Configure tenantId once or derive per-tenant clients with withTenant(id). Tenant ids follow Loki's rules (at most 150 bytes, not ./.., only A-Z a-z 0-9 ! - _ . * ' ( )). a|b queries several tenants at once and needs multiTenantQueries: true in the config and multi_tenant_queries_enabled on the server; pushing to a|b is always rejected by Loki (400 multiple org IDs present).