vectra-client 0.3.0 → 0.3.2

data/docs/guides/runbooks/cache-issues.md

@@ -0,0 +1,267 @@
+---
+layout: page
+title: "Runbook: Cache Issues"
+permalink: /guides/runbooks/cache-issues/
+---
+
+# Runbook: Cache Issues
+
+**Alert:** `VectraLowCacheHitRatio`  
+**Severity:** Warning  
+**Threshold:** Cache hit ratio <50% for 10 minutes
+
+## Symptoms
+
+- High cache miss rate
+- Increased database load
+- Higher latency than expected
+- Stale data being returned
+
+## Quick Diagnosis
+
+```ruby
+cache = Vectra::Cache.new
+stats = cache.stats
+
+puts "Size: #{stats[:size]} / #{stats[:max_size]}"
+puts "TTL: #{stats[:ttl]} seconds"
+puts "Keys: #{stats[:keys].count}"
+```
+
+```promql
+# Prometheus: Check hit ratio
+sum(vectra_cache_hits_total) / 
+(sum(vectra_cache_hits_total) + sum(vectra_cache_misses_total))
+```
+
+## Investigation Steps
+
+### 1. Check Cache Configuration
+
+```ruby
+# Current config
+puts Vectra.configuration.cache_enabled    # Should be true
+puts Vectra.configuration.cache_ttl        # Default: 300
+puts Vectra.configuration.cache_max_size   # Default: 1000
+```
+
+### 2. Analyze Access Patterns
+
+```ruby
+# Check what's being cached
+cache.stats[:keys].each do |key|
+  parts = key.split(":")
+  puts "Index: #{parts[0]}, Type: #{parts[1]}"
+end
+
+# Count by type
+keys = cache.stats[:keys]
+queries = keys.count { |k| k.include?(":q:") }
+fetches = keys.count { |k| k.include?(":f:") }
+puts "Query cache entries: #{queries}"
+puts "Fetch cache entries: #{fetches}"
+```
+
+### 3. Check for Cache Thrashing
+
+```ruby
+# If max_size is too small, cache thrashes
+# Sign: entries being evicted immediately after creation
+# Solution: Increase max_size
+
+stats = cache.stats
+if stats[:size] >= stats[:max_size] * 0.9
+  puts "WARNING: Cache near capacity - consider increasing max_size"
+end
+```
+
+### 4. Check TTL Appropriateness
+
+```ruby
+# If TTL is too short, cache misses are high
+# If TTL is too long, stale data is served
+
+# Check data freshness requirements
+# - Real-time data: TTL 30-60s
+# - Semi-static data: TTL 300-600s
+# - Static data: TTL 3600s+
+```
+
+## Resolution Steps
+
+### Low Hit Ratio
+
+#### Increase Cache Size
+
+```ruby
+cache = Vectra::Cache.new(
+  ttl: 300,
+  max_size: 5000  # Increase from 1000
+)
+cached_client = Vectra::CachedClient.new(client, cache: cache)
+```
+
+#### Adjust TTL
+
+```ruby
+# For high-churn data
+cache = Vectra::Cache.new(ttl: 60)  # 1 minute
+
+# For stable data  
+cache = Vectra::Cache.new(ttl: 3600)  # 1 hour
+```
+
+#### Cache Warming
+
+```ruby
+# Pre-populate cache on startup
+common_queries = load_common_queries()
+common_queries.each do |q|
+  cached_client.query(
+    index: q[:index],
+    vector: q[:vector],
+    top_k: q[:top_k]
+  )
+end
+```
+
+### Stale Data
+
+#### Reduce TTL
+
+```ruby
+cache = Vectra::Cache.new(ttl: 60)  # Reduce from 300
+```
+
+#### Implement Cache Invalidation
+
+```ruby
+# After upsert, invalidate affected cache
+def upsert_with_invalidation(index:, vectors:)
+  result = client.upsert(index: index, vectors: vectors)
+  cached_client.invalidate_index(index)
+  result
+end
+```
+
+#### Use Cache-Aside Pattern
+
+```ruby
+def get_vector(id)
+  # Check cache first
+  cached = cache.get("vector:#{id}")
+  return cached if cached
+
+  # Fetch from source
+  vector = client.fetch(index: "main", ids: [id])[id]
+  
+  # Cache with appropriate TTL
+  cache.set("vector:#{id}", vector)
+  vector
+end
+```
+
+### Cache Thrashing
+
+#### Increase Max Size
+
+```ruby
+# Rule of thumb: max_size = unique_queries_per_ttl * 1.5
+# Example: 1000 unique queries per 5 min, max_size = 1500
+cache = Vectra::Cache.new(
+  ttl: 300,
+  max_size: 1500
+)
+```
+
+#### Implement Tiered Caching
+
+```ruby
+# Hot cache: Small, short TTL
+hot_cache = Vectra::Cache.new(ttl: 60, max_size: 100)
+
+# Warm cache: Large, longer TTL
+warm_cache = Vectra::Cache.new(ttl: 600, max_size: 5000)
+
+# Check hot first, then warm
+def cached_query(...)
+  hot_cache.fetch(key) do
+    warm_cache.fetch(key) do
+      client.query(...)
+    end
+  end
+end
+```
+
+### Memory Issues
+
+#### Monitor Memory Usage
+
+```ruby
+# Estimate cache memory usage
+# Approximate: 1KB per cached query result
+estimated_mb = cache.stats[:size] * 1.0 / 1000
+puts "Estimated cache memory: #{estimated_mb} MB"
+```
+
+#### Implement LRU Eviction
+
+```ruby
+# Vectra::Cache already implements LRU
+# If memory is still an issue, reduce max_size
+cache = Vectra::Cache.new(max_size: 500)
+```
+
+## Prevention
+
+### 1. Right-size Cache
+
+```ruby
+# Calculate based on query patterns
+unique_queries_per_minute = 100
+ttl_minutes = 5
+buffer = 1.5
+
+max_size = unique_queries_per_minute * ttl_minutes * buffer
+# = 100 * 5 * 1.5 = 750
+```
+
+### 2. Monitor Cache Metrics
+
+```promql
+# Alert on low hit ratio
+sum(rate(vectra_cache_hits_total[5m])) /
+(sum(rate(vectra_cache_hits_total[5m])) + 
+ sum(rate(vectra_cache_misses_total[5m]))) < 0.5
+```
+
+### 3. Implement Cache Warm-up
+
+```ruby
+# In application boot
+Rails.application.config.after_initialize do
+  VectraCacheWarmer.perform_async
+end
+```
+
+### 4. Use Cache Namespacing
+
+```ruby
+# Separate caches for different use cases
+search_cache = Vectra::Cache.new(ttl: 60)   # Fast invalidation
+embed_cache = Vectra::Cache.new(ttl: 3600)  # Long-lived embeddings
+```
+
+## Escalation
+
+| Time | Action |
+|------|--------|
+| 10 min | Adjust TTL/max_size |
+| 30 min | Implement cache warming |
+| 1 hour | Review access patterns |
+| 2 hours | Consider Redis/Memcached |
+
+## Related
+
+- [Performance Guide]({{ site.baseurl }}/guides/performance)
+- [Monitoring Guide]({{ site.baseurl }}/guides/monitoring)

data/docs/guides/runbooks/high-error-rate.md

@@ -0,0 +1,152 @@
+---
+layout: page
+title: "Runbook: High Error Rate"
+permalink: /guides/runbooks/high-error-rate/
+---
+
+# Runbook: High Error Rate
+
+**Alert:** `VectraHighErrorRate`  
+**Severity:** Critical  
+**Threshold:** Error rate >5% for 5 minutes
+
+## Symptoms
+
+- Alert firing for high error rate
+- Users reporting failed operations
+- Increased latency alongside errors
+
+## Quick Diagnosis
+
+```bash
+# Check recent errors in logs
+grep -i "vectra.*error" /var/log/app.log | tail -50
+
+# Check error breakdown by type
+curl -s localhost:9090/api/v1/query?query=sum(vectra_errors_total)by(error_type) | jq
+```
+
+## Investigation Steps
+
+### 1. Identify Error Type
+
+```ruby
+# In Rails console
+Vectra::Client.new.stats(index: "your-index")
+```
+
+| Error Type | Likely Cause | Action |
+|------------|--------------|--------|
+| `AuthenticationError` | Invalid/expired API key | Check credentials |
+| `RateLimitError` | Too many requests | Implement backoff |
+| `ServerError` | Provider outage | Check provider status |
+| `ConnectionError` | Network issues | Check connectivity |
+| `ValidationError` | Bad request data | Check input validation |
+
+### 2. Check Provider Status
+
+- **Pinecone:** [status.pinecone.io](https://status.pinecone.io)
+- **Qdrant:** Check self-hosted logs or cloud dashboard
+- **pgvector:** `SELECT * FROM pg_stat_activity WHERE state = 'active';`
+
+### 3. Check Application Logs
+
+```bash
+# Filter by error class
+grep "Vectra::RateLimitError" /var/log/app.log | wc -l
+grep "Vectra::ServerError" /var/log/app.log | wc -l
+grep "Vectra::AuthenticationError" /var/log/app.log | wc -l
+```
+
+## Resolution Steps
+
+### Authentication Errors
+
+```ruby
+# Verify API key is set
+puts ENV['PINECONE_API_KEY'].nil? ? "MISSING" : "SET"
+
+# Test connection
+client = Vectra::Client.new
+client.list_indexes
+```
+
+### Rate Limit Errors
+
+```ruby
+# Implement exponential backoff
+Vectra.configure do |config|
+  config.max_retries = 5
+  config.retry_delay = 2  # Start with 2s delay
+end
+
+# Or use batch operations with concurrency limit
+batch = Vectra::Batch.new(client, concurrency: 2)  # Reduce from 4
+```
+
+### Server Errors
+
+1. Check provider status page
+2. If provider is down, enable fallback or circuit breaker
+3. Consider failover to backup provider
+
+```ruby
+# Simple circuit breaker
+class VectraCircuitBreaker
+  def self.call
+    return cached_response if circuit_open?
+    
+    yield
+  rescue Vectra::ServerError
+    open_circuit!
+    cached_response
+  end
+end
+```
+
+### Connection Errors
+
+```bash
+# Test network connectivity
+curl -I https://api.pinecone.io/health
+
+# Check DNS resolution
+nslookup api.pinecone.io
+
+# Check firewall rules
+iptables -L -n | grep -i pinecone
+```
+
+## Prevention
+
+1. **Set up retry logic:**
+   ```ruby
+   config.max_retries = 3
+   config.retry_delay = 1
+   ```
+
+2. **Monitor error rate trends:**
+   ```promql
+   increase(vectra_errors_total[1h])
+   ```
+
+3. **Implement circuit breakers** for provider outages
+
+4. **Cache frequently accessed data:**
+   ```ruby
+   cached_client = Vectra::CachedClient.new(client)
+   ```
+
+## Escalation
+
+| Time | Action |
+|------|--------|
+| 5 min | Page on-call engineer |
+| 15 min | Escalate to team lead |
+| 30 min | Consider provider failover |
+| 1 hour | Engage provider support |
+
+## Related
+
+- [High Latency Runbook]({{ site.baseurl }}/guides/runbooks/high-latency)
+- [Monitoring Guide]({{ site.baseurl }}/guides/monitoring)

data/docs/guides/runbooks/high-latency.md

@@ -0,0 +1,287 @@
+---
+layout: page
+title: "Runbook: High Latency"
+permalink: /guides/runbooks/high-latency/
+---
+
+# Runbook: High Latency
+
+**Alert:** `VectraHighLatency`  
+**Severity:** Warning  
+**Threshold:** P95 latency >2s for 5 minutes
+
+## Symptoms
+
+- Slow vector operations
+- Request timeouts
+- User-facing latency issues
+- Queue backlog building up
+
+## Quick Diagnosis
+
+```promql
+# Check current latency by operation
+histogram_quantile(0.95, 
+  sum(rate(vectra_request_duration_seconds_bucket[5m])) by (le, operation)
+)
+```
+
+```ruby
+# Test latency in console
+require 'benchmark'
+
+time = Benchmark.realtime do
+  client.query(index: "test", vector: [0.1] * 384, top_k: 10)
+end
+puts "Query latency: #{(time * 1000).round}ms"
+```
+
+## Investigation Steps
+
+### 1. Identify Slow Operations
+
+```promql
+# Which operations are slow?
+topk(5, 
+  histogram_quantile(0.95, 
+    sum(rate(vectra_request_duration_seconds_bucket[5m])) by (le, operation)
+  )
+)
+```
+
+| Operation | Expected P95 | Alert Threshold |
+|-----------|--------------|-----------------|
+| query | <500ms | >2s |
+| upsert (single) | <200ms | >1s |
+| upsert (batch 100) | <2s | >5s |
+| fetch | <100ms | >500ms |
+| delete | <200ms | >1s |
+
+### 2. Check Provider Status
+
+```bash
+# Test provider connectivity
+curl -w "@curl-format.txt" -o /dev/null -s https://api.pinecone.io/health
+
+# curl-format.txt:
+# time_namelookup: %{time_namelookup}\n
+# time_connect: %{time_connect}\n
+# time_starttransfer: %{time_starttransfer}\n
+# time_total: %{time_total}\n
+```
+
+### 3. Check Network Latency
+
+```bash
+# Ping provider endpoint
+ping -c 10 api.pinecone.io
+
+# Check for packet loss
+mtr api.pinecone.io
+
+# DNS resolution time
+time nslookup api.pinecone.io
+```
+
+### 4. Check Vector Dimensions
+
+```ruby
+# Large vectors = slower operations
+client.describe_index(index: "my-index")
+# => { dimension: 1536, ... }
+
+# Consider using smaller embeddings:
+# - text-embedding-3-small: 512-1536 dims
+# - text-embedding-ada-002: 1536 dims
+# - all-MiniLM-L6-v2: 384 dims (faster!)
+```
+
+### 5. Check Index Size
+
+```ruby
+stats = client.stats(index: "my-index")
+puts "Vector count: #{stats[:total_vector_count]}"
+puts "Index fullness: #{stats[:index_fullness]}"
+
+# Large indexes may need optimization
+# - Pinecone: Check pod type
+# - pgvector: Check IVFFlat parameters
+# - Qdrant: Check HNSW parameters
+```
+
+## Resolution Steps
+
+### Immediate: Increase Timeouts
+
+```ruby
+Vectra.configure do |config|
+  config.timeout = 60       # Increase from 30
+  config.open_timeout = 20  # Increase from 10
+end
+```
+
+### Enable Caching
+
+```ruby
+cache = Vectra::Cache.new(ttl: 300, max_size: 1000)
+cached_client = Vectra::CachedClient.new(client, cache: cache)
+
+# Repeat queries will be instant
+```
+
+### Optimize Batch Operations
+
+```ruby
+# Use smaller batches for faster responses
+batch = Vectra::Batch.new(client, concurrency: 2)
+
+result = batch.upsert_async(
+  index: "my-index",
+  vectors: vectors,
+  chunk_size: 50  # Smaller chunks = faster individual operations
+)
+```
+
+### Reduce top_k
+
+```ruby
+# Fewer results = faster query
+results = client.query(
+  index: "my-index",
+  vector: query_vec,
+  top_k: 5  # Instead of 100
+)
+```
+
+### Provider-Specific Optimizations
+
+#### Pinecone
+
+```ruby
+# Use serverless for auto-scaling
+# Or upgrade pod type for more capacity
+```
+
+#### pgvector
+
+```sql
+-- Check if index exists
+SELECT indexname FROM pg_indexes WHERE tablename = 'your_table';
+
+-- Create IVFFlat index for faster queries
+CREATE INDEX ON your_table 
+USING ivfflat (embedding vector_cosine_ops)
+WITH (lists = 100);
+
+-- Increase probes for accuracy vs speed trade-off
+SET ivfflat.probes = 10;  -- Default: 1
+```
+
+#### Qdrant
+
+```ruby
+# Optimize HNSW parameters
+client.provider.create_index(
+  name: "optimized",
+  dimension: 384,
+  metric: "cosine",
+  hnsw_config: {
+    m: 16,           # Connections per node
+    ef_construct: 100 # Build-time accuracy
+  }
+)
+```
+
+### Connection Pooling (pgvector)
+
+```ruby
+# Warmup connections to avoid cold start latency
+client.provider.warmup_pool(5)
+
+# Increase pool size for parallel queries
+Vectra.configure do |config|
+  config.pool_size = 20
+end
+```
+
+## Prevention
+
+### 1. Monitor Latency Trends
+
+```promql
+# Alert on increasing latency trend
+rate(vectra_request_duration_seconds_sum[1h]) /
+rate(vectra_request_duration_seconds_count[1h]) > 1
+```
+
+### 2. Implement Request Timeouts
+
+```ruby
+# Fail fast instead of hanging
+Vectra.configure do |config|
+  config.timeout = 10  # Strict timeout
+end
+```
+
+### 3. Use Async Operations
+
+```ruby
+# Don't block on upserts
+Thread.new do
+  batch.upsert_async(index: "bg-index", vectors: vectors)
+end
+```
+
+### 4. Index Maintenance
+
+```sql
+-- pgvector: Reindex periodically
+REINDEX INDEX your_ivfflat_index;
+
+-- Analyze for query planner
+ANALYZE your_table;
+```
+
+### 5. Geographic Optimization
+
+```ruby
+# Use closest region to your servers
+# Pinecone: us-east-1, us-west-2, eu-west-1
+# Qdrant Cloud: Select nearest region
+```
+
+## Benchmarking
+
+```ruby
+# Run benchmark to establish baseline
+require 'benchmark'
+
+results = Benchmark.bm do |x|
+  x.report("query") do
+    100.times { client.query(index: "test", vector: vec, top_k: 10) }
+  end
+  
+  x.report("upsert") do
+    client.upsert(index: "test", vectors: vectors_100)
+  end
+  
+  x.report("fetch") do
+    100.times { client.fetch(index: "test", ids: ["id1"]) }
+  end
+end
+```
+
+## Escalation
+
+| Time | Action |
+|------|--------|
+| 5 min | Enable caching, increase timeouts |
+| 15 min | Check provider status, optimize queries |
+| 30 min | Scale up provider resources |
+| 1 hour | Engage provider support |
+
+## Related
+
+- [High Error Rate Runbook]({{ site.baseurl }}/guides/runbooks/high-error-rate)
+- [Performance Guide]({{ site.baseurl }}/guides/performance)
+- [Monitoring Guide]({{ site.baseurl }}/guides/monitoring)