SOMS/.kiro/specs/upload-inspection-task-result-performance/configuration-guide.md

# Performance Optimization Configuration Guide

## Overview

This document describes the configuration options for the UploadInspectionTaskResult performance optimization feature.

## Configuration Location

Add the following configuration section to your `appsettings.json` file:

```json
{
  "PerformanceOptimization": {
    "EnableCache": true,
    "CacheExpirationHours": 1,
    "MaxDegreeOfParallelism": 4,
    "BatchSize": 100,
    "MaxConcurrentRequests": 50,
    "RequestTimeoutSeconds": 30,
    "MaxFileSizeMB": 50,
    "MaxFilesPerItem": 100,
    "AllowedFileExtensions": ".jpg,.jpeg,.png,.bmp,.gif",
    "EnablePerformanceMonitoring": true,
    "PerformanceWarningThresholdMs": 5000,
    "EnableRetry": true,
    "MaxRetryAttempts": 3,
    "RetryBaseDelayMs": 1000
  }
}
```

## Configuration Options

### Cache Settings

#### EnableCache
- **Type**: Boolean
- **Default**: `true`
- **Description**: Enable or disable Redis caching for preset points and video devices
- **Recommendation**: Keep enabled for production environments to reduce database load

#### CacheExpirationHours
- **Type**: Integer
- **Default**: `1`
- **Description**: Cache expiration time in hours
- **Recommendation**: 
  - Use 1-2 hours for frequently changing data
  - Use 4-8 hours for relatively stable data
  - Monitor cache hit rates to optimize

### Parallelism Settings

#### MaxDegreeOfParallelism
- **Type**: Integer
- **Default**: `4`
- **Description**: Maximum number of concurrent file processing operations
- **Recommendation**: 
  - Set to number of CPU cores for CPU-bound operations
  - Set to 2-4x CPU cores for I/O-bound operations
  - Monitor CPU and I/O utilization to tune

### Batch Operation Settings

#### BatchSize
- **Type**: Integer
- **Default**: `100`
- **Description**: Number of items to insert in a single MongoDB batch operation
- **Recommendation**:
  - Use 50-100 for small documents
  - Use 20-50 for large documents
  - Adjust based on document size and memory constraints

### Concurrency Settings

#### MaxConcurrentRequests
- **Type**: Integer
- **Default**: `50`
- **Description**: Maximum number of concurrent upload requests the system can handle
- **Recommendation**:
  - Start with 50 and monitor system resources
  - Increase if CPU/memory utilization is low
  - Decrease if experiencing resource exhaustion

### Timeout Settings

#### RequestTimeoutSeconds
- **Type**: Integer
- **Default**: `30`
- **Description**: Maximum time allowed for processing a single upload request
- **Recommendation**:
  - Set based on expected upload size and network speed
  - Monitor timeout occurrences and adjust accordingly
  - Consider 30-60 seconds for typical scenarios

### File Validation Settings

#### MaxFileSizeMB
- **Type**: Long
- **Default**: `50`
- **Description**: Maximum file size allowed for upload in megabytes
- **Recommendation**:
  - Balance between user needs and system capacity
  - Consider storage and bandwidth constraints
  - Typical range: 10-100 MB

#### MaxFilesPerItem
- **Type**: Integer
- **Default**: `100`
- **Description**: Maximum number of files allowed per inspection item
- **Recommendation**:
  - Set based on business requirements
  - Consider processing time and storage implications

#### AllowedFileExtensions
- **Type**: String (comma-separated)
- **Default**: `.jpg,.jpeg,.png,.bmp,.gif`
- **Description**: Allowed file extensions for upload
- **Recommendation**:
  - Restrict to necessary image formats
  - Add video formats if needed: `.mp4,.avi,.mov`

### Performance Monitoring Settings

#### EnablePerformanceMonitoring
- **Type**: Boolean
- **Default**: `true`
- **Description**: Enable performance monitoring and detailed logging
- **Recommendation**: 
  - Keep enabled in development and staging
  - Consider disabling in production if logging overhead is significant

#### PerformanceWarningThresholdMs
- **Type**: Long
- **Default**: `5000`
- **Description**: Operations exceeding this threshold (in milliseconds) will log warnings
- **Recommendation**:
  - Set based on SLA requirements
  - Typical values: 3000-10000 ms

### Retry Settings

#### EnableRetry
- **Type**: Boolean
- **Default**: `true`
- **Description**: Enable automatic retry for transient database errors
- **Recommendation**: Keep enabled for production resilience

#### MaxRetryAttempts
- **Type**: Integer
- **Default**: `3`
- **Description**: Maximum number of retry attempts for transient errors
- **Recommendation**: 
  - Use 2-3 retries for most scenarios
  - Increase for highly unreliable networks

#### RetryBaseDelayMs
- **Type**: Integer
- **Default**: `1000`
- **Description**: Base delay in milliseconds for exponential backoff retry strategy
- **Recommendation**:
  - Use 500-1000ms for typical scenarios
  - Actual delay = BaseDelay * 2^(attempt-1)

## Environment-Specific Recommendations

### Development Environment
```json
{
  "PerformanceOptimization": {
    "EnableCache": false,
    "EnablePerformanceMonitoring": true,
    "MaxDegreeOfParallelism": 2,
    "BatchSize": 50
  }
}
```

### Staging Environment
```json
{
  "PerformanceOptimization": {
    "EnableCache": true,
    "CacheExpirationHours": 1,
    "EnablePerformanceMonitoring": true,
    "MaxDegreeOfParallelism": 4,
    "BatchSize": 100
  }
}
```

### Production Environment
```json
{
  "PerformanceOptimization": {
    "EnableCache": true,
    "CacheExpirationHours": 2,
    "EnablePerformanceMonitoring": true,
    "PerformanceWarningThresholdMs": 5000,
    "MaxDegreeOfParallelism": 8,
    "BatchSize": 100,
    "MaxConcurrentRequests": 100
  }
}
```

## Monitoring and Tuning

### Key Metrics to Monitor

1. **Cache Hit Rate**: Should be > 80% for effective caching
2. **Average Request Duration**: Should be < PerformanceWarningThresholdMs
3. **Concurrent Request Count**: Should be < MaxConcurrentRequests
4. **Retry Rate**: Should be < 5% of total requests
5. **File Processing Time**: Monitor per-file processing duration

### Performance Tuning Steps

1. **Start with default values**
2. **Monitor system metrics** (CPU, memory, I/O, network)
3. **Identify bottlenecks** using performance logs
4. **Adjust relevant settings** incrementally
5. **Test and validate** improvements
6. **Repeat** until performance targets are met

### Common Issues and Solutions

#### High CPU Usage
- Reduce `MaxDegreeOfParallelism`
- Reduce `MaxConcurrentRequests`

#### High Memory Usage
- Reduce `BatchSize`
- Reduce `MaxConcurrentRequests`
- Reduce `CacheExpirationHours`

#### Slow Database Operations
- Enable caching if disabled
- Increase `BatchSize` (if not memory-constrained)
- Check database indexes

#### Frequent Timeouts
- Increase `RequestTimeoutSeconds`
- Reduce `MaxFileSizeMB`
- Increase `MaxDegreeOfParallelism` for file processing

## Redis Configuration

Ensure Redis is properly configured in your connection strings:

```json
{
  "ConnectionStrings": {
    "RedisSetting:Host": "localhost",
    "RedisSetting:Port": "6379",
    "RedisSetting:DefaultDatabaseIndex": "0",
    "RedisSetting:Name": "SOMS",
    "RedisSetting:Auth": ""
  }
}
```

## Validation

After configuration changes:

1. Restart the application
2. Check logs for configuration loading messages
3. Verify settings are applied correctly
4. Run performance tests to validate improvements

## Support

For issues or questions about configuration:
- Check application logs for configuration errors
- Review performance monitoring logs
- Consult the design document for detailed architecture information