[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
    },
    "result": { "success": true },
    "latencyMs": 1200
  }
  

• 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" }

---

Query Methods (Exported Functions)

The analytics worker exports query functions that are called via Service Bindings (not HTTP). Each builds a SQL query and executes it against the Cloudflare Analytics Engine SQL API:

All SQL queries are built via sanitizeQueryInputs() which validates parameters using allowlists and regex to prevent SQL injection.

---

4. Dashboard Visual Integrations

The metrics written to hoox-analytics are queried by the dashboard to render:

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.