blob: 5f63a690a30dc53c90213258a5c0abe1b9982bc2 [file] [log] [blame]
Scott Bakere7144bc2019-10-01 14:16:47 -07001# Sarama Cluster
2
3[![GoDoc](https://godoc.org/github.com/bsm/sarama-cluster?status.svg)](https://godoc.org/github.com/bsm/sarama-cluster)
4[![Build Status](https://travis-ci.org/bsm/sarama-cluster.svg?branch=master)](https://travis-ci.org/bsm/sarama-cluster)
5[![Go Report Card](https://goreportcard.com/badge/github.com/bsm/sarama-cluster)](https://goreportcard.com/report/github.com/bsm/sarama-cluster)
6[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
8Cluster extensions for [Sarama](https://github.com/Shopify/sarama), the Go client library for Apache Kafka 0.9 (and later).
9
10## Documentation
11
12Documentation and example are available via godoc at http://godoc.org/github.com/bsm/sarama-cluster
13
14## Examples
15
16Consumers have two modes of operation. In the default multiplexed mode messages (and errors) of multiple
17topics and partitions are all passed to the single channel:
18
19```go
20package main
21
22import (
23 "fmt"
24 "log"
25 "os"
26 "os/signal"
27
28 cluster "github.com/bsm/sarama-cluster"
29)
30
31func main() {{ "ExampleConsumer" | code }}
32```
33
34Users who require access to individual partitions can use the partitioned mode which exposes access to partition-level
35consumers:
36
37```go
38package main
39
40import (
41 "fmt"
42 "log"
43 "os"
44 "os/signal"
45
46 cluster "github.com/bsm/sarama-cluster"
47)
48
49func main() {{ "ExampleConsumer_Partitions" | code }}
50```
51
52## Running tests
53
54You need to install Ginkgo & Gomega to run tests. Please see
55http://onsi.github.io/ginkgo for more details.
56
57To run tests, call:
58
59 $ make test
60
61## Troubleshooting
62
63### Consumer not receiving any messages?
64
65By 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
67If 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`.