docs: Getting started rewrite #16497

Jayclifford345 · 2025-02-28T10:30:57Z

What this PR does / why we need it:
With the focus change to two deployment modes, Monolthic and Microservice, it was time to refresh the quick start guide to Loki. This incorporates much of the same flavour as the original:

Docker logs scraping
LogQL examples
Datasource setup

But includes newer features:

Grafana Logs Drilldown
Alloy Live debugging

Aswell as adding the Carnivouse Greehouse example to provide an interactive method to understanding LogQL queries.

Killercoda sample found here: https://killercoda.com/grafana-dev-testing/course/workshops/course-tracker-test

Checklist

Reviewed the CONTRIBUTING.md guide (required)
Documentation added
Tests updated
Title matches the required conventional commits format, see here
- Note that Promtail is considered to be feature complete, and future development for logs collection will be in Grafana Alloy. As such, feat PRs are unlikely to be accepted unless a case can be made for the feature actually being a bug fix to existing behavior.
Changes that require user attention or interaction to upgrade are documented in docs/sources/setup/upgrade/_index.md
If the change is deprecating or removing a configuration option, update the deprecated-config.yaml and deleted-config.yaml files respectively in the tools/deprecated-config-checker directory. Example PR

github-actions · 2025-02-28T10:32:25Z

💻 Deploy preview available: https://deploy-preview-loki-16497-zb444pucvq-vp.a.run.app/docs/loki/latest/

Jayclifford345 · 2025-03-04T10:00:53Z

@JStickler, for some reason, the tests keep failing on this one. We are ready for review, happy to discuss these changes on our call together as it was quite a big change to the getting started guide.

JStickler

Only made it through the docs before I ran out of time. I'll look at the KillerCoda tomorrow.

docs/sources/get-started/quick-start.md

Co-authored-by: J Stickler <[email protected]> Signed-off-by: Jay Clifford <[email protected]>

Jayclifford345 · 2025-03-10T09:54:07Z

Aaah thanks @JStickler! All changes are accepted, and the killercoda has been updated for your testing.

JStickler

Made it through both the docs/local install and the Killercoda today.

JStickler · 2025-03-11T15:16:58Z

docs/sources/get-started/quick-start.md

-If you want to experiment with Loki, you can run Loki locally using the Docker Compose file that ships with Loki. It runs Loki in a [monolithic deployment](https://grafana.com/docs/loki/<LOKI_VERSION>/get-started/deployment-modes/#monolithic-mode) mode and includes a sample application to generate logs.
-
-The Docker Compose configuration runs the following components, each in its own container:
+This quick start guide will walk you through deploying Loki in single binary mode (also known as [monolithic mode](https://grafana.com/docs/loki/<LOKI_VERSION>/get-started/deployment-modes/#monolithic-mode)) using Docker Compose. Grafana Loki is only one component of the Grafana observability stack for logs. In this tutorial we will refer to this stack as the **Loki stack**. The Loki stack consists of the following components:


Can we move the last sentence here (The Loki stack consists of the following components:) down below the graphic? Now that I can see the website preview, not having the lead in right before the bulleted list looks odd.

JStickler · 2025-03-11T15:28:45Z

docs/sources/get-started/quick-start.md

+With the Loki stack running, you can now verify each component is up and running:
+
+* **Alloy**: Open a browser and navigate to [http://localhost:12345/graph](http://localhost:12345/graph). You should see the Alloy UI.
+* **Grafana**: Open a browser and navigate to [http://localhost:3000](http://localhost:3000). You should see the Grafana home page.
+* **Loki**: Open a browser and navigate to [http://localhost:3100/metrics](http://localhost:3100/metrics). You should see the Loki metrics page.


Check my spacing on the bullets in the preview. I think I've got the indentation correct.

Suggested change

With the Loki stack running, you can now verify each component is up and running:

* **Alloy**: Open a browser and navigate to [http://localhost:12345/graph](http://localhost:12345/graph). You should see the Alloy UI.

* **Grafana**: Open a browser and navigate to [http://localhost:3000](http://localhost:3000). You should see the Grafana home page.

* **Loki**: Open a browser and navigate to [http://localhost:3100/metrics](http://localhost:3100/metrics). You should see the Loki metrics page.

1. With the Loki stack running, you can now verify each component is up and running:

* **Alloy**: Open a browser and navigate to [http://localhost:12345/graph](http://localhost:12345/graph). You should see the Alloy UI.

* **Grafana**: Open a browser and navigate to [http://localhost:3000](http://localhost:3000). You should see the Grafana home page.

* **Loki**: Open a browser and navigate to [http://localhost:3100/metrics](http://localhost:3100/metrics). You should see the Loki metrics page.

JStickler · 2025-03-11T15:34:00Z

docs/sources/get-started/quick-start.md


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

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

-## View your logs in Grafana
+Since Grafana Alloy is configured to tail logs from all Docker containers, Loki should already be receiving logs. The best place to verify log collection is using the Grafana Logs Drilldown feature. To do this, navigate to [http://localhost:3000/a/grafana-lokiexplore-app](http://localhost:3000/a/grafana-lokiexplore-app). You should see the Grafana Logs Drilldown page.


I'm getting a page not found error when I try to navigate to http://localhost:3000/a/grafana-lokiexplore-app. Do we need to update the docker image to a version with the name change?

JStickler · 2025-03-11T15:35:18Z

docs/sources/get-started/quick-start.md


-   You can access the Grafana cluster by browsing to [http://localhost:3000](http://localhost:3000).
+We will not cover the rest of the Grafana Logs Drilldown features in this quickstart guide. For more information on how to use the Grafana Logs Drilldown feature, see [the getting started page](https://grafana.com/docs/grafana/latest/explore/simplified-exploration/logs/get-started/).


Just to clarify, since we're already on a "getting started" page.

Suggested change

We will not cover the rest of the Grafana Logs Drilldown features in this quickstart guide. For more information on how to use the Grafana Logs Drilldown feature, see [the getting started page](https://grafana.com/docs/grafana/latest/explore/simplified-exploration/logs/get-started/).

We will not cover the rest of the Grafana Logs Drilldown features in this quickstart guide. For more information on how to use the Grafana Logs Drilldown feature, see [the Logs Drilldown getting started page](https://grafana.com/docs/grafana/latest/explore/simplified-exploration/logs/get-started/).

JStickler · 2025-03-11T15:52:22Z

docs/sources/get-started/quick-start.md

+
+     Once the command completes, you should see a similar output:
+
+     ```console


Looks like this needs to be updated? I have five less containers than the sample output shown.

My output was :
✔ Volume "greenhouse_pgdata" Created 0.0s
✔ Container greenhouse-websocket_service-1 Started 0.4s
✔ Container greenhouse-db-1 Started 0.4s
✔ Container greenhouse-user_service-1 Started 0.6s
✔ Container greenhouse-plant_service-1 Started 0.6s
✔ Container greenhouse-bug_service-1 Started 0.6s
✔ Container greenhouse-simulation_service-1 Started 0.8s
✔ Container greenhouse-main_app-1 Started 1.0s

JStickler · 2025-03-11T16:21:48Z

docs/sources/get-started/quick-start.md


-## Loki data source in Grafana
+In this view you can see the components of the Alloy configuration file and how they are connected:
+* **discovery.docker**: This component queries the metadata of the docker enviroment via the docker socket and discovers new containers, aswell as providing metdata about the containers.


Suggested change

* **discovery.docker**: This component queries the metadata of the docker enviroment via the docker socket and discovers new containers, aswell as providing metdata about the containers.

* **discovery.docker**: This component queries the metadata of the docker environment via the docker socket and discovers new containers, as well as providing metadata about the containers.

JStickler · 2025-03-11T16:23:44Z

docs/sources/get-started/quick-start.md

-In this example, the Loki data source is already configured in Grafana. This can be seen within the `docker-compose.yaml` file:
+### View Logs in realtime
+
+Grafana Alloy provides inbuilt realtime log viewer. This allows you to view current log entries and how they are being transformed via specific components of the pipeline. 


Suggested change

Grafana Alloy provides inbuilt realtime log viewer. This allows you to view current log entries and how they are being transformed via specific components of the pipeline.

Grafana Alloy provides a built-in real time log viewer. This allows you to view current log entries and how they are being transformed via specific components of the pipeline.

JStickler · 2025-03-11T16:53:57Z

docs/sources/get-started/quick-start.md

+  retention_enabled: true
+```
+To summarize the configuration file:
+* **auth_enabled**: This is set to false, meaning Loki does not need a [tenant ID](https://grafana.com/docs/loki/<LOKI_VERSION>/operations/multi-tenancy/) for ingest or query.


Do we want to call out that auth_enabled: true in the Loki Helm chart so that people don't think they should be running with this setting in production?

JStickler · 2025-03-11T16:55:32Z

docs/sources/get-started/quick-start.md

+* **auth_enabled**: This is set to false, meaning Loki does not need a [tenant ID](https://grafana.com/docs/loki/<LOKI_VERSION>/operations/multi-tenancy/) for ingest or query.
+* **server**: Defines the ports Loki listens on, the log level, and the maximum number of concurrent gRPC streams.
+* **common**:  Defines the common configuration for Loki. This includes the instance address, storage configuration, replication factor, and ring configuration.
+* **query_range**: This is defined to tell Loki to use inbuilt caching for query results. In production environments of Loki this is handled by a seperate cache service such as memcached.


Suggested change

* **query_range**: This is defined to tell Loki to use inbuilt caching for query results. In production environments of Loki this is handled by a seperate cache service such as memcached.

* **query_range**: This is configured to tell Loki to use inbuilt caching for query results. In production environments of Loki this is handled by a separate cache service such as memcached.

JStickler · 2025-03-11T17:12:55Z

docs/sources/get-started/quick-start.md

 Head back to where you started from to continue with the Loki documentation: [Loki documentation](https://grafana.com/docs/loki/latest/get-started/quick-start/).
 {{< /docs/ignore >}}

+You have completed the Loki Quickstart demo. So where to go next? Here are a few suggestions:
+* **Deploy:** Loki can be deployed in multiple ways. For production usecases we recommend deploying Loki via the [Helm chart](https://grafana.com/docs/loki/<LOKI_VERSION>/setup/install/helm/).
+* **Send Logs:** In this example we used Grafana Alloy to collect and send logs to Loki. However there are many other methods you can use depending upon your needs. For more information see [send data](https://grafana.com/docs/loki/next/send-data/).


Suggested change

* **Send Logs:** In this example we used Grafana Alloy to collect and send logs to Loki. However there are many other methods you can use depending upon your needs. For more information see [send data](https://grafana.com/docs/loki/next/send-data/).

* **Send Logs:** In this example we used Grafana Alloy to collect and send logs to Loki. However there are many other methods you can use depending upon your needs. For more information see [send data](https://grafana.com/docs/loki/<LOKI_VERSION>/send-data/).

Jayclifford345 added 5 commits February 21, 2025 17:52

draft

180613d

draft

74cbe6a

added killercoda

9756db8

fixed grammar

3a8a664

fixed naming

52b1f13

Jayclifford345 requested a review from a team as a code owner February 28, 2025 10:30

pull-request-size bot added the size/XL label Feb 28, 2025

github-actions bot added the type/docs Issues related to technical documentation; the Docs Squad uses this label across many repositories label Feb 28, 2025

Jayclifford345 and others added 3 commits February 28, 2025 10:56

Merge branch 'main' into getting-started-rewrite

b0f0688

fixed working, grammar, spelling

9184863

Merge branch 'main' into getting-started-rewrite

bbb46a5

Jayclifford345 requested a review from JStickler March 3, 2025 12:11

Merge branch 'main' into getting-started-rewrite

e4e077c

JStickler added 2 commits March 4, 2025 12:13

Merge branch 'main' into getting-started-rewrite

2453458

Merge branch 'main' into getting-started-rewrite

3a42c6d

JStickler reviewed Mar 6, 2025

View reviewed changes

Jayclifford345 and others added 2 commits March 10, 2025 09:47

Apply suggestions from code review

eb7318a

Co-authored-by: J Stickler <[email protected]> Signed-off-by: Jay Clifford <[email protected]>

Merge branch 'main' into getting-started-rewrite

9731c69

Jayclifford345 requested a review from JStickler March 10, 2025 09:54

JStickler reviewed Mar 11, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Getting started rewrite #16497

docs: Getting started rewrite #16497

Jayclifford345 commented Feb 28, 2025 •

edited

Loading

github-actions bot commented Feb 28, 2025 •

edited

Loading

Jayclifford345 commented Mar 4, 2025

JStickler left a comment

Jayclifford345 commented Mar 10, 2025

JStickler left a comment

JStickler Mar 11, 2025

JStickler Mar 11, 2025

JStickler Mar 11, 2025

JStickler Mar 11, 2025

JStickler Mar 11, 2025

JStickler Mar 11, 2025

JStickler Mar 11, 2025

JStickler Mar 11, 2025

JStickler Mar 11, 2025

JStickler Mar 11, 2025


		You can access the Grafana cluster by browsing to [http://localhost:3000](http://localhost:3000).
		We will not cover the rest of the Grafana Logs Drilldown features in this quickstart guide. For more information on how to use the Grafana Logs Drilldown feature, see [the getting started page](https://grafana.com/docs/grafana/latest/explore/simplified-exploration/logs/get-started/).


		Once the command completes, you should see a similar output:

		```console

	* discovery.docker: This component queries the metadata of the docker enviroment via the docker socket and discovers new containers, aswell as providing metdata about the containers.
	* discovery.docker: This component queries the metadata of the docker environment via the docker socket and discovers new containers, as well as providing metadata about the containers.

	Grafana Alloy provides inbuilt realtime log viewer. This allows you to view current log entries and how they are being transformed via specific components of the pipeline.
	Grafana Alloy provides a built-in real time log viewer. This allows you to view current log entries and how they are being transformed via specific components of the pipeline.

	* query_range: This is defined to tell Loki to use inbuilt caching for query results. In production environments of Loki this is handled by a seperate cache service such as memcached.
	* query_range: This is configured to tell Loki to use inbuilt caching for query results. In production environments of Loki this is handled by a separate cache service such as memcached.

	* Send Logs: In this example we used Grafana Alloy to collect and send logs to Loki. However there are many other methods you can use depending upon your needs. For more information see [send data](https://grafana.com/docs/loki/next/send-data/).
	* Send Logs: In this example we used Grafana Alloy to collect and send logs to Loki. However there are many other methods you can use depending upon your needs. For more information see [send data](https://grafana.com/docs/loki/<LOKI_VERSION>/send-data/).

docs: Getting started rewrite #16497

Are you sure you want to change the base?

docs: Getting started rewrite #16497

Conversation

Jayclifford345 commented Feb 28, 2025 • edited Loading

github-actions bot commented Feb 28, 2025 • edited Loading

Jayclifford345 commented Mar 4, 2025

JStickler left a comment

Choose a reason for hiding this comment

Jayclifford345 commented Mar 10, 2025

JStickler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Jayclifford345 commented Feb 28, 2025 •

edited

Loading

github-actions bot commented Feb 28, 2025 •

edited

Loading