Monitoring Architecture

Monitoring Architecture

Overview

┌──────────────────┐      OTLP HTTP       ┌──────────┐
│  terma-api        │ ──────────────────→  │  Jaeger  │
│  (port:3000)      │                      │  (trades)│
│  metrics:9090     │                      │  UI:16686│
└──────┬───────────┘                      └──────────┘
       │
       │ traceparent header
       ▼
┌──────────────────┐      OTLP HTTP       ┌──────────┐
│  terma-bot        │ ──────────────────→  │  Jaeger  │
│  (port:3001)      │                      │  (trades)│
│  metrics:9091     │                      └──────────┘
└──────────────────┘
       │                              ┌──────────┐
       └────────────────────────────→  │ Grafana  │
                                       │ (UI:3000)│
                                       └──────────┘
                                              ▲
┌──────────────────┐      pull               │
│   Prometheus     │ ←────────────────────    │
│   (port:9090)    │     /metrics             │
└──────────────────┘

Ports & Services

Service	Internal Port	Purpose
api	3000	Fastify REST API
bot	3001	Grammy Telegram Bot
prometheus	9090	Metrics collection
jaeger	4318	OTLP HTTP (traces)
jaeger	16686	Jaeger UI
grafana	3000	Dashboards
api-metrics	9090	Prometheus /metrics endpoint
bot-metrics	9091	Prometheus /metrics endpoint

Stack

OpenTelemetry SDK (packages/observability)

• Initialization: at each service startup
• HTTP instrumentation: automatic spans via @opentelemetry/instrumentation-http
• PrometheusExporter: metrics on a dedicated port
• OTLPTraceExporter: traces to Jaeger

Prometheus

• Pull model: polls /metrics on api (9090) and bot (9091)
• Configuration: scripts/prometheus-conf/prometheus.yml
• Retention: 15 days by default

Jaeger

• Push model: services send traces via OTLP HTTP
• Storage: badger (stage), in-memory (dev)
• UI: http://<vps>:16686

Grafana

• Auto-provisioned: datasource + dashboard on startup
• Prometheus datasource: http://prometheus:9090
• Jaeger datasource: http://jaeger:16686

Logging

• Format: structured JSON (pino)
• Fields: time, level, msg, traceId, spanId, name, method, url, statusCode, responseTime
• PII: in production, only technical identifiers are logged (update_id, chatId, type)

Health

The /api/health endpoint returns OTel status:

{
  "status": "ok" | "degraded",
  "version": "0.1.2",
  "otel": {
    "initialized": true,
    "tracer": "started",
    "meter": "started"
  },
  "uptime": 12345
}

Check:

curl -s https://termagrand.ru/api/health | jq

Starting the Stack

docker compose -f docker-compose.stage.yml up -d prometheus jaeger grafana
docker compose -f docker-compose.stage.yml ps