From 39af436be3fbbb557bed35e728a704aec99379a0 Mon Sep 17 00:00:00 2001 From: Travis Bischel Date: Tue, 1 Mar 2022 10:21:43 -0700 Subject: [PATCH] docs: add metrics-and-logging.md --- README.md | 1 + docs/README.md | 1 + docs/metrics-and-logging.md | 74 +++++++++++++++++++++++++++++++++++++ 3 files changed, 76 insertions(+) create mode 100644 docs/metrics-and-logging.md diff --git a/README.md b/README.md index 600cd7ef..46e9e332 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,7 @@ Supplementary information can be found in the docs directory: 
 docs
 ├── admin requests — an overview of how to issue admin requests
+├── metrics and logging — a small writeup on how to enable metrics & logging in franz-go, as well as a few thoughts on latency tracking
 ├── package layout — describes the packages in franz-go
 ├── producing and consuming — descriptions of producing & consuming & the guarantees
 └── transactions — a description of transactions and the safety even in a pre-KIP-447 world
diff --git a/docs/README.md b/docs/README.md
index 9b2a70b7..75687017 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,7 @@ Please refer to the directory tree below for what the pages mean!
 
 docs — you are here
 ├── admin requests — an overview of how to issue admin requests
+├── metrics and logging — a small writeup on how to enable metrics & logging in franz-go, as well as a few thoughts on latency tracking
 ├── package layout — describes the packages in franz-go
 ├── producing and consuming — descriptions of producing & consuming & the guarantees
 └── transactions — a description of transactions and the safety even in a pre-KIP-447 world
diff --git a/docs/metrics-and-logging.md b/docs/metrics-and-logging.md
new file mode 100644
index 00000000..4ed2e221
--- /dev/null
+++ b/docs/metrics-and-logging.md
@@ -0,0 +1,74 @@
+Metrics and logging
+===
+
+The `kgo` package supports both metrics and logging through options. By
+default, both are disabled.
+
+## Logging
+
+The [`WithLogger`][1] option can be used to enable internal logging. The
+default [`Logger`][2] interface is small but easy to implement, and there is a
+simple [`BasicLogger`][3] provided that you can use while developing or even in
+production. In production, it is recommended that you use a more "real" logger
+such as [zap][4], and to aid this, the franz-go repo provides a drop-in
+[`kzap`][5]. There also exists a drop-in [`zerolog`][6] [`kzerolog`][7]
+package. If you have another relatively standard logger that would be good to
+provide a drop-in package for, please open an issue and we can add it. It is
+recommended to use an info logging level: if you find that too noisy, please
+open an issue and we can figure out if some logs need to be changed.
+
+[1]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#WithLogger
+[2]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#Logger
+[3]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#BasicLogger
+[4]: https://github.com/uber-go/zap
+[5]: https://pkg.go.dev/github.com/twmb/franz-go/plugin/kzap
+[6]: https://pkg.go.dev/github.com/rs/zerolog
+[7]: https://pkg.go.dev/github.com/twmb/franz-go/plugin/kzerolog
+
+## Metrics
+
+`kgo` takes an unopinionated stance on metris, instead supporting ["hooks"][8]
+that you can provide functions for to implement your own metrics. You can
+provide an interface that hooks into any behavior you wish to monitor and
+provide yourself extremely coarse monitoring or extremely detailed monitoring.
+If there are angles you would like to monitor do not have a hook, please open
+an issue and we can figure out what hook to add where.
+
+Similar to logging, franz-go provides drop-in packages that provide some
+opinion of which metrics may be useful to monitoring: [`kprom`][9] for
+prometheus, and [`kgmetrics`][10] for gmetrics.
+
+[8]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#Hook
+[9]: https://pkg.go.dev/github.com/twmb/franz-go/plugin/kprom
+[10]: https://pkg.go.dev/github.com/twmb/franz-go/plugin/kgmetrics
+
+## Latency: brokers, requests, records
+
+The hooks mentioned just above can be used to glean insight into client <=>
+broker latency, request latency, and per-record consume & produce latency.
+Latencies are not provided by default in the plugin packages within franz-go
+because latencies can easily result in cardinality explosion, and it is
+difficult to know ahead of time which latency bucketing a user is interested
+in.
+
+The `OnBroker` hooks (write, read, e2e) can be used for broker latency. The
+hook also has a function parameter indicating the request key that was written
+or read; this key can be used to track per-request request kind latency. For
+example, if you are interested in produce request latency, you can hook into
+request key 0 and monitor it. Similar thought for fetch, with request key 1.
+
+Per-record latency is more difficult to track. When a record is produced, its
+`Timestamp` field is set. You can use `time.Since(r.Timestamp)` when the
+record's promise is called to track the e2e latency for an _individual_ record.
+Internally, records are produced in batches, so a chunk of records will be
+promised in a row all at once. The per-record latency for all of these is
+likely to be roughly the same; each `time.Since` to track latency is a
+_discrete_ observation: per-record latencies should not be added together in an
+attempt to learn something. For more thoughts on record & batch latency when
+producing, skim [#130][130]. Per-record fetch latency can be measured similarly
+to producing: it is more beneficial to measure fetch request latency, but
+per-record timestamp delta's can be used to glean producer <=> consumer e2e
+latency.
+
+[130]: https://github.com/twmb/franz-go/issues/130
+