guorui/SOMS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
SOMS/.kiro/specs/upload-inspection-task-result-performance/configuration-guide.md
guorui 111f8d06ff 1
2026-01-06 22:59:58 +08:00

7.3 KiB
Raw Blame History

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:

{
  "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

{
  "PerformanceOptimization": {
    "EnableCache": false,
    "EnablePerformanceMonitoring": true,
    "MaxDegreeOfParallelism": 2,
    "BatchSize": 50
  }
}

Staging Environment

{
  "PerformanceOptimization": {
    "EnableCache": true,
    "CacheExpirationHours": 1,
    "EnablePerformanceMonitoring": true,
    "MaxDegreeOfParallelism": 4,
    "BatchSize": 100
  }
}

Production Environment

{
  "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:

{
  "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