اطلاعات میزان استفاده منابع کانتینر

کانتینری که در حال اجرا است را برای دریافت آمار مصرف منابع (CPU، حافظه، I/O) کوئری می‌کند.

🧩 دستور کلی

async getUsageStats(containerId)

شرح عملکرد

این متد اطلاعات دقیق مصرف منابع سیستم توسط کانتینر مشخص شده را برمی‌گرداند. شامل آمار CPU، حافظه (RAM و Swap) و I/O است.

مهم: این اطلاعات از طریق cgroup سیستم لینوکس جمع‌آوری می‌شوند.

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
`containerId`	String	بله	شناسه یا نام کانتینر برای دریافت آمار منابع

خروجی

نوع: Object (شامل سه بخش: memoryStats، cpuStats، ioStats)

خروجی شامل آمار جامع منابع کانتینر:

{
  "memoryStats": {
    "Memory Current": "577536",
    "Memory High": "max",
    "Memory Low": "6228119552",
    "Memory Max": "6228119552",
    "Memory Min": "0",
    "Memory Swap Current": "0",
    "Memory Swap High": "max",
    "Memory Swap Max": "0"
  },
  "cpuStats": {
    "CPU Max": "1000000 500000",
    "CPU Pressure": "some avg10=0.00 avg60=0.00 avg300=0.00 total=657526\nfull avg10=0.00 avg60=0.00 avg300=0.00 total=657399",
    "CPU Uclamp Max": "max",
    "CPU Uclamp Min": "0.00",
    "CPU Usage": "usage_usec 254330\nuser_usec 54499\nsystem_usec 199830\nnice_usec 0\ncore_sched.force_idle_usec 0\nnr_periods 487\nnr_throttled 0\nthrottled_usec 0\nnr_bursts 0\nburst_usec 0",
    "CPU Weight": "100",
    "CPU Weight Nice": "0",
    "Effective CPUs": "0",
    "Exclusive CPUs": "",
    "Partition CPUs": "member"
  },
  "ioStats": {
    "IO Max": "",
    "IO Pressure": "some avg10=0.00 avg60=0.00 avg300=0.00 total=0\nfull avg10=0.00 avg60=0.00 avg300=0.00 total=0",
    "IO Priority Class": "no-change",
    "IO Stat": "8:0 rbytes=0 wbytes=12288 rios=0 wios=3 dbytes=0 dios=0",
    "IO Weight": "default 100"
  }
}

فیلدهای اصلی:

Memory Stats

Memory Current - حافظه جاری مصرف شده (بایت)
Memory High - محدودیت هشدار حافظه
Memory Max - حداکثر حافظه قابل استفاده (بایت)
Memory Low - کمترین حافظه حفاظت‌شده
Memory Swap Current - Swap جاری مصرف شده
Memory Swap Max - حداکثر Swap قابل استفاده

CPU Stats

CPU Usage - زمان استفاده CPU (microseconds)
- usage_usec - کل زمان استفاده
- user_usec - زمان حالت user
- system_usec - زمان حالت system
CPU Max - محدودیت CPU
CPU Pressure - فشار CPU (PSI metric)
CPU Weight - وزن CPU (۱-۱۰۰۰۰)
Effective CPUs - تعداد CPU موثر

I/O Stats

IO Stat - آمار I/O (rbytes: بایت خوانده شده، wbytes: بایت نوشته شده)
IO Pressure - فشار I/O (PSI metric)
IO Priority Class - کلاس اولویت I/O
IO Weight - وزن I/O

استثناها (Errors)

ContainerNotFound (404)

پیام: "No container exists with the specified name or ID prefix."

زمان رخ دادن: کانتینری با شناسه/نام درخواستی یافت نشود

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "containerId": "invalid-id"
}

راهنمای حل:

شناسه کانتینر را بررسی کنید
listContainers() استفاده کنید تا تمام کانتینرها را ببینید
نام یا ID صحیح را وارد کنید

ResolveContainerName (500)

پیام: "Database error occurred while resolving container name or ID."

زمان رخ دادن: خطای دیتابیس در تطابق شناسه/نام کانتینر

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "input": "container-id",
  "error": "Database connection lost"
}

راهنمای حل:

اتصال دیتابیس را بررسی کنید
لاگ‌های دیتابیس را مطالعه کنید
دیتابیس را راه‌اندازی کنید

OptionConflict (422)

پیام: "Failed to validate usage stats options."

زمان رخ دادن: گزینه‌های ورودی نامعتبر باشند

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "containerId": "abc123def456",
  "error": "Invalid schema"
}

راهنمای حل:

گزینه‌های ورودی را بررسی کنید
فقط String برای containerId استفاده کنید

InspectFailure (500)

پیام: "Failed to inspect container resource usage."

زمان رخ دادن: خطا در دریافت اطلاعات منابع

جزئیات:

{
  "type": "CONTAINER_SERVICE_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Runtime error"
}

راهنمای حل:

سرویس K3 فعال است یا خیر؟
لاگ‌های سرویس را مطالعه کنید
cgroup سیستم را بررسی کنید

FetchContainerStatusFailure (500)

پیام: "Failed to fetch container status."

زمان رخ دادن: خطای عمومی در دریافت اطلاعات

جزئیات:

{
  "type": "GENERIC_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Unknown error"
}

راهنمای حل:

سرویس‌های K3 را دوباره شروع کنید
لاگ‌ها را بررسی کنید

مثال‌های استفاده

مثال 1: دریافت آمار منابع ساده

const K3Core = require('k3-core');

(async () => {
  const k3 = new K3Core();
  
  try {
    const stats = await k3.containerCore.getUsageStats('my-container');
    console.log('Resource usage retrieved');
    
    // Display memory usage in MB
    const memMB = parseInt(stats.memoryStats['Memory Current']) / 1024 / 1024;
    console.log(`Memory used: ${memMB.toFixed(2)} MB`);
    
    // Display CPU weight
    console.log(`CPU weight: ${stats.cpuStats['CPU Weight']}`);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 2: تحلیل مصرف منابع

(async () => {
  const k3 = new K3Core();
  
  try {
    const stats = await k3.containerCore.getUsageStats('monitored-container');
    
    // Parse memory stats
    const currentMem = parseInt(stats.memoryStats['Memory Current']);
    const maxMem = parseInt(stats.memoryStats['Memory Max']);
    const memPercentage = (currentMem / maxMem * 100).toFixed(2);
    
    console.log(`Memory: ${currentMem / 1024}KB / ${maxMem / 1024}KB (${memPercentage}%)`);
    
    // Parse CPU usage
    const cpuUsageLines = stats.cpuStats['CPU Usage'].split('\n');
    const cpuMap = {};
    cpuUsageLines.forEach(line => {
      const [key, value] = line.trim().split(' ');
      cpuMap[key] = value;
    });
    
    const cpuUsecMicro = parseInt(cpuMap.usage_usec);
    const cpuUsecSec = cpuUsecMicro / 1_000_000;
    console.log(`CPU usage: ${cpuUsecSec.toFixed(3)} seconds`);
    
    // Parse I/O stats
    const ioStat = stats.ioStats['IO Stat'];
    const ioMatch = ioStat.match(/rbytes=(\d+)\s+wbytes=(\d+)/);
    if (ioMatch) {
      const readBytes = parseInt(ioMatch[1]);
      const writeBytes = parseInt(ioMatch[2]);
      console.log(`I/O: Read ${readBytes}B, Write ${writeBytes}B`);
    }
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: مانیتورینگ مصرف منابع

(async () => {
  const k3 = new K3Core();
  
  const monitorContainer = async (containerId, interval = 5000) => {
    console.log('Starting resource monitoring...');
    
    setInterval(async () => {
      try {
        const stats = await k3.containerCore.getUsageStats(containerId);
        if (!stats) {
          console.log('No stats available');
          return;
        }
        
        // Memory usage
        const memMB = parseInt(stats.memoryStats['Memory Current']) / 1024 / 1024;
        const maxMemMB = parseInt(stats.memoryStats['Memory Max']) / 1024 / 1024;
        
        // CPU pressure
        const cpuPressure = stats.cpuStats['CPU Pressure'].split('\n')[0];
        
        // I/O operations
        const ioStat = stats.ioStats['IO Stat'].match(/wios=(\d+)/);
        const writeOps = ioStat ? ioStat[1] : 'N/A';
        
        console.log(`[${new Date().toISOString()}]`);
        console.log(`  Memory: ${memMB.toFixed(2)}MB / ${maxMemMB.toFixed(2)}MB`);
        console.log(`  CPU Pressure: ${cpuPressure}`);
        console.log(`  Write I/O Ops: ${writeOps}`);
        
      } catch (error) {
        console.log('Monitoring error:', error.message);
      }
    }, interval);
  };
  
  await monitorContainer('app-container', 10000);
})();

مثال 4: بررسی محدودیت‌های منابع

(async () => {
  const k3 = new K3Core();
  
  try {
    const stats = await k3.containerCore.getUsageStats('limited-container');
    
    // Check memory limits
    const memMax = parseInt(stats.memoryStats['Memory Max']);
    const swapMax = parseInt(stats.memoryStats['Memory Swap Max']);
    
    console.log('Memory Limits:');
    console.log(`  RAM Max: ${(memMax / 1024 / 1024 / 1024).toFixed(2)}GB`);
    console.log(`  Swap Max: ${(swapMax / 1024 / 1024 / 1024).toFixed(2)}GB`);
    
    // Check CPU limits
    const cpuMax = stats.cpuStats['CPU Max'];
    console.log(`CPU Max: ${cpuMax}`);
    console.log(`CPU Weight: ${stats.cpuStats['CPU Weight']}`);
    
    // Check I/O limits
    const ioMax = stats.ioStats['IO Max'];
    console.log(`I/O Max: ${ioMax || 'Unlimited'}`);
    console.log(`I/O Weight: ${stats.ioStats['IO Weight']}`);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 5: مقایسه مصرف منابع چند کانتینر

(async () => {
  const k3 = new K3Core();
  
  try {
    const containerIds = ['container-1', 'container-2', 'container-3'];
    const statsArray = [];
    
    for (const id of containerIds) {
      try {
        const stats = await k3.containerCore.getUsageStats(id);
        if (stats) {
          const memMB = parseInt(stats.memoryStats['Memory Current']) / 1024 / 1024;
          statsArray.push({
            container: id,
            memory: memMB
          });
        }
      } catch (error) {
        console.log(`Could not get stats for ${id}: ${error.message}`);
      }
    }
    
    // Sort by memory usage
    statsArray.sort((a, b) => b.memory - a.memory);
    
    console.log('Container Resource Usage (sorted by memory):');
    statsArray.forEach(stat => {
      console.log(`${stat.container}: ${stat.memory.toFixed(2)}MB`);
    });
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: تحلیل فشار سیستمی (PSI)

(async () => {
  const k3 = new K3Core();
  
  try {
    const stats = await k3.containerCore.getUsageStats('system-container');
    
    // Parse CPU pressure
    console.log('CPU Pressure (PSI):');
    const cpuLines = stats.cpuStats['CPU Pressure'].split('\n');
    cpuLines.forEach(line => {
      console.log(`  ${line}`);
    });
    
    // Parse I/O pressure
    console.log('I/O Pressure (PSI):');
    const ioLines = stats.ioStats['IO Pressure'].split('\n');
    ioLines.forEach(line => {
      console.log(`  ${line}`);
    });
    
    // Extract some metrics
    const cpuMatch = cpuLines[0].match(/avg10=([0-9.]+)/);
    const ioMatch = ioLines[0].match(/avg10=([0-9.]+)/);
    
    if (cpuMatch) {
      console.log(`\nCPU Pressure (10s avg): ${cpuMatch[1]}%`);
    }
    if (ioMatch) {
      console.log(`I/O Pressure (10s avg): ${ioMatch[1]}%`);
    }
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

الگوهای خطا و راهنمای حل

الگو 1: کانتینر یافت نشد

خطا: ContainerNotFound (404)

راهنمای حل:

try {
  await k3.containerCore.getUsageStats('invalid-container');
} catch (error) {
  if (error.type === 'NOT_FOUND') {
    // Get list of all containers
    const allContainers = await k3.containerCore.listContainers({ all: true });
    
    console.log('Available containers:', allContainers.map(c => c.name));
    
    // Find and use the correct container
    const container = allContainers.find(c => c.name.includes('my'));
    if (container) {
      const stats = await k3.containerCore.getUsageStats(container.id);
      console.log('Stats retrieved');
    }
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 2: دریافت آمار خالی

راهنمای حل:

try {
  const stats = await k3.containerCore.getUsageStats('my-container');
  
  if (!stats) {
    console.log('Container has no stats available');
    console.log('This may happen if container just started or was recently stopped');
    return;
  }
  
  // Process stats
  const memMB = parseInt(stats.memoryStats['Memory Current']) / 1024 / 1024;
  console.log(`Memory: ${memMB.toFixed(2)}MB`);
  
} catch (error) {
  console.log(error.createFullMessage());
}

الگو 3: تحلیل Multiline Stats

راهنمای حل:

const parseStatsField = (field) => {
  const lines = field.split('\n').filter(l => l.trim());
  const result = {};
  
  lines.forEach(line => {
    const parts = line.trim().split(/\s+/);
    if (parts.length >= 2) {
      const key = parts[0];
      const value = parts.slice(1).join(' ');
      result[key] = value;
    }
  });
  
  return result;
};

try {
  const stats = await k3.containerCore.getUsageStats('my-container');
  
  // Parse CPU usage
  const cpuUsage = parseStatsField(stats.cpuStats['CPU Usage']);
  console.log('CPU Usage Details:', cpuUsage);
  
  // Parse CPU pressure
  const cpuPressure = parseStatsField(stats.cpuStats['CPU Pressure']);
  console.log('CPU Pressure Details:', cpuPressure);
  
} catch (error) {
  console.log(error.createFullMessage());
}

الگو 4: بررسی قبل از دریافت آمار

راهنمای حل:

const safeGetStats = async (containerId) => {
  try {
    // Check if container exists
    const [container] = await k3.containerCore.listContainers({ 
      containerId: containerId 
    });
    
    if (!container) {
      console.log('Container not found');
      return null;
    }
    
    // Get stats
    const stats = await k3.containerCore.getUsageStats(containerId);
    
    if (!stats) {
      console.log('No stats available for container');
      return null;
    }
    
    return stats;
    
  } catch (error) {
    console.log(error.createFullMessage());
    throw error;
  }
};

const stats = await safeGetStats('my-container');

نکات عملی

واحدهای استفاده:
- Memory: بایت (byte) - برای تبدیل به MB: تقسیم بر 1024²
- CPU: microseconds (µs)
- I/O: بایت (byte)
PSI Metrics:
- some - درصد زمانی که حداقل یک task منتظر است
- full - درصد زمانی که تمام tasks منتظر هستند
- avg10/60/300 - میانگین در 10، 60، 300 ثانیه اخیر
CPU Weight: -범위: 1 - 10000 (پیش‌فرض: 100)
- بالاتر = اولویت بیشتر
کاربردهای اصلی:
- مانیتورینگ مصرف منابع
- شناسایی کانتینرهای پر مصرف
- تشخیص مشکلات عملکرد
- بهینه‌سازی محدودیت‌ها
بهینه‌سازی:
- نتایج را کش کنید برای کاهش بار
- از بازه‌های زمانی مناسب برای مانیتورینگ استفاده کنید
- PSI metrics را برای شناسایی bottleneck استفاده کنید

مرجع سریع

وضعیت	کد	توضیح
موفق	200	آمار دریافت شدند
یافت نشد	404	`ContainerNotFound`
گزینه نامعتبر	422	`OptionConflict`
خطای بررسی	500	`InspectFailure`
خطای عمومی	500	`FetchContainerStatusFailure`

نسخه: 1.3
تاریخ آپدیت: 9 آذرماه ۱۴۰۴

🧩 دستور کلی​

شرح عملکرد​

ورودی‌ها​

خروجی​

Memory Stats​

CPU Stats​

I/O Stats​

استثناها (Errors)​

ContainerNotFound (404)​

ResolveContainerName (500)​

OptionConflict (422)​

InspectFailure (500)​

FetchContainerStatusFailure (500)​

مثال‌های استفاده​

مثال 1: دریافت آمار منابع ساده​

مثال 2: تحلیل مصرف منابع​

مثال 3: مانیتورینگ مصرف منابع​

مثال 4: بررسی محدودیت‌های منابع​

مثال 5: مقایسه مصرف منابع چند کانتینر​

مثال 6: تحلیل فشار سیستمی (PSI)​

الگوهای خطا و راهنمای حل​

الگو 1: کانتینر یافت نشد​

الگو 2: دریافت آمار خالی​

الگو 3: تحلیل Multiline Stats​

الگو 4: بررسی قبل از دریافت آمار​

نکات عملی​

مرجع سریع​

🧩 دستور کلی

شرح عملکرد

ورودی‌ها

خروجی

Memory Stats

CPU Stats

I/O Stats

استثناها (Errors)

ContainerNotFound (404)

ResolveContainerName (500)

OptionConflict (422)

InspectFailure (500)

FetchContainerStatusFailure (500)

مثال‌های استفاده

مثال 1: دریافت آمار منابع ساده

مثال 2: تحلیل مصرف منابع

مثال 3: مانیتورینگ مصرف منابع

مثال 4: بررسی محدودیت‌های منابع

مثال 5: مقایسه مصرف منابع چند کانتینر

مثال 6: تحلیل فشار سیستمی (PSI)

الگوهای خطا و راهنمای حل

الگو 1: کانتینر یافت نشد

الگو 2: دریافت آمار خالی

الگو 3: تحلیل Multiline Stats

الگو 4: بررسی قبل از دریافت آمار

نکات عملی

مرجع سریع