From a3b9534f372a99a5faae6995eb0ba03d8a3c31a0 Mon Sep 17 00:00:00 2001 From: Christian Haudum Date: Fri, 22 Sep 2023 18:45:08 +0200 Subject: [PATCH] Restructure API reference documentation (#10654) * Removed unsupported APIs * Change order so it matches the list on top * Write better headings * Make cURL examples consistent with command-response-blocks Signed-off-by: Christian Haudum --- .../get-started/labels/structured-metadata.md | 2 +- docs/sources/reference/api.md | 1088 +++++++---------- docs/sources/send-data/k6/_index.md | 12 +- docs/sources/send-data/promtail/_index.md | 2 +- .../send-data/promtail/configuration.md | 2 +- 5 files changed, 484 insertions(+), 622 deletions(-) diff --git a/docs/sources/get-started/labels/structured-metadata.md b/docs/sources/get-started/labels/structured-metadata.md index e59249c720..981142ad67 100644 --- a/docs/sources/get-started/labels/structured-metadata.md +++ b/docs/sources/get-started/labels/structured-metadata.md @@ -23,7 +23,7 @@ to extract at query time. ## Attaching structured metadata to log lines You have the option to attach structured metadata to log lines in the push payload along with each log line and the timestamp. -For more information on how to push logs to Loki via the HTTP endpoint, refer to the [HTTP API documentation]({{< relref "../../reference/api#push-log-entries-to-loki" >}}). +For more information on how to push logs to Loki via the HTTP endpoint, refer to the [HTTP API documentation]({{< relref "../../reference/api#ingest-logs" >}}). Alternatively, you can use the Grafana Agent or Promtail to extract and attach structured metadata to your log lines. See the [Promtail: Structured metadata stage]({{< relref "../../send-data/promtail/stages/structured_metadata" >}}) for more information. diff --git a/docs/sources/reference/api.md b/docs/sources/reference/api.md index 12233fc8ee..bf56041dc3 100644 --- a/docs/sources/reference/api.md +++ b/docs/sources/reference/api.md @@ -1,68 +1,79 @@ --- -title: Grafana Loki HTTP API -menuTitle: "HTTP API" -description: Loki exposes REST endpoints for operating on a Loki cluster. This section details the REST endpoints. +title: Loki HTTP API +menuTitle: HTTP API +description: Loki exposes HTTP endpoints for data ingestion, data retrieval, as well for cluster management. aliases: - ../api/ weight: 100 --- -# Grafana Loki HTTP API +# Loki HTTP API -Grafana Loki exposes an HTTP API for pushing, querying, and tailing log data. -Note that authenticating against the API is -out of scope for Loki. +Loki exposes an HTTP API for pushing, querying, and tailing log data, as well +as for viewing and managing cluster information. -## Microservices mode +**Note that authorization is not part of the Loki API.** +Authorization needs to be done separately, for example, using an open-source load-balancer such as NGINX. -When deploying Loki in microservices mode, the set of endpoints exposed by each -component is different. +## Endpoints -These endpoints are exposed by all components: +### Ingest endpoints -- [`GET /ready`](#identify-ready-loki-instance) -- [`GET /log_level`](#change-log-level-at-runtime) -- [`GET /metrics`](#return-exposed-prometheus-metrics) -- [`GET /config`](#list-current-configuration) +These endpoints are exposed by the `distributor`, `write`, and `all` components: + +- [`POST /loki/api/v1/push`](#ingest-logs) + +A [list of clients]({{< relref "../send-data" >}}) can be found in the clients documentation. + +### Query endpoints + +These HTTP endpoints are exposed by the `querier`, `query-frontend`, `read`, and `all` components: + +- [`GET /loki/api/v1/query`](#query-logs-at-a-single-point-in-time) +- [`GET /loki/api/v1/query_range`](#query-logs-within-a-range-of-time) +- [`GET /loki/api/v1/labels`](#query-labels) +- [`GET /loki/api/v1/label//values`](#query-label-values) +- [`GET /loki/api/v1/series`](#query-streams) +- [`GET /loki/api/v1/index/stats`](#query-log-statistics) +- [`GET /loki/api/v1/index/volume`](#query-log-volume) +- [`GET /loki/api/v1/index/volume_range`](#query-log-volume) +- [`GET /loki/api/v1/tail`](#stream-logs) + +### Status endpoints + +These HTTP endpoints are exposed by all components and return the status of the component: + +- [`GET /ready`](#readiness-probe) +- [`GET /log_level`](#change-log-level) +- [`GET /metrics`](#prometheus-metrics) +- [`GET /config`](#show-current-configuration) - [`GET /services`](#list-running-services) -- [`GET /loki/api/v1/status/buildinfo`](#list-build-information) -- [`GET /loki/api/v1/format_query`](#format-query) - -These endpoints are exposed by the querier and the query frontend: - -- [`GET /loki/api/v1/query`](#query-loki) -- [`GET /loki/api/v1/query_range`](#query-loki-over-a-range-of-time) -- [`GET /loki/api/v1/labels`](#list-labels-within-a-range-of-time) -- [`GET /loki/api/v1/label//values`](#list-label-values-within-a-range-of-time) -- [`GET /loki/api/v1/series`](#list-series) -- [`GET /loki/api/v1/index/stats`](#index-stats) -- [`GET /loki/api/v1/index/volume`](#volume) -- [`GET /loki/api/v1/index/volume_range`](#volume) -- [`GET /loki/api/v1/tail`](#stream-log-messages) -- **Deprecated** [`GET /api/prom/tail`](#get-apipromtail) -- **Deprecated** [`GET /api/prom/query`](#get-apipromquery) -- **Deprecated** [`GET /api/prom/label`](#get-apipromlabel) -- **Deprecated** [`GET /api/prom/label//values`](#get-apipromlabelnamevalues) -- **Deprecated** [`GET /api/prom/series`](#list-series) - -These endpoints are exposed by the distributor: - -- [`POST /loki/api/v1/push`](#push-log-entries-to-loki) -- [`GET /distributor/ring`](#display-distributor-consistent-hash-ring-status) -- **Deprecated** [`POST /api/prom/push`](#post-apiprompush) - -These endpoints are exposed by the ingester: +- [`GET /loki/api/v1/status/buildinfo`](#show-build-information) + +### Ring endpoints + +These HTTP endpoints are exposed by their respective component that is part of the ring URL prefix: + +- [`GET /distributor/ring`](#distributor-ring-status) +- [`GET /indexgateway/ring`](#index-gateway-ring-status) +- [`GET /ruler/ring`](#ruler-ring-status) +- [`GET /compactor/ring`](#compactor-ring-status) + +### Flush/shutdown endpoints + +These HTTP endpoints are exposed by the `ingester`, `write`, and `all` components for flushing chunks and/or shutting down. - [`POST /flush`](#flush-in-memory-chunks-to-backing-store) +- [`POST /ingester/prepare_shutdown`](#prepare-ingester-shutdown) - [`POST /ingester/shutdown`](#flush-in-memory-chunks-and-shut-down) +- **Deprecated** [`POST /ingester/flush_shutdown`](#post-ingesterflush_shutdown) -The API endpoints starting with `/loki/` are [Prometheus API-compatible](https://prometheus.io/docs/prometheus/latest/querying/api/) and the result formats can be used interchangeably. +### Rule endpoints -These endpoints are exposed by the ruler: +These HTTP endpoints are exposed by the `ruler` component: -- [`GET /ruler/ring`](#ruler-ring-status) - [`GET /loki/api/v1/rules`](#list-rule-groups) -- [`GET /loki/api/v1/rules/{namespace}`](#get-rule-groups-by-namespace) +- [`GET /loki/api/v1/rules/({namespace}`](#get-rule-groups-by-namespace) - [`GET /loki/api/v1/rules/{namespace}/{groupName}`](#get-rule-group) - [`POST /loki/api/v1/rules/{namespace}`](#set-rule-group) - [`DELETE /loki/api/v1/rules/{namespace}/{groupName}`](#delete-rule-group) @@ -76,53 +87,185 @@ These endpoints are exposed by the ruler: - [`GET /prometheus/api/v1/rules`](#list-rules) - [`GET /prometheus/api/v1/alerts`](#list-alerts) -These endpoints are exposed by the compactor: +API endpoints starting with `/api/prom` are [Prometheus API-compatible](https://prometheus.io/docs/prometheus/latest/querying/api/) and the result formats can be used interchangeably. + +### Log deletion endpoints + +These endpoints are exposed by the `compactor`, `backend`, and `all` components: -- [`GET /compactor/ring`](#compactor-ring-status) - [`POST /loki/api/v1/delete`](#request-log-deletion) - [`GET /loki/api/v1/delete`](#list-log-deletion-requests) - [`DELETE /loki/api/v1/delete`](#request-cancellation-of-a-delete-request) -A [list of clients]({{< relref "../send-data" >}}) can be found in the clients documentation. +### Other endpoints + +These HTTP endpoints are exposed by all individual components: + +- [`GET /loki/api/v1/format_query`](#format-a-logql-query) + +### Deprecated endpoints -## Matrix, vector, and streams +{{% admonition type="note" %}} +The following endpoints are deprecated. While they still exist and work, they should not be used for new deployments. +Existing deployments should upgrade to use the supported endpoints. +{{% /admonition %}} + +| Deprecated | Replacement | +| ---------- | ----------- | +| `POST /api/prom/push` | [`POST /loki/api/v1/push`](#ingest-logs) | +| `GET /api/prom/tail` | [`GET /loki/api/v1/tail`](#stream-logs) | +| `GET /api/prom/query` | [`GET /loki/api/v1/query`](#query-logs-at-a-single-point-in-time) | +| `GET /api/prom/label` | [`GET /loki/api/v1/labels`](#query-labels) | +| `GET /api/prom/label//values` | [`GET /loki/api/v1/label//values`](#query-label-values) | +| `GET /api/prom/series` | [`GET /loki/api/v1/series`](#query-streams) | + +## Format + +### Matrix, vector, and stream Some Loki API endpoints return a result of a matrix, a vector, or a stream: -- Matrix: a table of values where each row represents a different label set - and the columns are each sample value for that row over the queried time. +- **Matrix**: a table of values where each row represents a different label set + and the columns are each sample values for that row over the queried time. Matrix types are only returned when running a query that computes some value. -- Instant Vector: denoted in the type as just `vector`, an Instant Vector +- **Instant Vector**: denoted in the type as just `vector`, an Instant Vector represents the latest value of a calculation for a given labelset. Instant Vectors are only returned when doing a query against a single point in time. -- Stream: a Stream is a set of all values (logs) for a given label set over the +- **Stream**: a Stream is a set of all values (logs) for a given label set over the queried time range. Streams are the only type that will result in log lines being returned. -## Timestamp formats +### Timestamps + +The API accepts several formats for timestamps: + +* An integer with ten or fewer digits is interpreted as a Unix timestamp in seconds. +* More than ten digits are interpreted as a Unix timestamp in nanoseconds. +* A floating point number is a Unix timestamp with fractions of a second. +* A string in `RFC3339` and `RFC3339Nano` format, as supported by Go's [time](https://pkg.go.dev/time) package. + +### Statistics + +Query endpoints such as `/loki/api/v1/query` and `/loki/api/v1/query_range` return a set of statistics about the query execution. Those statistics allow users to understand the amount of data processed and at which speed. + +The example below show all possible statistics returned with their respective description. + +```json +{ + "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 + } + } + } +} +``` + +## Ingest logs + +``` +POST /loki/api/v1/push +``` + +`/loki/api/v1/push` is the endpoint used to send log entries to Loki. The default +behavior is for the POST body to be a [Snappy](https://github.com/google/snappy)-compressed [Protocol Buffer](https://github.com/protocolbuffers/protobuf) message: + +- [Protocol Buffer definition](https://github.com/grafana/loki/blob/main/pkg/logproto/logproto.proto) +- [Go client library](https://github.com/grafana/loki/blob/main/clients/pkg/promtail/client/client.go) + +These POST requests require the `Content-Type` HTTP header to be `application/x-protobuf`. + +Alternatively, if the `Content-Type` header is set to `application/json`, a JSON post body can be sent in the following format: + +``` +{ + "streams": [ + { + "stream": { + "label": "value" + }, + "values": [ + [ "", "" ], + [ "", "" ] + ] + } + ] +} +``` + +You can set `Content-Encoding: gzip` request header and post gzipped JSON. + +You can optionally attach [structured metadata]({{< relref "../get-started/labels/structured-metadata" >}}) to each log line by adding a JSON object to the end of the log line array. +The JSON object must be a valid JSON object with string keys and string values. The JSON object should not contain any nested object. +The JSON object must be set immediately after the log line. Here is an example of a log entry with some structured metadata attached: + +``` +"values": [ + [ "", "", {"trace_id": "0242ac120002", "user_id": "superUser123"}] +] +``` + +In microservices mode, `/loki/api/v1/push` is exposed by the distributor. + +### Examples -The API accepts several formats for timestamps. An integer with ten or fewer digits is interpreted as a Unix timestamp in seconds. More than ten digits are interpreted as a Unix timestamp in nanoseconds. A floating point number is a Unix timestamp with fractions of a second. +The following cURL command pushes a stream with the label "foo=bar2" and a single log line "fizzbuzz" using JSON encoding: -The timestamps can also be written in `RFC3339` and `RFC3339Nano` format, as supported by Go's [time](https://pkg.go.dev/time) package. +```bash +curl -H "Content-Type: application/json" \ + -s -X POST "http://localhost:3100/loki/api/v1/push" \ + --data-raw '{"streams": [{ "stream": { "foo": "bar2" }, "values": [ [ "1570818238000000000", "fizzbuzz" ] ] }]}' +``` -## Query Loki +## Query logs at a single point in time ``` GET /loki/api/v1/query ``` -`/loki/api/v1/query` allows for doing queries against a single point in time. The URL -query parameters support the following values: +`/loki/api/v1/query` allows for doing queries against a single point in time. +This type of query is often referred to as an instant query. Instant queries are mostly used for metric type LogQL queries. +It accepts the following query parameters in the URL: -- `query`: The [LogQL]({{< relref "../query" >}}) query to perform -- `limit`: The max number of entries to return. It defaults to `100`. Only applies to query types which produce a stream(log lines) response. -- `time`: The evaluation time for the query as a nanosecond Unix epoch or another [supported format](#timestamp-formats). Defaults to now. +- `query`: The [LogQL]({{< relref "../query" >}}) query to perform. +- `limit`: The max number of entries to return. It defaults to `100`. Only applies to query types which produce a stream (log lines) response. +- `time`: The evaluation time for the query as a nanosecond Unix epoch or another [supported format](#timestamps). Defaults to now. - `direction`: Determines the sort order of logs. Supported values are `forward` or `backward`. Defaults to `backward`. -In microservices mode, `/loki/api/v1/query` is exposed by the querier and the frontend. +In microservices mode, `/loki/api/v1/query` is exposed by the querier and the query frontend. Response format: @@ -176,12 +319,11 @@ See [statistics](#statistics) for information about the statistics returned by L ### Examples -This example query +This example cURL command ```bash curl -G -s "http://localhost:3100/loki/api/v1/query" \ - --data-urlencode \ - 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq + --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq ``` gave this response: @@ -233,8 +375,7 @@ Here is the same example query for the single tenant called `Tenant1`: ```bash curl -H 'X-Scope-OrgID:Tenant1' \ -G -s "http://localhost:3100/loki/api/v1/query" \ - --data-urlencode \ - 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq + --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq ``` To query against the three tenants `Tenant1`, `Tenant2`, and `Tenant3`, @@ -243,8 +384,7 @@ specify the tenant names separated by the pipe (`|`) character: ```bash curl -H 'X-Scope-OrgID:Tenant1|Tenant2|Tenant3' \ -G -s "http://localhost:3100/loki/api/v1/query" \ - --data-urlencode \ - 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq + --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq ``` The same example query for Grafana Enterprise Logs @@ -256,29 +396,29 @@ defined in the `API_TOKEN` environment variable: ```bash curl -u "Tenant1|Tenant2|Tenant3:$API_TOKEN" \ -G -s "http://localhost:3100/loki/api/v1/query" \ - --data-urlencode \ - 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq + --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq ``` -## Query Loki over a range of time +## Query logs within a range of time ``` GET /loki/api/v1/query_range ``` -`/loki/api/v1/query_range` is used to do a query over a range of time and -accepts the following query parameters in the URL: +`/loki/api/v1/query_range` is used to do a query over a range of time. +This type of query is often referred to as a range query. Range queries are used for both log and metric type LogQL queries. +It accepts the following query parameters in the URL: -- `query`: The [LogQL]({{< relref "../query" >}}) query to perform -- `limit`: The max number of entries to return. It defaults to `100`. Only applies to query types which produce a stream(log lines) response. -- `start`: The start time for the query as a nanosecond Unix epoch or another [supported format](#timestamp-formats). Defaults to one hour ago. Loki returns results with timestamp greater or equal to this value. -- `end`: The end time for the query as a nanosecond Unix epoch or another [supported format](#timestamp-formats). Defaults to now. Loki returns results with timestamp lower than this value. +- `query`: The [LogQL]({{< relref "../query" >}}) query to perform. +- `limit`: The max number of entries to return. It defaults to `100`. Only applies to query types which produce a stream (log lines) response. +- `start`: The start time for the query as a nanosecond Unix epoch or another [supported format](#timestamps). Defaults to one hour ago. Loki returns results with timestamp greater or equal to this value. +- `end`: The end time for the query as a nanosecond Unix epoch or another [supported format](#timestamps). Defaults to now. Loki returns results with timestamp lower than this value. - `since`: A `duration` used to calculate `start` relative to `end`. If `end` is in the future, `start` is calculated as this duration before now. Any value specified for `start` supersedes this parameter. - `step`: Query resolution step width in `duration` format or float number of seconds. `duration` refers to Prometheus duration strings of the form `[0-9]+[smhdwy]`. For example, 5m refers to a duration of 5 minutes. Defaults to a dynamic value based on `start` and `end`. Only applies to query types which produce a matrix response. -- `interval`: This parameter is experimental; see the explanation under Step versus interval. Only return entries at (or greater than) the specified interval, can be a `duration` format or float number of seconds. Only applies to queries which produce a stream response. +- `interval`: Only return entries at (or greater than) the specified interval, can be a `duration` format or float number of seconds. Only applies to queries which produce a stream response. Not to be confused with `step`, see the explanation under [Step versus interval](#step-versus-interval). - `direction`: Determines the sort order of logs. Supported values are `forward` or `backward`. Defaults to `backward.` -In microservices mode, `/loki/api/v1/query_range` is exposed by the querier and the frontend. +In microservices mode, `/loki/api/v1/query_range` is exposed by the querier and the query frontend. ### Step versus interval @@ -286,9 +426,7 @@ Use the `step` parameter when making metric queries to Loki, or queries which re Use the `interval` parameter when making log queries to Loki, or queries which return a stream response. It is evaluated by returning a log entry at `start`, then the next entry will be returned an entry with timestampe >= `start + interval`, and again at `start + interval + interval` and so on until `end` is reached. It does not fill missing entries. -Note about the experimental nature of the interval parameter: This flag may be removed in the future, if so it will likely be in favor of a LogQL expression to perform similar behavior, however that is uncertain at this time. [Issue 1779](https://github.com/grafana/loki/issues/1779) was created to track the discussion, if you are using `interval`, go add your use case and thoughts to that issue. - -Response: +Response format: ``` { @@ -301,7 +439,7 @@ Response: } ``` -Where `` is: +where `` is: ``` { @@ -345,8 +483,17 @@ See [statistics](#statistics) for information about the statistics returned by L ### Examples +This example cURL command + ```bash -$ curl -G -s "http://localhost:3100/loki/api/v1/query_range" --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' --data-urlencode 'step=300' | jq +curl -G -s "http://localhost:3100/loki/api/v1/query_range" \ + --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' \ + --data-urlencode 'step=300' | jq +``` + +gave this response: + +```json { "status": "success", "data": { @@ -398,8 +545,16 @@ $ curl -G -s "http://localhost:3100/loki/api/v1/query_range" --data-urlencode ' } ``` +This example cURL command + ```bash -$ curl -G -s "http://localhost:3100/loki/api/v1/query_range" --data-urlencode 'query={job="varlogs"}' | jq +curl -G -s "http://localhost:3100/loki/api/v1/query_range" \ + --data-urlencode 'query={job="varlogs"}' | jq +``` + +gave this response: + +```json { "status": "success", "data": { @@ -430,7 +585,7 @@ $ curl -G -s "http://localhost:3100/loki/api/v1/query_range" --data-urlencode ' } ``` -## List labels within a range of time +## Query labels ``` GET /loki/api/v1/labels @@ -446,7 +601,7 @@ It accepts the following query parameters in the URL: In microservices mode, `/loki/api/v1/labels` is exposed by the querier. -Response: +Response format: ``` { @@ -460,8 +615,15 @@ Response: ### Examples +This example cURL command + ```bash -$ curl -G -s "http://localhost:3100/loki/api/v1/labels" | jq +curl -G -s "http://localhost:3100/loki/api/v1/labels" | jq +``` + +gave this response: + +```json { "status": "success", "data": [ @@ -472,7 +634,7 @@ $ curl -G -s "http://localhost:3100/loki/api/v1/labels" | jq } ``` -## List label values within a range of time +## Query label values ``` GET /loki/api/v1/label//values @@ -489,7 +651,7 @@ It accepts the following query parameters in the URL: In microservices mode, `/loki/api/v1/label//values` is exposed by the querier. -Response: +Response format: ``` { @@ -503,8 +665,15 @@ Response: ### Examples +This example cURL command + ```bash -$ curl -G -s "http://localhost:3100/loki/api/v1/label/foo/values" | jq +curl -G -s "http://localhost:3100/loki/api/v1/label/foo/values" | jq +``` + +gave this response: + +```json { "status": "success", "data": [ @@ -515,194 +684,223 @@ $ curl -G -s "http://localhost:3100/loki/api/v1/label/foo/values" | jq } ``` -## Stream log messages +## Query streams -``` -GET /loki/api/v1/tail -``` +The Series API is available under the following: -`/loki/api/v1/tail` is a WebSocket endpoint that will stream log messages based on -a query. It accepts the following query parameters in the URL: +- `GET /loki/api/v1/series` +- `POST /loki/api/v1/series` -- `query`: The [LogQL]({{< relref "../query" >}}) query to perform -- `delay_for`: The number of seconds to delay retrieving logs to let slow - loggers catch up. Defaults to 0 and cannot be larger than 5. -- `limit`: The max number of entries to return. It defaults to `100`. -- `start`: The start time for the query as a nanosecond Unix epoch. Defaults to one hour ago. +This endpoint returns the list of streams (unique set of labels) that match a certain given selector. -In microservices mode, `/loki/api/v1/tail` is exposed by the querier. +URL query parameters: + +- `match[]=`: Repeated log stream selector argument that selects the streams to return. At least one `match[]` argument must be provided. +- `start=`: Start timestamp. +- `end=`: End timestamp. +- `since`: A `duration` used to calculate `start` relative to `end`. If `end` is in the future, `start` is calculated as this duration before now. Any value specified for `start` supersedes this parameter. + +You can URL-encode these parameters directly in the request body by using the POST method and `Content-Type: application/x-www-form-urlencoded` header. This is useful when specifying a large or dynamic number of stream selectors that may breach server-side URL character limits. + +In microservices mode, these endpoints are exposed by the querier. + +### Examples -Response (streamed): +This example cURL command +```bash +curl -s "http://localhost:3100/loki/api/v1/series" \ + --data-urlencode 'match[]={container_name=~"prometheus.*", component="server"}' \ + --data-urlencode 'match[]={app="loki"}' | jq '.' ``` + +gave this response: + +```json { - "streams": [ + "status": "success", + "data": [ { - "stream": { -