Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add multi-tenant query curl examples #6530

Merged
merged 2 commits into from
Jun 30, 2022
Merged

Docs: Add multi-tenant query curl examples #6530

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3788cee
Docs: Add multi-tenant query curl examples
KMiller-Grafana Jun 28, 2022
7d90f43
Revise per review suggestions.
KMiller-Grafana Jun 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 47 additions & 36 deletions docs/sources/api/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ query parameters support the following values:

In microservices mode, `/loki/api/v1/query` is exposed by the querier and the frontend.

Response:
Response format:

```
{
Expand All @@ -131,7 +131,7 @@ Response:
}
```

Where `<vector value>` is:
where `<vector value>` is:

```
{
Expand All @@ -145,7 +145,7 @@ Where `<vector value>` is:
}
```

And `<stream value>` is:
and `<stream value>` is:

```
{
Expand All @@ -170,8 +170,16 @@ See [statistics](#statistics) for information about the statistics returned by L

### Examples

This example query
```bash
$ curl -G -s "http://localhost:3100/loki/api/v1/query" --data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq
curl -G -s "http://localhost:3100/loki/api/v1/query" \
--data-urlencode \
'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq
```

gave this response:

```json
{
"status": "success",
"data": {
Expand Down Expand Up @@ -210,36 +218,39 @@ $ curl -G -s "http://localhost:3100/loki/api/v1/query" --data-urlencode 'query=
}
```

If your cluster has
[Grafana Loki Multi-Tenancy](../operations/multi-tenancy/) enabled,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[Grafana Loki Multi-Tenancy](../operations/multi-tenancy/) enabled,
[multi-tenancy](../operations/multi-tenancy/) enabled,

Feels weird to say 'Grafana Loki Multi-Tenancy' - makes it feel like its some sort of trademarked thing when multi-tenant software is sort of a general and widespread concept.

You could change it to If your Grafana Loki cluster has multi tenancy enabled should you so choose.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It does feel stilted and weird. However, a style guideline is to make the link name the same as the web page title or subsection title that we're sending someone to. It helps readers know that they've landed at the link we intended for them. That web page is titled "Grafana Loki Multi-tenancy," so I used it as the link title.

I'm going to leave this for now, but happy to figure out a future change that rewords and still follows the style guideline.

set the `X-Scope-OrgID` header to identify the tenant you want to query.
Here is the same example query for the single tenant called `Tenant1`:

```bash
$ curl -G -s "http://localhost:3100/loki/api/v1/query" --data-urlencode 'query={job="varlogs"}' | jq
{
"status": "success",
"data": {
"resultType": "streams",
"result": [
{
"stream": {
"filename": "/var/log/myproject.log",
"job": "varlogs",
"level": "info"
},
"values": [
[
"1568234281726420425",
"foo"
],
[
"1568234269716526880",
"bar"
]
],
}
],
"stats": {
...
}
}
}
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
```

To query against the three tenants `Tenant1`, `Tenant2`, and `Tenant3`,
KMiller-Grafana marked this conversation as resolved.
Show resolved Hide resolved
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
```

The same example query for Grafana Enterprise Logs
uses Basic Authentication and specifies the tenant names as a `user`.
The tenant names are separated by the pipe (`|`) character.
The password in this example is an access policy token that has been
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
```

## Query Loki over a range of time
Expand Down Expand Up @@ -1030,7 +1041,7 @@ URL encode the `query` parameter. This sample form of a cURL command URL encodes
```bash
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'
-H 'X-Scope-OrgID: 1'
```

The query parameter can also include filter operations. For example `query={foo="bar"} |= "other"` will filter out lines that contain the string "other" for the streams matching the stream selector `{foo="bar"}`.
Expand All @@ -1056,7 +1067,7 @@ Sample form of a cURL command:
```
curl -X GET \
<compactor_addr>/loki/api/v1/delete \
-H 'x-scope-orgid: <orgid>'
-H 'X-Scope-OrgID: <orgid>'
```

This endpoint returns both processed and unprocessed requests. It does not list canceled requests, as those requests will have been removed from storage.
Expand Down Expand Up @@ -1090,7 +1101,7 @@ Sample form of a cURL command:
```
curl -X DELETE \
'<compactor_addr>/loki/api/v1/delete?request_id=<request_id>' \
-H 'x-scope-orgid: <tenant-id>'
-H 'X-Scope-OrgID: <tenant-id>'
```

## Deprecated endpoints
Expand Down