From c20c489cf6d29adfc6fa7d0165ad6f6660c9cd92 Mon Sep 17 00:00:00 2001
From: Robert Fratto <robert.fratto@grafana.com>
Date: Tue, 3 Sep 2019 14:18:53 -0400
Subject: [PATCH] docs: add README.md to every folder
---
docs/README.md | 4 ++--
docs/logentry/README.md | 5 +++++
docs/loki/{overview.md => README.md} | 6 +++++-
docs/promtail/{overview.md => README.md} | 4 ++++
4 files changed, 16 insertions(+), 3 deletions(-)
create mode 100644 docs/logentry/README.md
rename docs/loki/{overview.md => README.md} (98%)
rename docs/promtail/{overview.md => README.md} (99%)
diff --git a/docs/README.md b/docs/README.md
index 3e800580..82307bac 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,13 +9,13 @@ instead of full-text indexing them, related logs are grouped using the same
labels as in Prometheus. This is much more efficient and scales better.
## Components
-- **[Loki](loki/overview.md)**: The main server component is called Loki. It is
+- **[Loki](loki/README.md)**: The main server component is called Loki. It is
responsible for permanently storing the logs it is being shipped and it
executes the LogQL
queries from clients.
Loki shares its high-level architecture with Cortex, a highly scalable
Prometheus backend.
-- **[Promtail](promtail/overview.md)**: To ship logs to a central place, an
+- **[Promtail](promtail/README.md)**: To ship logs to a central place, an
agent is required. Promtail
is deployed to every node that should be monitored and sends the logs to Loki.
It also does important task of pre-processing the log lines, including
diff --git a/docs/logentry/README.md b/docs/logentry/README.md
new file mode 100644
index 00000000..e9e1f159
--- /dev/null
+++ b/docs/logentry/README.md
@@ -0,0 +1,5 @@
+# logentry
+
+Both the Docker Driver and Promtail support transformations on received log
+entries to control what data is sent to Loki. Please see the documentation
+on how to [process log lines](processing-log-lines.md) for more information.
diff --git a/docs/loki/overview.md b/docs/loki/README.md
similarity index 98%
rename from docs/loki/overview.md
rename to docs/loki/README.md
index 8b827979..99b3e43e 100644
--- a/docs/loki/overview.md
+++ b/docs/loki/README.md
@@ -5,11 +5,13 @@ storing the ingested log lines, as well as executing the queries against its
persistent store to analyze the contents.
## Architecture
+
Loki mainly consists of three and a half individual services that achieve this
in common. The high level architecture is based on Cortex, most of their documentation
usually applies to Loki as well.
### Distributor
+
The distributor can be considered the "first stop" for the log lines ingested by
the agents (e.g. Promtail).
@@ -23,6 +25,7 @@ docs](https://github.com/cortexproject/cortex/blob/master/docs/architecture.md#d
for details on the internals.
### Ingester
+
The ingester service is responsible for de-duplicating and persisting the data
to long-term storage backends (DynamoDB, S3, Cassandra, etc.).
@@ -39,7 +42,7 @@ Loki is not database, so it needs some place to persist the ingested log lines
to, for a longer period of time.
The chunk store is not really a service of Loki in the traditional way, but
-rather some storage backend Loki uses.
+rather some storage backend Loki uses.
It consists of a key-value (KV) store for the actual **chunk data** and an
**index store** to keep track of them. Refer to [Storage](storage.md) for details.
@@ -49,6 +52,7 @@ docs](https://github.com/cortexproject/cortex/blob/master/docs/architecture.md#c
also have good information about this.
### Querier
+
The Querier executes the LogQL queries from clients such as Grafana and LogCLI.
It fetches its data directly from the [Chunk store](#chunk-store) and the
diff --git a/docs/promtail/overview.md b/docs/promtail/README.md
similarity index 99%
rename from docs/promtail/overview.md
rename to docs/promtail/README.md
index e24f49ad..f30a8e2f 100644
--- a/docs/promtail/overview.md
+++ b/docs/promtail/README.md
@@ -1,4 +1,5 @@
# Overview
+
Promtail is an agent which ships the content of local log files to Loki. It is
usually deployed to every machine that has applications needed to be monitored.
@@ -6,6 +7,7 @@ It primarily **discovers** targets, attaches **labels** to log streams and
**pushes** them to the Loki instance.
### Discovery
+
Before Promtail is able to ship anything to Loki, it needs to find about its
environment. This specifically means discovering applications emitting log lines
that need to be monitored.
@@ -24,6 +26,7 @@ and the final metadata attached to the log line. Refer to the
[configuration](configuration.md) for more details.
### Labeling and Parsing
+
During service discovery, metadata is determined (pod name, filename, etc.) that
may be attached to the log line as a label for easier identification afterwards.
Using `relabel_configs`, those discovered labels can be mutated into the form
@@ -36,6 +39,7 @@ correct the timestamp or rewrite the log line entirely. Refer to the [logentry
processing documentation](../logentry/processing-log-lines.md) for more details.
### Shipping
+
Once Promtail is certain about what to ingest and all labels are set correctly,
it starts *tailing* (continuously reading) the log files from the applications.
Once enough data is read into memory, it is flushed in as a batch to Loki.
--
GitLab