Loki HTTP API
Loki 提供了一个 HTTP API，用于推送、查询和尾随日志数据，以及用于查看和管理集群信息。
注意
请注意，授权不是 Loki API 的一部分。授权需要单独完成，例如，使用开源负载均衡器（如 NGINX）。
端点
摄取端点
这些端点由 distributor、write 和 all 组件暴露
客户端列表可在客户端文档中找到。
查询端点
注意
发送到查询端点的请求必须使用有效的 LogQL 语法。更多信息请参阅文档的 LogQL 部分。
这些 HTTP 端点由 querier、query-frontend、read 和 all 组件暴露
GET /loki/api/v1/queryGET /loki/api/v1/query_rangeGET /loki/api/v1/labelsGET /loki/api/v1/label/<name>/valuesGET /loki/api/v1/seriesGET /loki/api/v1/index/statsGET /loki/api/v1/index/volumeGET /loki/api/v1/index/volume_rangeGET /loki/api/v1/patternsGET /loki/api/v1/tail
状态端点
这些 HTTP 端点由所有组件暴露，并返回组件的状态
Ring 端点
这些 HTTP 端点由各自的组件暴露，这些组件是 ring URL 前缀的一部分
Flush/Shutdown 端点
这些 HTTP 端点由 ingester、write 和 all 组件暴露，用于刷新 chunk 和/或关闭。
规则端点
这些 HTTP 端点由 ruler 组件暴露
GET /loki/api/v1/rulesGET /loki/api/v1/rules/{namespace}GET /loki/api/v1/rules/{namespace}/{groupName}POST /loki/api/v1/rules/{namespace}DELETE /loki/api/v1/rules/{namespace}/{groupName}DELETE /loki/api/v1/rules/{namespace}GET /api/prom/rulesGET /api/prom/rules/{namespace}GET /api/prom/rules/{namespace}/{groupName}POST /api/prom/rules/{namespace}DELETE /api/prom/rules/{namespace}/{groupName}DELETE /api/prom/rules/{namespace}GET /prometheus/api/v1/rulesGET /prometheus/api/v1/alerts
以 /api/prom 开头的 API 端点与 Prometheus API 兼容，结果格式可以互换使用。
日志删除端点
这些端点由 compactor、backend 和 all 组件暴露
其他端点
这些 HTTP 端点由所有独立组件暴露
弃用端点
注意
以下端点已弃用。虽然它们仍然存在并可用，但不应在新部署中使用。现有部署应升级到使用支持的端点。
| 已弃用 | 替代方案 |
|---|---|
POST /api/prom/push | POST /loki/api/v1/push |
GET /api/prom/tail | GET /loki/api/v1/tail |
GET /api/prom/query | GET /loki/api/v1/query |
GET /api/prom/label | GET /loki/api/v1/labels |
GET /api/prom/label/<name>/values | GET /loki/api/v1/label/<name>/values |
GET /api/prom/series | GET /loki/api/v1/series |
格式
Matrix、Vector 和 Stream
一些 Loki API 端点返回 Matrix、Vector 或 Stream 结果
Matrix: 一个值表，其中每行代表不同的标签集，列是该行在查询时间内每个样本的值。Matrix 类型仅在运行计算某些值的查询时返回。
Instant Vector: 在类型中简称为 vector，Instant Vector 表示给定标签集计算的最新值。Instant Vector 仅在对单个时间点进行查询时返回。
Stream: Stream 是给定标签集在查询时间范围内所有值（日志）的集合。Stream 是唯一会返回日志行的类型。
时间戳
API 支持多种时间戳格式
- 所有 epoch 值将被解释为纳秒级别的 Unix 时间戳。
- 浮点数是带有小数部分的 Unix 时间戳。
- Go 的 time 包支持的
RFC3339和RFC3339Nano格式字符串。
注意
使用
/api/v1/push时，必须将时间戳作为字符串而不是数字发送，否则端点将返回 400 错误。
统计信息
/loki/api/v1/query 和 /loki/api/v1/query_range 等查询端点返回关于查询执行的一组统计信息。这些统计信息让用户能够了解处理的数据量和速度。
以下示例显示了所有可能返回的统计信息及其描述。
{
"status": "success",
"data": {
"resultType": "streams",
"result": [],
"stats": {
"ingester": {
"compressedBytes": 0, // Total bytes of compressed chunks (blocks) processed by ingesters
"decompressedBytes": 0, // Total bytes decompressed and processed by ingesters
"decompressedLines": 0, // Total lines decompressed and processed by ingesters
"headChunkBytes": 0, // Total bytes read from ingesters head chunks
"headChunkLines": 0, // Total lines read from ingesters head chunks
"totalBatches": 0, // Total batches sent by ingesters
"totalChunksMatched": 0, // Total chunks matched by ingesters
"totalDuplicates": 0, // Total of duplicates found by ingesters
"totalLinesSent": 0, // Total lines sent by ingesters
"totalReached": 0 // Amount of ingesters reached.
},
"store": {
"compressedBytes": 0, // Total bytes of compressed chunks (blocks) processed by the store
"decompressedBytes": 0, // Total bytes decompressed and processed by the store
"decompressedLines": 0, // Total lines decompressed and processed by the store
"chunksDownloadTime": 0, // Total time spent downloading chunks in seconds (float)
"totalChunksRef": 0, // Total chunks found in the index for the current query
"totalChunksDownloaded": 0, // Total of chunks downloaded
"totalDuplicates": 0 // Total of duplicates removed from replication
},
"summary": {
"bytesProcessedPerSecond": 0, // Total of bytes processed per second
"execTime": 0, // Total execution time in seconds (float)
"linesProcessedPerSecond": 0, // Total lines processed per second
"queueTime": 0, // Total queue time in seconds (float)
"totalBytesProcessed": 0, // Total amount of bytes processed overall for this request
"totalLinesProcessed": 0 // Total amount of lines processed overall for this request
}
}
}
}摄取日志
POST /loki/api/v1/push/loki/api/v1/push 是用于向 Loki 发送日志条目的端点。默认情况下，POST 主体是 Snappy 压缩的 Protocol Buffer 消息
这些 POST 请求要求 Content-Type HTTP 请求头为 application/x-protobuf。
或者，如果将 Content-Type 请求头设置为 application/json，可以发送以下格式的 JSON POST 主体
{
"streams": [
{
"stream": {
"label": "value"
},
"values": [
[ "<unix epoch in nanoseconds>", "<log line>" ],
[ "<unix epoch in nanoseconds>", "<log line>" ]
]
}
]
}您可以设置 Content-Encoding: gzip 请求头并发送 gzipped JSON。
您可以选择将结构化元数据附加到每行日志，方法是在日志行数组末尾添加一个 JSON 对象。该 JSON 对象必须是包含字符串键和字符串值的有效 JSON 对象。该 JSON 对象不应包含任何嵌套对象。该 JSON 对象必须紧跟在日志行之后。以下是附加了结构化元数据的一条日志条目示例
"values": [
[ "<unix epoch in nanoseconds>", "<log line>", {"trace_id": "0242ac120002", "user_id": "superUser123"}]
]在微服务模式下，/loki/api/v1/push 由 distributor 暴露。
如果配置了 block_ingestion_until 并且 push 请求被阻塞，端点将返回 block_ingestion_status_code 中配置的状态码（默认为 260）以及一条错误消息。如果配置的状态码是 200，则不会返回错误消息。
示例
以下 cURL 命令使用 JSON 编码推送一个带有标签 “foo=bar2” 和单行日志 “fizzbuzz” 的 stream
curl -H "Content-Type: application/json" \
-s -X POST "https://:3100/loki/api/v1/push" \
--data-raw '{"streams": [{ "stream": { "foo": "bar2" }, "values": [ [ "1570818238000000000", "fizzbuzz" ] ] }]}'使用 OTLP 摄取日志
POST /otlp/v1/logs/otlp/v1/logs 允许 OpenTelemetry Collector 使用 otlphttp 协议将日志发送到 Loki。
有关如何配置 Loki 的信息，请参阅 OTel Collector 主题。
注意
配置 OpenTelemetry Collector 时，必须使用
endpoint: http://<loki-addr>:3100/otlp，因为 Collector 会自动补全端点。输入完整端点将生成错误。
在单个时间点查询日志
GET /loki/api/v1/query/loki/api/v1/query 允许在单个时间点进行查询。这种类型的查询通常称为即时查询（instant query）。即时查询仅用于指标类型的 LogQL 查询，如果提供了日志类型查询，则会返回 400 (Bad Request) 错误。该端点接受 URL 中的以下查询参数
query：要执行的 LogQL 查询。未使用有效 LogQL 语法的请求将返回错误。limit：返回的最大条目数。默认为100。仅适用于生成 Stream（日志行）响应的查询类型。time：查询的评估时间，为纳秒 Unix epoch 或另一种支持的格式。默认为当前时间。direction：确定日志的排序顺序。支持的值为forward或backward。默认为backward。
在微服务模式下，/loki/api/v1/query 由 querier 和 query frontend 暴露。
响应格式
{
"status": "success",
"data": {
"resultType": "vector" | "streams",
"result": [<vector value>] | [<stream value>],
"stats" : [<statistics>]
}
}其中 <vector value> 是
{
"metric": {
<label key-value pairs>
},
"value": [
<number: second unix epoch>,
<string: value>
]
}并且 <stream value> 是
{
"stream": {
<label key-value pairs>
},
"values": [
[
<string: nanosecond unix epoch>,
<string: log line>
],
...
]
}values 数组中的项目按时间戳排序。使用 direction=backward 时，最新的项目排在最前面。使用 direction=forward 时，最旧的项目排在最前面。
通过将 Accept 请求头设置为 application/vnd.apache.parquet，可以将 Parquet 作为响应格式请求。
Stream 的 schema 如下
column_name | column_type |
|---|---|
| timestamp | TIMESTAMP WITH TIME ZONE |
| labels | MAP(VARCHAR, VARCHAR) |
line | VARCHAR |
对于指标
column_name | column_type |
|---|---|
| timestamp | TIMESTAMP WITH TIME ZONE |
| labels | MAP(VARCHAR, VARCHAR) |
value | DOUBLE |
有关 Loki 返回的统计信息，请参阅统计信息。
示例
此 cURL 命令示例
curl -G -s "https://:3100/loki/api/v1/query" \
--data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq返回此响应
{
"status": "success",
"data": {
"resultType": "vector",
"result": [
{
"metric": {},
"value": [
1588889221,
"1267.1266666666666"
]
},
{
"metric": {
"level": "warn"
},
"value": [
1588889221,
"37.77166666666667"
]
},
{
"metric": {
"level": "info"
},
"value": [
1588889221,
"37.69"
]
}
],
"stats": {
...
}
}
}如果您的集群启用了 Grafana Loki 多租户功能，请设置 X-Scope-OrgID 请求头以标识要查询的租户。以下是针对名为 Tenant1 的单个租户的相同查询示例
curl -H 'X-Scope-OrgID:Tenant1' \
-G -s "https://:3100/loki/api/v1/query" \
--data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq要查询三个租户 Tenant1、Tenant2 和 Tenant3，请指定租户名称并用竖线 (|) 字符分隔
curl -H 'X-Scope-OrgID:Tenant1|Tenant2|Tenant3' \
-G -s "https://:3100/loki/api/v1/query" \
--data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jqGrafana Enterprise Logs 的相同查询示例使用基本身份验证，并将租户名称指定为 user。租户名称用竖线 (|) 字符分隔。此示例中的密码是在 API_TOKEN 环境变量中定义的访问策略令牌
curl -u "Tenant1|Tenant2|Tenant3:$API_TOKEN" \
-G -s "https://:3100/loki/api/v1/query" \
--data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq要在 Grafana Cloud 中查询托管日志租户，请使用 Grafana Cloud stack 的 Loki 日志服务详细信息中提供的 User 和 URL 值。您可以在 Cloud Portal 中找到此信息。在您的查询中使用访问策略令牌进行身份验证。此示例中的密码是在 API_TOKEN 环境变量中定义的访问策略令牌
curl -u "User:$API_TOKEN" \
-G -s "<URL-PROVIDED-IN-LOKI-DATA-SOURCE-SETTINGS>/loki/api/v1/query" \
--data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq在时间范围内查询日志
GET /loki/api/v1/query_range/loki/api/v1/query_range 用于在一段时间范围内进行查询。这种类型的查询通常称为范围查询（range query）。范围查询用于日志类型和指标类型的 LogQL 查询。该端点接受 URL 中的以下查询参数
query：要执行的 LogQL 查询。limit：返回的最大条目数。默认为100。仅适用于生成 Stream（日志行）响应的查询类型。start：查询的开始时间，为纳秒 Unix epoch 或另一种支持的格式。默认为一小时前。Loki 返回时间戳大于或等于此值的结果。end：查询的结束时间，为纳秒 Unix epoch 或另一种支持的格式。默认为当前时间。Loki 返回时间戳小于此值的结果。since：用于计算相对于end的start的duration。如果end在未来，则start计算为当前时间减去此 duration。start指定的任何值都会覆盖此参数。step：查询分辨率步长宽度，可以是duration格式或浮点秒数。duration指的是 Prometheus duration 字符串，格式为[0-9]+[smhdwy]。例如，5m 指持续 5 分钟。默认为基于start和end的动态值。仅适用于生成 matrix 响应的查询类型。interval：仅返回指定间隔（或更大间隔）的条目，可以是duration格式或浮点秒数。仅适用于生成 stream 响应的查询。请勿与step混淆，请参阅 Step 与 Interval 对比 下的解释。direction：确定日志的排序顺序。支持的值为forward或backward。默认为backward。
在微服务模式下，/loki/api/v1/query_range 由 querier 和 query frontend 暴露。
Step 与 Interval 对比
对 Loki 进行指标查询或返回 matrix 响应的查询时，使用 step 参数。它的评估方式与 Prometheus 评估 step 完全相同。首先在 start 评估查询，然后在 start + step 再次评估，接着在 start + step + step 再次评估，直到达到 end。结果将是每个步骤评估的查询结果的 matrix。
对 Loki 进行日志查询或返回 stream 响应的查询时，使用 interval 参数。它的评估方式是返回 start 的日志条目，然后返回时间戳 >= start + interval 的下一个条目，接着在 start + interval + interval 再次返回条目，以此类推直到达到 end。它不会填充缺失的条目。
响应格式
{
"status": "success",
"data": {
"resultType": "matrix" | "streams",
"result": [<matrix value>] | [<stream value>]
"stats" : [<statistics>]
}
}其中 <matrix value> 是
{
"metric": {
<label key-value pairs>
},
"values": [
[
<number: second unix epoch>,
<string: value>
],
...
]
}values 数组中的项目按时间戳排序，最旧的项目排在最前面。
并且 <stream value> 是
{
"stream": {
<label key-value pairs>
},
"values": [
[
<string: nanosecond unix epoch>,
<string: log line>
],
...
]
}values 数组中的项目按时间戳排序。使用 direction=backward 时，最新的项目排在最前面。使用 direction=forward 时，最旧的项目排在最前面。
通过将 Accept 请求头设置为 application/vnd.apache.parquet，可以将 Parquet 作为响应格式请求。
Stream 的 schema 如下
column_name | column_type |
|---|---|
| timestamp | TIMESTAMP WITH TIME ZONE |
| labels | MAP(VARCHAR, VARCHAR) |
line | VARCHAR |
对于指标
column_name | column_type |
|---|---|
| timestamp | TIMESTAMP WITH TIME ZONE |
| labels | MAP(VARCHAR, VARCHAR) |
value | DOUBLE |
有关 Loki 返回的统计信息，请参阅统计信息。
示例
此 cURL 命令示例
curl -G -s "https://:3100/loki/api/v1/query_range" \
--data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' \
--data-urlencode 'step=300' | jq返回此响应
{
"status": "success",
"data": {
"resultType": "matrix",
"result": [
{
"metric": {
"level": "info"
},
"values": [
[
1588889221,
"137.95"
],
[
1588889221,
"467.115"
],
[
1588889221,
"658.8516666666667"
]
]
},
{
"metric": {
"level": "warn"
},
"values": [
[
1588889221,
"137.27833333333334"
],
[
1588889221,
"467.69"
],
[
1588889221,
"660.6933333333334"
]
]
}
],
"stats": {
...
}
}
}此 cURL 命令示例
curl -G -s "https://:3100/loki/api/v1/query_range" \
--data-urlencode 'query={job="varlogs"}' | jq返回此响应
{
"status": "success",
"data": {
"resultType": "streams",
"result": [
{
"stream": {
"filename": "/var/log/myproject.log",
"job": "varlogs",
"level": "info"
},
"values": [
[
"1569266497240578000",
"foo"
],
[
"1569266492548155000",
"bar"
]
]
}
],
"stats": {
...
}
}
}查询标签
GET /loki/api/v1/labels/loki/api/v1/labels 在给定时间跨度内检索已知标签列表。Loki 可能会使用比指定时间跨度更长的时间跨度。该端点接受 URL 中的以下查询参数
start：查询的开始时间，为纳秒 Unix epoch。默认为 6 小时前。end：查询的结束时间，为纳秒 Unix epoch。默认为当前时间。since：用于计算相对于end的start的duration。如果end在未来，则start计算为当前时间减去此 duration。start指定的任何值都会覆盖此参数。query：用于选择匹配并返回标签名称的 stream 的 Log stream selector。示例：{app="myapp", environment="dev"}
在微服务模式下，/loki/api/v1/labels 由 querier 暴露。
响应格式
{
"status": "success",
"data": [
<label string>,
...
]
}示例
此 cURL 命令示例
curl -G -s "https://:3100/loki/api/v1/labels" | jq返回此响应
{
"status": "success",
"data": [
"foo",
"bar",
"baz"
]
}查询标签值
GET /loki/api/v1/label/<name>/values/loki/api/v1/label/<name>/values 在给定时间跨度内检索给定标签的已知值列表。Loki 可能会使用比指定时间跨度更长的时间跨度。该端点接受 URL 中的以下查询参数
start：查询的开始时间，为纳秒 Unix epoch。默认为 6 小时前。end：查询的结束时间，为纳秒 Unix epoch。默认为当前时间。since：用于计算相对于end的start的duration。如果end在未来，则start计算为当前时间减去此 duration。start指定的任何值都会覆盖此参数。query：用于选择匹配并返回<name>的标签值的 stream 的 Log stream selector。示例：{app="myapp", environment="dev"}
在微服务模式下，/loki/api/v1/label/<name>/values 由 querier 暴露。
响应格式
{
"status": "success",
"data": [
<label value>,
...
]
}示例
此 cURL 命令示例
curl -G -s "https://:3100/loki/api/v1/label/foo/values" | jq返回此响应
{
"status": "success",
"data": [
"cat",
"dog",
"axolotl"
]
}查询 Streams
Series API 可通过以下方式访问
GET /loki/api/v1/seriesPOST /loki/api/v1/series
此端点返回匹配给定 selector 的 stream 列表（唯一标签集）。
URL 查询参数
match[]=<selector>：重复的 log stream selector 参数，用于选择要返回的 stream。必须提供至少一个match[]参数。start=<nanosecond Unix epoch>：开始时间戳。end=<nanosecond Unix epoch>：结束时间戳。since：用于计算相对于end的start的duration。如果end在未来，则start计算为当前时间减去此 duration。start指定的任何值都会覆盖此参数。
您可以通过使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 请求头，直接在请求主体中对这些参数进行 URL 编码。当指定大量或动态数量的 stream selector 可能超出服务器端 URL 字符限制时，这非常有用。
在微服务模式下，这些端点由 querier 暴露。
示例
此 cURL 命令示例
curl -s "https://:3100/loki/api/v1/series" \
--data-urlencode 'match[]={container_name=~"prometheus.*", component="server"}' \
--data-urlencode 'match[]={app="loki"}' | jq '.'返回此响应
{
"status": "success",
"data": [
{
"container_name": "loki",
"app": "loki",
"stream": "stderr",
"filename": "/var/log/pods/default_loki-stack-0_50835643-1df0-11ea-ba79-025000000001/loki/0.log",
"name": "loki",
"job": "default/loki",
"controller_revision_hash": "loki-stack-757479754d",
"statefulset_kubernetes_io_pod_name": "loki-stack-0",
"release": "loki-stack",
"namespace": "default",
"instance": "loki-stack-0"
},
{
"chart": "prometheus-9.3.3",
"container_name": "prometheus-server-configmap-reload",
"filename": "/var/log/pods/default_loki-stack-prometheus-server-696cc9ddff-87lmq_507b1db4-1df0-11ea-ba79-025000000001/prometheus-server-configmap-reload/0.log",
"instance": "loki-stack-prometheus-server-696cc9ddff-87lmq",
"pod_template_hash": "696cc9ddff",
"app": "prometheus",
"component": "server",
"heritage": "Tiller",
"job": "default/prometheus",
"namespace": "default",
"release": "loki-stack",
"stream": "stderr"
},
{
"app": "prometheus",
"component": "server",
"filename": "/var/log/pods/default_loki-stack-prometheus-server-696cc9ddff-87lmq_507b1db4-1df0-11ea-ba79-025000000001/prometheus-server/0.log",
"release": "loki-stack",
"namespace": "default",
"pod_template_hash": "696cc9ddff",
"stream": "stderr",
"chart": "prometheus-9.3.3",
"container_name": "prometheus-server",
"heritage": "Tiller",
"instance": "loki-stack-prometheus-server-696cc9ddff-87lmq",
"job": "default/prometheus"
}
]
}查询日志统计信息
GET /loki/api/v1/index/stats/loki/api/v1/index/stats 端点可用于查询索引，获取查询解析到的 streams、chunks、entries 和 bytes 数量。
URL 查询参数
query：要检查的 LogQL matchers（即{job="foo", env!="dev"}）。start=<nanosecond Unix epoch>：开始时间戳。end=<nanosecond Unix epoch>：结束时间戳。
您可以通过使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 请求头，直接在请求主体中对这些参数进行 URL 编码。当指定大量或动态数量的 stream selector 可能超出服务器端 URL 字符限制时，这非常有用。
响应
{
"streams": 100,
"chunks": 1000,
"entries": 5000,
"bytes": 100000
}这是近似值，有以下注意事项
- 不包括来自 ingester 的数据。
- 这是一种概率技术。
- 跨多个周期配置的 Streams/chunks 可能会被计算两次。
这些使得它通常对大型查询更有帮助。它可用于更好地了解在一段时间内针对 matcher 列表的吞吐量需求和数据拓扑。
查询日志体积
GET /loki/api/v1/index/volume
GET /loki/api/v1/index/volume_range注意
必须配置
volume_enabled: true以启用此功能。
/loki/api/v1/index/volume 和 /loki/api/v1/index/volume_range 端点可用于查询索引，获取有关标签和标签值组合的体积信息。这有助于探索 Loki 摄取的日志，找到高或低体积的 streams。volume 端点返回单个时间点的结果，即查询处理时的时间。每个数据点表示匹配标签或 series 在请求时间段内的聚合，以 Prometheus 风格的 vector 响应返回。volume_range 端点返回在一段时间范围内的系列数据点，以 Prometheus 风格的 matrix 响应返回，用于每个匹配的标签集或 series。查询 volume_range 时返回的时间戳数量将由提供的 step 参数和请求的时间范围决定。
query 应该是一个有效的 LogQL stream selector，例如 {job="foo", env=~".+"}。默认情况下，这些端点将聚合到 series 中，其中包含查询中包含的所有标签的匹配项。例如，假设您的系统中有 streams {job="foo", env="prod", team="alpha"}, {job="bar", env="prod", team="beta"}, {job="foo", env="dev", team="alpha"}, 和 {job="bar", env="dev", team="beta"}。查询 {job="foo", env=~".+"} 将返回两个 metric series {job="foo", env="dev"} 和 {job="foo", env="prod"}，每个都包含表示匹配该 selector 的 stream 的 chunk 累积值的数据点，在这种情况下分别为 streams {job="foo", env="dev", team="alpha"} 和 {job="foo", env="prod", team="alpha"}。
有两个参数可以影响聚合策略。首先，可以提供一个逗号分隔的 targetLabels 列表，允许仅按指定的 targetLabels 聚合体积。这对于否定很有用。例如，如果您说 {team="alpha", env!="dev"}，默认行为会将 env 包含在聚合集中。但是，也许您正在寻找 team alpha 的所有非 dev 作业，并且不关心它们所在的 env（除了关心它们不是 dev 作业）。要实现此目的，您可以指定 targetLabels=team,job，从而产生一个（在这种情况下）的 metric series {team="alpha", job="foo`}。
改变聚合的另一种方法是使用 aggregateBy 参数。其默认值为 series，它会聚合匹配的键值对组合。或者，可以将其指定为 labels，它将仅聚合标签。在这种情况下，响应将包含一个 metric series，其中包含与每个标签匹配的标签名称以及标签值 ""。这对于在高层次上探索日志很有用。例如，如果您想知道您的日志中带有 team 标签的百分比，您可以使用 aggregateBy=labels 查询日志，并使用对 team 进行精确或 regex 匹配的查询，或通过在 targetLabels 列表中包含 team。
URL 查询参数
query：要检查的 LogQL matchers（即{job="foo", env=~".+"}）。此参数是必需的。start=<nanosecond Unix epoch>：开始时间戳。此参数是必需的。end=<nanosecond Unix epoch>：结束时间戳。此参数是必需的。limit：要返回的 metric series 数量。此参数是可选的，默认为100。step：查询分辨率步长宽度，可以是duration格式或浮点秒数。duration指的是 Prometheus duration 字符串，格式为[0-9]+[smhdwy]。例如，5m 指持续 5 分钟。默认为基于start和end的动态值。仅在查询volume_range端点时适用，该端点始终返回 Prometheus 风格的 matrix 响应。此参数是可选的，并且仅适用于query_range。未提供时将使用为 range queries 配置的默认步长。targetLabels：逗号分隔的要聚合到的标签列表。此参数是可选的。未提供时，体积将聚合到匹配的标签或标签值对中。aggregateBy：是否聚合为标签或标签值对。此参数是可选的，默认为标签值对。
您可以通过使用 POST 方法和 Content-Type: application/x-www-form-urlencoded 请求头，直接在请求主体中对这些参数进行 URL 编码。当指定大量或动态数量的 stream selector 可能超出服务器端 URL 字符限制时，这非常有用。
模式检测
GET /loki/api/v1/patterns注意
您必须配置
pattern_ingester: enabled: true以启用此功能。
/loki/api/v1/patterns 端点可用于查询 Loki，获取日志中检测到的模式。这有助于了解 Loki 摄取的日志结构。
query 应该是一个有效的 LogQL stream selector，例如 {job="foo", env=~".+"}。结果将根据所有匹配 streams 中的 pattern 进行聚合。
对于检测到的每个模式，响应包括模式本身以及每个时间戳上每个模式的样本数量。
例如，如果您有以下日志
ts=2024-03-30T23:03:40 caller=grpc_logging.go:66 level=info method=/cortex.Ingester/Push duration=200ms msg=gRPC
ts=2024-03-30T23:03:41 caller=grpc_logging.go:66 level=info method=/cortex.Ingester/Push duration=500ms msg=gRPC检测到的模式可能是
ts=<_> caller=grpc_logging.go:66 level=info method=/cortex.Ingester/Push duration=<_> msg=gRPCURL 查询参数
query：要检查的 LogQL matchers（即{job="foo", env=~".+"}）。此参数是必需的。start=<nanosecond Unix epoch>：开始时间戳。此参数是必需的。end=<nanosecond Unix epoch>：结束时间戳。此参数是必需的。step=<duration string or float number of seconds>：此模式出现样本之间的步长。此参数是可选的。
示例
此 cURL 命令示例
curl -s "https://:3100/loki/api/v1/patterns" \
--data-urlencode 'query={app="loki"}' | jq返回此响应
{
"status": "success",
"data": [
{
"pattern": "<_> caller=grpc_logging.go:66 <_> level=error method=/cortex.Ingester/Push <_> msg=gRPC err=\"connection refused to object store\"",
"samples": [
[
1711839260,
1
],
[
1711839270,
2
],
[
1711839280,
1
]
]
},
{
"pattern": "<_> caller=grpc_logging.go:66 <_> level=info method=/cortex.Ingester/Push <_> msg=gRPC",
"samples": [
[
1711839260,
105
],
[
1711839270,
222
],
[
1711839280,
196
]
]
}
]
}结果是日志中检测到的模式列表，以及每个时间戳上每个模式的样本数量。模式格式与 LogQL pattern filter 和 parser 相同，可用于查询以过滤匹配的日志。每个样本都是时间戳（秒）和计数的元组。
Stream 日志
GET /loki/api/v1/tail/loki/api/v1/tail 是一个 WebSocket 端点，它根据查询向客户端 streaming 日志消息。该端点接受 URL 中的以下查询参数
query：要执行的 LogQL 查询。delay_for：延迟检索日志的秒数，以等待慢速日志记录器追赶上来。默认为 0，不能大于 5。limit：返回的最大条目数。默认为100。start：查询的开始时间，为纳秒 Unix epoch。默认为一小时前。
在微服务模式下，/loki/api/v1/tail 由 querier 暴露。
响应格式 (streamed)
{
"streams": [
{
"stream": {
<label key-value pairs>
},
"values": [
[
<string: nanosecond unix epoch>,
<string: log line>
]
]
}
],
"dropped_entries": [
{
"labels": {
<label key-value pairs>
},
"timestamp": "<nanosecond unix epoch>"
}
]
}就绪探针
GET /readyLoki 实例准备好接受流量时，/ready 返回 HTTP 200。如果在 Kubernetes 上运行 Loki，/ready 可用作就绪探针。
在微服务模式下，/ready 端点由所有组件暴露。
更改日志级别
GET /log_level
POST /log_level/log_level GET 请求返回当前日志级别，POST 请求允许您在运行时更改 Loki 进程的日志级别。这在事件期间访问调试信息时非常有用。在 debug 日志级别下运行时应谨慎，因为会产生大量数据。
该端点接受 URL 中的以下查询参数
log_level：一个有效的日志级别，可以作为 URL 参数 (?log_level=<level>) 或在POST请求中作为表单值传递。有效级别：[debug, info, warn, error]
在微服务模式下，/log_level 端点由所有组件暴露。
Prometheus 指标
GET /metrics/metrics 返回暴露的 Prometheus 指标。有关导出的指标列表，请参阅 Observing Loki。
在微服务模式下，/metrics 端点由所有组件暴露。
显示当前配置
GET /config/config 暴露当前配置。可选的 mode 查询参数可用于修改输出。如果其值为 diffs，则仅返回默认配置与当前配置之间的差异。值为 defaults 则返回默认配置。
在微服务模式下，/config 端点由所有组件暴露。
列出正在运行的服务
GET /services/services 返回所有正在运行的服务及其当前状态列表。
服务可以具有以下状态
- New：服务是新的，尚未运行（初始状态）
- Starting：服务正在启动；如果启动成功，服务将进入 Running 状态
- 运行中 (Running)：服务现已完全运行；当服务停止运行时，会进入 停止中 (Stopping) 状态
- 停止中 (Stopping)：服务正在关闭
- 已终止 (Terminated)：服务已成功停止（终端状态）
- 失败 (Failed)：服务在 启动中 (Starting)、运行中 (Running) 或 停止中 (Stopping) 状态下失败（终端状态）
显示构建信息
GET /loki/api/v1/status/buildinfo/loki/api/v1/status/buildinfo 以 JSON 对象形式暴露构建信息。字段包括 version、revision、branch、buildDate、buildUser 和 goVersion。
将内存中的 chunks 刷新到后端存储
POST /flush/flush 触发 ingesters 持有的所有内存中 chunks 刷新到后端存储。主要用于本地测试。
在微服务模式下，/flush 端点由 ingester 暴露。
准备 ingester 关闭
GET, POST, DELETE /ingester/prepare_shutdown此端点用于告知 ingester 在收到下一个 SIGTERM 或 SIGINT 信号时释放所有资源。
向 /ingester/prepare_shutdown 端点发送 POST 请求会配置 ingester 进行完全关闭并立即返回。只有当 ingester 进程收到 SIGINT 或 SIGTERM 停止信号时，它才会从环中注销，并且内存中的数据将被刷新到长期存储。此端点会覆盖任何 YAML 配置，如果 ingester 已配置为从环中注销或在关闭时刷新，则无需使用此端点。
向 /ingester/prepare_shutdown 端点发送 GET 请求会返回此配置的状态，可以是 set 或 unset。
向 /ingester/prepare_shutdown 端点发送 DELETE 请求会将 ingester 的配置恢复到其先前的状态（关于关闭时注销以及内存数据刷新到长期存储）。
此 API 端点通常由特定于 Kubernetes 的缩容自动化工具使用，例如 rollout-operator。
刷新内存中的 chunks 并关闭
GET, POST /ingester/shutdown/ingester/shutdown 触发 ingester 关闭，值得注意的是，它总是会刷新其持有的所有内存中 chunks。这对于缩减启用了 WAL 的 ingester 非常有用，在这种情况下，我们希望确保旧的 WAL 目录不会成为孤立文件，而是被刷新到我们的 chunk 后端。
它接受三个 URL 查询参数：flush、delete_ring_tokens 和 terminate。
URL 查询参数
flush=<bool>：控制是否刷新 ingester 持有的任何内存中 chunks 的标志。默认为true。delete_ring_tokens=<bool>：控制是否删除包含实例 ingester 环 tokens 的文件（如果指定了-ingester.token-file-path）的标志。默认为false。terminate=<bool>：控制服务关闭后是否终止 Loki 进程的标志。默认为true。
与已弃用的 /ingester/flush_shutdown 处理程序相比，此处理程序默认终止 Loki 进程。通过将 terminate 查询参数设置为 false 可以改变此行为。
在微服务模式下，/ingester/shutdown 端点由 ingester 暴露。
Distributor 环状态
GET /distributor/ring显示一个网页，其中包含 distributor 哈希环状态，包括每个 distributor 的状态、健康状况和最后一次心跳时间。
Index gateway 环状态
GET /indexgateway/ring显示一个网页，其中包含 index gateway 哈希环状态，包括每个 index gateway 的状态、健康状况和最后一次心跳时间。
Ruler (规则器)
ruler API 端点需要配置后端对象存储来存储记录规则和警报。ruler API 在创建规则组时使用“namespace”的概念。这代表 Prometheus 中规则文件的名称。规则组在 namespace 内必须具有唯一名称。
注意
您必须配置
enable_api: true才能启用此功能。
Ruler 环状态
GET /ruler/ring显示一个网页，其中包含 ruler 哈希环状态，包括每个 ruler 的状态、健康状况和最后一次心跳时间。
列出规则组
GET /loki/api/v1/rules列出已认证租户配置的所有规则。此端点返回一个 YAML 字典，其中包含每个 namespace 的所有规则组，并在成功时返回 200 状态码。
响应示例
---
<namespace1>:
- name: <string>
interval: <duration;optional>
rules:
- alert: <string>
expr: <string>
for: <duration>
annotations:
<annotation_name>: <string>
labels:
<label_name>: <string>
- name: <string>
interval: <duration;optional>
rules:
- alert: <string>
expr: <string>
for: <duration>
annotations:
<annotation_name>: <string>
labels:
<label_name>: <string>
<namespace2>:
- name: <string>
interval: <duration;optional>
rules:
- alert: <string>
expr: <string>
for: <duration>
annotations:
<annotation_name>: <string>
labels:
<label_name>: <string>按 namespace 获取规则组
GET /loki/api/v1/rules/{namespace}返回给定 namespace 定义的规则组。
响应示例
name: <string>
interval: <duration;optional>
rules:
- alert: <string>
expr: <string>
for: <duration>
annotations:
<annotation_name>: <string>
labels:
<label_name>: <string>获取规则组
GET /loki/api/v1/rules/{namespace}/{groupName}返回与请求的 namespace 和组名称匹配的规则组。
设置规则组
POST /loki/api/v1/rules/{namespace}创建或更新规则组。此端点期望请求包含 Content-Type: application/yaml 头并在请求体中包含规则的 YAML 定义，并在成功时返回 202。
请求示例
请求头
Content-Type: application/yaml
请求体
name: <string>
interval: <duration;optional>
rules:
- alert: <string>
expr: <string>
for: <duration>
annotations:
<annotation_name>: <string>
labels:
<label_name>: <string>删除规则组
DELETE /loki/api/v1/rules/{namespace}/{groupName}按 namespace 和组名称删除规则组。此端点在成功时返回 202。
删除 namespace
DELETE /loki/api/v1/rules/{namespace}删除 namespace 中的所有规则组（包括 namespace 本身）。此端点在成功时返回 202。
列出规则
GET /prometheus/api/v1/rules?type={alert|record}&file={}&rule_group={}&rule_name={}Prometheus 兼容的规则端点，用于列出当前加载的警报规则和记录规则。
type 参数是可选的。如果设置，仅返回指定类型的规则。
file、rule_group 和 rule_name 参数是可选的，可以接受多个值。如果设置，则根据这些参数过滤响应内容。
有关更多信息，请参阅 Prometheus 规则 文档。
列出警报
GET /prometheus/api/v1/alertsPrometheus 兼容的规则端点，用于列出所有活动警报。
有关更多信息，请参阅 Prometheus 警报 文档。
Compactor (压缩器)
Compactor 环状态
GET /compactor/ring显示一个网页，其中包含 compactor 哈希环状态，包括每个 compactor 的状态、健康状况和最后一次心跳时间。
请求日志删除
POST /loki/api/v1/delete
PUT /loki/api/v1/delete为已认证租户创建新的删除请求。日志条目删除 文档包含配置详情。
日志条目删除仅在为索引存储配置了 TSDB 或 BoltDB Shipper 时受支持。
查询参数
query=<series_selector>：查询参数，用于标识要从中删除的流，可包含可选的行过滤器。start=<rfc3339 | unix_seconds_timestamp>：标识删除条目时间窗口开始的时间戳。此参数是必需的。end=<rfc3339 | unix_seconds_timestamp>：标识删除条目时间窗口结束的时间戳。如果未指定，则默认为当前时间。max_interval=<duration>：删除请求可以跨越的最大时间段。如果请求大于此值，则会拆分为若干个 <=max_interval的请求。有效的时间单位包括s、m和h。
204 响应表示成功。
query 参数还可以包含过滤操作。例如 query={foo="bar"} |= "other" 将过滤掉与流选择器 {foo="bar"} 匹配的流中包含字符串“other”的行。
示例
URL 编码 query 参数。此 cURL 命令的示例形式对 query={foo="bar"} 进行 URL 编码。
curl -g -X POST \
'http://127.0.0.1:3100/loki/api/v1/delete?query={foo="bar"}&start=1591616227&end=1591619692' \
-H 'X-Scope-OrgID: 1'Grafana Enterprise Logs 的相同删除请求示例使用基本认证，并将租户名称指定为用户；此示例中的租户名称是 Tenant1。此示例中的密码是在 API_TOKEN 环境变量中定义的访问策略 token。该 token 必须属于具有 logs:delete 作用域的访问策略，且作用于用户字段中指定的租户
curl -u "Tenant1:$API_TOKEN" \
-g -X POST \
'http://127.0.0.1:3100/loki/api/v1/delete?query={foo="bar"}&start=1591616227&end=1591619692'列出日志删除请求
GET /loki/api/v1/delete列出已认证租户的现有删除请求。日志条目删除 文档包含配置详情。
日志条目删除仅在为索引存储配置了 TSDB 或 BoltDB Shipper 时受支持。
使用以下 API 列出现有删除请求
GET /loki/api/v1/delete此端点返回已处理和未处理的删除请求。它不列出已取消的请求，因为这些请求已从存储中移除。
示例
cURL 命令示例
curl -X GET \
<compactor_addr>/loki/api/v1/delete \
-H 'X-Scope-OrgID: <orgid>'Grafana Enterprise Logs 的相同删除请求示例使用基本认证，并将租户名称指定为用户；此示例中的租户名称是 Tenant1。此示例中的密码是在 API_TOKEN 环境变量中定义的访问策略 token。该 token 必须属于具有 logs:delete 作用域的访问策略，且作用于用户字段中指定的租户。
curl -u "Tenant1:$API_TOKEN" \
-X GET \
<compactor_addr>/loki/api/v1/delete请求取消删除请求
DELETE /loki/api/v1/delete移除已认证租户的删除请求。日志条目删除 文档包含配置详情。
Loki 允许在请求被处理之前取消删除请求。这由 delete_request_cancel_period YAML 配置或调用 Loki 时等效的命令行选项控制。要取消已被处理或部分完成的删除请求，请将 force=true 查询参数传递给 API。
日志条目删除仅在为索引存储配置了 TSDB 或 BoltDB Shipper 时受支持。
使用此 compactor 端点取消删除请求
DELETE /loki/api/v1/delete查询参数
request_id=<request_id>：标识要取消的删除请求；ID 可以通过delete端点找到。force=<boolean>：当force查询参数为 true 时，部分完成的删除请求将被取消。注意
请求中的某些数据可能仍然被删除，并且被删除的请求将被列为“已处理”。
204 响应表示成功。
示例
cURL 命令示例
curl -X DELETE \
'<compactor_addr>/loki/api/v1/delete?request_id=<request_id>' \
-H 'X-Scope-OrgID: <tenant-id>'Grafana Enterprise Logs 的相同删除取消请求示例使用基本认证，并将租户名称指定为用户；此示例中的租户名称是 Tenant1。此示例中的密码是在 API_TOKEN 环境变量中定义的访问策略 token。该 token 必须属于具有 logs:delete 作用域的访问策略，且作用于用户字段中指定的租户。
curl -u "Tenant1:$API_TOKEN" \
-X DELETE \
'<compactor_addr>/loki/api/v1/delete?request_id=<request_id>'格式化 LogQL 查询
GET /loki/api/v1/format_query
POST /loki/api/v1/format_query该端点接受 URL 中的以下查询参数
query：LogQL 查询字符串。在GET和POST请求中都可以作为 URL 参数传递 (?query=<query>)。在POST请求中也可以作为表单值传递。
/loki/api/v1/format_query 端点允许您格式化 LogQL 查询。如果传递的 LogQL 无效，它将返回错误。此端点由所有 Loki 组件暴露，有助于提高 LogQL 查询的可读性和调试体验。
以下示例将 LogQL 表达式 {foo= "bar"} 格式化为
{
"status" : "success",
"data" : "{foo=\"bar\"}"
}此页面是否有帮助？
来自 Grafana Labs 的相关资源
