analytics-worker Isolate Profile

The analytics-worker is the observability engine of the Hoox trading platform. Deployed as a private internal microservice, it aggregates time-series metrics, database query latencies, execution performance ratios, and API status codes across all V8 isolates. By translating incoming events and writing them to Cloudflare Analytics Engine, it provides the backend telemetry used to draw live charts in the Next.js Dashboard.

---

⚡ 1. Declared Wrangler Configurations & Bindings

The analytics-worker binds directly to Cloudflare’s Analytics Engine dataset and does not expose any public endpoints:

{
  "name": "analytics-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-04-17",
  "compatibility_flags": ["nodejs_compat"],
  "account_id": "debc6545e63bea36be059cbc82d80ec8",
  "analytics_engine_datasets": [
    {
      "binding": "ANALYTICS_ENGINE",
      "dataset": "hoox-analytics",
    },
  ],
  "placement": { "mode": "smart" },
  "observability": { "enabled": true, "head_sampling_rate": 1 },
}

No CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID are in secrets — these are set as vars in wrangler.jsonc and used for the Cloudflare SQL API query path.

---

🔑 2. Environmental Variables & Encrypted Secrets

• CLOUDFLARE_API_TOKEN (var): A secure token with Account.Analytics read permissions, allowing the worker to query stored datasets via the Cloudflare SQL API.
• CLOUDFLARE_ACCOUNT_ID (var): Your Cloudflare Account ID used in SQL API requests.

---

🔌 3. Internal REST API Specification

Note: For the canonical endpoint directory with full request/response examples across all workers, see /docs/devops/api/endpoints.

All endpoints are reachable via Cloudflare Service Bindings only (no public URL). Each endpoint validates its payload with a Zod schema using .strict() to reject unknown fields.

A. Track Trade Event

• Endpoint: POST /track/trade
• Payload:

  {'{'}
    "payload": {'{'}
      "exchange": "binance",
      "symbol": "BTCUSDT",
      "action": "LONG",
      "quantity": 0.5,
      "price": 68425.5,
      "test": true
    {'}'},
    "result": {'{'} "success": true {'}'},
    "latencyMs": 1200
  {'}'}
  

• Optional test: when true, the Analytics Engine exchange blob is written as binance:test (or bybit:test) so sandbox fills can be filtered separately from live volume. Omitted/false → plain exchange name.
• Response: { "success": true }

B. Track API Call Event

Invoked by other workers (like hoox or trade-worker) immediately upon completing an action.

• Endpoint: POST /track/api-call
• Payload:

  {'{'}
    "worker": "trade-worker",
    "endpoint": "/api/v3/order",
    "latencyMs": 250,
    "success": true
  {'}'}
  

Under-the-Hood Analytics Engine Write

The worker formats and writes a time-series data point to the hoox-analytics dataset:

env.ANALYTICS_ENGINE.writeDataPoint({
  blobs: ["api-call", "trade-worker", "success", "/api/v3/order", ""],
  doubles: [250, 0, 0],
  indexes: ["550e8400-e29b-41d4-a716-446655440000"],
});

• Response (200) : { "success": true }

C. Track Worker Performance

• Endpoint: POST /track/worker-perf
• Payload:

  {'{'}
    "data": {'{'}
      "worker": "trade-worker",
      "requests": 100,
      "errors": 0,
      "duration": 25000
    {'}'}
  {'}'}
  

D. Track Signal

• Endpoint: POST /track/signal
• Payload:

  {'{'}
    "data": {'{'}
      "source": "agent-worker",
      "type": "BUY",
      "symbol": "ETHUSDT",
      "confidence": 0.85
    {'}'}
  {'}'}
  

E. Track Notification

• Endpoint: POST /track/notification
• Payload:

  {'{'}
    "data": {'{'} "type": "trade_executed", "target": "telegram", "success": true {'}'}
  {'}'}
  

F. Health

• Endpoint: GET /health
• Response: { "status": "ok", "worker": "analytics-worker" }

---

Write-Path Validation & Safe Drop

• All /track/* bodies use Zod .strict() schemas (unknown fields rejected).
• Numbers must be finite and range-bounded; strings capped (default 256 chars).
• JSON body hard-capped at 64 KiB; invalid JSON → 400 (not 500).
• Blob/index values are truncated before writeDataPoint (max 256 / 96 chars; max 8 indexes).
• Fail-closed internal auth on every /track/* route (X-Internal-Auth-Key).
• Query path: Analytics Engine is write-only from this isolate. Dashboard aggregates and report inputs use D1 via d1-worker (bindings-over-REST). The REST SQL API query-builder was removed.

---

📈 4. Dashboard Visual Integrations

The metrics written to hoox-analytics (and related D1 rollups) feed:

1. System Health Indicators: Real-time error spikes trigger warning banners in under 2 seconds.
2. Isolate Latency Charts: Visual line graphs showing V8 processing speeds vs exchange API transit speeds.
3. Volume Load Heatmaps: Visualizes peak trading hours and signal traffic volumes globally.

---

🔗 Next Steps

• System Observability Guides — Deepen your understanding of time-series logging and metrics.
• trade-worker Profile — Review how execution latency details are generated and offloaded.