iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Para enviar logs de uma aplicação Python ou PHP ao Loki, faça um POST para /loki/api/v1/push com um corpo JSON que contenha rótulos e pares de timestamp e mensagem. O endpoint, a autenticação e os cabeçalhos de tenant dependem de como o Loki está hospedado. Abaixo estão exemplos legíveis com Python e PHP, além dos cuidados para evitar erros comuns.
Como funciona o envio HTTP para o Loki
O endpoint padrão é POST /loki/api/v1/push. Combine esse caminho com a URL base da sua instância; por exemplo, a documentação usa http://localhost:3100 em uma chamada local. Esse endereço é um exemplo de desenvolvimento, não uma recomendação de endpoint público ou de produção.
O formato JSON exige o cabeçalho Content-Type: application/json e um objeto com a propriedade streams. Cada stream reúne um conjunto de rótulos e uma lista de entradas. Cada entrada contém primeiro um timestamp Unix em nanossegundos, representado como texto, e depois a linha de log, também como texto.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall{
"streams": [
{
"stream": {"job": "mini-app", "environment": "dev"},
"values": [
["1760000000000000000", "application started"]
]
}
]
}O timestamp do exemplo é apenas um valor ilustrativo no formato esperado; gere-o a partir do instante real do evento. Rótulos identificam e agrupam streams. Use valores estáveis e úteis, como nome do serviço e ambiente, em vez de colocar dados que variam a cada linha — por exemplo, um identificador de usuário ou de requisição — nos rótulos.
#1 Best Overall
JSON não é a única codificação
A referência da API documenta JSON, mas descreve Snappy-compressed Protocol Buffers como o comportamento padrão, normalmente com Content-Type: application/x-protobuf. Este guia escolhe JSON porque é fácil de inspecionar durante a integração. Se seu cliente ou agente envia protobuf, siga a codificação e os cabeçalhos correspondentes; não misture um corpo JSON com o tipo de conteúdo de protobuf.
Enviar logs de Python
O exemplo oficial de Python da Grafana usa a biblioteca requests, monta a estrutura de streams, envia JSON e verifica a resposta com raise_for_status(). Instale a dependência no ambiente da aplicação, por exemplo com python -m pip install requests, e adapte o envio ao ponto do código em que a mensagem de log já está disponível.
import time
import requests
LOKI_URL = "http://localhost:3100"
payload = {
"streams": [
{
"stream": {"job": "mini-app", "environment": "dev"},
"values": [
[str(time.time_ns()), "application started"]
],
}
]
}
response = requests.post(
f"{LOKI_URL}/loki/api/v1/push",
json=payload,
timeout=10,
)
response.raise_for_status()time.time_ns() fornece o timestamp em nanossegundos, e json=payload serializa o corpo como JSON e define o tipo de conteúdo. O exemplo oficial também menciona httpx como alternativa com uma API semelhante para código que precisa de operações assíncronas.
Enviar logs de PHP
Não há aqui um cliente ou uma receita oficial específica para PHP. O exemplo abaixo é uma implementação ilustrativa com cURL: cria a mesma estrutura JSON, faz o POST e trata respostas HTTP de erro. Confirme os detalhes de sintaxe e as opções disponíveis na versão do PHP e no ambiente que você usa.
<?php
$lokiUrl = 'http://localhost:3100';
// Use um relógio com precisão suficiente para produzir nanossegundos.
// Aqui, segundos e nanossegundos são montados a partir de microtime().
$now = microtime(true);
$seconds = (int) floor($now);
$nanoseconds = (int) (($now - $seconds) * 1_000_000_000);
$timestampNs = sprintf('%d%09d', $seconds, $nanoseconds);
$payload = [
'streams' => [[
'stream' => [
'job' => 'mini-app',
'environment' => 'dev',
],
'values' => [[
$timestampNs,
'application started',
]],
]],
];
$body = json_encode($payload, JSON_THROW_ON_ERROR);
$ch = curl_init($lokiUrl . '/loki/api/v1/push');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
]);
$responseBody = curl_exec($ch);
if ($responseBody === false) {
$error = curl_error($ch);
curl_close($ch);
throw new RuntimeException('Falha ao enviar log ao Loki: ' . $error);
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status < 200 || $status >= 300) {
throw new RuntimeException(
'Loki respondeu HTTP ' . $status . ': ' . $responseBody
);
}A conversão de microtime(true) acima é uma forma ilustrativa de montar a string esperada; para sistemas em que a precisão ou a ordenação temporal são críticas, use uma fonte de timestamp apropriada à aplicação. Em ambos os idiomas, envie a linha de log como texto e trate falhas de rede separadamente das respostas HTTP do Loki.
Autenticação e tenant conforme a implantação
Não presuma que toda instalação usa a mesma autenticação. Um Loki local de desenvolvimento pode aceitar chamadas sem credenciais, enquanto uma implantação self-hosted pode delegar autenticação a um proxy reverso. A documentação de autenticação mostra uma configuração com proxy, como NGINX; configure o cliente e o proxy de acordo com a arquitetura real, sem expor o serviço publicamente por confiar no exemplo local.
Loki multi-tenant
Quando o modo multi-tenant está habilitado, a requisição precisa identificar o tenant com X-Scope-OrgID. O cliente, agente ou proxy confiável deve enviar o valor correto para a instalação. Autenticação e identificação de tenant são responsabilidades distintas: autenticar uma conexão com mTLS, por si só, não preenche X-Scope-OrgID.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Grafana Cloud
Para Grafana Cloud, use a URL do serviço Loki e as informações de usuário ou instância indicadas nas configurações do serviço, junto com um token de access policy, seguindo as instruções atuais da conta. Os exemplos Python da Grafana demonstram Basic Authentication. Mantenha o token em um mecanismo de segredos da aplicação ou do ambiente de execução; não o grave no repositório nem o imprima em logs de erro.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Verificar o envio e diagnosticar erros
O cliente deve examinar o código HTTP e, quando seguro, a resposta do servidor. Em Python, raise_for_status() transforma respostas de erro em exceções; em PHP, verifique o código retornado pelo cURL. Registre contexto útil para diagnóstico, mas remova credenciais e outros segredos antes de armazenar ou exibir a resposta.
- 400: verifique a estrutura de
streams, os tipos dos valores, o timestamp em nanossegundos e a codificação indicada porContent-Type. Repetir uma requisição malformada não corrige o problema. - 401: confira as credenciais exigidas pela implantação, a configuração do proxy e, no Grafana Cloud, os dados e o token usados para Basic Authentication.
- 429: a requisição foi limitada. Considere uma repetição com espera progressiva e um número máximo de tentativas, respeitando os sinais e limites do serviço.
- 5xx ou falha de rede: podem ser transitórios; use tentativas limitadas com backoff, timeout e registro seguro do resultado. Evite um ciclo de repetição sem limite, que pode ampliar a carga durante uma indisponibilidade.
Para um teste inicial, use a chamada curl JSON da referência oficial da API com a URL, os cabeçalhos e a autenticação da sua implantação. Depois envie uma única entrada pela aplicação e procure o stream no fluxo de consulta do Loki/Grafana configurado para esse tenant. Isso separa problemas de conectividade e configuração dos problemas de construção do payload.
Limites indicados para Grafana Cloud
Os limites abaixo são os publicados pela Grafana Labs para o endpoint push padrão do Grafana Cloud, consultados em 2026. Eles não devem ser tratados como valores universais para instalações self-hosted, cujos limites dependem da configuração. Consulte a página de limites vigente para o serviço hospedado antes de projetar ingestão ou dimensionamento.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsQuick Recap
- Comprimento máximo da linha de log: 256 KB.
- Máximo de rótulos por stream: 15.
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.
