WASM Procedures: Monitoring & Debugging

WASM Procedures: Monitoring & Debugging

Documentation Home > User Guides > Features > Monitoring & Debugging

---

Overview

This guide covers comprehensive monitoring, debugging, logging, and profiling capabilities for WASM procedures in HeliosDB, enabling effective production operation and troubleshooting.

Related Sections:

• Performance - Performance optimization
• Procedure Management - Managing procedures
• Security Model - Security monitoring

---

Monitoring & Debugging

Execution Metrics

View Procedure Statistics

SELECT
    procedure_name,
    total_calls,
    successful_calls,
    failed_calls,
    success_rate,
    avg_execution_time_ms,
    min_execution_time_ms,
    max_execution_time_ms,
    p50_execution_time_ms,
    p95_execution_time_ms,
    p99_execution_time_ms
FROM heliosdb_procedure_metrics
WHERE procedure_name = 'calculate_discount';

Example Output:

procedure_name      | total_calls | successful_calls | failed_calls | success_rate | avg_execution_time_ms
--------------------|-------------|------------------|--------------|--------------|----------------------
calculate_discount  | 15234       | 15198            | 36           | 99.76%       | 7.3

Real-Time Monitoring

-- Monitor active executions
SELECT
    procedure_name,
    execution_id,
    started_at,
    duration_ms,
    status,
    user_id
FROM heliosdb_procedure_executions
WHERE status = 'running'
ORDER BY duration_ms DESC;

Fuel Consumption

SELECT
    procedure_name,
    avg_fuel_consumed,
    max_fuel_consumed,
    fuel_limit,
    fuel_exceeded_count
FROM heliosdb_procedure_fuel_stats;

Example Output:

procedure_name      | avg_fuel_consumed | max_fuel_consumed | fuel_limit   | fuel_exceeded_count
--------------------|-------------------|-------------------|--------------|--------------------
calculate_discount  | 145,234           | 289,421           | 1,000,000    | 0
process_order       | 1,234,567         | 2,456,789         | 10,000,000   | 3

Memory Usage

SELECT
    procedure_name,
    avg_memory_bytes,
    max_memory_bytes,
    memory_limit_bytes,
    oom_count
FROM heliosdb_procedure_memory_stats;

Error Tracking

-- View recent errors
SELECT
    procedure_name,
    error_message,
    error_count,
    last_occurrence,
    stack_trace
FROM heliosdb_procedure_errors
WHERE last_occurrence > NOW() - INTERVAL '1 hour'
ORDER BY error_count DESC;

Example Output:

procedure_name   | error_message              | error_count | last_occurrence
-----------------|----------------------------|-------------|-------------------
process_order    | Insufficient funds         | 12          | 2025-11-02 14:32:15
transfer_funds   | Account not found          | 5           | 2025-11-02 14:28:42

Logging

Configure Log Level

-- Set global log level
SET heliosdb.procedure_log_level = 'info';  -- trace, debug, info, warn, error

-- Set per-procedure log level
ALTER PROCEDURE my_procedure
SET log_level = 'debug';

View Procedure Logs

SELECT
    timestamp,
    procedure_name,
    log_level,
    message,
    execution_id
FROM heliosdb_procedure_logs
WHERE procedure_name = 'calculate_discount'
  AND timestamp > NOW() - INTERVAL '10 minutes'
ORDER BY timestamp DESC
LIMIT 100;

Log Retention

-- Set log retention period (days)
SET heliosdb.procedure_log_retention_days = 30;

-- Manual cleanup
DELETE FROM heliosdb_procedure_logs
WHERE timestamp < NOW() - INTERVAL '30 days';

Profiling

Enable detailed profiling for performance analysis:

-- Enable profiling
ALTER PROCEDURE my_procedure
SET profiling = true;

-- Run procedure
SELECT my_procedure(params);

-- View profiling results
SELECT * FROM heliosdb_procedure_profile
WHERE procedure_name = 'my_procedure'
ORDER BY timestamp DESC
LIMIT 1;

Profiling Output:

{
  "procedure_name": "my_procedure",
  "total_time_ms": 23.4,
  "compilation_time_ms": 2.1,
  "execution_time_ms": 21.3,
  "breakdown": {
    "database_calls": {
      "count": 5,
      "total_time_ms": 15.2
    },
    "host_functions": {
      "count": 12,
      "total_time_ms": 3.1
    },
    "computation": {
      "time_ms": 3.0
    }
  },
  "memory": {
    "peak_bytes": 2048576,
    "allocated_bytes": 1843200,
    "freed_bytes": 1024000
  }
}

Debugging

Enable Debug Mode

ALTER PROCEDURE my_procedure
SET debug_mode = true;

In debug mode:

• Detailed logging enabled
• Stack traces included in errors
• WASM source maps loaded (if available)
• Slower execution (not for production)

Stack Traces

When errors occur, get detailed stack traces:

SELECT
    procedure_name,
    error_message,
    stack_trace,
    source_location
FROM heliosdb_procedure_errors
WHERE procedure_name = 'my_procedure'
ORDER BY occurred_at DESC
LIMIT 1;

Example:

error_message: Division by zero
stack_trace:
  at calculate_total (procedure.wasm:calculate_total:145)
  at process_order (procedure.wasm:process_order:67)
  at main (procedure.wasm:main:12)
source_location: src/lib.rs:145:9

Alerts

Configure alerts for anomalies:

-- Create alert rule
CREATE ALERT RULE slow_procedure_alert
ON heliosdb_procedure_metrics
WHEN avg_execution_time_ms > 1000
THEN NOTIFY 'ops-team@example.com';

-- Create error rate alert
CREATE ALERT RULE high_error_rate
ON heliosdb_procedure_metrics
WHEN success_rate < 95.0
THEN NOTIFY 'ops-team@example.com';

Logging Best Practices

1. Use appropriate log levels:

log_trace("Entering function calculate_discount");  // Development only
log_debug(&format!("Processing order {}", order_id));  // Debugging
log_info("Order processed successfully");  // Normal operations
log_warn("Slow query detected");  // Potential issues
log_error("Failed to process order");  // Errors

2. Include context:

log_info(&format!(
    "User {} performed action {} on resource {} at {}",
    user_id, action, resource, timestamp
));

3. Avoid logging sensitive data:

// Bad
log_info(&format!("Password: {}", password));

// Good
log_info("User authentication attempted");

4. Use structured logging:

log_json(LogLevel::Info, json!({
    "event": "order_processed",
    "order_id": order_id,
    "user_id": user_id,
    "total": total,
    "processing_time_ms": elapsed
}));

---

Key Takeaways

1. Comprehensive Metrics: Track execution time, success rate, fuel consumption, and memory usage
2. Real-Time Monitoring: Monitor active executions and identify slow procedures
3. Error Tracking: Aggregate and track errors with detailed stack traces
4. Flexible Logging: Configure log levels globally or per-procedure
5. Profiling: Deep performance analysis with breakdown by operation type
6. Alerts: Proactive notification of performance degradation or errors

Monitoring Checklist

• Monitor success rate to detect failing procedures
• Track p95/p99 execution times to identify performance regressions
• Review fuel consumption to prevent resource exhaustion
• Check memory usage to avoid OOM errors
• Configure alerts for critical thresholds
• Retain logs for compliance and debugging

Next Steps

• Advanced Topics - Advanced monitoring patterns
• Performance - Optimize based on metrics
• API Reference - Complete API documentation

---

Navigation: ← Performance | Index | Advanced Topics →