A robust Node.js utility for tracking and estimating resource costs ("gas") during asynchronous function execution. Gas2nel monitors CPU usage, memory allocation, network I/O, and file system operations to provide realistic resource utilization metrics.
- 🔍 Comprehensive resource tracking
- CPU time and percentage
- Memory usage (RSS, heap, external)
- Network bandwidth (sent/received bytes)
- File I/O operations
- 📊 Configurable metric reporting
- ⚡ Real-time resource monitoring
- 🎯 Accurate gas cost estimation
- 🔄 Event-driven architecture
- 💪 TypeScript-friendly API
npm install gas2nel
const Gas2nel = require('gas2nel');
// Initialize with optional configuration
const gas2nel = new Gas2nel({
include: ["metric", "report"] // Include detailed metrics and human-readable report
});
// Example async function to monitor
async function complexOperation() {
const data = await fetch('https://api.example.com/data');
await processData(data);
return 'Operation completed';
}
// Estimate gas usage
const result = await gas2nel.estimateGas(complexOperation);
console.log(result);
The Gas2nel constructor accepts an options object with the following properties:
{
include: string[] // Array of additional outputs to include: "metric" and/or "report"
}
Creates a new Gas2nel instance.
const gas2nel = new Gas2nel({
include: ["metric", "report"]
});
Executes a function while monitoring resource usage and returns detailed metrics.
Parameters:
-
fn
: Async function to monitor -
...args
: Arguments to pass to the function
Returns:
{
success: boolean, // Whether the function executed successfully
data: any, // Function return value or error message
gas: number, // Estimated gas cost (0 to 1 scale)
metric?: { // Optional detailed metrics
cpuTimeMs: number,
cpuPercentage: number,
memoryRSS: number,
memoryHeapUsed: number,
memoryExternal: number,
sentBytes: number,
receivedBytes: number,
wallTimeMs: number,
fileReadBytes: number,
fileWriteBytes: number
},
report?: { // Optional human-readable report
cpuTimeMs: number,
wallTimeMs: number,
peakMemoryRSS: string,
memoryHeapUsed: string,
memoryExternal: string,
networkTransferred: string,
fileIO: string
}
}
Updates the configuration options.
gas2nel.setOptions({
include: ["report"]
});
Resets all counters (network and file I/O metrics).
gas2nel.reset();
Gas2nel uses a weighted combination of various metrics to estimate the total resource cost:
Metric | Weight | Description |
---|---|---|
CPU Time | 35% | Process CPU time in milliseconds |
CPU Percentage | 20% | CPU utilization percentage |
RSS Memory | 15% | Resident Set Size memory usage |
Heap Memory | 10% | V8 heap memory usage |
External Memory | 5% | V8 external memory usage |
Network Sent | 5% | Bytes sent over network |
Network Received | 5% | Bytes received over network |
Wall Time | 5% | Total execution time |
const Gas2nel = require('gas2nel');
const gas2nel = new Gas2nel();
async function example() {
// CPU-intensive operation
const result = await gas2nel.estimateGas(async () => {
let sum = 0;
for (let i = 0; i < 1000000; i++) {
sum += Math.sqrt(i);
}
return sum;
});
console.log(result);
}
const gas2nel = new Gas2nel({ include: ["metric"] });
const result = await gas2nel.estimateGas(async () => {
const response = await fetch('https://api.example.com/data');
return await response.json();
});
console.log(`Network usage: ${result.metric.sentBytes + result.metric.receivedBytes} bytes`);
const gas2nel = new Gas2nel({ include: ["report"] });
const result = await gas2nel.estimateGas(async () => {
await fs.promises.writeFile('output.txt', 'Hello World');
const data = await fs.promises.readFile('output.txt');
return data.toString();
});
console.log(`File I/O: ${result.report.fileIO}`);
Gas2nel gracefully handles errors in monitored functions:
const result = await gas2nel.estimateGas(async () => {
throw new Error('Something went wrong');
});
console.log(result);
// {
// success: false,
// data: 'Something went wrong',
// gas: 0.023, // Resources used before error
// ...
// }
-
Reset Between Operations
gas2nel.reset(); // Clear previous metrics
-
Include Appropriate Metrics
// For debugging gas2nel.setOptions({ include: ["metric", "report"] }); // For production gas2nel.setOptions({}); // Minimal output
-
Monitor Specific Operations
// Good: Monitoring specific operation await gas2nel.estimateGas(specificOperation); // Avoid: Monitoring too much await gas2nel.estimateGas(async () => { await operation1(); await operation2(); await operation3(); });
Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.