# Configuration Guide
**Crate**: `cloudops-execution-engine`
Complete configuration reference for the Execution Engine.
---
## ExecutionConfig
Main configuration structure for the execution engine.
```rust
pub struct ExecutionConfig {
/// Default timeout in milliseconds
pub default_timeout_ms: u64,
/// Maximum allowed timeout in milliseconds
pub max_timeout_ms: u64,
/// Enable real-time output streaming
pub stream_output: bool,
/// Custom log directory (None = system temp dir)
pub log_dir: Option<PathBuf>,
/// Maximum concurrent executions (enforced via Semaphore)
pub max_concurrent_executions: usize,
/// Maximum executions to keep in memory
pub max_in_memory_executions: usize,
/// Auto-cleanup executions older than this (seconds)
pub execution_retention_secs: u64,
/// Enable automatic cleanup background task
pub enable_auto_cleanup: bool,
/// Maximum output to buffer per stream (bytes)
pub max_output_size_bytes: usize,
/// Truncate output if exceeded
pub truncate_large_output: bool,
/// How to handle oversized output
pub oversized_output_strategy: OversizedOutputStrategy,
}
pub enum OversizedOutputStrategy {
/// Truncate with warning marker
TruncateWithWarning,
/// Fail execution with error
FailExecution,
/// Stream to temporary file
StreamToFile,
}
```
---
## Default Configuration
```rust
impl Default for ExecutionConfig {
fn default() -> Self {
Self {
default_timeout_ms: 120_000, // 2 minutes
max_timeout_ms: 600_000, // 10 minutes
stream_output: true,
log_dir: None, // System temp dir
max_concurrent_executions: 100, // Semaphore-enforced
max_in_memory_executions: 1000, // Memory cleanup threshold
execution_retention_secs: 3600, // 1 hour
enable_auto_cleanup: true, // Auto cleanup background task
max_output_size_bytes: 10_485_760, // 10 MB per stream
truncate_large_output: true, // Truncate instead of fail
oversized_output_strategy: OversizedOutputStrategy::TruncateWithWarning,
}
}
}
```
**Usage:**
```rust
let config = ExecutionConfig::default();
let engine = ExecutionEngine::new(config);
```
---
## Configuration Options
### Timeout Settings
#### `default_timeout_ms`
Default timeout for commands that don't specify a timeout.
```rust
let config = ExecutionConfig {
default_timeout_ms: 300_000, // 5 minutes
..Default::default()
};
```
#### `max_timeout_ms`
Maximum allowed timeout. Commands exceeding this will be rejected.
```rust
let config = ExecutionConfig {
max_timeout_ms: 1_800_000, // 30 minutes
..Default::default()
};
```
### Output Streaming
#### `stream_output`
Enable/disable real-time output streaming via events.
```rust
let config = ExecutionConfig {
stream_output: true, // Enable streaming
..Default::default()
};
```
**When to disable:**
- Not using event handlers
- Performance-sensitive scenarios
- Only care about final result
### Log Directory
#### `log_dir`
Custom directory for execution logs.
```rust
let config = ExecutionConfig {
log_dir: Some(PathBuf::from("/var/log/cloudops")),
..Default::default()
};
```
**Default behavior (None):**
- Uses system temp directory
- Path: `/tmp/cloudops-executions/` on Unix
- Path: `C:\Users\{user}\AppData\Local\Temp\cloudops-executions\` on Windows
### Concurrency
#### `max_concurrent_executions`
Maximum number of parallel executions (enforced via `tokio::sync::Semaphore`).
```rust
let config = ExecutionConfig {
max_concurrent_executions: 20,
..Default::default()
};
```
**Implementation:**
- Uses Semaphore for concurrency limiting
- Executions block if limit is reached
- Prevents resource exhaustion from too many concurrent processes
---
### Memory Management
#### `max_in_memory_executions`
Maximum number of executions to keep in memory before triggering cleanup.
```rust
let config = ExecutionConfig {
max_in_memory_executions: 2000, // Keep 2000 executions
..Default::default()
};
```
**Default:** 1000 executions
**When to increase:**
- Long-running applications
- Need access to older execution history
- Sufficient memory available
**When to decrease:**
- Memory-constrained environments
- Short execution retention needs
#### `execution_retention_secs`
Auto-cleanup executions older than this duration (in seconds).
```rust
let config = ExecutionConfig {
execution_retention_secs: 7200, // 2 hours
..Default::default()
};
```
**Default:** 3600 seconds (1 hour)
**Common values:**
- `300` - 5 minutes (high-volume systems)
- `1800` - 30 minutes (typical)
- `3600` - 1 hour (default)
- `7200` - 2 hours (need longer history)
#### `enable_auto_cleanup`
Enable automatic background cleanup task.
```rust
let config = ExecutionConfig {
enable_auto_cleanup: true, // Enable cleanup
..Default::default()
};
```
**Default:** `true` (enabled)
**Behavior when enabled:**
- Background task runs every 5 minutes
- Removes executions older than `execution_retention_secs`
- Removes oldest executions if count exceeds `max_in_memory_executions`
- Logs cleanup activity
**When to disable:**
- Manual cleanup control needed
- Testing scenarios
- Very short-lived applications
---
### Output Management
#### `max_output_size_bytes`
Maximum output to buffer per stream (stdout/stderr).
```rust
let config = ExecutionConfig {
max_output_size_bytes: 52_428_800, // 50 MB
..Default::default()
};
```
**Default:** 10,485,760 bytes (10 MB)
**Common values:**
- `1_048_576` - 1 MB (strict limits)
- `10_485_760` - 10 MB (default, typical)
- `52_428_800` - 50 MB (large outputs)
- `104_857_600` - 100 MB (very large, use with caution)
#### `truncate_large_output`
Truncate output if size limit exceeded (alternative to failing).
```rust
let config = ExecutionConfig {
truncate_large_output: true, // Truncate instead of fail
..Default::default()
};
```
**Default:** `true`
**When true:**
- Output is truncated at limit
- Warning marker added to output
- Execution continues normally
**When false:**
- Execution fails with OversizedOutput error
- No output returned
#### `oversized_output_strategy`
How to handle output exceeding size limits.
```rust
let config = ExecutionConfig {
oversized_output_strategy: OversizedOutputStrategy::StreamToFile,
..Default::default()
};
```
**Default:** `OversizedOutputStrategy::TruncateWithWarning`
**Strategies:**
1. **TruncateWithWarning** (default)
- Truncate at limit
- Add `\n[... output truncated at 10MB ...]` marker
- Execution succeeds
2. **FailExecution**
- Fail with `ExecutionError::OversizedOutput`
- No output returned
- Use for strict size enforcement
3. **StreamToFile**
- Stream output to temporary file
- Return file path in result
- Use for very large outputs
**Example - Fail on large output:**
```rust
let config = ExecutionConfig {
max_output_size_bytes: 5_242_880, // 5 MB
truncate_large_output: false,
oversized_output_strategy: OversizedOutputStrategy::FailExecution,
..Default::default()
};
```
**Example - Stream to file:**
```rust
let config = ExecutionConfig {
max_output_size_bytes: 10_485_760, // 10 MB
oversized_output_strategy: OversizedOutputStrategy::StreamToFile,
..Default::default()
};
// Result includes file path
let result = engine.get_result(execution_id).await?;
if let Some(file_path) = result.output_file {
println!("Large output written to: {}", file_path);
}
```
---
## Configuration Examples
### Production Configuration
```rust
let config = ExecutionConfig {
default_timeout_ms: 300_000, // 5 minutes
max_timeout_ms: 1_800_000, // 30 minutes
stream_output: true,
log_dir: Some(PathBuf::from("/var/log/cloudops")),
max_concurrent_executions: 100,
max_in_memory_executions: 2000,
execution_retention_secs: 7200, // 2 hours
enable_auto_cleanup: true,
max_output_size_bytes: 52_428_800, // 50 MB
truncate_large_output: true,
oversized_output_strategy: OversizedOutputStrategy::TruncateWithWarning,
};
```
### Development Configuration
```rust
let config = ExecutionConfig {
default_timeout_ms: 60_000, // 1 minute
max_timeout_ms: 300_000, // 5 minutes
stream_output: true,
log_dir: None, // Use temp dir
max_concurrent_executions: 10,
max_in_memory_executions: 100,
execution_retention_secs: 1800, // 30 minutes
enable_auto_cleanup: true,
max_output_size_bytes: 10_485_760, // 10 MB
truncate_large_output: true,
oversized_output_strategy: OversizedOutputStrategy::TruncateWithWarning,
};
```
### Testing Configuration
```rust
let config = ExecutionConfig {
default_timeout_ms: 10_000, // 10 seconds
max_timeout_ms: 30_000, // 30 seconds
stream_output: false, // Disable streaming
log_dir: Some(PathBuf::from("/tmp/test-logs")),
max_concurrent_executions: 1, // Serial only
max_in_memory_executions: 10, // Very small
execution_retention_secs: 300, // 5 minutes
enable_auto_cleanup: false, // Manual cleanup
max_output_size_bytes: 1_048_576, // 1 MB
truncate_large_output: true,
oversized_output_strategy: OversizedOutputStrategy::TruncateWithWarning,
};
```
### High-Volume Configuration
```rust
let config = ExecutionConfig {
default_timeout_ms: 300_000, // 5 minutes
max_timeout_ms: 1_800_000, // 30 minutes
stream_output: true,
log_dir: Some(PathBuf::from("/var/log/cloudops")),
max_concurrent_executions: 200, // High concurrency
max_in_memory_executions: 5000, // Large buffer
execution_retention_secs: 300, // 5 minutes (fast cleanup)
enable_auto_cleanup: true,
max_output_size_bytes: 5_242_880, // 5 MB (strict)
truncate_large_output: true,
oversized_output_strategy: OversizedOutputStrategy::TruncateWithWarning,
};
```
### Memory-Constrained Configuration
```rust
let config = ExecutionConfig {
default_timeout_ms: 120_000, // 2 minutes
max_timeout_ms: 600_000, // 10 minutes
stream_output: false, // Reduce overhead
log_dir: Some(PathBuf::from("/var/log/cloudops")),
max_concurrent_executions: 5, // Low concurrency
max_in_memory_executions: 50, // Small buffer
execution_retention_secs: 600, // 10 minutes
enable_auto_cleanup: true,
max_output_size_bytes: 1_048_576, // 1 MB (strict)
truncate_large_output: true,
oversized_output_strategy: OversizedOutputStrategy::TruncateWithWarning,
};
```
---
## Environment-based Configuration
```rust
use std::env;
fn load_config_from_env() -> ExecutionConfig {
ExecutionConfig {
default_timeout_ms: env::var("EXEC_DEFAULT_TIMEOUT_MS")
.ok()
.and_then(|s| s.parse().ok())
.unwrap_or(120_000),
max_timeout_ms: env::var("EXEC_MAX_TIMEOUT_MS")
.ok()
.and_then(|s| s.parse().ok())
.unwrap_or(600_000),
stream_output: env::var("EXEC_STREAM_OUTPUT")
.ok()
.and_then(|s| s.parse().ok())
.unwrap_or(true),
log_dir: env::var("EXEC_LOG_DIR")
.ok()
.map(PathBuf::from),
max_concurrent_executions: env::var("EXEC_MAX_CONCURRENT")
.ok()
.and_then(|s| s.parse().ok())
.unwrap_or(10),
}
}
```
---
## Configuration Files
### TOML Configuration
```toml
# config/execution.toml
[execution]
default_timeout_ms = 300000
max_timeout_ms = 1800000
stream_output = true
log_dir = "/var/log/cloudops"
max_concurrent_executions = 50
```
```rust
use serde::Deserialize;
#[derive(Deserialize)]
struct ConfigFile {
execution: ExecutionConfig,
}
fn load_config_from_file(path: &str) -> Result<ExecutionConfig, Box<dyn std::error::Error>> {
let content = std::fs::read_to_string(path)?;
let config_file: ConfigFile = toml::from_str(&content)?;
Ok(config_file.execution)
}
```
### JSON Configuration
```json
{
"default_timeout_ms": 300000,
"max_timeout_ms": 1800000,
"stream_output": true,
"log_dir": "/var/log/cloudops",
"max_concurrent_executions": 50
}
```
```rust
fn load_config_from_json(path: &str) -> Result<ExecutionConfig, Box<dyn std::error::Error>> {
let content = std::fs::read_to_string(path)?;
let config: ExecutionConfig = serde_json::from_str(&content)?;
Ok(config)
}
```
---
## Best Practices
### 1. Set Appropriate Timeouts
```rust
// Too short - may timeout frequently
default_timeout_ms: 10_000 // 10 seconds
// Recommended for AWS operations
default_timeout_ms: 120_000 // 2 minutes
// For long-running operations
default_timeout_ms: 600_000 // 10 minutes
```
### 2. Tune Concurrency
```rust
// Low concurrency for resource-constrained systems
max_concurrent_executions: 5
// Medium concurrency for typical workloads
max_concurrent_executions: 10-20
// High concurrency for powerful systems
max_concurrent_executions: 50-100
```
### 3. Use Structured Logs
```rust
let config = ExecutionConfig {
log_dir: Some(PathBuf::from("/var/log/cloudops")),
..Default::default()
};
// Logs will be written to:
// /var/log/cloudops/{execution_id}.log
```
### 4. Disable Streaming When Not Needed
```rust
// If not using event handlers, disable streaming
let config = ExecutionConfig {
stream_output: false,
..Default::default()
};
```
---
## Validation
Configuration is validated on engine creation:
```rust
let config = ExecutionConfig {
default_timeout_ms: 700_000, // Exceeds max
max_timeout_ms: 600_000,
..Default::default()
};
// This will panic or return error
let engine = ExecutionEngine::new(config);
```
---
## Related Documents
- [API Reference](api.md)
- [Usage Examples](usage.md)
- [Error Handling](error-handling.md)