Loki API完整参考5分钟掌握日志推送、查询与标签探索【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki当你想把日志写进 Loki、不想打开 Grafana 界面就取回历史日志和统计数据、或者需要确认集群里存在哪些标签值时绕过界面直接调用 Loki API 是最快的路径。这篇文章把 Loki API 的主干端点拆成写入、取回、元数据探索三个场景每个场景都给你一条可直接复制运行的最短 curl以及响应逐段的读法。先交代几个术语RESTful API 指通过 HTTP 暴露的一组接口Content-Type 是请求头告诉服务器请求体的格式LogQL 是 Loki 的日志查询语言纳秒时间戳指精确到十亿分之一秒的时间数值。基础规则调用第一条 Loki API 前先看这张总览表这一节解决一个合法请求长什么样基础路径、请求格式、认证方式都在这里定好后面所有 curl 只换路径和参数。基础路径http://host:3100/loki/api/v1/3100 是默认 HTTP 端口请求格式application/json人可读本文全部用它或application/x-protobuf二进制面向高性能客户端压缩请求体可用Content-Encoding: gzip或deflate压缩认证本地单租户默认不鉴权多租户用请求头X-Scope-OrgID指定租户 ID生产环境通常在前面挂带 Basic Auth 或 OAuth 的反向代理主干端点总览路径均可在 pkg/util/constants/api_paths.go 中找到定义端点方法用途所需权限/loki/api/v1/pushPOST推送日志条目写/loki/api/v1/queryGET / POST时间点查询读/loki/api/v1/query_rangeGET / POST时间范围查询、聚合统计读/loki/api/v1/labelsGET / POST列出全部标签名读/loki/api/v1/label/{name}/valuesGET / POST列出某标签的全部值读/loki/api/v1/seriesGET / POST查询已存在的日志流读/loki/api/v1/tailGET / POST实时日志流类似tail -f读⚠️ 一条贯穿全文的规则时间戳一律是字符串请求体里单位是纳秒。场景一写入数据 —— 30秒跑通第一条 Loki push 请求这一节的目标只有一个让你自己的日志进入 Loki。端点是POST /loki/api/v1/push把下面这条 curl 原样执行返回 204 即成功curl -X POST http://localhost:3100/loki/api/v1/push \ -H Content-Type: application/json \ -d { streams: [ { stream: {job: demo, host: web-01}, values: [[1756828800000000000, 通过Loki API推送的第一行日志]] } ] }怎么读响应✅ 成功时返回204 No Content响应体为空。空就是好消息Loki 不会给你回显内容。逐字段含义字段含义streams数组一次请求可以携带多条日志流stream该日志流的标签Label键值对集合。标签就像贴在日志流上的分类吊牌决定了日志归属哪个流values日志条目数组每个条目是[时间戳, 日志内容]时间戳字符串单位纳秒。误用秒级时间戳日志会被推回 1970 年推完之后用/loki/api/v1/label/job/values验证demo是否出现见场景三。推送请求的解析逻辑可参考源码 pkg/loghttp/push/push.go。场景二取回数据 —— 按你想看什么写出查询请求这一节把你想看什么映射到具体的 Loki 查询示例看时间点、看时间段、看聚合统计各给一条请求。三类查询都使用 LogQL 选择器基本形状是{labelvalue}URL 中双引号要写成%22。2.1 时间点查询/loki/api/v1/querycurl http://localhost:3100/loki/api/v1/query?query{job%22demo%22}limit5参数含义queryLogQL 语句必填time查询时间点缺省为当前时间接受 epoch 秒或 RFC3339limit每个流最多返回的条数缺省 100directionforward或backward缺省backward向过去取响应逐段解读{ status: success, data: { resultType: streams, result: [ { stream: {job: demo, host: web-01}, values: [[1756828800000000000, 通过Loki API推送的第一行日志]] } ] } }status: success表示请求本身被正常处理resultType: streams表示返回的是原始日志result里每个元素是一条日志流stream是它的标签values是[纳秒时间戳, 日志行]对2.2 时间范围查询/loki/api/v1/query_rangecurl http://localhost:3100/loki/api/v1/query_range?query{job%22demo%22}start$(date -d 1 hour ago %s)end$(date %s)limit5start、end接受 epoch 秒或 RFC3339start缺省为一小时前end缺省为当前。响应结构与时间点查询相同只是覆盖一段时间。2.3 聚合统计看趋势而不是原文要每分钟的日志条数这类数字时用时间窗口函数包裹选择器%5B%5D是[]的转义curl http://localhost:3100/loki/api/v1/query_range?querysum%20by%20(job)%20(count_over_time({job%22demo%22}%5B1m%5D))start$(date -d 1 hour ago %s)end$(date %s)step1m响应里resultType变为vector每个点是[时间戳, 数值]形式的序列。查询参数的完整解析规则见 pkg/loghttp/params.go。场景三元数据探索 —— 查标签名、标签值与已有日志流这一节解决不知道集群里有什么数据时先翻目录再取件的问题读完你就能不写任何 LogQL 就把数据画像摸出来。所有标签名curl http://localhost:3100/loki/api/v1/labels响应形如{status:success,data:[job,host]}。某标签的全部值curl http://localhost:3100/loki/api/v1/label/job/values响应形如{status:success,data:[demo]}。两个端点都可带可选的start、end参数缩小时间范围。已存在的日志流curl http://localhost:3100/loki/api/v1/series?match[]{job%22demo%22}start$(date -d 1 day ago %s)end$(date %s) 典型用途给 Grafana 变量和查询模板供值、巡检标签基数是否失控、写脚本前先探测命名规范。常见坑位错误码症状对照表这一节把返回了某个状态码下一步该做什么整理成可直接对号入座的症状表。状态码典型症状解法400push 返回 bad request检查 JSON 合法性漏写Content-Type时 Loki 会按 protobuf 解析必错400查询报 LogQL 解析错误双引号未转义成%22或选择器拼写错误400数据被写入异常时间values时间戳必须是纳秒字符串不是秒401 / 403认证被拒补认证头多租户检查X-Scope-OrgID413push 请求体过大受服务端max_received_message_size限制改用 gzip 压缩或分批推送429限流拒绝指数退避后重试500 / 503服务端失败查看 Loki 自身日志定位客户端对 503 应重试还有一个隐蔽坑push 的204空响应是成功不是请求没送达别按超时重试反复补推。提速与稳定清单这一节给 5 条一句话就能落地的优化项按需取用推送体加 gzip 压缩并声明Content-Encoding: gzip带宽立省字段一个不用改。批量推送单请求携带多个流和成百上千条条目别逐条调用 API。要统计就用count_over_time等窗口函数要原文才拉原始日志二者混用会放大流量。查询永远带上limit防止大时间范围返回超大响应拖慢下游。标签设计保持低基数{job...}这类稳定值进选择器trace ID 之类的高频变化值别做成标签否则日志流数量会爆炸。结语与延伸阅读Loki API 的主循环其实只有三件事push写入、query/query_range读取、labels与标签值探索元数据掌握它们之后任何脚本、CI 流程或自研采集器都能直接对接。延伸阅读仓库内相对路径端点路径常量定义pkg/util/constants/api_paths.go推送请求解析实现pkg/loghttp/push/push.go查询参数解析实现pkg/loghttp/params.go数据接入文档docs/sources/send-data/LogQL 查询文档docs/sources/query/【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Loki API完整参考：5分钟掌握日志推送、查询与标签探索
Loki API完整参考5分钟掌握日志推送、查询与标签探索【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki当你想把日志写进 Loki、不想打开 Grafana 界面就取回历史日志和统计数据、或者需要确认集群里存在哪些标签值时绕过界面直接调用 Loki API 是最快的路径。这篇文章把 Loki API 的主干端点拆成写入、取回、元数据探索三个场景每个场景都给你一条可直接复制运行的最短 curl以及响应逐段的读法。先交代几个术语RESTful API 指通过 HTTP 暴露的一组接口Content-Type 是请求头告诉服务器请求体的格式LogQL 是 Loki 的日志查询语言纳秒时间戳指精确到十亿分之一秒的时间数值。基础规则调用第一条 Loki API 前先看这张总览表这一节解决一个合法请求长什么样基础路径、请求格式、认证方式都在这里定好后面所有 curl 只换路径和参数。基础路径http://host:3100/loki/api/v1/3100 是默认 HTTP 端口请求格式application/json人可读本文全部用它或application/x-protobuf二进制面向高性能客户端压缩请求体可用Content-Encoding: gzip或deflate压缩认证本地单租户默认不鉴权多租户用请求头X-Scope-OrgID指定租户 ID生产环境通常在前面挂带 Basic Auth 或 OAuth 的反向代理主干端点总览路径均可在 pkg/util/constants/api_paths.go 中找到定义端点方法用途所需权限/loki/api/v1/pushPOST推送日志条目写/loki/api/v1/queryGET / POST时间点查询读/loki/api/v1/query_rangeGET / POST时间范围查询、聚合统计读/loki/api/v1/labelsGET / POST列出全部标签名读/loki/api/v1/label/{name}/valuesGET / POST列出某标签的全部值读/loki/api/v1/seriesGET / POST查询已存在的日志流读/loki/api/v1/tailGET / POST实时日志流类似tail -f读⚠️ 一条贯穿全文的规则时间戳一律是字符串请求体里单位是纳秒。场景一写入数据 —— 30秒跑通第一条 Loki push 请求这一节的目标只有一个让你自己的日志进入 Loki。端点是POST /loki/api/v1/push把下面这条 curl 原样执行返回 204 即成功curl -X POST http://localhost:3100/loki/api/v1/push \ -H Content-Type: application/json \ -d { streams: [ { stream: {job: demo, host: web-01}, values: [[1756828800000000000, 通过Loki API推送的第一行日志]] } ] }怎么读响应✅ 成功时返回204 No Content响应体为空。空就是好消息Loki 不会给你回显内容。逐字段含义字段含义streams数组一次请求可以携带多条日志流stream该日志流的标签Label键值对集合。标签就像贴在日志流上的分类吊牌决定了日志归属哪个流values日志条目数组每个条目是[时间戳, 日志内容]时间戳字符串单位纳秒。误用秒级时间戳日志会被推回 1970 年推完之后用/loki/api/v1/label/job/values验证demo是否出现见场景三。推送请求的解析逻辑可参考源码 pkg/loghttp/push/push.go。场景二取回数据 —— 按你想看什么写出查询请求这一节把你想看什么映射到具体的 Loki 查询示例看时间点、看时间段、看聚合统计各给一条请求。三类查询都使用 LogQL 选择器基本形状是{labelvalue}URL 中双引号要写成%22。2.1 时间点查询/loki/api/v1/querycurl http://localhost:3100/loki/api/v1/query?query{job%22demo%22}limit5参数含义queryLogQL 语句必填time查询时间点缺省为当前时间接受 epoch 秒或 RFC3339limit每个流最多返回的条数缺省 100directionforward或backward缺省backward向过去取响应逐段解读{ status: success, data: { resultType: streams, result: [ { stream: {job: demo, host: web-01}, values: [[1756828800000000000, 通过Loki API推送的第一行日志]] } ] } }status: success表示请求本身被正常处理resultType: streams表示返回的是原始日志result里每个元素是一条日志流stream是它的标签values是[纳秒时间戳, 日志行]对2.2 时间范围查询/loki/api/v1/query_rangecurl http://localhost:3100/loki/api/v1/query_range?query{job%22demo%22}start$(date -d 1 hour ago %s)end$(date %s)limit5start、end接受 epoch 秒或 RFC3339start缺省为一小时前end缺省为当前。响应结构与时间点查询相同只是覆盖一段时间。2.3 聚合统计看趋势而不是原文要每分钟的日志条数这类数字时用时间窗口函数包裹选择器%5B%5D是[]的转义curl http://localhost:3100/loki/api/v1/query_range?querysum%20by%20(job)%20(count_over_time({job%22demo%22}%5B1m%5D))start$(date -d 1 hour ago %s)end$(date %s)step1m响应里resultType变为vector每个点是[时间戳, 数值]形式的序列。查询参数的完整解析规则见 pkg/loghttp/params.go。场景三元数据探索 —— 查标签名、标签值与已有日志流这一节解决不知道集群里有什么数据时先翻目录再取件的问题读完你就能不写任何 LogQL 就把数据画像摸出来。所有标签名curl http://localhost:3100/loki/api/v1/labels响应形如{status:success,data:[job,host]}。某标签的全部值curl http://localhost:3100/loki/api/v1/label/job/values响应形如{status:success,data:[demo]}。两个端点都可带可选的start、end参数缩小时间范围。已存在的日志流curl http://localhost:3100/loki/api/v1/series?match[]{job%22demo%22}start$(date -d 1 day ago %s)end$(date %s) 典型用途给 Grafana 变量和查询模板供值、巡检标签基数是否失控、写脚本前先探测命名规范。常见坑位错误码症状对照表这一节把返回了某个状态码下一步该做什么整理成可直接对号入座的症状表。状态码典型症状解法400push 返回 bad request检查 JSON 合法性漏写Content-Type时 Loki 会按 protobuf 解析必错400查询报 LogQL 解析错误双引号未转义成%22或选择器拼写错误400数据被写入异常时间values时间戳必须是纳秒字符串不是秒401 / 403认证被拒补认证头多租户检查X-Scope-OrgID413push 请求体过大受服务端max_received_message_size限制改用 gzip 压缩或分批推送429限流拒绝指数退避后重试500 / 503服务端失败查看 Loki 自身日志定位客户端对 503 应重试还有一个隐蔽坑push 的204空响应是成功不是请求没送达别按超时重试反复补推。提速与稳定清单这一节给 5 条一句话就能落地的优化项按需取用推送体加 gzip 压缩并声明Content-Encoding: gzip带宽立省字段一个不用改。批量推送单请求携带多个流和成百上千条条目别逐条调用 API。要统计就用count_over_time等窗口函数要原文才拉原始日志二者混用会放大流量。查询永远带上limit防止大时间范围返回超大响应拖慢下游。标签设计保持低基数{job...}这类稳定值进选择器trace ID 之类的高频变化值别做成标签否则日志流数量会爆炸。结语与延伸阅读Loki API 的主循环其实只有三件事push写入、query/query_range读取、labels与标签值探索元数据掌握它们之后任何脚本、CI 流程或自研采集器都能直接对接。延伸阅读仓库内相对路径端点路径常量定义pkg/util/constants/api_paths.go推送请求解析实现pkg/loghttp/push/push.go查询参数解析实现pkg/loghttp/params.go数据接入文档docs/sources/send-data/LogQL 查询文档docs/sources/query/【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
