---
title: "WASM Procedures: Monitoring & Debugging"
---

# WASM Procedures: Monitoring & Debugging

:::caution[Planned design: not yet available in the server]
The current `heliosdb-full` server does not run WASM procedures. SQL that
would create or call one fails with SQLSTATE `0A000`. This page describes the
planned design for this upcoming feature. Only the [Go SDK](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_language_sdks/#go-sdk) is
published. Rust, JavaScript and Python examples are illustrations: no SDK
package exists for those languages. See the
[Quick Start](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_quick_start/) for what works today.
:::

**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](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_performance/) - Performance optimization
- [Procedure Management](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_procedure_management/) - Managing procedures
- [Security Model](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_security_model/) - Security monitoring

---

## Monitoring & Debugging

### Execution Metrics

#### View Procedure Statistics

```sql
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

```sql
-- 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

```sql
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

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

### Error Tracking

```sql
-- 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

```sql
-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
-- 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

```sql
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

```sql
-- 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:

```sql
-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
-- 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:**
```json
{
  "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

```sql
-- Planned syntax for the upcoming WASM procedures feature; the current server does not accept it.
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:

```sql
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:

```sql
-- 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:**

```rust
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:**

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

3. **Avoid logging sensitive data:**

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

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

4. **Use structured logging:**

```rust
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](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_advanced_topics/)** - Advanced monitoring patterns
- **[Performance](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_performance/)** - Optimize based on metrics
- **[API Reference](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_api_reference/)** - Complete API documentation

---

**Navigation:** [← Performance](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_performance/) | [Index](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_user_guide/) | [Advanced Topics →](https://www.heliosdb.com/docs/full/guides/features/wasm_procedures_advanced_topics/)