From 266a74f225a0fd5d727a8c65c66b64c2f117f2aa Mon Sep 17 00:00:00 2001 From: lingniu Date: Thu, 2 Jul 2026 19:12:17 +0800 Subject: [PATCH] docs: document go service observability endpoints --- docs/ops/go-service-observability.md | 45 ++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/ops/go-service-observability.md diff --git a/docs/ops/go-service-observability.md b/docs/ops/go-service-observability.md new file mode 100644 index 00000000..c48f2130 --- /dev/null +++ b/docs/ops/go-service-observability.md @@ -0,0 +1,45 @@ +# Go Service Observability + +## ECS + +Host: `115.29.187.205` + +The Go services expose local-only health and metrics endpoints. They are intended for ECS-local checks, Prometheus scraping through an agent, or SSH troubleshooting. They are not public business APIs. + +## Endpoints + +| Service | systemd unit | Address | Health | Readiness | Metrics | +| --- | --- | --- | --- | --- | --- | +| Gateway | `lingniu-go-gateway.service` | `127.0.0.1:20211` | `/healthz` | `/readyz` | `/metrics` | +| History writer | `lingniu-go-history-writer.service` | `127.0.0.1:20212` | `/healthz` | `/readyz` | `/metrics` | +| Stat writer | `lingniu-go-stat-writer.service` | `127.0.0.1:20213` | `/healthz` | `/readyz` | `/metrics` | +| NATS Kafka bridge | `lingniu-go-nats-kafka-bridge.service` | `127.0.0.1:20214` | `/healthz` | `/readyz` | `/metrics` | +| Realtime API | `lingniu-go-realtime-api.service` | `0.0.0.0:20200` | `/healthz` | `/readyz` | `/metrics` | + +## Quick Checks + +```bash +curl -fsS http://127.0.0.1:20211/readyz +curl -fsS http://127.0.0.1:20211/metrics +curl -fsS http://127.0.0.1:20212/readyz +curl -fsS http://127.0.0.1:20213/readyz +curl -fsS http://127.0.0.1:20214/readyz +curl -fsS http://127.0.0.1:20200/readyz +``` + +## Core Counters + +| Metric | Meaning | +| --- | --- | +| `vehicle_gateway_frames_total` | Protocol frames received and parsed by the gateway. Labels: `protocol`, `status`. | +| `vehicle_gateway_publish_total` | Gateway publish result for raw and unified events. Labels: `protocol`, `kind`, `status`. | +| `vehicle_bridge_messages_total` | NATS messages fetched by the bridge. Labels: `subject`, `status`. | +| `vehicle_bridge_kafka_writes_total` | Bridge writes to Kafka. Labels: `topic`, `status`. | +| `vehicle_bridge_nats_acks_total` | NATS ack results after Kafka write. Labels: `subject`, `status`. | +| `vehicle_history_writes_total` | TDengine history writes. Labels: `topic`, `status`. | +| `vehicle_stat_writes_total` | MySQL metric writes. Labels: `topic`, `status`. | +| `vehicle_realtime_updates_total` | Redis/MySQL realtime projector updates. Labels: `topic`, `status`. | + +## First Principle + +These metrics are operational telemetry. They should stay out of MySQL and TDengine business tables unless a product query explicitly requires persisted aggregates. Persisted aggregate metrics should be derived from Kafka replay rather than by widening realtime or raw tables.