@usherlabs/cex-broker 0.1.20 → 0.2.0

package/README.md

@@ -65,33 +65,43 @@ CEX_BROKER_BINANCE_API_KEY_1=your_secondary_binance_api_key
 CEX_BROKER_BINANCE_API_SECRET_1=your_secondary_binance_api_secret
 CEX_BROKER_BINANCE_API_KEY_2=your_tertiary_binance_api_key
 CEX_BROKER_BINANCE_API_SECRET_2=your_tertiary_binance_api_secret
+
+# OpenTelemetry Metrics (Optional)
+# Send metrics via OTLP to a collector
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_SERVICE_NAME=cex-broker
+# Or use CEX_BROKER_OTEL_* (default port 4318). Legacy: CEX_BROKER_CLICKHOUSE_* also supported.
+# CEX_BROKER_OTEL_HOST=otel-collector
+# CEX_BROKER_OTEL_PORT=4318
+# CEX_BROKER_OTEL_PROTOCOL=http
 ```
 
 **Note**: Only configure API keys for exchanges you plan to use. The system will automatically detect and initialize configured exchanges.
 
+**Metrics (OpenTelemetry)**: Metrics are exported via OTLP. If neither `OTEL_EXPORTER_OTLP_ENDPOINT` nor `CEX_BROKER_OTEL_HOST` (or legacy `CEX_BROKER_CLICKHOUSE_HOST`) is set, metrics are disabled. When enabled, the broker sends metrics to the configured OTLP endpoint (e.g. an OpenTelemetry Collector).
+
 ### Policy Configuration
 
-Configure trading policies in `policy/policy.json`:
+Configure trading policies in `policy/policy.json`.
+
+- **Full reference**: see `POLICY.md` (supported options, matching rules, reload behaviour, and troubleshooting)
+- **Example policy**: `policy/policy.json`
 
 ```json
 {
   "withdraw": {
-    "rule": {
-      "networks": ["BEP20", "ARBITRUM", "ETHEREUM"],
-      "whitelist": ["0x9d467fa9062b6e9b1a46e26007ad82db116c67cb"],
-      "amounts": [
-        {
-          "ticker": "USDC",
-          "max": 100000,
-          "min": 1
-        },
-        {
-          "ticker": "USDT",
-          "max": 100000,
-          "min": 1
-        }
-      ]
-    }
+    "rule": [
+      {
+        "exchange": "BINANCE",
+        "network": "BEP20",
+        "whitelist": ["0x9d467fa9062b6e9b1a46e26007ad82db116c67cb"]
+      },
+      {
+        "exchange": "BINANCE",
+        "network": "ARBITRUM",
+        "whitelist": ["0x9d467fa9062b6e9b1a46e26007ad82db116c67cb"]
+      }
+    ]
   },
   "deposit": {},
   "order": {
@@ -103,10 +113,7 @@ Configure trading policies in `policy/policy.json`:
         "BINANCE:BTC/ETH"
       ],
       "limits": [
-        { "from": "USDT", "to": "ETH", "min": 1, "max": 100000 },
-        { "from": "ETH", "to": "USDT", "min": 0.5, "max": 5 },
-        { "from": "ARB", "to": "USDC", "min": 1, "max": 1000 },
-        { "from": "USDC", "to": "ARB", "min": 1, "max": 10000 }
+        { "from": "USDT", "to": "ETH", "min": 1, "max": 100000 }
       ]
     }
   }
@@ -394,6 +401,45 @@ const response = await client.ExecuteAction(request, metadata);
 - Monitor API usage and set appropriate rate limits
 - Use secondary brokers for redundancy and load distribution
 
+## 📊 OpenTelemetry Metrics
+
+The broker exports metrics via **OpenTelemetry (OTLP)** for monitoring and analytics. Metrics are collected for:
+
+- **ExecuteAction requests**: Request counts, success/failure rates, latency histograms
+- **Subscribe streams**: Subscription counts, duration, error rates
+- **Action-specific metrics**: Tagged by action type, CEX, and symbol
+
+### Metrics (OTLP)
+
+The following metrics are exported as OTLP counters and histograms:
+
+- `execute_action_requests_total` (counter): Total ExecuteAction requests
+- `execute_action_success_total` (counter): Successful ExecuteAction requests
+- `execute_action_errors_total` (counter): Failed ExecuteAction requests
+- `execute_action_duration_ms` (histogram): ExecuteAction latency
+- `subscribe_requests_total` (counter): Total Subscribe requests
+- `subscribe_errors_total` (counter): Failed Subscribe requests
+- `subscribe_duration_ms` (histogram): Subscribe stream duration
+
+All metrics include attributes: `action`, `cex`, `symbol`, `error_type`, `service`.
+
+### Setting Up Metrics
+
+1. **Run an OTLP receiver** (e.g. [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/)):
+   - Default endpoint: `http://localhost:4318/v1/metrics`
+   - To store in ClickHouse or other backends, use the appropriate exporter in the collector pipeline (e.g. [ClickHouse exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/clickhouseexporter)).
+
+2. **Configure the broker**:
+   - Set `OTEL_EXPORTER_OTLP_ENDPOINT` (e.g. `http://localhost:4318`) or use `CEX_BROKER_OTEL_HOST` (and optional `CEX_BROKER_OTEL_PORT`, `CEX_BROKER_OTEL_PROTOCOL`). Legacy `CEX_BROKER_CLICKHOUSE_*` env vars are also supported.
+
+3. Metrics are pushed periodically to the configured endpoint; no database schema is created by the broker (handled by the collector/backend).
+
+**Local or Docker: OTLP → ClickHouse (no Prometheus)**  
+Use the included OpenTelemetry + ClickHouse stack so metrics go only to ClickHouse (no Prometheus exporter):
+
+- **Docker**: `docker compose -f docker-compose.otel.yaml up -d`, then set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318` and start the broker.
+- **Config**: `otel/collector-config.yaml` (OTLP receiver → batch → ClickHouse exporter). See [otel/README.md](otel/README.md) for full instructions (Docker and local).
+
 ## 🏗️ Architecture
 
 ### Project Structure
@@ -527,17 +573,18 @@ for (const [currency, info] of Object.entries(currencies)) {
 ```json
 {
   "withdraw": {
-    "rule": {
-      "networks": ["BEP20", "ARBITRUM", "ETH"],  // Networks supported by your exchanges
-      "whitelist": ["0x9d467fa9062b6e9b1a46e26007ad82db116c67cb"],
-      "amounts": [
-        {
-          "ticker": "USDT",
-          "max": 100000,
-          "min": 1
-        }
-      ]
-    }
+    "rule": [
+      {
+        "exchange": "BINANCE",
+        "network": "BEP20",
+        "whitelist": ["0x9d467fa9062b6e9b1a46e26007ad82db116c67cb"]
+      },
+      {
+        "exchange": "BINANCE",
+        "network": "ARBITRUM",
+        "whitelist": ["0x9d467fa9062b6e9b1a46e26007ad82db116c67cb"]
+      }
+    ]
   }
 }
 ```
@@ -572,6 +619,7 @@ bun run check
 
 ### Core Dependencies
 
+- `@opentelemetry/*`: OpenTelemetry API, SDK metrics, OTLP HTTP exporter for metrics
 - `@grpc/grpc-js`: gRPC server implementation
 - `@grpc/proto-loader`: Protocol buffer loading
 - `@usherlabs/ccxt`: Enhanced CCXT library with Verity support