Para enviar logs de uma aplicação pequena ao Loki, faça um POST para /loki/api/v1/push com um corpo JSON que contenha streams, labels e pares de timestamp e mensagem. Em Python, a documentação oficial demonstra o envio com requests; em PHP, o mesmo formato pode ser enviado com um cliente HTTP comum. O endereço completo, a autenticação e os cabeçalhos de tenant dependem de como o Loki foi implantado.
O que o endpoint do Loki espera
O endpoint padrão de gravação é POST /loki/api/v1/push. A forma JSON é adequada para exemplos e integrações pequenas porque é fácil de inspecionar. Envie o cabeçalho Content-Type: application/json e um corpo com um array streams. Cada item tem um objeto stream, que contém labels, e um array values, cujos itens são pares: timestamp seguido do texto do log.
As an Amazon Associate I earn from qualifying purchases.
{
"streams": [
{
"stream": {"job": "mini-app", "environment": "dev"},
"values": [
["1735689600000000000", "application started"]
]
}
]
}O timestamp desse exemplo é um valor Unix epoch em nanossegundos, codificado como string. Use o horário do evento, não um contador de tempo decorrido. As labels descrevem o stream; mantenha nelas dimensões estáveis, como o nome da aplicação e o ambiente, e coloque detalhes variáveis — por exemplo, um identificador de requisição — no texto do log.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsJSON não é a única codificação aceita. A referência da API documenta Snappy-compressed Protocol Buffers como o comportamento padrão, com Content-Type: application/x-protobuf, além da opção JSON. Se escolher JSON, envie explicitamente o cabeçalho correspondente e não misture esse formato com o corpo Protobuf.
#1 Best Overall
Como enviar logs de Python
O exemplo oficial do Grafana usa requests para preparar o payload, fazer o POST e verificar a resposta com raise_for_status(). Este exemplo segue esse fluxo e deixa o endereço e as credenciais como configuração do ambiente, em vez de gravá-los no código:
import os
import time
import requests
loki_url = os.environ["LOKI_URL"].rstrip("/")
push_url = f"{loki_url}/loki/api/v1/push"
payload = {
"streams": [
{
"stream": {"job": "mini-app", "environment": "dev"},
"values": [[str(time.time_ns()), "application started"]],
}
]
}
headers = {"Content-Type": "application/json"}
tenant_id = os.getenv("LOKI_TENANT_ID")
if tenant_id:
headers["X-Scope-OrgID"] = tenant_id
auth_user = os.getenv("LOKI_USERNAME")
auth_token = os.getenv("LOKI_TOKEN")
auth = (auth_user, auth_token) if auth_user and auth_token else None
response = requests.post(
push_url,
json=payload,
headers=headers,
auth=auth,
timeout=10,
)
response.raise_for_status()Instale requests no ambiente da aplicação. Configure LOKI_URL com a URL-base fornecida pela sua implantação; o código acrescenta o caminho de push. Para uso assíncrono, a documentação oficial também aponta httpx como alternativa com uma API semelhante.
Como enviar logs de PHP
Não há uma receita oficial específica de PHP nas referências citadas; o exemplo abaixo é uma implementação ilustrativa com cURL da API HTTP genérica. Confira a sintaxe e as opções disponíveis na versão do PHP e do cURL instaladas. A configuração do tenant e da autenticação deve corresponder à implantação.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
<?php
$lokiUrl = rtrim(getenv('LOKI_URL'), '/');
$pushUrl = $lokiUrl . '/loki/api/v1/push';
$timestampNs = sprintf('%.0f', microtime(true) * 1000000000);
$payload = [
'streams' => [[
'stream' => ['job' => 'mini-app', 'environment' => 'dev'],
'values' => [[$timestampNs, 'application started']],
]],
];
$headers = ['Content-Type: application/json'];
$tenantId = getenv('LOKI_TENANT_ID');
if ($tenantId !== false && $tenantId !== '') {
$headers[] = 'X-Scope-OrgID: ' . $tenantId;
}
$ch = curl_init($pushUrl);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
]);
$username = getenv('LOKI_USERNAME');
$token = getenv('LOKI_TOKEN');
if ($username !== false && $token !== false) {
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $token);
}
$responseBody = curl_exec($ch);
if ($responseBody === false) {
$error = curl_error($ch);
curl_close($ch);
throw new RuntimeException('Falha na chamada HTTP ao Loki: ' . $error);
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status < 200 || $status >= 300) {
throw new RuntimeException('Loki respondeu HTTP ' . $status);
}microtime(true) fornece tempo Unix com precisão limitada pelo relógio e pela representação numérica do PHP; formatar o resultado como inteiro não cria precisão real de nanossegundos. O formato da API exige a string do timestamp em nanossegundos, mas a aplicação deve usar uma fonte de horário apropriada e não presumir que esse cálculo tenha precisão de relógio de alta resolução.
Configure endpoint, autenticação e tenant
O URL final é a URL-base do serviço mais /loki/api/v1/push. O exemplo local sem autenticação usado na documentação é destinado a uma instância acessível localmente, não deve ser tomado como configuração segura para produção. Em instalações próprias, a API do Loki não implica, por si só, autenticação de usuário: uma configuração comum é colocar um proxy autenticador, como NGINX, à frente do serviço.
Em modo multi-tenant, as requisições precisam identificar o tenant com X-Scope-OrgID. Esse cabeçalho deve ser definido pelo cliente ou por um proxy confiável, conforme o modelo de confiança da implantação; não o aceite cegamente de clientes não confiáveis.
Na Grafana Cloud, use a URL do serviço Loki e as informações de usuário/instância exibidas nas configurações da conta, junto com um token de access policy, seguindo as instruções atuais do serviço. Os exemplos Python oficiais demonstram Basic Authentication. Guarde o token em um mecanismo de segredos ou variável de ambiente protegida; não o comite no repositório.
A documentação de autenticação também descreve mTLS. TLS mútuo não preenche X-Scope-OrgID: se auth_enabled estiver ativo, a identificação do tenant continua necessária e precisa ser acrescentada pelo cliente, agente ou proxy adequado.
Escolha labels e respeite limites
Labels definem a identidade do stream. Prefira um conjunto pequeno e previsível, como job, environment e serviço. IDs únicos por evento, URLs completas ou outros valores altamente variáveis tendem a criar muitos streams e não são boas labels; mantenha esses dados na linha de log.
Para a API padrão de push da Grafana Cloud, a página de limites consultada em 2026 informa máximo de 256 KB por linha e 15 labels por stream. Esses números se aplicam ao serviço Cloud documentado, não são limites universais para toda instalação autogerenciada. Confira os limites vigentes da sua implantação.
Diagnostique respostas 400, 401, 429 e 5xx
Verifique o status HTTP e, quando seguro, o corpo da resposta. Não registre tokens, cabeçalhos de autenticação nem dados sensíveis ao investigar falhas. O exemplo Python oficial usa raise_for_status() para transformar respostas HTTP de erro em exceções tratáveis.
- 400: inspecione o payload, o timestamp, o cabeçalho de conteúdo e a configuração do stream. Reenviar sem corrigir uma requisição malformada não resolve o problema.
- 401: confira credenciais e o mecanismo de autenticação do serviço. Em Loki autogerenciado, verifique também a configuração do proxy que protege o endpoint.
- 429: pode indicar limitação de taxa. Reduza a taxa de envio e faça novas tentativas com espera crescente e limite de tentativas.
- 5xx: pode ser transitório ou refletir um problema do serviço. Use novas tentativas limitadas com backoff e monitore falhas persistentes.
Antes de conectar a aplicação, faça um smoke test com o exemplo curl JSON da referência oficial da API, adaptado ao endpoint e à autenticação reais. Depois envie uma linha pela aplicação e confirme que ela aparece no fluxo de consulta Loki/Grafana usado pela equipe. Isso separa problemas de conectividade e configuração de problemas no código da aplicação.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
