feat(go): expose runtime ingest metrics

go/vehicle-gateway/internal/gateway/mqtt_client.go

@@ -17,6 +17,7 @@ import (
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/eventbus"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/identity"
+	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/metrics"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/protocol/yutongmqtt"
 )
 
@@ -38,6 +39,7 @@ type MQTTClientConfig struct {
 	Sink                    eventbus.Sink
 	Resolver                identity.Resolver
 	Logger                  *slog.Logger
+	Metrics                 *metrics.Registry
 }
 
 type MQTTClient struct {
@@ -208,14 +210,41 @@ func (c *MQTTClient) handleMessage(ctx context.Context, topic string, payload []
 			env = resolved
 		}
 	}
+	c.recordFrameMetric(env.ParseStatus)
 	if err := c.cfg.Sink.PublishRaw(messageCtx, env); err != nil {
+		c.recordPublishMetric("raw", "error")
 		c.cfg.Logger.Error("publish mqtt raw failed", "topic", topic, "event_id", env.StableEventID(), "error", err)
 		return
 	}
+	c.recordPublishMetric("raw", "ok")
 	if env.ParseStatus == envelope.ParseBadFrame {
 		return
 	}
 	if err := c.cfg.Sink.PublishUnified(messageCtx, env); err != nil {
+		c.recordPublishMetric("unified", "error")
 		c.cfg.Logger.Error("publish mqtt unified failed", "topic", topic, "event_id", env.StableEventID(), "error", err)
+		return
 	}
+	c.recordPublishMetric("unified", "ok")
+}
+
+func (c *MQTTClient) recordFrameMetric(status envelope.ParseStatus) {
+	if c.cfg.Metrics == nil {
+		return
+	}
+	c.cfg.Metrics.IncCounter("vehicle_gateway_frames_total", metrics.Labels{
+		"protocol": string(envelope.ProtocolYutongMQTT),
+		"status":   string(status),
+	})
+}
+
+func (c *MQTTClient) recordPublishMetric(kind string, status string) {
+	if c.cfg.Metrics == nil {
+		return
+	}
+	c.cfg.Metrics.IncCounter("vehicle_gateway_publish_total", metrics.Labels{
+		"protocol": string(envelope.ProtocolYutongMQTT),
+		"kind":     kind,
+		"status":   status,
+	})
 }

go/vehicle-gateway/internal/gateway/mqtt_client_test.go

@@ -11,10 +11,12 @@ import (
 	"math/big"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
+	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/metrics"
 )
 
 func TestMQTTClientHandleMessagePublishesRawAndUnified(t *testing.T) {
@@ -45,6 +47,39 @@ func TestMQTTClientHandleMessagePublishesRawAndUnified(t *testing.T) {
 	}
 }
 
+func TestMQTTClientRecordsMessageMetrics(t *testing.T) {
+	registry := metrics.NewRegistry()
+	client, err := NewMQTTClient(MQTTClientConfig{
+		EndpointName: "endpoint-a",
+		Broker:       "tcp://127.0.0.1:1883",
+		ClientID:     "test-client",
+		Topics:       []string{"/ytforward/shln/+"},
+		Sink:         &recordingSink{},
+		Logger:       slog.New(slog.NewTextHandler(testWriter{t: t}, nil)),
+		Metrics:      registry,
+	})
+	if err != nil {
+		t.Fatalf("NewMQTTClient() error = %v", err)
+	}
+
+	client.handleMessage(context.Background(), "/ytforward/shln/dev1", []byte(`{
+	  "device":"LTEST000000000001",
+	  "time":"20260413100000",
+	  "data":{"METER_SPEED":52.3,"TOTAL_MILEAGE":123456.7}
+	}`))
+
+	text := registry.Render()
+	for _, want := range []string{
+		`vehicle_gateway_frames_total{protocol="YUTONG_MQTT",status="OK"} 1`,
+		`vehicle_gateway_publish_total{kind="raw",protocol="YUTONG_MQTT",status="ok"} 1`,
+		`vehicle_gateway_publish_total{kind="unified",protocol="YUTONG_MQTT",status="ok"} 1`,
+	} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("metrics missing %s:\n%s", want, text)
+		}
+	}
+}
+
 func TestMQTTClientHandleBadPayloadPublishesOnlyRaw(t *testing.T) {
 	sink := &recordingSink{}
 	client, err := NewMQTTClient(MQTTClientConfig{

go/vehicle-gateway/internal/gateway/tcp_server.go

@@ -15,6 +15,7 @@ import (
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/eventbus"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/identity"
+	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/metrics"
 )
 
 type FrameExtractor func([]byte) (frames [][]byte, remainder []byte, err error)
@@ -36,6 +37,7 @@ type TCPServer struct {
 	sink           eventbus.Sink
 	resolver       identity.Resolver
 	logger         *slog.Logger
+	metrics        *metrics.Registry
 	readBufferSize int
 	idleTimeout    time.Duration
 	maxConnections int
@@ -46,6 +48,7 @@ type TCPServerConfig struct {
 	Sink           eventbus.Sink
 	Resolver       identity.Resolver
 	Logger         *slog.Logger
+	Metrics        *metrics.Registry
 	ReadBufferSize int
 	IdleTimeout    time.Duration
 	MaxConnections int
@@ -89,6 +92,7 @@ func NewTCPServer(cfg TCPServerConfig) (*TCPServer, error) {
 		sink:           cfg.Sink,
 		resolver:       cfg.Resolver,
 		logger:         cfg.Logger,
+		metrics:        cfg.Metrics,
 		readBufferSize: cfg.ReadBufferSize,
 		idleTimeout:    cfg.IdleTimeout,
 		maxConnections: cfg.MaxConnections,
@@ -209,18 +213,23 @@ func (s *TCPServer) handleFrame(ctx context.Context, conn net.Conn, raw []byte,
 			env = resolved
 		}
 	}
+	s.recordFrameMetric(env.ParseStatus)
 
 	if err := s.sink.PublishRaw(frameCtx, env); err != nil {
+		s.recordPublishMetric("raw", "error")
 		s.logger.Error("publish raw failed", "protocol", s.protocol.Protocol, "event_id", env.StableEventID(), "error", err)
 		return
 	}
+	s.recordPublishMetric("raw", "ok")
 	if env.ParseStatus == envelope.ParseBadFrame {
 		return
 	}
 	if err := s.sink.PublishUnified(frameCtx, env); err != nil {
+		s.recordPublishMetric("unified", "error")
 		s.logger.Error("publish unified failed", "protocol", s.protocol.Protocol, "event_id", env.StableEventID(), "error", err)
 		return
 	}
+	s.recordPublishMetric("unified", "ok")
 	if s.protocol.Respond == nil {
 		return
 	}
@@ -238,6 +247,27 @@ func (s *TCPServer) handleFrame(ctx context.Context, conn net.Conn, raw []byte,
 	}
 }
 
+func (s *TCPServer) recordFrameMetric(status envelope.ParseStatus) {
+	if s.metrics == nil {
+		return
+	}
+	s.metrics.IncCounter("vehicle_gateway_frames_total", metrics.Labels{
+		"protocol": string(s.protocol.Protocol),
+		"status":   string(status),
+	})
+}
+
+func (s *TCPServer) recordPublishMetric(kind string, status string) {
+	if s.metrics == nil {
+		return
+	}
+	s.metrics.IncCounter("vehicle_gateway_publish_total", metrics.Labels{
+		"protocol": string(s.protocol.Protocol),
+		"kind":     kind,
+		"status":   status,
+	})
+}
+
 func (p TCPProtocol) String() string {
 	return fmt.Sprintf("%s@%s", p.Protocol, p.Addr)
 }

go/vehicle-gateway/internal/gateway/tcp_server_test.go

@@ -6,10 +6,12 @@ import (
 	"io"
 	"log/slog"
 	"net"
+	"strings"
 	"testing"
 	"time"
 
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/envelope"
+	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/metrics"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/protocol/gb32960"
 	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/protocol/jt808"
 )
@@ -45,6 +47,47 @@ func TestTCPServerPublishesGoodFrameToRawAndUnified(t *testing.T) {
 	}
 }
 
+func TestTCPServerRecordsFrameMetrics(t *testing.T) {
+	registry := metrics.NewRegistry()
+	server, err := NewTCPServer(TCPServerConfig{
+		Protocol: TCPProtocol{
+			Protocol: envelope.ProtocolJT808,
+			Addr:     ":0",
+			Extract:  jt808.ExtractFrames,
+			Parse: func(_ []byte, receivedAtMS int64, sourceEndpoint string) (envelope.FrameEnvelope, error) {
+				return envelope.FrameEnvelope{
+					Protocol:       envelope.ProtocolJT808,
+					MessageID:      "0x0200",
+					Phone:          "13307795425",
+					SourceEndpoint: sourceEndpoint,
+					ReceivedAtMS:   receivedAtMS,
+					EventTimeMS:    receivedAtMS,
+					ParseStatus:    envelope.ParseOK,
+				}, nil
+			},
+		},
+		Sink:    &recordingSink{},
+		Logger:  slog.New(slog.NewTextHandler(testWriter{t: t}, nil)),
+		Metrics: registry,
+	})
+	if err != nil {
+		t.Fatalf("NewTCPServer() error = %v", err)
+	}
+
+	server.handleFrame(context.Background(), nil, []byte{0x01}, "127.0.0.1:808")
+
+	text := registry.Render()
+	for _, want := range []string{
+		`vehicle_gateway_frames_total{protocol="JT808",status="OK"} 1`,
+		`vehicle_gateway_publish_total{kind="raw",protocol="JT808",status="ok"} 1`,
+		`vehicle_gateway_publish_total{kind="unified",protocol="JT808",status="ok"} 1`,
+	} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("metrics missing %s:\n%s", want, text)
+		}
+	}
+}
+
 func TestTCPServerPublishesBadFrameOnlyToRaw(t *testing.T) {
 	good := buildGBFrame(0x02, 0xfe, "LNBSCB3D4R1234567", nil)
 	good[len(good)-1] ^= 0xff

go/vehicle-gateway/internal/health/health.go

@@ -7,6 +7,8 @@ import (
 	"net/http"
 	"strings"
 	"time"
+
+	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/metrics"
 )
 
 type Check struct {
@@ -32,22 +34,25 @@ func NewHandler(service string, checks []Check) *Handler {
 	return &Handler{service: service, checks: checks}
 }
 
-func NewMux(service string, checks []Check) *http.ServeMux {
+func NewMux(service string, checks []Check, registry *metrics.Registry) *http.ServeMux {
 	mux := http.NewServeMux()
 	handler := NewHandler(service, checks)
 	mux.Handle("/healthz", handler)
 	mux.Handle("/readyz", handler)
+	if registry != nil {
+		mux.Handle("/metrics", metrics.NewHandler(registry))
+	}
 	return mux
 }
 
-func NewServer(addr string, service string, checks []Check) *http.Server {
+func NewServer(addr string, service string, checks []Check, registry *metrics.Registry) *http.Server {
 	addr = strings.TrimSpace(addr)
 	if addr == "" {
 		return nil
 	}
 	return &http.Server{
 		Addr:              addr,
-		Handler:           NewMux(service, checks),
+		Handler:           NewMux(service, checks, registry),
 		ReadHeaderTimeout: 5 * time.Second,
 	}
 }

go/vehicle-gateway/internal/health/health_test.go

@@ -7,6 +7,8 @@ import (
 	"net/http/httptest"
 	"strings"
 	"testing"
+
+	"lingniu-vehicle-ingest/go/vehicle-gateway/internal/metrics"
 )
 
 func TestHandlerReturnsHealthyWhenAllChecksPass(t *testing.T) {
@@ -63,10 +65,12 @@ func TestHandlerRejectsUnknownPath(t *testing.T) {
 }
 
 func TestNewMuxRegistersHealthAndReadinessRoutes(t *testing.T) {
+	registry := metrics.NewRegistry()
+	registry.IncCounter("vehicle_test_total", metrics.Labels{"service": "stat"})
 	mux := NewMux("vehicle-stat-writer", []Check{
 		{Name: "mysql", Check: func(context.Context) error { return nil }},
-	})
-	for _, path := range []string{"/healthz", "/readyz"} {
+	}, registry)
+	for _, path := range []string{"/healthz", "/readyz", "/metrics"} {
 		request := httptest.NewRequest(http.MethodGet, path, nil)
 		response := httptest.NewRecorder()
 
@@ -79,13 +83,13 @@ func TestNewMuxRegistersHealthAndReadinessRoutes(t *testing.T) {
 }
 
 func TestNewServerReturnsNilWhenAddressIsEmpty(t *testing.T) {
-	if server := NewServer("", "vehicle-gateway", nil); server != nil {
+	if server := NewServer("", "vehicle-gateway", nil, nil); server != nil {
 		t.Fatalf("server = %#v, want nil", server)
 	}
 }
 
 func TestNewServerBuildsConfiguredHTTPServer(t *testing.T) {
-	server := NewServer(":20290", "vehicle-gateway", nil)
+	server := NewServer(":20290", "vehicle-gateway", nil, nil)
 	if server == nil {
 		t.Fatal("server is nil")
 	}

go/vehicle-gateway/internal/metrics/metrics.go

@@ -0,0 +1,141 @@
+package metrics
+
+import (
+	"fmt"
+	"net/http"
+	"sort"
+	"strings"
+	"sync"
+)
+
+type Labels map[string]string
+
+type Registry struct {
+	mu       sync.RWMutex
+	counters map[string]map[string]float64
+}
+
+func NewRegistry() *Registry {
+	return &Registry{counters: map[string]map[string]float64{}}
+}
+
+func (r *Registry) IncCounter(name string, labels Labels) {
+	r.AddCounter(name, labels, 1)
+}
+
+func (r *Registry) AddCounter(name string, labels Labels, value float64) {
+	name = strings.TrimSpace(name)
+	if r == nil || name == "" || value == 0 {
+		return
+	}
+	key := labelsKey(labels)
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if r.counters[name] == nil {
+		r.counters[name] = map[string]float64{}
+	}
+	r.counters[name][key] += value
+}
+
+func (r *Registry) Render() string {
+	if r == nil {
+		return ""
+	}
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	var names []string
+	for name := range r.counters {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	var b strings.Builder
+	for _, name := range names {
+		b.WriteString("# TYPE ")
+		b.WriteString(name)
+		b.WriteString(" counter\n")
+		var keys []string
+		for key := range r.counters[name] {
+			keys = append(keys, key)
+		}
+		sort.Strings(keys)
+		for _, key := range keys {
+			b.WriteString(name)
+			if key != "" {
+				b.WriteString("{")
+				b.WriteString(key)
+				b.WriteString("}")
+			}
+			b.WriteString(" ")
+			b.WriteString(formatNumber(r.counters[name][key]))
+			b.WriteString("\n")
+		}
+	}
+	return b.String()
+}
+
+func NewHandler(registry *Registry) http.Handler {
+	if registry == nil {
+		registry = NewRegistry()
+	}
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		if strings.Trim(r.URL.Path, "/") != "metrics" {
+			http.NotFound(w, r)
+			return
+		}
+		w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
+		_, _ = w.Write([]byte(registry.Render()))
+	})
+}
+
+func labelsKey(labels Labels) string {
+	if len(labels) == 0 {
+		return ""
+	}
+	keys := make([]string, 0, len(labels))
+	for key := range labels {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	parts := make([]string, 0, len(keys))
+	for _, key := range keys {
+		value := labels[key]
+		parts = append(parts, fmt.Sprintf(`%s="%s"`, sanitizeLabelName(key), escapeLabelValue(value)))
+	}
+	return strings.Join(parts, ",")
+}
+
+func sanitizeLabelName(value string) string {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return "label"
+	}
+	var b strings.Builder
+	for i, r := range value {
+		ok := r == '_' || (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (i > 0 && r >= '0' && r <= '9')
+		if ok {
+			b.WriteRune(r)
+		} else {
+			b.WriteByte('_')
+		}
+	}
+	return b.String()
+}
+
+func escapeLabelValue(value string) string {
+	value = strings.ReplaceAll(value, `\`, `\\`)
+	value = strings.ReplaceAll(value, "\n", `\n`)
+	return strings.ReplaceAll(value, `"`, `\"`)
+}
+
+func formatNumber(value float64) string {
+	if value == float64(int64(value)) {
+		return fmt.Sprintf("%d", int64(value))
+	}
+	return fmt.Sprintf("%g", value)
+}

go/vehicle-gateway/internal/metrics/metrics_test.go

@@ -0,0 +1,60 @@
+package metrics
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestRegistryRendersCountersWithLabels(t *testing.T) {
+	registry := NewRegistry()
+	registry.AddCounter("vehicle_frames_total", Labels{"protocol": "JT808", "status": "ok"}, 2)
+	registry.IncCounter("vehicle_frames_total", Labels{"status": "ok", "protocol": "JT808"})
+	registry.IncCounter("vehicle_publish_errors_total", Labels{"target": "kafka"})
+
+	text := registry.Render()
+
+	for _, want := range []string{
+		`# TYPE vehicle_frames_total counter`,
+		`vehicle_frames_total{protocol="JT808",status="ok"} 3`,
+		`# TYPE vehicle_publish_errors_total counter`,
+		`vehicle_publish_errors_total{target="kafka"} 1`,
+	} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("metrics missing %s:\n%s", want, text)
+		}
+	}
+}
+
+func TestHandlerServesPrometheusText(t *testing.T) {
+	registry := NewRegistry()
+	registry.IncCounter("vehicle_kafka_commits_total", Labels{"service": "history"})
+	handler := NewHandler(registry)
+	request := httptest.NewRequest(http.MethodGet, "/metrics", nil)
+	response := httptest.NewRecorder()
+
+	handler.ServeHTTP(response, request)
+
+	if response.Code != http.StatusOK {
+		t.Fatalf("status = %d body=%s", response.Code, response.Body.String())
+	}
+	if got := response.Header().Get("Content-Type"); !strings.Contains(got, "text/plain") {
+		t.Fatalf("content-type = %q", got)
+	}
+	if !strings.Contains(response.Body.String(), `vehicle_kafka_commits_total{service="history"} 1`) {
+		t.Fatalf("body = %s", response.Body.String())
+	}
+}
+
+func TestHandlerRejectsNonMetricsPath(t *testing.T) {
+	handler := NewHandler(NewRegistry())
+	request := httptest.NewRequest(http.MethodGet, "/readyz", nil)
+	response := httptest.NewRecorder()
+
+	handler.ServeHTTP(response, request)
+
+	if response.Code != http.StatusNotFound {
+		t.Fatalf("status = %d", response.Code)
+	}
+}