Running and Debugging

This guide covers how to run your flows, monitor executions, and debug issues effectively.

Running Flows

Automatic Execution

Most flows run automatically based on triggers:

Trigger Type	Activation
HTTP Server	Incoming HTTP request
Ticker	On configured interval
Signal	Manual trigger
External Event	Webhook, message queue

Once deployed, these triggers activate your flow automatically.

Manual Execution

To trigger a flow manually:

1. Using Signal Node

   • Add a Signal component to your flow
   • Click the "Send" button in the node's control panel

2. Using the Run Button

   • Select a node with a trigger capability
   • Click Run in the toolbar

3. Using API

   # Trigger via TinySignal
   kubectl apply -f - <<EOF
   apiVersion: operator.tinysystems.io/v1alpha1
   kind: TinySignal
   metadata:
     name: manual-trigger
     namespace: tinysystems
   spec:
     node: my-node-name
     port: input
     data:
       message: "Hello"
   EOF

Viewing Execution

Execution Panel

The execution panel at the bottom of the editor shows real-time information:

┌─────────────────────────────────────────────────────────────────────┐
│ Executions                                                    [🔄]  │
├─────────────────────────────────────────────────────────────────────┤
│ ⏱ 2024-01-15 10:30:00 │ Duration: 45ms │ Status: ✅ Success        │
│ ⏱ 2024-01-15 10:29:55 │ Duration: 52ms │ Status: ✅ Success        │
│ ⏱ 2024-01-15 10:29:50 │ Duration: 120ms│ Status: ❌ Error          │
└─────────────────────────────────────────────────────────────────────┘

Execution Details

Click an execution to see:

1. Trace View: Visual path through nodes
2. Data View: Input/output at each node
3. Timing: Duration per node
4. Errors: Error messages and stack traces

Trace Visualization

HTTP Server ──▶ Router ──▶ Modify ──▶ HTTP Server
   [15ms]       [5ms]      [10ms]      [15ms]

Total: 45ms

The trace shows:

• Path taken: Which nodes were executed
• Per-node timing: How long each step took
• Data flow: What data moved between nodes

Using the Debug Component

The Debug component is essential for troubleshooting.

Adding Debug Nodes

1. Drag Debug from Common Module onto the canvas
2. Connect it inline or as a branch
3. Deploy the flow

Inline Debugging

┌──────────┐     ┌───────┐     ┌──────────┐
│ HTTP     │────▶│ Debug │────▶│ Modify   │
│ Server   │     │       │     │          │
└──────────┘     └───────┘     └──────────┘

The Debug node passes data through unchanged while logging it.

Branch Debugging

┌──────────┐     ┌───────────┐
│ HTTP     │────▶│ Modify    │
│ Server   │     │           │
└──────────┘     └───────────┘
      │
      └─────────▶┌───────┐
                 │ Debug │  (logs only, doesn't affect main flow)
                 └───────┘

Debug Output

{
  "timestamp": "2024-01-15T10:30:00Z",
  "node": "debug-1",
  "port": "input",
  "data": {
    "method": "POST",
    "path": "/api/webhook",
    "body": {
      "event": "user.created",
      "userId": "12345"
    }
  }
}

Reading Logs

Log Levels

Level	Color	Use
DEBUG	Gray	Detailed information
INFO	Blue	General information
WARN	Yellow	Potential issues
ERROR	Red	Failures

Accessing Logs

In Editor:

1. Open the execution panel
2. Click an execution
3. View logs in the detail panel

In Dashboard:

1. Navigate to Flow > Logs
2. Filter by time range
3. Search by keyword

Via kubectl:

kubectl logs -n tinysystems deployment/my-module -f

Log Filtering

Filter logs by:

• Time range: Last hour, day, week
• Level: ERROR, WARN, INFO, DEBUG
• Node: Specific node name
• Text: Keyword search

Common Issues and Solutions

Flow Not Triggering

Symptoms: Nothing happens when you expect the flow to run.

Checklist:

1. Is the flow deployed? (Green status indicator)
2. Is the trigger configured correctly?
3. Are there any deployment errors?

Solutions:

• Check deployment status
• Verify trigger settings
• Check cluster connectivity

Data Not Mapping Correctly

Symptoms: Output doesn't contain expected data.

Debug Steps:

1. Add Debug node before the problematic edge
2. Check the actual data format
3. Compare with expected schema

Common Causes:

• Typo in expression path
• Missing $ prefix
• Wrong field name (case-sensitive)

Example:

# Wrong
message: "{{.body.text}}"

# Correct
message: "{{$.body.text}}"

Type Mismatch Errors

Symptoms: Error about unexpected type.

Debug Steps:

1. Check source port schema
2. Check target port schema
3. Verify expression produces correct type

Example Fix:

# String when number expected
count: "{{$.items.length}}"  # Returns string

# Force number type
count: {{$.items.length}}    # Returns number (no quotes)

Connection Timeouts

Symptoms: Flow times out waiting for response.

Solutions:

1. Check external service availability
2. Increase timeout settings
3. Add retry logic

Configure Timeout:

# HTTP Client settings
timeout: "60s"
retries: 3

Memory/Resource Issues

Symptoms: Flow fails with resource errors.

Solutions:

1. Process smaller batches
2. Use Split component for arrays
3. Increase module resource limits

Expression Evaluation Errors

Symptoms: Error evaluating expression.

Common Issues:

Error	Cause	Fix
"path not found"	Field doesn't exist	Check spelling, add ? for optional
"cannot index"	Indexing non-array	Verify data is array
"type error"	Operation on wrong type	Check types with Debug

Testing Strategies

Unit Testing Nodes

Test individual nodes in isolation:

1. Create a test flow with just that node
2. Add Signal to trigger
3. Add Debug to capture output
4. Verify expected behavior

Integration Testing

Test complete paths:

1. Deploy to a test cluster
2. Send test requests
3. Verify end-to-end behavior
4. Check all edge cases

Load Testing

For production readiness:

1. Use HTTP load testing tools
2. Monitor resource usage
3. Identify bottlenecks
4. Scale as needed

Monitoring

Metrics

Access flow metrics:

• Request rate: Executions per second
• Error rate: Failed executions percentage
• Latency: P50, P95, P99 execution times
• Active instances: Currently running executions

Alerting

Set up alerts for:

• Error rate > threshold
• Latency > acceptable limit
• Flow not executing (dead letter)
• Resource exhaustion

Best Practices

1. Add Debug Nodes During Development

Always add Debug nodes while building:

• Easy to remove later
• Saves time troubleshooting

2. Use Descriptive Node Names

Name nodes clearly:

• "Validate Request" not "Modify 1"
• "Route by Event Type" not "Router"

3. Check Data at Each Step

Verify data format:

1. Log inputs and outputs
2. Compare with schemas
3. Test edge cases

4. Handle Errors Explicitly

Add error handling:

• Connect to error ports
• Add fallback paths
• Log failures

5. Monitor Production Flows

Set up monitoring:

• Track key metrics
• Alert on anomalies
• Review logs regularly

Next Steps

• Flow Basics - Understand flow concepts
• Data Mapping - Master data transformation
• Expression Syntax - Learn expression language