Add docs, changelog and upgrade guide

Signed-off-by: Kaviraj <kavirajkanagaraj@gmail.com>

CHANGELOG.md

@@ -5,6 +5,7 @@
 #### Loki
 
 ##### Enhancements
+* [7063](https://github.com/grafana/loki/pull/7063) **kavirajk**: Add additional `push` mode to Loki canary that can directly push logs to given Loki URL.
 * [6983](https://github.com/grafana/loki/pull/6983) **slim-bean**: `__timestamp__` and `__line__` are now available in the logql `label_format` query stage.
 * [6821](https://github.com/grafana/loki/pull/6821) **kavirajk**: Introduce new cache type `embedded-cache` which is an in-process cache system that runs loki without the need for an external cache (like memcached, redis, etc). It can be run in two modes `distributed: false` (default, and same as old `fifocache`) and `distributed: true` which runs cache in distributed fashion sharding keys across peers if Loki is run in microservices or SSD mode.
 * [6691](https://github.com/grafana/loki/pull/6691) **dannykopping**: Update production-ready Loki cluster in docker-compose

cmd/loki-canary/main.go

@@ -41,7 +41,7 @@ func main() {
 	sValue := flag.String("streamvalue", "stdout", "The unique stream value for this instance of loki-canary to use in the log selector")
 	port := flag.Int("port", 3500, "Port which loki-canary should expose metrics")
 	addr := flag.String("addr", "", "The Loki server URL:Port, e.g. loki:3100")
-	push := flag.Bool("push", false, "Push the logs to given Loki address inaddition to writing to stdout")
+	push := flag.Bool("push", false, "Push the logs directly to given Loki address")
 	useTLS := flag.Bool("tls", false, "Does the loki connection use TLS?")
 	certFile := flag.String("cert-file", "", "Client PEM encoded X.509 certificate for optional use with TLS connection to Loki")
 	keyFile := flag.String("key-file", "", "Client PEM encoded X.509 key for optional use with TLS connection to Loki")

docs/sources/operations/loki-canary.md

@@ -328,13 +328,15 @@ All options:
   -out-of-order-percentage int
       	Percentage (0-100) of log entries that should be sent out of order
   -pass string
-        Loki password
+        Loki password. This credential should have both read and write permissions to Loki endpoints
   -port int
         Port which Loki Canary should expose metrics (default 3500)
   -pruneinterval duration
         Frequency to check sent versus received logs, and also the frequency at which queries
         for missing logs will be dispatched to Loki, and the frequency spot check queries are run
         (default 1m0s)
+  -push
+	    Push the logs directly to given Loki address
   -query-timeout duration
         How long to wait for a query response from Loki (default 10s)
   -size int

docs/sources/upgrading/_index.md

@@ -33,6 +33,10 @@ The output is incredibly verbose as it shows the entire internal config struct u
 
 ### Loki
 
+### Loki Canary Permission
+We introduced new `push` mode to [Loki canary](https://grafana.com/docs/loki/latest/operations/loki-canary/), that can push logs generated by Loki canary directly to given Loki URL (previously it just writes to local file and you need some agent like promtail to scrape and push it to Loki).
+So if you run Loki behind some proxy with different authorization policies to read and write to Loki, then auth credentials we pass to Loki canary now needs to have both `READ` and `WRITE` permissions.
+
 ### Engine query timeout is deprecated
 
 Previously, we had two configurations to define a query timeout: `engine.timeout` and `querier.query-timeout`.

pkg/canary/writer/push.go

@@ -22,8 +22,6 @@ import (
 	"github.com/prometheus/common/model"
 )
 
-var p io.Writer = &Push{}
-
 const (
 	defaultContentType         = "application/x-protobuf"
 	defaultMaxReponseBufferLen = 1024
@@ -55,6 +53,7 @@ type Push struct {
 	labelName, labelValue, streamName, streamValue string
 }
 
+// NewPush creates an instance of `Push` which writes logs directly to given `lokiAddr`
 func NewPush(
 	lokiAddr, tenantID string,
 	timeout time.Duration,
@@ -109,7 +108,7 @@ func NewPush(
 	}, nil
 }
 
-// Write implements the io.Writer. Needed to inject it as dependency for canary.
+// Write implements the io.Writer.
 func (p *Push) Write(payload []byte) (int, error) {
 	ctx, cancel := context.WithTimeout(context.Background(), p.httpClient.Timeout)
 	defer cancel()