Golang Kafka Integration: Outbox Worker, Producer, Consumer Group E-Commerce
Implementasi lengkap Kafka integration Santekno Shop. Outbox worker yang publish ke Kafka, producer setup dengan sarama, consumer group untuk notification — end-to-end event flow.
Golang Kafka integration dengan outbox pattern adalah tulang punggung arsitektur event-driven Santekno Shop yang belum kita rampungkan. Di Part 2, outbox worker masih berupa stub — event ditulis ke tabel outbox_events tapi tidak pernah benar-benar dipublish ke Kafka. Di artikel ini kita tutup loop tersebut: Kafka producer yang publish event dari outbox, consumer group untuk notification service, dan end-to-end test untuk seluruh event flow.
Kita mulai dari setup topic, publisher dengan idempotent producer, outbox worker berbasis FOR UPDATE SKIP LOCKED, hingga strategi partition key untuk menjaga urutan event.
12.01 Kafka Topics Setup
Langkah pertama adalah membuat semua topic yang dibutuhkan Santekno Shop. Script berikut membuat topic order, payment, dan DLQ dengan 3 partisi masing-masing.
1# Setup Kafka topics untuk Santekno Shop
2# Jalankan setelah kafka ready di docker-compose
3
4KAFKA_BROKER=localhost:9092
5
6# Buat semua topics dengan 3 partitions, replication factor 1 (dev)
7topics=(
8 "santekno.orders.placed"
9 "santekno.orders.confirmed"
10 "santekno.orders.cancelled"
11 "santekno.orders.shipped"
12 "santekno.payments.completed"
13 "santekno.payments.failed"
14 "santekno.notifications.dlq"
15)
16
17for topic in "${topics[@]}"; do
18 kafka-topics --create \
19 --bootstrap-server $KAFKA_BROKER \
20 --topic "$topic" \
21 --partitions 3 \
22 --replication-factor 1 \
23 --if-not-exists
24 echo "✅ Created topic: $topic"
25done
26
27# Verify
28kafka-topics --list --bootstrap-server $KAFKA_BROKER | grep santeknoPemilihan 3 partisi per topic bukan angka acak: ia menentukan batas maksimal jumlah consumer instance yang bisa memproses secara paralel, jadi rencanakan sesuai target throughput sejak awal.
12.02 Kafka Publisher: Interface dan Implementation
Publisher membungkus sarama SyncProducer dengan konfigurasi yang mengutamakan durability dan exactly-once per partisi. Kode berikut menunjukkan implementasi lengkap plus NoOpPublisher untuk development tanpa Kafka.
1// internal/event/kafka/publisher.go
2
3package kafka
4
5import (
6 "context"
7 "encoding/json"
8 "fmt"
9
10 "github.com/IBM/sarama"
11
12 "github.com/santekno/santekno-shop/internal/event"
13)
14
15type Publisher struct {
16 producer sarama.SyncProducer
17}
18
19func NewPublisher(brokers []string) (*Publisher, error) {
20 config := sarama.NewConfig()
21 config.Producer.Return.Successes = true
22 config.Producer.Return.Errors = true
23 config.Producer.RequiredAcks = sarama.WaitForAll // acks from all ISR
24 config.Producer.Retry.Max = 3
25 config.Producer.Compression = sarama.CompressionSnappy
26
27 // Idempotent producer: exactly-once per partition
28 config.Producer.Idempotent = true
29 config.Net.MaxOpenRequests = 1 // required for idempotent
30
31 producer, err := sarama.NewSyncProducer(brokers, config)
32 if err != nil {
33 return nil, fmt.Errorf("kafkaPublisher.New: %w", err)
34 }
35
36 return &Publisher{producer: producer}, nil
37}
38
39func (p *Publisher) Publish(ctx context.Context, e event.Event) error {
40 payload, err := json.Marshal(e.Payload)
41 if err != nil {
42 return fmt.Errorf("kafkaPublisher.Publish: marshal: %w", err)
43 }
44
45 msg := &sarama.ProducerMessage{
46 Topic: e.Topic,
47 Value: sarama.ByteEncoder(payload),
48 }
49
50 // Use event key for partition routing (same key = same partition = ordered)
51 if e.Key != "" {
52 msg.Key = sarama.StringEncoder(e.Key)
53 }
54
55 _, _, err = p.producer.SendMessage(msg)
56 if err != nil {
57 return fmt.Errorf("kafkaPublisher.Publish [%s]: %w", e.Topic, err)
58 }
59
60 return nil
61}
62
63func (p *Publisher) Close() error {
64 return p.producer.Close()
65}
66
67// NoOpPublisher: untuk development tanpa Kafka running
68type NoOpPublisher struct{}
69
70func (p *NoOpPublisher) Publish(_ context.Context, e event.Event) error {
71 fmt.Printf("[EVENT] topic=%s key=%s\n", e.Topic, e.Key)
72 return nil
73}Kombinasi Idempotent = true dan RequiredAcks = WaitForAll adalah kunci: yang pertama mencegah duplikat akibat retry jaringan, yang kedua menjamin data tidak hilang sampai semua replica ISR mengonfirmasi.
12.03 Outbox Worker: Full Implementation
Outbox worker adalah jembatan antara PostgreSQL (ACID) dan Kafka (eventually consistent). Kode berikut mem-poll event yang belum dipublish, mengirimnya ke Kafka, lalu menandainya published.
1// internal/event/outbox/worker.go
2
3package outbox
4
5import (
6 "context"
7 "encoding/json"
8 "fmt"
9 "time"
10
11 "github.com/jackc/pgx/v5/pgxpool"
12 "github.com/santekno/santekno-shop/internal/event"
13)
14
15type Worker struct {
16 db *pgxpool.Pool
17 publisher event.Publisher
18 batchSize int
19 interval time.Duration
20 stopCh chan struct{}
21}
22
23func NewWorker(db *pgxpool.Pool, publisher event.Publisher) *Worker {
24 return &Worker{
25 db: db,
26 publisher: publisher,
27 batchSize: 100,
28 interval: 5 * time.Second,
29 stopCh: make(chan struct{}),
30 }
31}
32
33func (w *Worker) Run(ctx context.Context) {
34 ticker := time.NewTicker(w.interval)
35 defer ticker.Stop()
36
37 fmt.Println("Outbox worker started")
38 for {
39 select {
40 case <-ctx.Done():
41 fmt.Println("Outbox worker stopped (context)")
42 return
43 case <-w.stopCh:
44 fmt.Println("Outbox worker stopped (signal)")
45 return
46 case <-ticker.C:
47 if err := w.processOnce(ctx); err != nil {
48 fmt.Printf("outbox worker error: %v\n", err)
49 }
50 }
51 }
52}
53
54func (w *Worker) Stop() {
55 close(w.stopCh)
56}
57
58// processOnce: ambil batch events yang belum published, publish ke Kafka
59func (w *Worker) processOnce(ctx context.Context) error {
60 // Fetch unpublished events (SKIP LOCKED untuk multiple worker instances)
61 rows, err := w.db.Query(ctx,
62 `SELECT id, topic, payload, event_type
63 FROM outbox_events
64 WHERE published = false
65 ORDER BY created_at ASC
66 LIMIT $1
67 FOR UPDATE SKIP LOCKED`, // prevent duplicate processing
68 w.batchSize,
69 )
70 if err != nil {
71 return fmt.Errorf("outbox.processOnce: fetch: %w", err)
72 }
73 defer rows.Close()
74
75 type outboxRow struct {
76 ID string
77 Topic string
78 Payload json.RawMessage
79 EventType string
80 }
81
82 var events []outboxRow
83 for rows.Next() {
84 var row outboxRow
85 if err := rows.Scan(&row.ID, &row.Topic, &row.Payload, &row.EventType); err != nil {
86 return fmt.Errorf("outbox.processOnce: scan: %w", err)
87 }
88 events = append(events, row)
89 }
90 rows.Close()
91
92 if len(events) == 0 {
93 return nil // nothing to do
94 }
95
96 // Publish each event
97 published := 0
98 for _, e := range events {
99 if err := w.publisher.Publish(ctx, event.Event{
100 Topic: e.Topic,
101 Key: extractKey(e.Payload), // extract order_id or user_id
102 Payload: e.Payload,
103 }); err != nil {
104 // Log tapi tidak stop — coba event berikutnya
105 fmt.Printf("outbox: publish failed [%s]: %v\n", e.EventType, err)
106 continue
107 }
108
109 // Mark as published
110 if _, err := w.db.Exec(ctx,
111 `UPDATE outbox_events
112 SET published = true, published_at = NOW()
113 WHERE id = $1`,
114 e.ID,
115 ); err != nil {
116 fmt.Printf("outbox: mark published failed [%s]: %v\n", e.ID, err)
117 }
118 published++
119 }
120
121 if published > 0 {
122 fmt.Printf("outbox: published %d/%d events\n", published, len(events))
123 }
124 return nil
125}
126
127// extractKey: extract partition key dari payload JSON
128func extractKey(payload json.RawMessage) string {
129 var m map[string]interface{}
130 if err := json.Unmarshal(payload, &m); err != nil {
131 return ""
132 }
133 for _, key := range []string{"order_id", "user_id", "payment_id"} {
134 if val, ok := m[key].(string); ok && val != "" {
135 return val
136 }
137 }
138 return ""
139}Klausa FOR UPDATE SKIP LOCKED di query fetch inilah yang membuat worker aman dijalankan multi-instance: setiap worker mengunci baris yang diambilnya dan melewati baris yang sudah dikunci worker lain, jadi tidak ada event yang dipublish ganda.
12.04 Consumer Group: Order Event Consumer
Consumer group generik ini memetakan topic ke handler dan menerapkan manual commit. Kode berikut adalah versi reusable dari consumer yang bisa dipakai lintas service.
1// internal/event/kafka/consumer_group.go
2
3package kafka
4
5import (
6 "context"
7 "fmt"
8 "log"
9
10 "github.com/IBM/sarama"
11)
12
13type MessageHandler func(ctx context.Context, topic string, key, value []byte) error
14
15type ConsumerGroup struct {
16 client sarama.ConsumerGroup
17 topics []string
18 handlers map[string]MessageHandler
19}
20
21func NewConsumerGroup(brokers []string, groupID string, handlers map[string]MessageHandler) (*ConsumerGroup, error) {
22 config := sarama.NewConfig()
23 config.Consumer.Group.Rebalance.GroupStrategies = []sarama.BalanceStrategy{
24 sarama.NewBalanceStrategyRoundRobin(),
25 }
26 config.Consumer.Offsets.Initial = sarama.OffsetNewest
27 config.Consumer.Offsets.AutoCommit.Enable = false // manual commit only
28
29 client, err := sarama.NewConsumerGroup(brokers, groupID, config)
30 if err != nil {
31 return nil, fmt.Errorf("kafka.NewConsumerGroup: %w", err)
32 }
33
34 topics := make([]string, 0, len(handlers))
35 for topic := range handlers {
36 topics = append(topics, topic)
37 }
38
39 return &ConsumerGroup{
40 client: client,
41 topics: topics,
42 handlers: handlers,
43 }, nil
44}
45
46func (cg *ConsumerGroup) Run(ctx context.Context) error {
47 handler := &groupHandler{handlers: cg.handlers}
48 for {
49 if err := cg.client.Consume(ctx, cg.topics, handler); err != nil {
50 log.Printf("consumer group error: %v", err)
51 }
52 if ctx.Err() != nil {
53 return ctx.Err()
54 }
55 }
56}
57
58func (cg *ConsumerGroup) Close() error {
59 return cg.client.Close()
60}
61
62type groupHandler struct {
63 handlers map[string]MessageHandler
64}
65
66func (h *groupHandler) Setup(sarama.ConsumerGroupSession) error { return nil }
67func (h *groupHandler) Cleanup(sarama.ConsumerGroupSession) error { return nil }
68
69func (h *groupHandler) ConsumeClaim(
70 session sarama.ConsumerGroupSession,
71 claim sarama.ConsumerGroupClaim,
72) error {
73 for msg := range claim.Messages() {
74 handler, ok := h.handlers[msg.Topic]
75 if !ok {
76 session.MarkMessage(msg, "")
77 continue
78 }
79
80 ctx := context.Background()
81 if err := handler(ctx, msg.Topic, msg.Key, msg.Value); err != nil {
82 // Don't commit — Kafka will redeliver
83 log.Printf("handler error [%s]: %v", msg.Topic, err)
84 continue
85 }
86
87 // Commit only on success
88 session.MarkMessage(msg, "")
89 session.Commit()
90 }
91 return nil
92}Tipe MessageHandler sebagai function signature membuat consumer ini agnostik terhadap domain — service apa pun bisa mendaftarkan handler-nya sendiri tanpa mengubah kode consumer group inti.
12.05 Wiring: Main Server dengan Kafka
Semua komponen dirakit di main server, dengan Kafka opsional lewat flag config. Kode berikut menyatukan publisher, outbox worker, consumer, dan HTTP server dalam satu lifecycle.
1// cmd/server/main.go — update dengan Kafka
2
3func main() {
4 cfg, _ := config.Load()
5 ctx, cancel := context.WithCancel(context.Background())
6 defer cancel()
7
8 // Database
9 pool, _ := pgxpool.New(ctx, cfg.Database.URL)
10 defer pool.Close()
11 rdb := redis.NewClient(&redis.Options{Addr: cfg.Redis.URL})
12 defer rdb.Close()
13
14 // Kafka Publisher
15 var publisher event.Publisher
16 if cfg.Kafka.Enabled {
17 kafkaPublisher, err := kafkaPkg.NewPublisher(cfg.Kafka.Brokers)
18 if err != nil {
19 log.Fatalf("kafka publisher: %v", err)
20 }
21 defer kafkaPublisher.Close()
22 publisher = kafkaPublisher
23 } else {
24 publisher = &event.NoOpPublisher{} // development tanpa Kafka
25 }
26
27 // Build container (semua usecases)
28 container := BuildContainer(cfg, pool, rdb, publisher)
29
30 // Outbox Worker
31 outboxWorker := outbox.NewWorker(pool, publisher)
32 go outboxWorker.Run(ctx)
33
34 // Kafka Consumer (notification service)
35 if cfg.Kafka.Enabled {
36 notifHandlers := buildNotificationHandlers(pool)
37 consumer, _ := kafkaPkg.NewConsumerGroup(
38 cfg.Kafka.Brokers,
39 "santekno-notification",
40 notifHandlers,
41 )
42 defer consumer.Close()
43 go consumer.Run(ctx)
44 }
45
46 // HTTP server
47 e := SetupRouter(container, cfg)
48 go e.Start(":" + cfg.App.Port)
49
50 // Graceful shutdown
51 quit := make(chan os.Signal, 1)
52 signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
53 <-quit
54
55 outboxWorker.Stop()
56 shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second)
57 defer shutdownCancel()
58 e.Shutdown(shutdownCtx)
59 cancel() // stop consumer goroutines
60}Flag cfg.Kafka.Enabled membuat Kafka bisa dinonaktifkan di development dan digantikan NoOpPublisher — developer bisa menjalankan aplikasi tanpa harus menyalakan cluster Kafka lokal.
12.06 Config: Kafka Settings
Konfigurasi Kafka dibaca dari environment variable dengan default yang masuk akal. Kode berikut mendefinisikan KafkaConfig dan cara memuatnya.
1// config/config.go
2
3type KafkaConfig struct {
4 Enabled bool
5 Brokers []string
6 GroupID string
7}
8
9func Load() (*Config, error) {
10 return &Config{
11 // ...
12 Kafka: KafkaConfig{
13 Enabled: getEnvBool("KAFKA_ENABLED", true),
14 Brokers: strings.Split(getEnv("KAFKA_BROKERS", "localhost:9092"), ","),
15 GroupID: getEnv("KAFKA_GROUP_ID", "santekno-notification"),
16 },
17 }, nil
18}
19
20// .env.example
21// KAFKA_ENABLED=true
22// KAFKA_BROKERS=localhost:9092
23// KAFKA_GROUP_ID=santekno-notificationMenyimpan broker dan group ID di environment variable menjaga aplikasi tetap portable antar environment — dari laptop developer sampai cluster production — tanpa mengubah kode.
12.07 End-to-End Test: PlaceOrder → Kafka Event
End-to-end test membuktikan seluruh flow bekerja: order dibuat lewat API, dipublish worker, dan diterima di Kafka. Kode berikut menjalankan skenario tersebut dengan consumer sarama langsung.
1// tests/e2e/order_flow_test.go
2//go:build e2e
3
4package e2e_test
5
6import (
7 "context"
8 "encoding/json"
9 "testing"
10 "time"
11
12 "github.com/IBM/sarama"
13 "github.com/stretchr/testify/assert"
14 "github.com/stretchr/testify/require"
15)
16
17// TestOrderFlow_PlaceOrder_PublishesKafkaEvent:
18// 1. Place an order via HTTP API
19// 2. Wait for outbox worker to publish
20// 3. Verify event received in Kafka
21func TestOrderFlow_PlaceOrder_PublishesKafkaEvent(t *testing.T) {
22 ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
23 defer cancel()
24
25 // Setup Kafka consumer to capture events
26 config := sarama.NewConfig()
27 config.Consumer.Offsets.Initial = sarama.OffsetNewest
28 consumer, err := sarama.NewConsumer([]string{"localhost:9092"}, config)
29 require.NoError(t, err)
30 defer consumer.Close()
31
32 partConsumer, err := consumer.ConsumePartition("santekno.orders.placed", 0, sarama.OffsetNewest)
33 require.NoError(t, err)
34 defer partConsumer.Close()
35
36 // Place order via API (using test helper)
37 orderID := placeTestOrder(t)
38
39 // Wait for outbox worker to publish (max 15 seconds)
40 select {
41 case msg := <-partConsumer.Messages():
42 var payload map[string]interface{}
43 require.NoError(t, json.Unmarshal(msg.Value, &payload))
44
45 assert.Equal(t, orderID, payload["order_id"])
46 assert.NotEmpty(t, payload["user_id"])
47 assert.NotEmpty(t, payload["total_amount_idr"])
48 t.Logf("✅ Event received: order_id=%s", orderID)
49
50 case err := <-partConsumer.Errors():
51 t.Fatalf("consumer error: %v", err)
52
53 case <-ctx.Done():
54 t.Fatal("timeout: event not received within 15 seconds")
55 }
56}
57
58func placeTestOrder(t *testing.T) string {
59 t.Helper()
60 // Login, place order via HTTP, return order_id
61 // (simplified — actual HTTP calls to test server)
62 return "test-order-id-xxx"
63}Test ini memverifikasi kontrak paling penting dari sistem: sebuah order yang dibuat customer benar-benar menghasilkan event di Kafka dalam hitungan detik — sesuatu yang unit test terisolasi tidak bisa buktikan.
12.08 FOR UPDATE SKIP LOCKED: Concurrency Safety
Untuk memahami kenapa FOR UPDATE SKIP LOCKED krusial, mari bandingkan skenario dengan dan tanpanya. Diagram berikut menggambarkan bagaimana dua worker bisa memproses event yang sama tanpa lock.
1MASALAH: multiple outbox worker instances running
2
3Tanpa SKIP LOCKED:
4 Worker A: SELECT WHERE published=false LIMIT 100
5 Worker B: SELECT WHERE published=false LIMIT 100
6 → Keduanya ambil event yang sama!
7 → Duplicate publish ke Kafka
8
9DENGAN FOR UPDATE SKIP LOCKED:
10 Worker A: SELECT ... FOR UPDATE SKIP LOCKED
11 → Lock rows, skip yang sudah di-lock worker lain
12 Worker B: SELECT ... FOR UPDATE SKIP LOCKED
13 → Skip rows yang di-lock Worker A
14 → Ambil rows yang belum di-lock
15
16Result: setiap event hanya diproses satu worker
17Note: Kafka consumer masih harus idempoten (Kafka sendiri bisa redeliver)Perhatikan catatan terakhir: SKIP LOCKED mencegah duplikat di sisi producer, tapi Kafka tetap bisa redeliver di sisi consumer — itulah kenapa idempotency di handler (via event_id dari Artikel 10) tetap wajib.
12.09 Kafka Offset Management
Strategi commit offset menentukan apakah sistem kehilangan pesan saat crash. Kode berikut membandingkan auto-commit yang berbahaya dengan manual commit yang aman.
1// Strategi offset commit yang benar untuk notification service
2
3// WRONG: AutoCommit enabled
4// → Message committed sebelum diproses → message loss kalau crash
5
6config.Consumer.Offsets.AutoCommit.Enable = false
7
8// RIGHT: Manual commit setelah berhasil diproses
9func (h *groupHandler) ConsumeClaim(session sarama.ConsumerGroupSession, claim sarama.ConsumerGroupClaim) error {
10 for msg := range claim.Messages() {
11 if err := h.handlers[msg.Topic](ctx, msg.Topic, msg.Key, msg.Value); err != nil {
12 continue // retry — offset tidak maju
13 }
14 session.MarkMessage(msg, "")
15 session.Commit() // offset maju hanya setelah sukses
16 }
17 return nil
18}
19
20// Consequence: jika process crash setelah publish tapi sebelum commit
21// → Kafka redeliver saat restart
22// → Handler harus idempoten (sudah di-handle oleh event_id di Artikel 10)Dengan manual commit, kontraknya menjadi at-least-once: pesan mungkin diproses lebih dari sekali saat recovery, tapi tidak pernah hilang — trade-off yang tepat untuk notifikasi yang tidak boleh terlewat.
12.10 Dead Letter Queue: Implementation
DLQ menangani pesan yang gagal permanen tanpa memblokir consumer. Kode berikut adalah producer khusus yang mengirim pesan gagal ke topic DLQ lengkap dengan metadata error.
1// internal/event/kafka/dlq_producer.go
2
3package kafka
4
5import (
6 "context"
7 "fmt"
8 "time"
9
10 "github.com/IBM/sarama"
11)
12
13const DLQTopic = "santekno.notifications.dlq"
14
15type DLQProducer struct {
16 producer sarama.SyncProducer
17}
18
19func NewDLQProducer(brokers []string) (*DLQProducer, error) {
20 config := sarama.NewConfig()
21 config.Producer.Return.Successes = true
22 producer, err := sarama.NewSyncProducer(brokers, config)
23 if err != nil {
24 return nil, fmt.Errorf("dlqProducer: %w", err)
25 }
26 return &DLQProducer{producer: producer}, nil
27}
28
29func (p *DLQProducer) SendToDLQ(ctx context.Context, originalTopic string, key, value []byte, err error) {
30 _, _, sendErr := p.producer.SendMessage(&sarama.ProducerMessage{
31 Topic: DLQTopic,
32 Key: sarama.ByteEncoder(key),
33 Value: sarama.ByteEncoder(value),
34 Headers: []sarama.RecordHeader{
35 {Key: []byte("original-topic"), Value: []byte(originalTopic)},
36 {Key: []byte("error"), Value: []byte(err.Error())},
37 {Key: []byte("failed-at"), Value: []byte(time.Now().UTC().Format(time.RFC3339))},
38 },
39 })
40 if sendErr != nil {
41 fmt.Printf("DLQ send failed: %v\n", sendErr)
42 }
43}Menyertakan original-topic, error, dan failed-at di header pesan DLQ memberi tim ops konteks lengkap untuk diagnosis — mereka bisa mengetahui apa yang gagal, kenapa, dan kapan tanpa menebak.
12.11 Partition Key Strategy
Partition key menentukan urutan dan distribusi pesan antar partisi. Panduan berikut merangkum strategi key per jenis topic di Santekno Shop.
1Partition key menentukan partisi mana yang menerima message.
2Messages dengan key yang sama → partisi yang sama → ordered.
3
4Santekno Shop partition key strategy:
5
6santekno.orders.*:
7 Key: order_id
8 Benefit: semua events untuk satu order di partisi yang sama
9 Consumer membaca events secara ordered per order
10
11santekno.payments.*:
12 Key: order_id (bukan payment_id)
13 Benefit: payment events dan order events berkorelasi via order_id
14
15santekno.notifications.*:
16 Key: user_id
17 Benefit: semua notifikasi untuk satu user di partisi yang sama
18 Ordering guarantee per user
19
20Implementation di outbox worker:
21 extractKey(payload) → cari "order_id" dulu, lalu "user_id"Keputusan memakai order_id (bukan payment_id) sebagai key untuk topic payment adalah detail penting: ia menjaga event order dan payment untuk transaksi yang sama tetap berkorelasi di partisi yang sama.
12.12 Monitoring: Consumer Lag
Consumer lag adalah metrik kesehatan paling penting untuk sistem event-driven. Kode berikut menghitung total lag per topic dengan menghubungi Kafka admin API.
1// pkg/kafka/lag_monitor.go
2
3package kafka
4
5import (
6 "context"
7 "fmt"
8 "time"
9
10 "github.com/IBM/sarama"
11)
12
13type LagMonitor struct {
14 brokers []string
15 groupID string
16}
17
18func NewLagMonitor(brokers []string, groupID string) *LagMonitor {
19 return &LagMonitor{brokers: brokers, groupID: groupID}
20}
21
22// CheckLag: return total consumer lag untuk semua topics
23func (m *LagMonitor) CheckLag(ctx context.Context) (map[string]int64, error) {
24 client, err := sarama.NewClient(m.brokers, sarama.NewConfig())
25 if err != nil {
26 return nil, fmt.Errorf("lagMonitor.CheckLag: %w", err)
27 }
28 defer client.Close()
29
30 admin, _ := sarama.NewClusterAdminFromClient(client)
31 defer admin.Close()
32
33 // Get committed offsets per topic/partition
34 groups, _ := admin.ListConsumerGroupOffsets(m.groupID, nil)
35
36 lags := make(map[string]int64)
37 for topic, partitions := range groups.Blocks {
38 for partition, block := range partitions {
39 latest, _ := client.GetOffset(topic, partition, sarama.OffsetNewest)
40 lag := latest - block.Offset
41 if lag < 0 { lag = 0 }
42 lags[topic] += lag
43 }
44 }
45 return lags, nil
46}Lag yang terus membesar berarti consumer tidak sanggup mengejar laju produksi event — sinyal untuk menambah instance atau mengoptimasi handler sebelum notifikasi customer terlambat berjam-jam.
12.13 Retry Policy untuk Failed Events di Outbox
Event yang gagal dipublish perlu di-retry dengan batas dan backoff. SQL berikut memperluas tabel outbox dengan kolom retry dan query polling yang menghormati backoff.
1-- internal/event/outbox/retry.go
2-- Jika publisher gagal, event tetap di outbox (published = false)
3-- Worker akan retry di polling berikutnya (setiap 5 detik)
4-- Untuk events yang terus gagal (e.g., Kafka down > 1 jam):
5-- Tambahkan retry_count dan last_error ke outbox_events table
6
7ALTER TABLE outbox_events
8 ADD COLUMN retry_count INT NOT NULL DEFAULT 0,
9 ADD COLUMN last_error TEXT,
10 ADD COLUMN last_retry_at TIMESTAMPTZ;
11
12-- Query untuk processOnce dengan max retry:
13SELECT id, topic, payload, event_type
14FROM outbox_events
15WHERE published = false
16 AND retry_count < 10 -- max 10 retry
17 AND (last_retry_at IS NULL OR last_retry_at < NOW() - INTERVAL '30 seconds')
18ORDER BY created_at ASC
19LIMIT 100
20FOR UPDATE SKIP LOCKED;
21
22-- Update setelah failed publish:
23UPDATE outbox_events
24SET retry_count = retry_count + 1,
25 last_error = $2,
26 last_retry_at = NOW()
27WHERE id = $1;Batas retry_count < 10 mencegah event beracun di-retry selamanya, sementara filter last_retry_at menerapkan backoff sehingga Kafka yang sedang down tidak dibombardir permintaan setiap 5 detik.
12.14 Kafka Topic Configuration
Topic production butuh setelan retention dan replikasi yang tepat. Perintah berikut mengatur retention 7 hari, minimum in-sync replicas, dan batas ukuran pesan.
1# Production topic configuration
2# Retention: 7 hari (default)
3# Cleanup policy: delete (bukan compact — events bukan log)
4
5kafka-configs --bootstrap-server localhost:9092 \
6 --entity-type topics \
7 --entity-name santekno.orders.placed \
8 --alter \
9 --add-config \
10 retention.ms=604800000,\ # 7 days
11 min.insync.replicas=2,\ # production: butuh 2 replicas
12 max.message.bytes=1048576 # 1MB max message
13
14# Verify
15kafka-configs --bootstrap-server localhost:9092 \
16 --entity-type topics \
17 --entity-name santekno.orders.placed \
18 --describeSetelan min.insync.replicas=2 bekerja sama dengan RequiredAcks=WaitForAll di producer: keduanya harus dikonfigurasi konsisten agar jaminan durability benar-benar tercapai, bukan sekadar di atas kertas.
12.15 Integration Test: Outbox Worker
Integration test memverifikasi worker benar-benar mem-publish dan menandai event published di database. Kode berikut menguji satu siklus proses dengan mock publisher yang menangkap event.
1// internal/event/outbox/worker_integration_test.go
2//go:build integration
3
4func TestOutboxWorker_PublishesToKafka(t *testing.T) {
5 pool := setupDB(t)
6 ctx := context.Background()
7
8 // Insert a test outbox event
9 _, err := pool.Exec(ctx,
10 `INSERT INTO outbox_events (event_type, topic, payload)
11 VALUES ($1, $2, $3)`,
12 "order.placed",
13 "santekno.orders.placed",
14 `{"order_id":"test-123","user_id":"user-456","total_amount_idr":500000}`,
15 )
16 require.NoError(t, err)
17
18 // Setup mock publisher to capture published events
19 published := make(chan event.Event, 10)
20 mockPub := &capturePublisher{ch: published}
21
22 worker := outbox.NewWorker(pool, mockPub)
23
24 // Run one processing cycle
25 err = worker.ProcessOnce(ctx) // expose processOnce for testing
26 require.NoError(t, err)
27
28 // Verify event was published
29 select {
30 case evt := <-published:
31 assert.Equal(t, "santekno.orders.placed", evt.Topic)
32 assert.Contains(t, string(evt.Payload.(json.RawMessage)), "test-123")
33 case <-time.After(2 * time.Second):
34 t.Fatal("event not published")
35 }
36
37 // Verify event marked as published in DB
38 var isPublished bool
39 pool.QueryRow(ctx, "SELECT published FROM outbox_events WHERE event_type = 'order.placed'").Scan(&isPublished)
40 assert.True(t, isPublished)
41}
42
43type capturePublisher struct{ ch chan event.Event }
44func (p *capturePublisher) Publish(_ context.Context, e event.Event) error {
45 p.ch <- e
46 return nil
47}Test ini memverifikasi dua efek sekaligus: event terkirim ke publisher DAN baris di database ditandai published = true — memastikan worker tidak akan mem-publish ulang event yang sama di siklus berikutnya.
12.16 Kafka UI: Development Tool
Kafka UI mempercepat debugging dengan tampilan visual topic, pesan, dan consumer lag. Konfigurasi berikut menambahkan Kafka UI ke docker-compose development.
1# docker-compose.yml — Kafka UI untuk development
2
3kafka-ui:
4 image: provectuslabs/kafka-ui:latest
5 ports:
6 - "8090:8080"
7 environment:
8 KAFKA_CLUSTERS_0_NAME: santekno-local
9 KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:29092
10 KAFKA_CLUSTERS_0_READONLY: "false"
11 depends_on:
12 - kafkaFitur yang tersedia lewat UI ini merangkum alur debugging sehari-hari, dari inspeksi pesan sampai memantau lag. Daftar berikut merinci kegunaannya.
1Fitur Kafka UI yang berguna:
2 → Topics: lihat partisi, retention, messages
3 → Messages: browse messages per topic/partition/offset
4 → Consumer Groups: lihat lag real-time
5 → Produce: test publish message manual
6 → Schema Registry: (opsional, untuk Avro)
7
8Akses: http://localhost:8090Dengan Kafka UI, developer bisa memverifikasi payload pesan dan lag consumer secara visual — jauh lebih cepat daripada mengetik perintah kafka-console-consumer berulang kali saat debugging.
12.17 Event Schema Evolution
Skema event akan berevolusi seiring waktu, dan perubahannya harus dikelola agar tidak memutus consumer lama. Panduan berikut membedakan perubahan yang aman dan yang butuh versioning.
1BACKWARD COMPATIBLE CHANGES (aman):
2 + Add new optional field ke payload
3 → Consumer lama ignore field baru → OK
4
5FORWARD COMPATIBLE CHANGES (perlu versioning):
6 - Remove field dari payload
7 - Change field type
8 → Consumer baru tidak bisa baca event lama
9
10Strategy untuk Santekno Shop:
11 Semua fields di payload: kebijakan "add-only"
12 Jangan pernah remove atau rename field dari event payload
13 Add field baru jika perlu extend
14
15Versioning (Topik 9 — LLMOps):
16 event_type: "order.placed.v2" untuk breaking changes
17 Consumer subscribe ke "order.placed.v1" DAN "order.placed.v2"
18 Setelah semua consumer di-update: deprecated v1Kebijakan “add-only” adalah aturan sederhana yang menghindari 90% masalah kompatibilitas: selama field hanya ditambah dan tidak pernah dihapus atau diubah tipenya, consumer lama tetap bekerja tanpa perubahan.
12.18 Kafka Best Practices
Ada sejumlah praktik yang memisahkan integrasi Kafka yang tahan banting dari yang rapuh. Daftar DO dan DON’T berikut merangkum pelajaran yang sudah kita terapkan di sepanjang artikel ini.
1DO:
2✅ Use idempotent producer (config.Producer.Idempotent = true)
3✅ Set RequiredAcks = WaitForAll untuk durability
4✅ Manual commit hanya setelah processing berhasil
5✅ Use FOR UPDATE SKIP LOCKED di outbox polling
6✅ Design consumer handlers untuk idempotent
7✅ Set meaningful partition keys (order_id, user_id)
8✅ Monitor consumer lag via Prometheus/Grafana
9✅ Set retention period sesuai business need
10
11DON'T:
12❌ Auto-commit (risk: message loss on crash)
13❌ String partition key yang terlalu kardinalitas rendah (e.g., status)
14 → Semua PENDING orders ke partisi yang sama → hot partition
15❌ Block Kafka consumer goroutine dengan operasi mahal
16❌ Retry tanpa backoff → overwhelm Kafka
17❌ Trust at-most-once delivery → always design for at-least-onceSatu jebakan yang sering terlewat ada di daftar DON’T: memilih partition key berkardinalitas rendah seperti status membuat semua order PENDING menumpuk di satu partisi — hot partition yang meniadakan manfaat paralelisme Kafka.
12.19 Metrics untuk Kafka
Metrik Prometheus memberi visibilitas kuantitatif atas kesehatan pipeline. Kode berikut mendefinisikan counter, gauge, dan aturan alert untuk outbox dan consumer lag.
1// Prometheus metrics untuk Kafka integration
2
3var (
4 outboxPublished = prometheus.NewCounterVec(
5 prometheus.CounterOpts{Name: "outbox_events_published_total"},
6 []string{"topic"},
7 )
8 outboxFailed = prometheus.NewCounterVec(
9 prometheus.CounterOpts{Name: "outbox_events_failed_total"},
10 []string{"topic", "error"},
11 )
12 outboxPendingGauge = prometheus.NewGaugeFunc(
13 prometheus.GaugeOpts{Name: "outbox_events_pending"},
14 func() float64 {
15 var count float64
16 db.QueryRow(context.Background(),
17 "SELECT COUNT(*) FROM outbox_events WHERE published = false").Scan(&count)
18 return count
19 },
20 )
21 consumerLag = prometheus.NewGaugeVec(
22 prometheus.GaugeOpts{Name: "kafka_consumer_lag"},
23 []string{"topic", "consumer_group"},
24 )
25)
26
27// Alert rules (Prometheus):
28// ALERT OutboxBacklog IF outbox_events_pending > 1000 FOR 5m
29// ALERT ConsumerLagHigh IF kafka_consumer_lag > 500 FOR 10mGauge outbox_events_pending yang seharusnya selalu mendekati nol adalah alarm dini terbaik: kalau angkanya menumpuk, worker macet atau Kafka bermasalah — jauh sebelum customer merasakan dampaknya.
12.20 Ringkasan: Kafka Integration Complete
Event flow Santekno Shop sekarang fully functional end-to-end:
PlaceOrder → DB transaction (INSERT order + INSERT outbox_events) → Outbox Worker (poll setiap 5s, FOR UPDATE SKIP LOCKED) → Kafka Publisher (idempotent producer, RequiredAcks=All) → Kafka Topics → Consumer Group (manual commit, at-least-once) → Notification Handler (idempotent via event_id).
Outbox Worker: FOR UPDATE SKIP LOCKED untuk multiple instance, retry dengan exponential backoff, metrics untuk monitoring.
Consumer Group: manual commit, DLQ untuk permanent failure, graceful shutdown.
Partition strategy: order_id sebagai key → ordering guarantee per order, sehingga perjalanan customer dari placed sampai shipped selalu tiba berurutan.
Dengan Kafka integration selesai, seluruh infrastruktur event sudah tersambung. Berikutnya kita optimasi performa dengan menambahkan lapisan caching Redis per service untuk mengurangi beban database.