Skip to content
Santekno.com | Level Up Your Engineering Skills
ID
📖 0%
19 Nov 2026 · 21 mnt baca ·Artikel 92 / 208
Go

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.

IH
Ihsan Arif
Penulis di Santekno · Backend Engineer

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.

bash
 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 santekno

Pemilihan 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.

go
 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.

go
  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.

go
 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.

go
 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.

go
 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-notification

Menyimpan 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.

go
 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.

text
 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.

go
 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.

go
 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.

text
 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.

go
 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.

sql
 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.

bash
 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    --describe

Setelan 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.

go
 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.

yaml
 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    - kafka

Fitur yang tersedia lewat UI ini merangkum alur debugging sehari-hari, dari inspeksi pesan sampai memantau lag. Daftar berikut merinci kegunaannya.

text
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:8090

Dengan 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.

text
 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 v1

Kebijakan “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.

text
 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-once

Satu 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.

go
 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 10m

Gauge 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.

Artikel Terkait

💬 Komentar