Quickstart¶
Connect to Grafana Loki, check that it is ready, push a log line, read it back and close the
client. The client reads GROW_GRAFANA_LOKI_URL and the optional tenant and credential variables
(and the vendor variables listed in Configuration), or
takes the values in code.
export GROW_GRAFANA_LOKI_URL=http://127.0.0.1:3100
export GROW_GRAFANA_LOKI_TENANT_ID=team-a # only for a multi-tenant Loki (X-Scope-OrgID)
# behind a gateway / Grafana Cloud: GROW_GRAFANA_LOKI_USERNAME + GROW_GRAFANA_LOKI_PASSWORD
# or GROW_GRAFANA_LOKI_BEARER_TOKEN, from your secret store (never commit them)
import { LogQL, LokiClient } from "@grow-codes/grafana-loki";
const client = LokiClient.fromEnv();
try {
const health = await client.health();
console.log("healthy:", health.healthy, health.status, await client.serverVersion());
// Push one stream; labels outside the allowlist go to structured metadata.
await client.push([
{
labels: { service_name: "checkout", level: "error" },
entries: [{ line: "payment failed", structuredMetadata: { order_id: "o-1" } }],
},
]);
// Read it back with a safely built LogQL query.
const logql = LogQL.selector({ service_name: "checkout" }).lineContains("payment").build();
const result = await client.queryRange(logql, { sinceMs: 5 * 60_000, limit: 10 });
for (const s of result.streams)
for (const e of s.entries) console.log(e.timestamp, e.line, e.structuredMetadata);
} finally {
await client.close();
}
use std::time::Duration;
use grow_grafana_loki::{Entry, LogQL, LokiClient, PushOptions, QueryRangeOptions, Stream};
#[tokio::main]
async fn main() -> grow_grafana_loki::Result<()> {
let client = LokiClient::from_env()?;
let health = client.health().await?;
println!("healthy: {} {} {}", health.healthy, health.status, client.server_version().await?);
// Push one stream; labels outside the allowlist go to structured metadata.
let stream = Stream::new([("service_name", "checkout"), ("level", "error")])
.entry(Entry::new("payment failed").metadata("order_id", "o-1"));
client.push(&[stream], PushOptions::default()).await?;
// Read it back with a safely built LogQL query.
let logql = LogQL::selector([("service_name", "checkout")]).line_contains("payment").build()?;
let opts = QueryRangeOptions { since: Some(Duration::from_secs(300)), limit: 10, ..Default::default() };
for s in client.query_range(&logql, opts).await?.streams {
for e in s.entries {
println!("{:?} {} {:?}", e.timestamp, e.line, e.structured_metadata);
}
}
client.close().await;
Ok(())
}
package main
import (
"context"
"fmt"
"log"
"time"
loki "github.com/grow-codes-packages/grafana-loki/go"
)
func main() {
ctx := context.Background()
client, err := loki.NewClientFromEnv()
if err != nil {
log.Fatal(err)
}
defer client.Close()
health, err := client.Health(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println("healthy:", health.Healthy, health.Status)
// Push one stream; labels outside the allowlist go to structured metadata.
err = client.Push(ctx, []loki.Stream{{
Labels: map[string]string{"service_name": "checkout", "level": "error"},
Entries: []loki.Entry{{Line: "payment failed", StructuredMetadata: map[string]string{"order_id": "o-1"}}},
}}, loki.PushOptions{})
if err != nil {
log.Fatal(err) // errors.Is(err, loki.ErrAuthentication), loki.ErrValidation, ...
}
// Read it back with a safely built LogQL query.
logql, err := loki.Selector(map[string]string{"service_name": "checkout"}).LineContains("payment").Build()
if err != nil {
log.Fatal(err)
}
res, err := client.QueryRange(ctx, logql, loki.QueryRangeOptions{Since: 5 * time.Minute, Limit: 10})
if err != nil {
log.Fatal(err)
}
for _, s := range res.Streams {
for _, e := range s.Entries {
fmt.Println(e.Timestamp, e.Line, e.StructuredMetadata)
}
}
}
from grow_grafana_loki import LogQL, LokiClient, LokiEntry, LokiStream
with LokiClient.from_env() as client:
health = client.health()
print("healthy:", health.healthy, health.status, client.server_version())
# Push one stream; labels outside the allowlist go to structured metadata.
client.push([
LokiStream(
{"service_name": "checkout", "level": "error"},
[LokiEntry("payment failed", structured_metadata={"order_id": "o-1"})],
)
])
# Read it back with a safely built LogQL query.
logql = LogQL.selector({"service_name": "checkout"}).line_contains("payment").build()
for stream in client.query_range(logql, since_s=300, limit=10).streams:
for entry in stream.entries:
print(entry.timestamp, entry.line, entry.structured_metadata)
import codes.grow.packages.loki.*;
import java.time.Duration;
import java.util.List;
import java.util.Map;
try (LokiClient client = LokiClient.fromEnv()) {
var health = client.health();
System.out.println("healthy: " + health.healthy() + " " + client.serverVersion());
// Push one stream; labels outside the allowlist go to structured metadata.
client.push(List.of(LokiStream.of(
Map.of("service_name", "checkout", "level", "error"),
LokiEntry.of(java.time.Instant.now(), "payment failed", Map.of("order_id", "o-1")))));
// Read it back with a safely built LogQL query.
String logql = LogQL.selector(Map.of("service_name", "checkout")).lineContains("payment").build();
QueryResult result = client.queryRange(logql,
QueryRangeOptions.builder().since(Duration.ofMinutes(5)).limit(10).build());
for (StreamResult s : result.streams()) {
for (StreamEntry e : s.entries()) {
System.out.println(e.timestamp() + " " + e.line() + " " + e.structuredMetadata());
}
}
}
Async code: Python AsyncLokiClient (async with AsyncLokiClient.from_env() as client: and
await on every call), Java …Async methods returning CompletableFuture, Rust's blocking
feature for synchronous code.
Next steps¶
- Configuration: timeouts, retries, TLS, proxy, environment variables.
- Functions: the Grafana Loki API of this SDK (push, query, tail, LogQL builder).
- Logging: batching log client, logger facade and framework adapters.
- Error handling: error codes and retries.