Cache Management - NeuraTrade

Overview

Cache management endpoints provide visibility into Redis cache performance, hit/miss rates, and memory usage. These endpoints help optimize caching strategies and diagnose performance issues.

GET /api/v1/cache/stats

Get cache statistics for all categories.

Request

curl http://localhost:3000/api/v1/cache/stats

Response

success

boolean

required

Operation success indicator

data

object

required

Cache statistics grouped by category

Show data

[category]

object

Statistics for a specific cache category (e.g., market_data, funding_rates, exchanges, overall)

Show category stats

hits

integer

required

Number of cache hits for this category

misses

integer

required

Number of cache misses for this category

hit_rate

number

required

Cache hit rate as a decimal (0.0 to 1.0)

total_ops

integer

required

Total cache operations (hits + misses)

last_updated

string

required

ISO 8601 timestamp of last statistic update

Cache Categories

Common cache categories tracked by NeuraTrade:

market_data - Ticker prices, trading pairs, market summaries
funding_rates - Futures funding rate data
exchanges - Exchange configuration and capabilities
orderbook - Order book snapshots
technical_analysis - Indicator calculations (RSI, MACD, etc.)
overall - Aggregated stats across all categories

Example Response

{
  "success": true,
  "data": {
    "overall": {
      "hits": 15420,
      "misses": 1230,
      "hit_rate": 0.926,
      "total_ops": 16650,
      "last_updated": "2026-03-03T14:32:10Z"
    },
    "market_data": {
      "hits": 8920,
      "misses": 580,
      "hit_rate": 0.939,
      "total_ops": 9500,
      "last_updated": "2026-03-03T14:32:08Z"
    },
    "funding_rates": {
      "hits": 3200,
      "misses": 320,
      "hit_rate": 0.909,
      "total_ops": 3520,
      "last_updated": "2026-03-03T14:31:45Z"
    },
    "exchanges": {
      "hits": 2150,
      "misses": 50,
      "hit_rate": 0.977,
      "total_ops": 2200,
      "last_updated": "2026-03-03T14:30:12Z"
    }
  }
}

GET /api/v1/cache/stats/:category

Get cache statistics for a specific category.

Request

curl http://localhost:3000/api/v1/cache/stats/market_data

Path Parameters

Response

success

boolean

required

Operation success indicator

data

object

required

Cache statistics for the requested category

Show data

hits

integer

required

Number of cache hits

misses

integer

required

Number of cache misses

hit_rate

number

required

Cache hit rate (0.0 to 1.0)

total_ops

integer

required

Total cache operations

last_updated

string

required

ISO 8601 timestamp of last update

Error Responses

400 Bad Request: Category parameter is missing

Example Response

{
  "success": true,
  "data": {
    "hits": 8920,
    "misses": 580,
    "hit_rate": 0.939,
    "total_ops": 9500,
    "last_updated": "2026-03-03T14:32:08Z"
  }
}

GET /api/v1/cache/metrics

Get comprehensive cache metrics including Redis server information.

Request

curl http://localhost:3000/api/v1/cache/metrics

Response

success

boolean

required

Operation success indicator

data

object

required

Comprehensive cache metrics

Show data

overall

object

required

Aggregated statistics across all categories

by_category

object

required

Statistics grouped by cache category

redis_info

object

Raw Redis INFO output with memory, clients, and keyspace data

Show redis_info

used_memory

string

Memory used by Redis (human-readable format)

used_memory_peak

string

Peak memory usage

connected_clients

string

Number of connected clients

total_commands_processed

string

Total commands processed since server start

instantaneous_ops_per_sec

string

Current operations per second

memory_usage_bytes

integer

Redis memory usage in bytes

connected_clients

integer

Number of connected Redis clients

key_count

integer

Total number of keys in Redis database

Error Responses

500 Internal Server Error: Failed to retrieve cache metrics from Redis

This endpoint performs multiple Redis operations (INFO, MEMORY USAGE, CLIENT LIST, DBSIZE) and may take longer to respond than simple stats endpoints.

Example Response

{
  "success": true,
  "data": {
    "overall": {
      "hits": 15420,
      "misses": 1230,
      "hit_rate": 0.926,
      "total_ops": 16650,
      "last_updated": "2026-03-03T14:32:10Z"
    },
    "by_category": {
      "market_data": {
        "hits": 8920,
        "misses": 580,
        "hit_rate": 0.939,
        "total_ops": 9500,
        "last_updated": "2026-03-03T14:32:08Z"
      },
      "funding_rates": {
        "hits": 3200,
        "misses": 320,
        "hit_rate": 0.909,
        "total_ops": 3520,
        "last_updated": "2026-03-03T14:31:45Z"
      }
    },
    "redis_info": {
      "used_memory": "45678912",
      "used_memory_human": "43.56M",
      "used_memory_peak": "52428800",
      "connected_clients": "12",
      "total_commands_processed": "892456",
      "instantaneous_ops_per_sec": "342"
    },
    "memory_usage_bytes": 45678912,
    "connected_clients": 12,
    "key_count": 3456
  }
}

POST /api/v1/cache/stats/reset

Admin Only - Reset all cache statistics to zero.

Request

curl -X POST http://localhost:3000/api/v1/cache/stats/reset

Response

success

boolean

required

Operation success indicator

message

string

required

Success message

Example Response

{
  "success": true,
  "message": "Cache statistics reset successfully"
}

Resetting cache statistics does NOT clear the actual cache data in Redis. It only resets the hit/miss counters. To clear cache data, use Redis FLUSHDB or delete specific keys.

POST /api/v1/cache/hit

Testing Only - Manually record cache hits for testing purposes.

Request

curl -X POST "http://localhost:3000/api/v1/cache/hit?category=market_data&count=10"

Query Parameters

Response

success

boolean

required

Operation success indicator

message

string

required

Success message

count

integer

required

Number of hits recorded

Error Responses

400 Bad Request: Category parameter is missing

Example Response

{
  "success": true,
  "message": "Cache hits recorded successfully",
  "count": 10
}

POST /api/v1/cache/miss

Testing Only - Manually record cache misses for testing purposes.

Request

curl -X POST "http://localhost:3000/api/v1/cache/miss?category=market_data&count=5"

Query Parameters

Response

success

boolean

required

Operation success indicator

message

string

required

Success message

count

integer

required

Number of misses recorded

Error Responses

400 Bad Request: Category parameter is missing

Example Response

{
  "success": true,
  "message": "Cache misses recorded successfully",
  "count": 5
}

The /cache/hit and /cache/miss endpoints are intended for testing and development. They allow simulation of cache behavior without triggering actual cache operations.

Cache Analytics Strategy

Automatic Tracking

The cache analytics service automatically tracks hit/miss rates when:

Market data is fetched from Redis cache
Funding rate queries check the cache
Exchange configuration is retrieved
Technical indicator results are cached

Performance Optimization

Recommended cache hit rate targets:

Market Data: > 90% (data changes frequently but is queried more often)
Funding Rates: > 85% (updates every 8 hours for most exchanges)
Exchange Config: > 95% (rarely changes, heavily cached)
Order Books: > 70% (high volatility, shorter TTL)

TTL Configuration

Default cache TTL by category:

exchange:config: 1 hour
exchange:supported: 30 minutes
market:ticker: 5 seconds
market:funding: 5 minutes
cache:analytics:stats: 24 hours (self-reporting)

Monitoring Best Practices

Track Hit Rates: Monitor /api/v1/cache/stats to identify categories with low hit rates
Memory Usage: Use /api/v1/cache/metrics to watch Redis memory consumption
Key Count Growth: Alert on unexpected key count increases (potential memory leak)
Client Connections: Monitor connected_clients to detect connection leaks

Source Reference

Cache endpoints are implemented in:

Handler: services/backend-api/internal/api/handlers/cache.go:48-231
Service: services/backend-api/internal/services/cache_analytics.go:15-343
Route Registration: services/backend-api/internal/api/routes.go:1163-1171

Overview

Market Data

Trading

Arbitrage

Analysis

Autonomous Operations

System

​Overview

​GET /api/v1/cache/stats

​Request

​Response

​Cache Categories

​Example Response

​GET /api/v1/cache/stats/:category

​Request

​Path Parameters

​Response

​Error Responses

​Example Response

​GET /api/v1/cache/metrics

​Request

​Response

​Error Responses

​Example Response

​POST /api/v1/cache/stats/reset

​Request

​Response

​Example Response

​POST /api/v1/cache/hit

​Request

​Query Parameters

​Response

​Error Responses

​Example Response

​POST /api/v1/cache/miss

​Request

​Query Parameters

​Response

​Error Responses

​Example Response

​Cache Analytics Strategy

​Automatic Tracking

​Performance Optimization

​TTL Configuration

​Monitoring Best Practices

​Source Reference

Build docs developers (and LLMs) love

Overview

GET /api/v1/cache/stats

Request

Response

Cache Categories

Example Response

GET /api/v1/cache/stats/:category

Request

Path Parameters

Response

Error Responses

Example Response

GET /api/v1/cache/metrics

Request

Response

Error Responses

Example Response

POST /api/v1/cache/stats/reset

Request

Response

Example Response

POST /api/v1/cache/hit

Request

Query Parameters

Response

Error Responses

Example Response

POST /api/v1/cache/miss

Request

Query Parameters

Response

Error Responses

Example Response

Cache Analytics Strategy

Automatic Tracking

Performance Optimization

TTL Configuration

Monitoring Best Practices

Source Reference