Runtime Connector Configuration

AxonFlow supports runtime connector configuration with automatic cache management, enabling dynamic changes without service restarts. This guide covers the configuration system and cache management APIs.

Overview

AxonFlow uses a three-tier configuration hierarchy for connectors:

Priority	Source	Use Case
1 (Highest)	Database	Enterprise: Customer Portal-managed configs
2	Config File	Community: YAML/JSON file at startup
3 (Lowest)	Environment Variables	Backward compatibility fallback

Higher-priority sources override lower ones, allowing flexible deployment options.

Configuration Sources

Environment Variables (Priority 3)

The simplest approach, suitable for Docker/Kubernetes deployments:

# PostgreSQL connector
export POSTGRES_HOST=db.example.com
export POSTGRES_PORT=5432
export POSTGRES_USER=myuser
export POSTGRES_PASSWORD=mypassword
export POSTGRES_DATABASE=mydb

# MySQL connector
export MYSQL_HOST=mysql.example.com
export MYSQL_PORT=3306
export MYSQL_USER=myuser
export MYSQL_PASSWORD=mypassword
export MYSQL_DATABASE=mydb

Config File (Priority 2)

For more complex configurations, use a YAML or JSON config file:

# axonflow.yaml
version: "1.0"

connectors:
  customer_db:
    type: postgres
    enabled: true
    display_name: "Customer Database"
    connection_url: postgres://db.example.com:5432/customers
    credentials:
      username: readonly
      password: ${DB_PASSWORD}
    options:
      max_open_conns: 10
    timeout_ms: 30000

  analytics_db:
    type: mysql
    enabled: true
    connection_url: mysql://analytics.example.com:3306/metrics
    credentials:
      username: analytics_user
      password: ${ANALYTICS_DB_PASSWORD}

  cache:
    type: redis
    enabled: true
    connection_url: redis://redis.example.com:6379
    options:
      db: 0

llm_providers:
  openai:
    enabled: true
    credentials:
      api_key: ${OPENAI_API_KEY}

Set the config file path:

export AXONFLOW_CONFIG_FILE=/etc/axonflow/axonflow.yaml

AxonFlow also checks these default locations automatically:

• ./axonflow.yaml
• ./config/axonflow.yaml
• /etc/axonflow/axonflow.yaml

Database (Priority 1 - Enterprise)

Enterprise deployments can manage connector configurations through the Customer Portal, storing them in the database. See the Enterprise Overview for details on enterprise features.

Connector Cache

AxonFlow caches connector instances for performance. The cache uses a 30-second TTL by default.

Cache Behavior

1. First Request: Loads configuration, creates connector instance, caches it
2. Subsequent Requests: Returns cached connector (fast path)
3. After TTL: Next request triggers config reload if changed
4. Manual Refresh: API endpoints for immediate cache invalidation

Cache Configuration

# Cache TTL (default: 30s)
export CONNECTOR_CACHE_TTL=30s

# Disable dynamic loading (use static registration only)
export ENABLE_DYNAMIC_CONNECTORS=false

Cache Management API

AxonFlow provides REST endpoints for manual cache management.

Refresh All Connectors

Clear all cached connectors across all tenants:

curl -X POST https://agent.example.com/api/v1/connectors/refresh \
  -H "X-License-Key: your-license-key"

Response:

{
  "success": true,
  "message": "All connector caches refreshed",
  "scope": "all",
  "duration": "12.345ms",
  "stats": {
    "cached_connectors": 0,
    "hits": 12345,
    "misses": 234,
    "evictions": 15,
    "hit_rate_percent": 98.1
  }
}

Refresh Tenant Connectors

Clear cached connectors for a specific tenant:

curl -X POST https://agent.example.com/api/v1/connectors/refresh/tenant-123 \
  -H "X-License-Key: your-license-key"

Refresh Specific Connector

Clear a single connector cache entry:

curl -X POST https://agent.example.com/api/v1/connectors/refresh/tenant-123/customer-db \
  -H "X-License-Key: your-license-key"

Get Cache Statistics

Monitor cache health and performance:

curl https://agent.example.com/api/v1/connectors/cache/stats \
  -H "X-License-Key: your-license-key"

Response:

{
  "cached_connectors": 15,
  "hits": 12345,
  "misses": 234,
  "evictions": 12,
  "factory_creations": 246,
  "factory_failures": 0,
  "connection_errors": 2,
  "hit_rate_percent": 98.1,
  "last_eviction": "2025-12-09T10:30:00Z",
  "registry_enabled": true,
  "timestamp": "2025-12-09T14:25:00Z"
}

Monitoring

Prometheus Metrics

Metric	Type	Description
axonflow_connector_refresh_total	Counter	Total refresh operations by scope and status
axonflow_connector_refresh_duration_seconds	Histogram	Refresh operation latency
axonflow_connector_cache_stats	Gauge	Cache statistics (hits, misses, etc.)
axonflow_tenant_connector_operations_total	Counter	Registry operations
axonflow_tenant_connector_cache_size	Gauge	Current cache size

Useful PromQL Queries

# Cache hit rate
sum(rate(axonflow_connector_cache_stats{stat="hits"}[5m])) /
(sum(rate(axonflow_connector_cache_stats{stat="hits"}[5m])) +
 sum(rate(axonflow_connector_cache_stats{stat="misses"}[5m])))

# Refresh latency P95
histogram_quantile(0.95, rate(axonflow_connector_refresh_duration_seconds_bucket[5m]))

Recommended Alerts

# Alert if cache hit rate drops below 85%
- alert: ConnectorCacheHitRateLow
  expr: axonflow_connector_cache_stats{stat="hit_rate"} < 85
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "Connector cache hit rate below 85%"

# Alert on factory failures
- alert: ConnectorFactoryFailures
  expr: increase(axonflow_tenant_connector_operations_total{operation="factory_create",status="error"}[5m]) > 5
  for: 2m
  labels:
    severity: critical
  annotations:
    summary: "Multiple connector factory failures detected"

Configuration Updates

Updating Config File

1. Edit the config file
2. Validate YAML syntax:

   python3 -c "import yaml; yaml.safe_load(open('axonflow.yaml'))"

3. Wait for automatic reload (30-second TTL), OR refresh immediately:

   curl -X POST https://agent.example.com/api/v1/connectors/refresh

Credential Rotation

1. Update credentials in AWS Secrets Manager:

   aws secretsmanager update-secret \
     --secret-id "axonflow/connectors/customer-db" \
     --secret-string '{"username": "newuser", "password": "newpass"}'

2. Refresh the connector cache:

   curl -X POST https://agent.example.com/api/v1/connectors/refresh/tenant-123/customer-db

3. Verify connectivity with a test query

Troubleshooting

High Cache Miss Rate

Symptoms: Slow response times, high factory_creations count

Resolution:

• Increase cache TTL if config changes are rare
• Pre-warm cache with test queries to frequently-used connectors

Stale Configuration

Symptoms: Connector using old credentials after update

Resolution:

1. Verify the config file/database was updated
2. Force refresh:

   curl -X POST https://agent.example.com/api/v1/connectors/refresh

3. Check logs for successful reload

Factory Failures

Symptoms: factory_failures > 0 in stats

Resolution:

1. Check connector configuration for errors
2. Verify network connectivity to external systems
3. Validate credentials are not expired
4. Review agent logs for detailed error messages

Related Documentation

• MCP Connectors Overview - Connector types and capabilities
• Config File Reference - Full config file syntax
• Connector SDK - Building custom connectors