towerops/AGENT_NEXT_STEPS.md

Agent System - Next Steps

This document outlines the remaining work to complete the remote SNMP polling agent system.

Current Status

✅ Complete:

• Backend API with token authentication
• Agent management UI
• Organization/equipment-level configuration
• Rust agent architecture (compiles successfully)
• SQLite buffering
• Docker deployment files
• 401 tests passing

🔄 In Progress:

• SNMP library integration (simplified implementation)

Critical Path to Production

1. Complete SNMP Integration (Priority: HIGH)

Problem: The Rust snmp crate v0.2 API differs from the initially designed implementation. Current code compiles but returns errors for actual SNMP operations.

Options:

Option A: Complete snmp crate integration (Recommended)

Effort: 4-8 hours File: towerops-agent/src/snmp/client.rs

Research the correct snmp crate 0.2 API:

# In towerops-agent/
cargo doc --open --package snmp

Key methods to implement:

• SyncSession::new() - Create session
• session.get() or similar - Perform GET
• session.getnext() or similar - Perform GETNEXT (for WALK)
• Error handling for timeouts, auth failures

Reference: Check snmp crate examples and tests

Option B: Use alternative SNMP library

Effort: 6-12 hours

Alternatives:

• snmp-mp - More actively maintained
• snmp-parser - Lower level, more control
• rasn-snmp - ASN.1 based

Replace in Cargo.toml and reimplement client.rs.

Option C: Implement basic SNMP manually

Effort: 16-24 hours

Implement SNMPv1/v2c protocol directly:

• ASN.1 BER encoding/decoding
• UDP socket communication
• PDU construction

Not recommended - reinventing the wheel.

2. Integration Testing (Priority: HIGH)

Prerequisites: SNMP integration complete

Test Environment Setup:

1. Deploy test SNMP device (or use simulator)
2. Deploy Phoenix backend
3. Deploy Rust agent via Docker
4. Create agent token via UI
5. Assign test equipment to agent

Test Cases:

• Agent connects and authenticates
• Agent fetches configuration
• Agent polls sensors successfully
• Agent polls interfaces successfully
• Metrics appear in Phoenix database
• Threshold violations trigger events
• Agent survives API outage (test 24h buffering)
• Agent reconnects after network issues
• Heartbeat updates agent status

Duration: 1-2 days

3. Load & Performance Testing (Priority: MEDIUM)

Test Scenarios:

Scenario 1: Single Agent, Many Devices

• 100 devices
• 500 sensors
• 200 interfaces
• 60-second poll interval
• Monitor: Memory, CPU, database growth

Scenario 2: Many Agents

• 10 agents
• 10 devices each
• Concurrent polling
• Monitor: API performance, database connections

Scenario 3: Long-Running Stability

• 1 agent
• 50 devices
• Run for 7 days
• Monitor: Memory leaks, database size, errors

Duration: 3-5 days

4. Production Readiness (Priority: MEDIUM)

Docker Image:

• Build optimized image
• Publish to container registry
• Tag releases (v0.1.0, latest)
• Multi-architecture support (amd64, arm64)

Documentation:

• User guide with screenshots
• Troubleshooting guide
• Network/firewall requirements
• Upgrade procedure
• Disaster recovery

Monitoring:

• Grafana dashboard for agent health
• Alerts for offline agents
• Metrics on agent performance
• Database query for agent statistics

Duration: 2-3 days

Optional Enhancements

Phase 6: Advanced Features (Priority: LOW)

SNMPv3 Support

• User authentication
• Privacy encryption
• Configuration UI changes

Agent-Side Filtering

• Threshold checks in agent
• Reduce bandwidth for high-sensor-count equipment
• Configurable sampling rates

Equipment Polling Modes

• Add polling_mode enum: :server, :agent, :both
• Allows gradual migration
• Enables A/B testing

Agent Health Metrics

• CPU/memory usage
• Metrics queue depth
• Polling success rate
• Average latency per device

Quick Start Guide

For Development

1. Fix SNMP Integration (Start Here)

cd towerops-agent
cargo doc --open --package snmp
# Read documentation, update client.rs
cargo test

2. Test Locally

# Terminal 1: Start Phoenix
mix phx.server

# Terminal 2: Start agent
cd towerops-agent
cargo run -- \
  --api-url http://localhost:4000 \
  --token <your-test-token>

3. Create Test Agent

• Visit http://localhost:4000/orgs/:slug/agents
• Create agent, copy token
• Use token in step 2

For Production Deployment

1. Build Docker Image

cd towerops-agent
docker build -t towerops/agent:0.1.0 .
docker tag towerops/agent:0.1.0 towerops/agent:latest

2. Push to Registry

docker push towerops/agent:0.1.0
docker push towerops/agent:latest

3. Deploy to Customer

# Provide customer with docker-compose.yml
# They run:
docker-compose up -d

Estimated Timeline

Phase	Effort	Duration
SNMP Integration	4-8 hours	1 day
Integration Testing	16 hours	2 days
Load Testing	24 hours	3 days
Production Prep	16 hours	2 days
Total	60-68 hours	8-10 days

Success Criteria

The agent system is ready for production when:

• Agent authenticates with token successfully
• Agent fetches configuration from API
• Agent polls SNMP devices (sensors + interfaces)
• Metrics appear in database within 60 seconds
• Threshold violations trigger events
• Agent survives 24h API outage without data loss
• UI shows agent status (online/offline)
• Token revocation works immediately
• Agent uses <256 MB memory with 50 devices
• Docker image is <50 MB
• Load test: 100 devices, 500 sensors, 200 interfaces
• Stability test: 7 days continuous operation

Questions & Decisions Needed

1. SNMP Library Choice: Stick with snmp v0.2 or switch?
2. Release Strategy: Beta testing with select customers first?
3. Support Plan: How will customers get help with agent deployment?
4. Monitoring: What metrics should we track about agent usage?
5. Pricing: Does remote agent feature affect pricing tiers?

Resources

• Implementation Doc: /Users/graham/dev/towerops/AGENT_IMPLEMENTATION.md
• Agent README: /Users/graham/dev/towerops/towerops-agent/README.md
• SNMP Crate Docs: https://docs.rs/snmp/0.2.2/snmp/
• Original Plan: /Users/graham/.claude/plans/melodic-coalescing-truffle.md

Contact

For questions about this implementation:

• Review AGENT_IMPLEMENTATION.md for architecture details
• Check git history for context on specific changes
• All code follows project conventions in CLAUDE.md