✨ Integrate monitoring server for observability, adding health and metrics endpoints. Update configuration to enable monitoring features and enhance README with deployment examples for Kubernetes and systemd. Refactor application initialization to include monitoring server setup and improve error handling in message processing metrics.

2025-11-15 16:30:29 +08:00
parent c3f98e9c7c
commit 53208997e8
17 changed files with 1092 additions and 182 deletions
@@ -0,0 +1,109 @@
+# Kubernetes Deployment Example
+
+The following manifest shows the essential pieces needed to run `caatsm` on Kubernetes with native config management and probes.
+
+## 1. ConfigMap and Secret
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: caatsm-config
+data:
+  config.toml: |
+    # trimmed for brevity; see configs/config.prod.toml
+    [nats]
+    url = "nats://nats.jetstream.svc:4222"
+    stream = "TELEGRAM"
+    consumer = "telegram-consumer"
+
+    [postgres]
+    # default overridden by CAATSM_POSTGRES_URL in env
+    url = "postgres://caatsm:password@timescale.svc:5432/aviation?sslmode=disable"
+
+    [monitoring]
+    addr = ":2112"
+    enable_metrics = true
+    enable_health = true
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: caatsm-secrets
+type: Opaque
+stringData:
+  CAATSM_POSTGRES_URL: postgres://caatsm:super-secret@timescale.svc:5432/aviation?sslmode=disable
+```
+
+## 2. Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: caatsm
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: caatsm
+  template:
+    metadata:
+      labels:
+        app: caatsm
+    spec:
+      containers:
+        - name: caatsm
+          image: ghcr.io/<org>/caatsm:latest
+          args: ["listen", "--config", "/etc/caatsm/config.toml"]
+          envFrom:
+            - secretRef:
+                name: caatsm-secrets
+          env:
+            - name: GO_ENV
+              value: prod
+          ports:
+            - name: monitoring
+              containerPort: 2112
+          volumeMounts:
+            - name: config
+              mountPath: /etc/caatsm
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: monitoring
+            initialDelaySeconds: 10
+            periodSeconds: 15
+          readinessProbe:
+            httpGet:
+              path: /healthz
+              port: monitoring
+            initialDelaySeconds: 5
+            periodSeconds: 15
+      volumes:
+        - name: config
+          configMap:
+            name: caatsm-config
+```
+
+## 3. Service and Scraping
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: caatsm-metrics
+  labels:
+    app: caatsm
+spec:
+  selector:
+    app: caatsm
+  ports:
+    - name: http
+      port: 2112
+      targetPort: monitoring
+      protocol: TCP
+```
+
+Point Prometheus at the service above (or annotate it if you use `prometheus-operator`). The `/healthz` probe doubles as a readiness check and quickly surfaces upstream connectivity issues.
+
@@ -0,0 +1,64 @@
+# Systemd Deployment Example
+
+This example targets a single host running the `caatsm` binary under systemd with minimal moving parts.
+
+## 1. Install the Binary
+
+```
+sudo install -m 755 bin/receiver /usr/local/bin/caatsm
+sudo install -d /etc/caatsm/configs
+sudo cp configs/config.dev.toml /etc/caatsm/configs/config.prod.toml
+```
+
+Adjust the config file to point at your production NATS cluster, TimescaleDB endpoint, and telemetry collector.
+
+## 2. Environment File
+
+Create `/etc/caatsm/caatsm.env` to hold secrets or overrides (systemd keeps file permissions intact):
+
+```
+CAATSM_NATS_URL=nats://nats.prod.svc.cluster.local:4222
+CAATSM_POSTGRES_URL=postgres://caatsm:***@tsdb.prod:5432/aviation?sslmode=require
+CAATSM_LOG_LEVEL=info
+GO_ENV=prod
+```
+
+## 3. systemd Unit
+
+`/etc/systemd/system/caatsm.service`
+
+```
+[Unit]
+Description=CAATSM Telegram Processor
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+EnvironmentFile=/etc/caatsm/caatsm.env
+WorkingDirectory=/etc/caatsm
+ExecStart=/usr/local/bin/caatsm listen
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+LimitNOFILE=65535
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Reload and start:
+
+```
+sudo systemctl daemon-reload
+sudo systemctl enable --now caatsm
+```
+
+## 4. Observability Hooks
+
+- Expose `monitoring.addr = ":2112"` (default) and add firewall rules so Prometheus can scrape `http://host:2112/metrics`.
+- systemd watchdogs can use `curl -sf http://127.0.0.1:2112/healthz`.
+
+With these three files (binary, config, env) the service becomes repeatable and easy to operate.
+