1<p align="center"><img src="docs/sources/logo_and_name.png" alt="Loki Logo"></p> 2 3<a href="https://drone.grafana.net/grafana/loki"><img src="https://drone.grafana.net/api/badges/grafana/loki/status.svg" alt="Drone CI" /></a> 4<a href="https://circleci.com/gh/grafana/loki/tree/master"><img src="https://circleci.com/gh/grafana/loki.svg?style=shield&circle-token=618193e5787b2951c1ea3352ad5f254f4f52313d" alt="CircleCI" /></a> 5<a href="https://goreportcard.com/report/github.com/grafana/loki"><img src="https://goreportcard.com/badge/github.com/grafana/loki" alt="Go Report Card" /></a> 6<a href="https://slack.grafana.com/"><img src="https://img.shields.io/badge/join%20slack-%23loki-brightgreen.svg" alt="Slack" /></a> 7[](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:loki) 8 9# Loki: like Prometheus, but for logs. 10 11Loki is a horizontally-scalable, highly-available, multi-tenant log aggregation system inspired by [Prometheus](https://prometheus.io/). 12It is designed to be very cost effective and easy to operate. 13It does not index the contents of the logs, but rather a set of labels for each log stream. 14 15Compared to other log aggregation systems, Loki: 16 17- does not do full text indexing on logs. By storing compressed, unstructured logs and only indexing metadata, Loki is simpler to operate and cheaper to run. 18- indexes and groups log streams using the same labels you’re already using with Prometheus, enabling you to seamlessly switch between metrics and logs using the same labels that you’re already using with Prometheus. 19- is an especially good fit for storing [Kubernetes](https://kubernetes.io/) Pod logs. Metadata such as Pod labels is automatically scraped and indexed. 20- has native support in Grafana (needs Grafana v6.0). 21 22A Loki-based logging stack consists of 3 components: 23 24- `promtail` is the agent, responsible for gathering logs and sending them to Loki. 25- `loki` is the main server, responsible for storing logs and processing queries. 26- [Grafana](https://github.com/grafana/grafana) for querying and displaying the logs. 27 28Loki is like Prometheus, but for logs: we prefer a multidimensional label-based approach to indexing, and want a single-binary, easy to operate system with no dependencies. 29Loki differs from Prometheus by focusing on logs instead of metrics, and delivering logs via push, instead of pull. 30 31## Getting started 32 33* [Installing Loki](https://grafana.com/docs/loki/latest/installation/) 34* [Installing Promtail](https://grafana.com/docs/loki/latest/clients/promtail/installation/) 35* [Getting Started](https://grafana.com/docs/loki/latest/getting-started/) 36 37## Upgrading 38 39* [Upgrading Loki](https://grafana.com/docs/loki/latest/upgrading/) 40 41## Documentation 42 43* [Latest release](https://grafana.com/docs/loki/latest/) 44* [Upcoming release](https://grafana.com/docs/loki/next/), at the tip of the main branch 45 46Commonly used sections: 47 48- [API documentation](https://grafana.com/docs/loki/latest/api/) for getting logs into Loki. 49- [Labels](https://grafana.com/docs/loki/latest/getting-started/labels/) 50- [Operations](https://grafana.com/docs/loki/latest/operations/) 51- [Promtail](https://grafana.com/docs/loki/latest/clients/promtail/) is an agent which tails log files and pushes them to Loki. 52- [Pipelines](https://grafana.com/docs/loki/latest/clients/promtail/pipelines/) details the log processing pipeline. 53- [Docker Driver Client](https://grafana.com/docs/loki/latest/clients/docker-driver/) is a Docker plugin to send logs directly to Loki from Docker containers. 54- [LogCLI](https://grafana.com/docs/loki/latest/getting-started/logcli/) provides a command-line interface for querying logs. 55- [Loki Canary](https://grafana.com/docs/loki/latest/operations/loki-canary/) monitors your Loki installation for missing logs. 56- [Troubleshooting](https://grafana.com/docs/loki/latest/getting-started/troubleshooting/) presents help dealing with error messages. 57- [Loki in Grafana](https://grafana.com/docs/loki/latest/getting-started/grafana/) describes how to set up a Loki datasource in Grafana. 58 59## Getting Help 60 61If you have any questions or feedback regarding Loki: 62 63- Search existing thread in the Grafana Labs community forum for Loki: [https://community.grafana.com](https://community.grafana.com/c/grafana-loki/) 64- Ask a question on the Loki Slack channel. To invite yourself to the Grafana Slack, visit [https://slack.grafana.com/](https://slack.grafana.com/) and join the #loki channel. 65- [File an issue](https://github.com/grafana/loki/issues/new) for bugs, issues and feature suggestions. 66- Send an email to [lokiproject@googlegroups.com](mailto:lokiproject@googlegroups.com), or use the [web interface](https://groups.google.com/forum/#!forum/lokiproject). 67- UI issues should be filed directly in [Grafana](https://github.com/grafana/grafana/issues/new). 68 69Your feedback is always welcome. 70 71## Further Reading 72 73- The original [design doc](https://docs.google.com/document/d/11tjK_lvp1-SVsFZjgOTr1vV3-q6vBAsZYIQ5ZeYBkyM/view) for Loki is a good source for discussion of the motivation and design decisions. 74- Callum Styan's March 2019 DevOpsDays Vancouver talk "[Grafana Loki: Log Aggregation for Incident Investigations][devopsdays19-talk]". 75- Grafana Labs blog post "[How We Designed Loki to Work Easily Both as Microservices and as Monoliths][architecture-blog]". 76- Tom Wilkie's early-2019 CNCF Paris/FOSDEM talk "[Grafana Loki: like Prometheus, but for logs][fosdem19-talk]" ([slides][fosdem19-slides], [video][fosdem19-video]). 77- David Kaltschmidt's KubeCon 2018 talk "[On the OSS Path to Full Observability with Grafana][kccna18-event]" ([slides][kccna18-slides], [video][kccna18-video]) on how Loki fits into a cloud-native environment. 78- Goutham Veeramachaneni's blog post "[Loki: Prometheus-inspired, open source logging for cloud natives](https://grafana.com/blog/2018/12/12/loki-prometheus-inspired-open-source-logging-for-cloud-natives/)" on details of the Loki architecture. 79- David Kaltschmidt's blog post "[Closer look at Grafana's user interface for Loki](https://grafana.com/blog/2019/01/02/closer-look-at-grafanas-user-interface-for-loki/)" on the ideas that went into the logging user interface. 80 81[devopsdays19-talk]: https://grafana.com/blog/2019/05/06/how-loki-correlates-metrics-and-logs-and-saves-you-money/ 82[architecture-blog]: https://grafana.com/blog/2019/04/15/how-we-designed-loki-to-work-easily-both-as-microservices-and-as-monoliths/ 83[fosdem19-talk]: https://fosdem.org/2019/schedule/event/loki_prometheus_for_logs/ 84[fosdem19-slides]: https://speakerdeck.com/grafana/grafana-loki-like-prometheus-but-for-logs 85[fosdem19-video]: https://mirror.as35701.net/video.fosdem.org/2019/UB2.252A/loki_prometheus_for_logs.mp4 86[kccna18-event]: https://kccna18.sched.com/event/GrXC/on-the-oss-path-to-full-observability-with-grafana-david-kaltschmidt-grafana-labs 87[kccna18-slides]: https://speakerdeck.com/davkal/on-the-path-to-full-observability-with-oss-and-launch-of-loki 88[kccna18-video]: https://www.youtube.com/watch?v=U7C5SpRtK74&list=PLj6h78yzYM2PZf9eA7bhWnIh_mK1vyOfU&index=346 89 90## Contributing 91 92Refer to [CONTRIBUTING.md](CONTRIBUTING.md) 93 94### Building from source 95 96Loki can be run in a single host, no-dependencies mode using the following commands. 97 98You need `go`, we recommend using the version found in [our build Dockerfile](https://github.com/grafana/loki/blob/master/loki-build-image/Dockerfile) 99 100```bash 101 102$ go get github.com/grafana/loki 103$ cd $GOPATH/src/github.com/grafana/loki # GOPATH is $HOME/go by default. 104 105$ go build ./cmd/loki 106$ ./loki -config.file=./cmd/loki/loki-local-config.yaml 107... 108``` 109 110To build Promtail on non-Linux platforms, use the following command: 111 112```bash 113$ go build ./clients/cmd/promtail 114``` 115 116On Linux, Promtail requires the systemd headers to be installed for 117Journal support. 118 119With Journal support on Ubuntu, run with the following commands: 120 121```bash 122$ sudo apt install -y libsystemd-dev 123$ go build ./clients/cmd/promtail 124``` 125 126With Journal support on CentOS, run with the following commands: 127 128```bash 129$ sudo yum install -y systemd-devel 130$ go build ./clients/cmd/promtail 131``` 132 133Otherwise, to build Promtail without Journal support, run `go build` 134with CGO disabled: 135 136```bash 137$ CGO_ENABLED=0 go build ./clients/cmd/promtail 138``` 139 140## License 141 142Grafana Loki is distributed under [AGPL-3.0-only](LICENSE). For Apache-2.0 exceptions, see [LICENSING.md](LICENSING.md). 143
){kind=link}