نمایش پروسس کانتینر

کانتینری که در حال اجرا است را برای نمایش فرآیندهای درون آن کوئری می‌کند.

🧩 دستور کلی

async getProcessInfo(containerId, options = {})

شرح عملکرد

این متد فرآیندهای درون کانتینر مشخص شده را با جزئیات نمایش می‌دهد. شامل اطلاعات مثل PID، PPID، نام دستور و دیگر جزئیات پروسس است.

مهم: این دستور فقط روی کانتینرهای در وضعیت running کار می‌کند.

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
`containerId`	String	بله	شناسه یا نام کانتینر برای نمایش پروسس
`options`	Object	خیر	گزینه‌های اختیاری
`options.all`	Boolean	خیر	نمایش تمام جزئیات پروسس‌ها

خروجی

نوع: Array<Object> (آرایه‌ای از اشیاء)

خروجی شامل لیست پروسس‌های درون کانتینر:

[
  {
    "C": "0",
    "CMD": "(sh)",
    "PID": "24006",
    "PPID": "24004",
    "STIME": "24006",
    "TIME": "0",
    "TTY": "24006",
    "UID": "0"
  },
  {
    "C": "0",
    "CMD": "(tail)",
    "PID": "24053",
    "PPID": "24006",
    "STIME": "24006",
    "TIME": "4",
    "TTY": "24006",
    "UID": "0"
  }
]

فیلدهای خروجی:

C - CPU usage percentage
CMD - دستور یا نام برنامه
PID - Process ID (شناسه پروسس)
PPID - Parent Process ID (شناسه پروسس والد)
STIME - زمان شروع
TIME - کل زمان CPU استفاده شده
TTY - Terminal type
UID - User ID

استثناها (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"
}

راهنمای حل:

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

❌ FetchContainerState (500)

پیام: "Database error occurred while fetching container state."

زمان رخ دادن: خطای دیتابیس هنگام خواندن وضعیت کانتینر

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Query timeout"
}

راهنمای حل:

دیتابیس را بررسی کنید
اتصال را تأیید کنید

❌ NotRunning (400)

پیام: "Container is not in a running state. Start the container first."

زمان رخ دادن: کانتینر در وضعیت دیگری باشد (مثلاً stopped، paused، created)

جزئیات:

{
  "type": "INVALID_STATE",
  "statusCode": 400,
  "containerId": "abc123def456",
  "currentState": "stopped"
}

راهنمای حل:

اگر کانتینر متوقف است، ابتدا با startContainer() شروع کنید
فقط کانتینرهای در حال اجرا دارای پروسس هستند

❌ OptionConflict (422)

پیام: "Failed to validate process info options."

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

جزئیات:

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

راهنمای حل:

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

❌ InspectFailure (500)

پیام: "Failed to inspect container processes."

زمان رخ دادن: خطا در دریافت اطلاعات پروسس‌ها

جزئیات:

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

راهنمای حل:

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

❌ 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 processes = await k3.containerCore.getProcessInfo('my-container');
    console.log('Process list retrieved');
    processes.forEach(proc => {
      console.log(`PID: ${proc.PID}, CMD: ${proc.CMD}`);
    });
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 2: دریافت تمام جزئیات پروسس‌ها

(async () => {
  const k3 = new K3Core();
  
  try {
    // Get all process details
    const processes = await k3.containerCore.getProcessInfo('web-server', {
      all: true
    });
    console.log('Detailed process information:');
    console.table(processes);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: تحلیل پروسس‌های اجرا شده

(async () => {
  const k3 = new K3Core();
  
  try {
    const processes = await k3.containerCore.getProcessInfo('app-container', {
      all: true
    });
    
    // Filter shell processes
    const shells = processes.filter(p => p.CMD.includes('sh'));
    console.log(`Found ${shells.length} shell processes`);
    
    // Find main process (lowest PID)
    const mainProcess = processes.reduce((min, p) => 
      parseInt(p.PID) < parseInt(min.PID) ? p : min
    );
    console.log('Main process:', mainProcess.CMD);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 4: نمایش درخت پروسس‌ها

(async () => {
  const k3 = new K3Core();
  
  try {
    const processes = await k3.containerCore.getProcessInfo('container-id');
    
    // Build process tree
    const buildTree = (parentPid, indent = '') => {
      const children = processes.filter(p => p.PPID === parentPid);
      children.forEach(proc => {
        console.log(`${indent}├─ [${proc.PID}] ${proc.CMD} (UID: ${proc.UID})`);
        buildTree(proc.PID, indent + '│  ');
      });
    };
    
    console.log('Process tree:');
    const roots = processes.filter(p => !processes.some(x => x.PID === p.PPID));
    roots.forEach(root => {
      console.log(`[${root.PID}] ${root.CMD}`);
      buildTree(root.PID, '');
    });
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 5: مانیتورینگ مصرف CPU

(async () => {
  const k3 = new K3Core();
  
  try {
    const processes = await k3.containerCore.getProcessInfo('monitored-container', {
      all: true
    });
    
    // Sort by CPU usage
    const sorted = processes.sort((a, b) => 
      parseInt(b.C) - parseInt(a.C)
    );
    
    console.log('Top CPU consuming processes:');
    sorted.slice(0, 5).forEach(proc => {
      console.log(`${proc.CMD}: ${proc.C}% CPU (PID: ${proc.PID})`);
    });
    
    // Calculate total CPU usage
    const totalCPU = sorted.reduce((sum, p) => sum + parseInt(p.C), 0);
    console.log(`Total CPU usage: ${totalCPU}%`);
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: تحقق از وجود فرآیند خاص

(async () => {
  const k3 = new K3Core();
  
  try {
    const processes = await k3.containerCore.getProcessInfo('app-container');
    
    const findProcess = (cmdName) => {
      return processes.find(p => p.CMD.includes(cmdName));
    };
    
    const pythonProc = findProcess('python');
    if (pythonProc) {
      console.log(`Python process found: PID ${pythonProc.PID}`);
      console.log(`Running time: ${pythonProc.TIME}s`);
    } else {
      console.log('Python process not found');
    }
    
    const nodeProc = findProcess('node');
    if (nodeProc) {
      console.log(`Node.js process found: PID ${nodeProc.PID}`);
    } else {
      console.log('Node.js process not found');
    }
    
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

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

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

خطا: ContainerNotFound (404)

راهنمای حل:

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

الگو 2: کانتینر در حال اجرا نیست

خطا: NotRunning (400)

راهنمای حل:

try {
  await k3.containerCore.getProcessInfo('my-container');
} catch (error) {
  if (error.type === 'INVALID_STATE') {
    // Check current container status
    const [status] = await k3.containerCore.listContainers({ 
      containerId: 'my-container' 
    });
    
    if (status.status !== 'running') {
      console.log(`Container is ${status.status} - starting it first...`);
      await k3.containerCore.startContainer('my-container');
      
      // Wait for container to fully start
      await new Promise(resolve => setTimeout(resolve, 2000));
      
      // Now get process info
      const processes = await k3.containerCore.getProcessInfo('my-container');
      console.log('Process info:', processes);
    }
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 3: بررسی قبل از دریافت پروسس

راهنمای حل:

const safeGetProcessInfo = async (containerId) => {
  try {
    // Check if container exists and is running
    const [container] = await k3.containerCore.listContainers({ 
      containerId: containerId 
    });
    
    if (!container) {
      console.log('Container not found');
      return null;
    }
    
    if (container.status !== 'running') {
      console.log(`Container is ${container.status} - cannot get process info`);
      return null;
    }
    
    // Get process information
    const processes = await k3.containerCore.getProcessInfo(containerId);
    console.log(`Retrieved ${processes.length} processes`);
    return processes;
    
  } catch (error) {
    console.log(error.createFullMessage());
    throw error;
  }
};

const procs = await safeGetProcessInfo('my-container');

نکات عملی

شرط‌های دریافت پروسس:
- فقط کانتینرهای running دارای پروسس هستند
- کانتینرهای paused یا stopped هیچ پروسس‌ای برنمی‌گردانند
پارامتر all:
- فعال کردن جزئیات بیشتر
- پیش‌فرض: false
- برای تحلیل عمیق‌تر مفید است
فیلدهای خروجی:
- PID: برای پیدا کردن و terminate کردن پروسس‌ها
- PPID: برای درک درخت پروسس
- CMD: برای شناسایی نوع برنامه
- TIME: برای بررسی مصرف CPU
کاربردهای اصلی:
- مانیتورینگ فرآیندهای کانتینر
- تشخیص مشکلات عملکرد
- تحلیل مصرف منابع
- تایید اجرای برنامه‌های مورد انتظار
بهینه‌سازی:
- فقط در صورت نیاز از all: true استفاده کنید
- نتایج را کش کنید اگر مکرر نیاز دارید
- برای مانیتورینگ دوره‌ای، بازه زمانی مناسب انتخاب کنید

مرجع سریع

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

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

🧩 دستور کلی​

شرح عملکرد​

ورودی‌ها​

خروجی​

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

❌ ContainerNotFound (404)​

❌ ResolveContainerName (500)​

❌ FetchContainerState (500)​

❌ NotRunning (400)​

❌ OptionConflict (422)​

❌ InspectFailure (500)​

❌ FetchContainerStatusFailure (500)​

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

مثال 1: دریافت پروسس‌های ساده​

مثال 2: دریافت تمام جزئیات پروسس‌ها​

مثال 3: تحلیل پروسس‌های اجرا شده​

مثال 4: نمایش درخت پروسس‌ها​

مثال 5: مانیتورینگ مصرف CPU​

مثال 6: تحقق از وجود فرآیند خاص​

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

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

الگو 2: کانتینر در حال اجرا نیست​

الگو 3: بررسی قبل از دریافت پروسس​

نکات عملی​

مرجع سریع​

🧩 دستور کلی

شرح عملکرد

ورودی‌ها

خروجی

استثناها (Errors)

❌ ContainerNotFound (404)

❌ ResolveContainerName (500)

❌ FetchContainerState (500)

❌ NotRunning (400)

❌ OptionConflict (422)

❌ InspectFailure (500)

❌ FetchContainerStatusFailure (500)

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

مثال 1: دریافت پروسس‌های ساده

مثال 2: دریافت تمام جزئیات پروسس‌ها

مثال 3: تحلیل پروسس‌های اجرا شده

مثال 4: نمایش درخت پروسس‌ها

مثال 5: مانیتورینگ مصرف CPU

مثال 6: تحقق از وجود فرآیند خاص

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

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

الگو 2: کانتینر در حال اجرا نیست

الگو 3: بررسی قبل از دریافت پروسس

نکات عملی

مرجع سریع