feat(go): expose runtime ingest metrics

go/vehicle-gateway/cmd/realtime-api/main.go

@@ -20,6 +20,7 @@ import (
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/health"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/history"
+	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/metrics"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/observability"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/realtime"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/stats"
@@ -47,9 +48,11 @@ func main() {
 	})
 
 	mux := http.NewServeMux()
+	registry := metrics.NewRegistry()
 	healthChecks := []health.Check{
 		{Name: "redis", Check: func(ctx context.Context) error { return client.Ping(ctx).Err() }},
 	}
+	mux.Handle("/metrics", metrics.NewHandler(registry))
 	mux.Handle("/openapi.json", realtime.NewOpenAPIHandler())
 	mux.Handle("/swagger-ui/", realtime.NewSwaggerUIHandler())
 	mux.Handle("/api/realtime/vehicles/", realtime.NewHandler(repository))
@@ -96,7 +99,7 @@ func main() {
 	}
 	defer closeStats()
 	if brokers := splitCSV(os.Getenv("KAFKA_BROKERS")); len(brokers) > 0 {
-		go consumeKafka(ctx, logger, updater, brokers)
+		go consumeKafka(ctx, logger, registry, updater, brokers)
 	} else {
 		logger.Warn("KAFKA_BROKERS is empty; realtime api will serve existing redis data only")
 	}
@@ -159,7 +162,7 @@ func consumeKafka(ctx context.Context, logger interface {
 	Info(string, ...any)
 	Error(string, ...any)
 	Warn(string, ...any)
-}, updater realtimeUpdater, brokers []string) {
+}, registry *metrics.Registry, updater realtimeUpdater, brokers []string) {
 	reader := kafka.NewReader(kafka.ReaderConfig{
 		Brokers:     brokers,
 		GroupID:     env("KAFKA_GROUP", "go-realtime-api"),
@@ -178,7 +181,7 @@ func consumeKafka(ctx context.Context, logger interface {
 			logger.Error("kafka fetch failed", "error", err)
 			continue
 		}
-		processRealtimeMessage(ctx, logger, updater, reader, message)
+		processRealtimeMessage(ctx, logger, registry, updater, reader, message)
 	}
 }
 
@@ -210,23 +213,40 @@ type kafkaMessageCommitter interface {
 func processRealtimeMessage(ctx context.Context, logger interface {
 	Error(string, ...any)
 	Warn(string, ...any)
-}, updater realtimeUpdater, committer kafkaMessageCommitter, message kafka.Message) {
+}, registry *metrics.Registry, updater realtimeUpdater, committer kafkaMessageCommitter, message kafka.Message) {
 	messageCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), kafkaMessageOperationTimeout)
 	defer cancel()
 
+	addRealtimeMetric(registry, "vehicle_realtime_kafka_messages_total", message, "received")
 	var env envelope.FrameEnvelope
 	if err := json.Unmarshal(message.Value, &env); err != nil {
+		addRealtimeMetric(registry, "vehicle_realtime_kafka_messages_total", message, "invalid_json")
 		logger.Warn("skip invalid envelope json", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "error", err)
 		_ = committer.CommitMessages(messageCtx, message)
 		return
 	}
 	if err := updater.Update(messageCtx, env); err != nil {
+		addRealtimeMetric(registry, "vehicle_realtime_updates_total", message, "error")
 		logger.Error("redis realtime update failed", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "event_id", env.StableEventID(), "error", err)
 		return
 	}
+	addRealtimeMetric(registry, "vehicle_realtime_updates_total", message, "ok")
 	if err := committer.CommitMessages(messageCtx, message); err != nil {
+		addRealtimeMetric(registry, "vehicle_realtime_kafka_commits_total", message, "error")
 		logger.Error("kafka commit failed", "topic", message.Topic, "partition", message.Partition, "offset", message.Offset, "error", err)
+		return
 	}
+	addRealtimeMetric(registry, "vehicle_realtime_kafka_commits_total", message, "ok")
+}
+
+func addRealtimeMetric(registry *metrics.Registry, name string, message kafka.Message, status string) {
+	if registry == nil {
+		return
+	}
+	registry.IncCounter(name, metrics.Labels{
+		"topic":  message.Topic,
+		"status": status,
+	})
 }
 
 func env(key string, fallback string) string {

go/vehicle-gateway/cmd/realtime-api/main_test.go

@@ -3,11 +3,13 @@ package main
 import (
 	"context"
 	"encoding/json"
+	"strings"
 	"testing"
 
 	"github.com/segmentio/kafka-go"
 
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
+	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/metrics"
 )
 
 func TestProcessRealtimeMessageUsesUncancelledContextForUpdateAndCommit(t *testing.T) {
@@ -29,7 +31,7 @@ func TestProcessRealtimeMessageUsesUncancelledContextForUpdateAndCommit(t *testi
 	updater := &contextCheckingRealtimeUpdater{}
 	committer := &contextCheckingMessageCommitter{}
 
-	processRealtimeMessage(parent, discardRealtimeLogger{}, updater, committer, kafka.Message{Value: payload})
+	processRealtimeMessage(parent, discardRealtimeLogger{}, nil, updater, committer, kafka.Message{Value: payload})
 
 	if updater.ctxErr != nil {
 		t.Fatalf("updater saw cancelled context: %v", updater.ctxErr)
@@ -42,6 +44,42 @@ func TestProcessRealtimeMessageUsesUncancelledContextForUpdateAndCommit(t *testi
 	}
 }
 
+func TestProcessRealtimeMessageRecordsMetrics(t *testing.T) {
+	env := envelope.FrameEnvelope{
+		Protocol:     envelope.ProtocolJT808,
+		MessageID:    "0x0200",
+		Phone:        "13307795425",
+		EventTimeMS:  1782918600000,
+		ReceivedAtMS: 1782918600000,
+		ParseStatus:  envelope.ParseOK,
+	}
+	payload, err := json.Marshal(env)
+	if err != nil {
+		t.Fatal(err)
+	}
+	registry := metrics.NewRegistry()
+
+	processRealtimeMessage(
+		context.Background(),
+		discardRealtimeLogger{},
+		registry,
+		&contextCheckingRealtimeUpdater{},
+		&contextCheckingMessageCommitter{},
+		kafka.Message{Topic: "vehicle.event.go.unified.v1", Value: payload},
+	)
+
+	text := registry.Render()
+	for _, want := range []string{
+		`vehicle_realtime_kafka_messages_total{status="received",topic="vehicle.event.go.unified.v1"} 1`,
+		`vehicle_realtime_updates_total{status="ok",topic="vehicle.event.go.unified.v1"} 1`,
+		`vehicle_realtime_kafka_commits_total{status="ok",topic="vehicle.event.go.unified.v1"} 1`,
+	} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("metrics missing %s:\n%s", want, text)
+		}
+	}
+}
+
 func TestCompositeRealtimeUpdaterUpdatesBothStores(t *testing.T) {
 	env := envelope.FrameEnvelope{Protocol: envelope.ProtocolGB32960, VIN: "VIN001"}
 	redisUpdater := &contextCheckingRealtimeUpdater{}