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

Chore: Prod to staging #175

Merged
merged 4 commits into from
Dec 12, 2024
Merged

Chore: Prod to staging #175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
aefe771
updated logcli
Jayclifford345 Dec 11, 2024
f8a2805
added two new tutorials
Jayclifford345 Dec 12, 2024
a4634cc
Update generated tutorials
grafanabot Dec 12, 2024
b204764
Merge pull request #174 from grafana/update-generated-tutorials
Jayclifford345 Dec 12, 2024
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
14 changes: 14 additions & 0 deletions .github/workflows/regenerate-tutorials.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,10 @@ jobs:
with:
repository: grafana/mimir
path: mimir
- uses: actions/checkout@v4
with:
repository: grafana/pyroscope
path: pyroscope
- uses: actions/checkout@v4
with:
path: killercoda
Expand Down Expand Up @@ -66,6 +70,11 @@ jobs:
"${GITHUB_WORKSPACE}/loki/docs/sources/send-data/fluentbit/fluent-bit-loki-tutorial.md"
"${GITHUB_WORKSPACE}/killercoda/loki/fluentbit-loki-tutorial"
working-directory: killercoda/tools/transformer
- run: >
./transformer
"${GITHUB_WORKSPACE}/loki/docs/sources/query/logcli/logcli-tutorial.md"
"${GITHUB_WORKSPACE}/killercoda/loki/logcli-tutorial"
working-directory: killercoda/tools/transformer
- run: >
./transformer
"${GITHUB_WORKSPACE}/grafana/docs/sources/tutorials/alerting-get-started/index.md"
Expand Down Expand Up @@ -101,6 +110,11 @@ jobs:
"${GITHUB_WORKSPACE}/mimir/docs/sources/mimir/get-started/play-with-grafana-mimir/index.md"
"${GITHUB_WORKSPACE}/killercoda/mimir/play-with-mimir"
working-directory: killercoda/tools/transformer
- run: >
./transformer
"${GITHUB_WORKSPACE}/pyroscope/docs/sources/get-started/ride-share-tutorial.md"
"${GITHUB_WORKSPACE}/killercoda/pyroscope/ride-share-tutorial"
working-directory: killercoda/tools/transformer
- run: ./scripts/manage-pr.bash
env:
GH_TOKEN: ${{ github.token }}
Expand Down
110 changes: 77 additions & 33 deletions loki/logcli-tutorial/preprocessed.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,25 +60,25 @@ The logs are processed from Grafana Alloy to extract labels and structured metad

## Setup

To get started, we need to clone the [Alloy Scenario](https://github.com/grafana/alloy-scenarios) repository and spin up the mail-house example:
To get started, we need to clone the [Alloy Scenario](https://github.com/grafana/alloy-scenarios) repository and start the mail-house example:

1. Clone the repository:
```bash
git clone https://github.com/grafana/alloy-scenarios.git
```
1. Spin up the mail-house example:
1. Start the mail-house example:
```bash
docker compose -f alloy-scenarios/mail-house/docker-compose.yml up -d
```

This will start the mail-house example and expose the Loki instance on [`http://localhost:3100`](http://localhost:3100). We have also included a Grafana instance to verify the LogCLI results which can be accessed on [`http://localhost:3000`](http://localhost:3000).
This will start the mail-house example and expose the Loki instance at [`http://localhost:3100`](http://localhost:3100). We have also included a Grafana instance to verify the LogCLI results which can be accessed at [http://localhost:3000](http://localhost:3000).

### Connecting LogCLI to Loki

To connect LogCLI to the Loki instance, you need to set the `LOKI_ADDR` environment variable:

> **Tip:**
> If you are running this example against your own Loki instance and have configured authentication, you will need to set the `LOKI_USERNAME` and `LOKI_PASSWORD` environment variables as well.
> If you are running this example against your own Loki instance and have configured authentication, you will also need to set the `LOKI_USERNAME` and `LOKI_PASSWORD` environment variables.

```bash
export LOKI_ADDR=http://localhost:3100
Expand All @@ -99,7 +99,7 @@ service_name
state
```

This confirms that LogCLI is connected to the Loki instance and we now know that the logs contain the following labels: `package_size`, `service_name`, and `state`. Let's now run some queries against Loki to better understand our package logistics.
This confirms that LogCLI is connected to the Loki instance and we now know that the logs contain the following labels: `package_size`, `service_name`, and `state`. Let's run some queries against Loki to better understand our package logistics.

<!-- INTERACTIVE page step1.md END -->

Expand All @@ -111,7 +111,7 @@ As part of our role within the logistics company, we need to build a report on t

### Find all critical packages

To find all critical packages in the last hour, we can run the following query:
To find all critical packages in the last hour (the default lookback time), we can run the following query:

```bash
logcli query '{service_name="Delivery World"} | package_status="critical"'
Expand All @@ -138,21 +138,63 @@ This will query all logs for the `package_status` `critical` in the last 24 hour
logcli query --since 24h --limit 100 '{service_name="Delivery World"} | package_status="critical"'
```

### Metric Queries
### Metric queries

We can also use LogCLI to query logs based on metrics. For instance as part of the site report we want to count how many packages are being sent from California in the last 5 minutes. We can use the following query:
We can also use LogCLI to query logs based on metrics. For instance as part of the site report we want to count the total number of packages sent from California in the last 24 hours in 1 hour intervals. We can use the following query:

```bash
logcli query 'sum(count_over_time({state="California"}[5m]))'
logcli query --since 24h 'sum(count_over_time({state="California"}[1h]))'
```

Lets suppose we only want to know the number of packages of type `document` being sent from California in the last 5 minutes. We can use the following query:
This will return a JSON object containing a list of timestamps (Unix format) and the number of packages sent from California in 1 hour intervals. Since we summing the count of logs over time, we will see the total number of logs steadily increase over time. The output will look similar to the following:

```console
[
{
"metric": {},
"values": [
[
1733913765,
"46"
],
[
1733914110,
"114"
],
[
1733914455,
"179"
],
[
1733914800,
"250"
],
[
1733915145,
"318"
],
[
1733915490,
"392"
],
[
1733915835,
"396"
]
]
}
]
```

We can take this a step further and filter the logs based on the `package_type` label. For instance, we can count the number of documents sent from California in the last 24 hours in 1 hour intervals:

```bash
logcli query 'count_over_time({state="California"}| json | package_type= "Documents" [5m])'
logcli query --since 24h 'sum(count_over_time({state="California"}| json | package_type= "Documents" [1h]))'
```

### Instant Metric Queries
This will return a similar JSON object above but will only show a trend of the number of documents sent from California in 1 hour intervals.

### Instant metric queries

Instant metric queries are a subset of metric queries that return the value of the metric at a specific point in time. This can be useful for quickly understanding an aggregate state of the stored logs.

Expand All @@ -173,12 +215,12 @@ This will return a result similar to the following:
"58"
]
}
]%
]
```

### Writing query results to a file

Another useful feature of LogCLI is the ability to write the query results to a file. This can be useful for offloading the results of our inventory report:
Another useful feature of LogCLI is the ability to write the query results to a file. This can be useful for downloading the results of our inventory report:

First we need to create a directory to store the logs:
```bash
Expand All @@ -204,7 +246,7 @@ This will write all logs for the `service_name` `Delivery World` in the last 24

<!-- INTERACTIVE page step3.md START -->

## Meta Queries
## Meta queries

As site managers, it's essential to maintain good data hygiene and ensure Loki operates efficiently. Understanding the labels and log volume in your logs plays a key role in this process. Beyond querying logs, LogCLI also supports meta queries on your Loki instance. Meta queries don't return log data but provide insights into the structure of your logs and the performance of your queries. The following examples demonstrate some of the core meta queries we run internally to better understand how a Loki instance is performing.

Expand Down Expand Up @@ -252,9 +294,9 @@ package_size 3 15
service_name 1 15
```

### Detected Fields
### Detected fields

Another useful feature of LogCLI is the ability to detect fields in your logs. This can be useful for understanding the structure of your logs and the keys that are present. This will allow us to detect keys which could be promoted to labels and others to structured metadata.
Another useful feature of LogCLI is the ability to detect fields in your logs. This can be useful for understanding the structure of your logs and the keys that are present. This will let us detect keys which could be promoted to labels or to structured metadata.

```bash
logcli detected-fields --since 24h '{service_name="Delivery World"}'
Expand All @@ -263,23 +305,25 @@ logcli detected-fields --since 24h '{service_name="Delivery World"}'
This will return a list of all the keys detected in our logs. The output will look similar to the following:

```console
label: city type: string cardinality: 15
label: detected_level type: string cardinality: 3
label: note type: string cardinality: 7
label: package_id type: string cardinality: 7136
label: package_status type: string cardinality: 4
label: package_type type: string cardinality: 5
label: receiver_address type: string cardinality: 6962
label: receiver_name type: string cardinality: 100
label: sender_address type: string cardinality: 6981
label: sender_name type: string cardinality: 100
label: timestamp type: string cardinality: 7438
label: city type: string cardinality: 15
label: detected_level type: string cardinality: 3
label: note type: string cardinality: 7
label: package_id type: string cardinality: 994
label: package_size_extracted type: string cardinality: 3
label: package_status type: string cardinality: 4
label: package_type type: string cardinality: 5
label: receiver_address type: string cardinality: 991
label: receiver_name type: string cardinality: 100
label: sender_address type: string cardinality: 991
label: sender_name type: string cardinality: 100
label: state_extracted type: string cardinality: 5
label: timestamp type: string cardinality: 1000
```

You can now see why we opted to keep `package_id` in structured metadata and `package_size` as a label. Package ID has a high cardinality and is unique to each log entry, making it a good candidate for structured metadata since we potentially may need to query for it directly. Package size, on the other hand, has a low cardinality and is a good candidate for a label.
You can now see why we opted to keep `package_id` in structured metadata and `package_size` as a label. Package ID has a high cardinality and is unique to each log entry, making it a good candidate for structured metadata since we potentially may need to query for it directly. Package size, on the other hand, has a low cardinality, making it a good candidate for a label.


### Checking Query Performance
### Checking query performance

Another important aspect of keeping Loki healthy is to monitor the query performance. We can use LogCLI to check the query performance of our logs.

Expand Down Expand Up @@ -371,7 +415,7 @@ This will provide a similar JSON object but will aggregate the log volume into b

## Queries against static log files

In addition to querying logs from Loki, LogCLI also supports querying static log files. This can be useful for querying logs that are not stored in Loki using LogQL. Earlier in the tutorial we stored the logs in the `./inventory` directory. Lets run a similar query but pipe it into a log file:
In addition to querying logs from Loki, LogCLI also supports querying static log files. This can be useful for querying logs that are not stored in Loki. Earlier in the tutorial we stored the logs in the `./inventory` directory. Lets run a similar query but pipe it into a log file:

```bash
logcli query \
Expand All @@ -391,9 +435,9 @@ Next lets run a query against the static log file:
cat ./inventory/complete.log | logcli --stdin query '{service_name="Delivery World"} | json | package_status="critical"'
```

Note that since we are querying a static log file labels are not automatically detected:
Note that since we are querying a static log file, labels are not automatically detected:
* `{service_name="Delivery World"}` is optional in this case but is recommended for clarity.
* `json` is required to parse the log file as JSON. This allows us to extract the `package_status` field.
* `json` is required to parse the log file as JSON. This lets us extract the `package_status` field.

For example, suppose we try to query the log file without the `json` filter:

Expand Down
10 changes: 5 additions & 5 deletions loki/logcli-tutorial/step1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
# Setup

To get started, we need to clone the [Alloy Scenario](https://github.com/grafana/alloy-scenarios) repository and spin up the mail-house example:
To get started, we need to clone the [Alloy Scenario](https://github.com/grafana/alloy-scenarios) repository and start the mail-house example:

1. Clone the repository:
```bash
git clone https://github.com/grafana/alloy-scenarios.git
```{{exec}}

1. Spin up the mail-house example:
1. Start the mail-house example:
```bash
docker compose -f alloy-scenarios/mail-house/docker-compose.yml up -d
```{{exec}}

This will start the mail-house example and expose the Loki instance on [`http://localhost:3100`{{copy}}]({{TRAFFIC_HOST1_3100}}). We have also included a Grafana instance to verify the LogCLI results which can be accessed on [`http://localhost:3000`{{copy}}]({{TRAFFIC_HOST1_3000}}).
This will start the mail-house example and expose the Loki instance at [`http://localhost:3100`{{copy}}]({{TRAFFIC_HOST1_3100}}). We have also included a Grafana instance to verify the LogCLI results which can be accessed at [http://localhost:3000]({{TRAFFIC_HOST1_3000}}).

## Connecting LogCLI to Loki

To connect LogCLI to the Loki instance, you need to set the `LOKI_ADDR`{{copy}} environment variable:

> **Tip:**
> If you are running this example against your own Loki instance and have configured authentication, you will need to set the `LOKI_USERNAME`{{copy}} and `LOKI_PASSWORD`{{copy}} environment variables as well.
> If you are running this example against your own Loki instance and have configured authentication, you will also need to set the `LOKI_USERNAME`{{copy}} and `LOKI_PASSWORD`{{copy}} environment variables.

```bash
export LOKI_ADDR=http://localhost:3100
Expand All @@ -40,4 +40,4 @@ service_name
state
```{{copy}}

This confirms that LogCLI is connected to the Loki instance and we now know that the logs contain the following labels: `package_size`{{copy}}, `service_name`{{copy}}, and `state`{{copy}}. Let’s now run some queries against Loki to better understand our package logistics.
This confirms that LogCLI is connected to the Loki instance and we now know that the logs contain the following labels: `package_size`{{copy}}, `service_name`{{copy}}, and `state`{{copy}}. Let’s run some queries against Loki to better understand our package logistics.
60 changes: 51 additions & 9 deletions loki/logcli-tutorial/step2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ As part of our role within the logistics company, we need to build a report on t

## Find all critical packages

To find all critical packages in the last hour, we can run the following query:
To find all critical packages in the last hour (the default lookback time), we can run the following query:

```bash
logcli query '{service_name="Delivery World"} | package_status="critical"'
Expand All @@ -31,21 +31,63 @@ This will query all logs for the `package_status`{{copy}} `critical`{{copy}} in
logcli query --since 24h --limit 100 '{service_name="Delivery World"} | package_status="critical"'
```{{exec}}

## Metric Queries
## Metric queries

We can also use LogCLI to query logs based on metrics. For instance as part of the site report we want to count how many packages are being sent from California in the last 5 minutes. We can use the following query:
We can also use LogCLI to query logs based on metrics. For instance as part of the site report we want to count the total number of packages sent from California in the last 24 hours in 1 hour intervals. We can use the following query:

```bash
logcli query 'sum(count_over_time({state="California"}[5m]))'
logcli query --since 24h 'sum(count_over_time({state="California"}[1h]))'
```{{exec}}

Lets suppose we only want to know the number of packages of type `document`{{copy}} being sent from California in the last 5 minutes. We can use the following query:
This will return a JSON object containing a list of timestamps (Unix format) and the number of packages sent from California in 1 hour intervals. Since we summing the count of logs over time, we will see the total number of logs steadily increase over time. The output will look similar to the following:

```console
[
{
"metric": {},
"values": [
[
1733913765,
"46"
],
[
1733914110,
"114"
],
[
1733914455,
"179"
],
[
1733914800,
"250"
],
[
1733915145,
"318"
],
[
1733915490,
"392"
],
[
1733915835,
"396"
]
]
}
]
```{{copy}}

We can take this a step further and filter the logs based on the `package_type`{{copy}} label. For instance, we can count the number of documents sent from California in the last 24 hours in 1 hour intervals:

```bash
logcli query 'count_over_time({state="California"}| json | package_type= "Documents" [5m])'
logcli query --since 24h 'sum(count_over_time({state="California"}| json | package_type= "Documents" [1h]))'
```{{exec}}

## Instant Metric Queries
This will return a similar JSON object above but will only show a trend of the number of documents sent from California in 1 hour intervals.

## Instant metric queries

Instant metric queries are a subset of metric queries that return the value of the metric at a specific point in time. This can be useful for quickly understanding an aggregate state of the stored logs.

Expand All @@ -66,12 +108,12 @@ This will return a result similar to the following:
"58"
]
}
]%
]
```{{copy}}

## Writing query results to a file

Another useful feature of LogCLI is the ability to write the query results to a file. This can be useful for offloading the results of our inventory report:
Another useful feature of LogCLI is the ability to write the query results to a file. This can be useful for downloading the results of our inventory report:

First we need to create a directory to store the logs:

Expand Down
Loading
Loading