| Scott Baker | eee8dd8 | 2019-09-24 12:52:34 -0700 | [diff] [blame] | 1 | # Sarama Cluster |
| 2 | |
| 3 | [](https://godoc.org/github.com/bsm/sarama-cluster) |
| 4 | [](https://travis-ci.org/bsm/sarama-cluster) |
| 5 | [](https://goreportcard.com/report/github.com/bsm/sarama-cluster) |
| 6 | [](https://opensource.org/licenses/MIT) |
| 7 | |
| 8 | Cluster extensions for [Sarama](https://github.com/Shopify/sarama), the Go client library for Apache Kafka 0.9 (and later). |
| 9 | |
| 10 | ## Documentation |
| 11 | |
| 12 | Documentation and example are available via godoc at http://godoc.org/github.com/bsm/sarama-cluster |
| 13 | |
| 14 | ## Examples |
| 15 | |
| 16 | Consumers have two modes of operation. In the default multiplexed mode messages (and errors) of multiple |
| 17 | topics and partitions are all passed to the single channel: |
| 18 | |
| 19 | ```go |
| 20 | package main |
| 21 | |
| 22 | import ( |
| 23 | "fmt" |
| 24 | "log" |
| 25 | "os" |
| 26 | "os/signal" |
| 27 | |
| 28 | cluster "github.com/bsm/sarama-cluster" |
| 29 | ) |
| 30 | |
| 31 | func main() {{ "ExampleConsumer" | code }} |
| 32 | ``` |
| 33 | |
| 34 | Users who require access to individual partitions can use the partitioned mode which exposes access to partition-level |
| 35 | consumers: |
| 36 | |
| 37 | ```go |
| 38 | package main |
| 39 | |
| 40 | import ( |
| 41 | "fmt" |
| 42 | "log" |
| 43 | "os" |
| 44 | "os/signal" |
| 45 | |
| 46 | cluster "github.com/bsm/sarama-cluster" |
| 47 | ) |
| 48 | |
| 49 | func main() {{ "ExampleConsumer_Partitions" | code }} |
| 50 | ``` |
| 51 | |
| 52 | ## Running tests |
| 53 | |
| 54 | You need to install Ginkgo & Gomega to run tests. Please see |
| 55 | http://onsi.github.io/ginkgo for more details. |
| 56 | |
| 57 | To run tests, call: |
| 58 | |
| 59 | $ make test |
| 60 | |
| 61 | ## Troubleshooting |
| 62 | |
| 63 | ### Consumer not receiving any messages? |
| 64 | |
| 65 | By default, sarama's `Config.Consumer.Offsets.Initial` is set to `sarama.OffsetNewest`. This means that in the event that a brand new consumer is created, and it has never committed any offsets to kafka, it will only receive messages starting from the message after the current one that was written. |
| 66 | |
| 67 | If you wish to receive all messages (from the start of all messages in the topic) in the event that a consumer does not have any offsets committed to kafka, you need to set `Config.Consumer.Offsets.Initial` to `sarama.OffsetOldest`. |