Isolated workflow orchestration environment for testing and development

Getting Started


Flow Sandbox is an isolated testing and development environment within Blazing Flow that allows you to prototype, test, and validate workflow orchestration workloads before deploying to production.

<Alert type="warn">
  <div className="flex flex-col gap-2">
    <div className="font-semibold">Coming Soon</div>
    <div>
      Flow Sandbox is currently in development. Get in touch for priority access and early-bird pricing.
    </div>
  </div>
</Alert>

## Overview

Flow Sandbox provides a safe, isolated environment where you can:

- **Test Workflows**: Run and debug workflow orchestrations without affecting production
- **Prototype Pipelines**: Experiment with data processing workflows
- **Validate at Scale**: Test with production-sized datasets in isolation
- **Develop Safely**: Build and iterate on workflows in a dedicated environment

### Key Features

- **Isolated Execution**: Complete separation from production workloads
- **Production-Like**: Same infrastructure and capabilities as production Blazing Flow
- **Cost-Effective**: Pay only for the resources you use during testing
- **Quick Provisioning**: Spin up sandbox environments in minutes
- **Easy Migration**: Promote tested workloads to production with minimal changes

## Use Cases

### Development and Testing

Create dedicated sandbox environments for:

- **Unit Testing**: Test individual workflow components in isolation
- **Integration Testing**: Validate end-to-end data pipelines
- **Performance Testing**: Benchmark jobs with production-scale datasets
- **Regression Testing**: Verify changes don't break existing functionality

### Prototyping

Experiment with new approaches:

- **Algorithm Development**: Test new data processing algorithms
- **Pipeline Design**: Prototype complex multi-stage workflows
- **Tool Evaluation**: Try different workflow orchestration tools and frameworks
- **Architecture Validation**: Prove out design patterns before production implementation

### Training and Learning

Safe environment for learning:

- **Onboarding**: Train new team members without risk
- **Experimentation**: Learn workflow orchestration best practices
- **Documentation**: Generate tutorials and runbooks
- **Demos**: Showcase capabilities to stakeholders

## How It Works

Flow Sandbox provides isolated environments with the same capabilities as production Blazing Flow:

```mermaid
graph LR
    Dev[Developer] --> SB[Sandbox Environment]
    SB --> Compute[Compute Resources]
    SB --> Storage[Isolated Storage]
    SB --> Network[Private Network]

    SB -.->|Promote| Prod[Production]

    style SB fill:#FA4F1D,stroke:#FA4F1D,color:#fff
    style Prod fill:#1a1a1a,stroke:#FA4F1D
    style Compute fill:#1a1a1a,stroke:#555
    style Storage fill:#1a1a1a,stroke:#555
    style Network fill:#1a1a1a,stroke:#555
```

### Isolation Guarantees

Each sandbox environment includes:

1. **Dedicated Compute**: Isolated processing resources
2. **Private Storage**: Separate data storage with no cross-contamination
3. **Network Isolation**: Private networking with optional connectivity
4. **IAM Separation**: Distinct identity and access management
5. **Resource Limits**: Configurable quotas to control costs

## Sandbox Lifecycle

### 1. Create Sandbox

Provision a new sandbox environment:

```bash
blazing sandbox create \
  --name my-dev-sandbox \
  --region us-west-2 \
  --compute-tier standard
```

### 2. Develop and Test

Deploy and test your workflows:

```bash
# Deploy workflow to sandbox
blazing flow deploy \
  --sandbox my-dev-sandbox \
  --job data-processing-pipeline

# Run test with sample data
blazing flow run \
  --sandbox my-dev-sandbox \
  --job data-processing-pipeline \
  --input s3://sandbox-data/sample.csv
```

### 3. Validate Results

Review outputs and metrics:

- Job execution logs
- Processing metrics
- Output data validation
- Cost analysis

### 4. Promote to Production

Once validated, promote to production:

```bash
blazing flow promote \
  --from my-dev-sandbox \
  --job data-processing-pipeline \
  --to production
```

## Sandbox Types

### Development Sandbox

For active development and iteration:

- **Persistent**: Long-lived environment for ongoing work
- **Full Access**: Complete control over configuration
- **Shared Resources**: Cost-effective resource sharing
- **Quick Iteration**: Fast deployment cycles

### Testing Sandbox

For automated testing:

- **Ephemeral**: Created on-demand for test runs
- **Reproducible**: Consistent environment for each test
- **Isolated**: Completely separate from other sandboxes
- **CI/CD Integration**: Automated testing in pipelines

### Staging Sandbox

For pre-production validation:

- **Production-Like**: Mirrors production configuration
- **Realistic Scale**: Production-sized datasets and workloads
- **Extended Retention**: Longer data retention for validation
- **Performance Testing**: Load and stress testing

## Resource Management

### Compute Resources

Control sandbox compute allocation:

- **CPU/Memory**: Configure compute tier (small, standard, large)
- **GPU Support**: Optional GPU resources for ML workloads
- **Autoscaling**: Automatic scaling within defined limits
- **Spot Instances**: Use spot instances for cost savings

### Storage

Isolated storage for each sandbox:

- **Object Storage**: S3-compatible storage for input/output data
- **Database**: Optional database for metadata and results
- **Temporary Storage**: Fast ephemeral storage for processing
- **Retention Policies**: Automatic cleanup of old data

### Cost Controls

Manage sandbox costs:

- **Resource Quotas**: Set maximum compute and storage limits
- **Auto-Shutdown**: Automatically stop inactive sandboxes
- **Budget Alerts**: Notifications when approaching spend limits
- **Usage Tracking**: Detailed cost breakdown by sandbox

## Integration with Blazing Flow

Flow Sandbox seamlessly integrates with Blazing Flow production environments:

### Shared Configurations

- **Job Definitions**: Reuse job configurations between sandbox and production
- **Secrets Management**: Separate secrets with same structure
- **Monitoring**: Same observability tools and dashboards
- **IAM Policies**: Consistent permission model

### Promotion Workflow

Move validated workloads to production:

1. **Code Review**: Review and approve workflow changes
2. **Configuration Update**: Adjust production-specific settings
3. **Gradual Rollout**: Deploy with canary or blue-green strategy
4. **Monitoring**: Track production metrics post-deployment
5. **Rollback**: Quick rollback if issues detected

## Getting Started

<Alert type="info">
  <div className="flex flex-col gap-2">
    <div className="font-semibold">Priority Access Available</div>
    <div>
      Flow Sandbox is coming soon. Contact us to get priority access and early-bird pricing.
    </div>
  </div>
</Alert>

### Prerequisites

- Blazing Flow account
- Basic understanding of workflow orchestration
- Batch job definitions ready for testing

### Quick Start

1. **Request Access**: Contact us for Flow Sandbox early access
2. **Create Sandbox**: Provision your first sandbox environment
3. **Deploy Job**: Upload and deploy a test workflow
4. **Run Tests**: Execute jobs with sample data
5. **Promote**: Move validated jobs to production

## Pricing

Flow Sandbox pricing will be based on actual resource usage:

- **Compute**: Pay for compute hours (CPU/GPU)
- **Storage**: Pay for data stored in sandbox
- **Networking**: Pay for data transfer
- **No Base Fee**: Only pay for resources used

**Coming Soon**: Detailed pricing will be announced with product launch.

## Support

Need help with Flow Sandbox?

- **Documentation**: Browse our comprehensive guides (coming soon)
- **Community**: Join our Discord for peer support
- **Priority Access**: Contact us for early access and dedicated support

## Next Steps

- **Contact Us**: Get priority access to Flow Sandbox
- **Learn More**: Read about Blazing Flow capabilities
- **Explore**: Check out workflow orchestration best practices


Flow Sandbox Introduction


Flow Sandbox provides an isolated environment for developing, testing, and debugging Blazing Flow workflows without affecting production systems.

## What is Flow Sandbox?

Flow Sandbox is an isolated workflow orchestration environment that lets you:

- **Test workflows** without affecting production
- **Debug issues** with detailed execution traces
- **Develop faster** with instant feedback
- **Validate changes** before deploying to production
- **Replay scenarios** to reproduce and fix bugs

## Prerequisites

Before you begin, ensure you have:

- A Blazing Core account
- Blazing CLI installed (`npm install -g @blazing/cli`)
- Basic understanding of Blazing Flow
- Node.js 18+ or Python 3.8+

## Installation

### Install Blazing CLI

```bash
npm install -g @blazing/cli
```

### Authenticate

```bash
blazing login
```

## Create Your First Sandbox

### 1. Initialize Sandbox

Create a new sandbox environment:

```bash
blazing sandbox create my-first-sandbox
```

This creates an isolated environment with:
- Dedicated workflow executor
- Isolated state store
- Separate event queue
- Independent metrics

### 2. Configure Sandbox

Create a `sandbox.yaml` configuration:

```yaml
version: 1

sandbox:
  name: my-first-sandbox

  # Execution settings
  execution:
    timeout: 5m
    max_retries: 3
    parallelism: 10

  # State isolation
  state:
    storage: memory  # memory, postgres, redis
    ttl: 24h         # Auto-cleanup after 24 hours

  # Event routing
  events:
    mode: isolated   # isolated, mirror, hybrid
```

Apply the configuration:

```bash
blazing sandbox apply --config sandbox.yaml
```

### 3. Deploy Workflow to Sandbox

Deploy a test workflow:

```python
# workflow.py
from blazing import Flow

flow = Flow(name="test-workflow")

@flow.task
async def process_data(data: dict):
    """Process incoming data"""
    result = {
        'processed': True,
        'input': data,
        'timestamp': datetime.now().isoformat()
    }
    return result

@flow.task
async def send_notification(result: dict):
    """Send notification about processed data"""
    print(f"Data processed: {result}")
    return result
```

Deploy to sandbox:

```bash
blazing sandbox deploy \
  --sandbox my-first-sandbox \
  --workflow workflow.py
```

### 4. Run Workflow in Sandbox

Execute the workflow:

```bash
blazing sandbox run test-workflow \
  --sandbox my-first-sandbox \
  --input '{"data": "test-value"}'
```

You'll see real-time execution output:

```
[12:34:56] Starting workflow: test-workflow
[12:34:56] Task started: process_data
[12:34:57] Task completed: process_data (1.2s)
[12:34:57] Task started: send_notification
[12:34:57] Data processed: {'processed': True, 'input': {'data': 'test-value'}, ...}
[12:34:57] Task completed: send_notification (0.1s)
[12:34:57] Workflow completed successfully (1.3s)
```

### 5. Inspect Execution

View detailed execution trace:

```bash
blazing sandbox trace <execution-id>
```

This shows:
- Task execution timeline
- Input/output for each task
- State changes
- Error details (if any)
- Resource usage

## Development Workflow

### Local Development

Run sandbox locally for faster iteration:

```bash
# Start local sandbox
blazing sandbox local start

# Deploy workflow
blazing sandbox local deploy workflow.py

# Run workflow
blazing sandbox local run test-workflow --input test-data.json

# Watch for changes and auto-reload
blazing sandbox local watch workflow.py
```

### Testing Workflows

Write tests using the sandbox:

```python
# test_workflow.py
import pytest
from blazing.testing import SandboxClient

@pytest.fixture
async def sandbox():
    """Create test sandbox"""
    client = SandboxClient("test-sandbox")
    await client.deploy("workflow.py")
    yield client
    await client.cleanup()

async def test_process_data(sandbox):
    """Test data processing workflow"""

    # Run workflow
    result = await sandbox.run(
        "test-workflow",
        input={"data": "test-value"}
    )

    # Assertions
    assert result['status'] == 'completed'
    assert result['output']['processed'] is True
    assert result['duration'] < 5.0  # < 5 seconds

async def test_error_handling(sandbox):
    """Test error handling"""

    # Run with invalid input
    result = await sandbox.run(
        "test-workflow",
        input={"invalid": "data"}
    )

    # Should handle error gracefully
    assert result['status'] == 'failed'
    assert 'error' in result
```

Run tests:

```bash
pytest test_workflow.py
```

### Debugging Workflows

Enable debug mode for detailed logging:

```bash
# Run with debug logging
blazing sandbox run test-workflow \
  --sandbox my-first-sandbox \
  --input test-data.json \
  --debug

# Stream logs in real-time
blazing sandbox logs my-first-sandbox --follow

# Get execution trace
blazing sandbox trace <execution-id> --verbose
```

## Sandbox Modes

### Isolated Mode (Default)

Complete isolation from production:

```yaml
sandbox:
  events:
    mode: isolated
```

- Workflows run in complete isolation
- No interaction with production systems
- Safe for testing breaking changes

### Mirror Mode

Mirror production events for testing:

```yaml
sandbox:
  events:
    mode: mirror
    source: production
    sampling_rate: 0.1  # Mirror 10% of events
```

- Receive copy of production events
- Test with real data patterns
- Validate changes against live traffic

### Hybrid Mode

Combine isolation with selective production integration:

```yaml
sandbox:
  events:
    mode: hybrid
    sources:
      - type: isolated
        weight: 70
      - type: mirror
        source: production
        weight: 30
        sampling_rate: 0.5
```

## Environment Management

### Create Multiple Sandboxes

Create sandboxes for different purposes:

```bash
# Development sandbox
blazing sandbox create dev-sandbox --config dev.yaml

# Staging sandbox
blazing sandbox create staging-sandbox --config staging.yaml

# Testing sandbox
blazing sandbox create test-sandbox --config test.yaml
```

### List Sandboxes

```bash
blazing sandbox list
```

Output:
```
NAME              STATUS    CREATED          WORKFLOWS
dev-sandbox       running   2 hours ago      3
staging-sandbox   running   1 day ago        5
test-sandbox      stopped   1 week ago       2
```

### Switch Between Sandboxes

```bash
# Set default sandbox
blazing sandbox use dev-sandbox

# Run command in specific sandbox
blazing sandbox run workflow --sandbox staging-sandbox
```

## Data Management

### Reset Sandbox State

Clear all state and start fresh:

```bash
blazing sandbox reset my-first-sandbox
```

### Export Sandbox Data

Export workflow executions for analysis:

```bash
blazing sandbox export my-first-sandbox \
  --format json \
  --output sandbox-data.json
```

### Import Test Data

Load test data into sandbox:

```bash
blazing sandbox import my-first-sandbox \
  --file test-data.json
```

## Integration with CI/CD

### GitHub Actions

```yaml
# .github/workflows/test-workflows.yml
name: Test Workflows

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - name: Install Blazing CLI
        run: npm install -g @blazing/cli

      - name: Authenticate
        run: blazing login --token ${{ secrets.BLAZING_TOKEN }}

      - name: Create test sandbox
        run: blazing sandbox create ci-${{ github.run_id }}

      - name: Deploy workflows
        run: blazing sandbox deploy --sandbox ci-${{ github.run_id }} .

      - name: Run tests
        run: pytest tests/

      - name: Cleanup sandbox
        if: always()
        run: blazing sandbox delete ci-${{ github.run_id }}
```

## Best Practices

### 1. Use Descriptive Names

```bash
# Good
blazing sandbox create feature-user-auth
blazing sandbox create bugfix-payment-retry

# Bad
blazing sandbox create test1
blazing sandbox create sandbox2
```

### 2. Set Resource Limits

```yaml
sandbox:
  resources:
    max_executions: 1000
    max_duration: 1h
    max_memory: 512MB
```

### 3. Auto-Cleanup

```yaml
sandbox:
  cleanup:
    enabled: true
    after: 24h  # Delete sandbox after 24 hours of inactivity
```

### 4. Use Version Control

```bash
# Save sandbox configuration
blazing sandbox export-config my-sandbox > sandbox.yaml

# Commit to git
git add sandbox.yaml
git commit -m "Add sandbox configuration"
```

## Next Steps

- [Learn about sandbox features](/docs/features-overview)
- [Explore advanced examples](/docs/sandbox-examples)
- [Learn about Blazing Flow](/docs/flow-overview)

## Troubleshooting

### Sandbox won't start

Check resource quotas:

```bash
blazing sandbox quota
```

### Workflows fail in sandbox but work in production

Compare configurations:

```bash
blazing sandbox diff my-sandbox production
```

### Slow execution in sandbox

Increase parallelism:

```yaml
sandbox:
  execution:
    parallelism: 20  # Increase from default
```

## Getting Help

- Join our [Discord community](https://discord.gg/blazing)
- Check the [Flow Sandbox documentation](/docs/introduction)
- Contact support at support@blazing.run


Quick Start Guide

Comprehensive guide to Flow Sandbox features and capabilities

Features


Flow Sandbox provides powerful features for developing, testing, and debugging Blazing Flow workflows in isolation.

## Core Features

### 1. Isolated Execution Environment

Run workflows in complete isolation from production systems.

**Benefits:**
- Test breaking changes safely
- Experiment without risk
- Develop independently
- Validate before production

**Configuration:**

```yaml
sandbox:
  isolation:
    level: strict  # strict, moderate, permissive

    # Resource isolation
    resources:
      cpu: 2
      memory: 4GB
      storage: 10GB

    # Network isolation
    network:
      mode: isolated
      allowed_endpoints:
        - https://api.example.com
        - https://external-service.com
```

### 2. State Management

Manage workflow state independently from production.

**Storage Options:**

```yaml
sandbox:
  state:
    # In-memory (fastest, non-persistent)
    storage: memory

    # PostgreSQL (persistent, queryable)
    # storage: postgres
    # connection: postgresql://localhost/sandbox

    # Redis (fast, persistent)
    # storage: redis
    # connection: redis://localhost:6379

    # TTL for automatic cleanup
    ttl: 24h
```

**State Operations:**

```bash
# View current state
blazing sandbox state get <execution-id>

# Modify state for testing
blazing sandbox state set <execution-id> --key foo --value bar

# Reset state
blazing sandbox state reset <execution-id>

# Export state snapshot
blazing sandbox state export --output state.json
```

### 3. Event Replay

Replay historical events to test workflows.

**Capture Events:**

```bash
# Capture production events
blazing events capture \
  --source production \
  --output events.json \
  --duration 1h
```

**Replay in Sandbox:**

```bash
# Replay captured events
blazing sandbox replay events.json \
  --sandbox my-sandbox \
  --speed 10x  # Replay at 10x speed
```

**Selective Replay:**

```yaml
sandbox:
  replay:
    # Filter events
    filters:
      - event_type: "order.created"
      - user_id: "test-user-123"

    # Time manipulation
    speed: 10x          # 10x faster
    start_time: "2024-01-01T00:00:00Z"

    # Error injection
    inject_errors:
      - rate: 0.05      # 5% error rate
        type: timeout
      - rate: 0.02      # 2% error rate
        type: network
```

### 4. Time Travel Debugging

Step through workflow execution like a debugger.

**Features:**
- Pause execution at any point
- Step forward/backward through tasks
- Inspect state at each step
- Modify variables and resume

**Usage:**

```bash
# Start workflow in debug mode
blazing sandbox debug test-workflow \
  --sandbox my-sandbox \
  --breakpoint process_data

# Debug commands
> step           # Execute next task
> continue       # Continue to next breakpoint
> back           # Step backward
> state          # Show current state
> set key=value  # Modify state
> restart        # Restart from beginning
```

**Programmatic Debugging:**

```python
from blazing.testing import SandboxDebugger

async def debug_workflow():
    debugger = SandboxDebugger("my-sandbox")

    # Set breakpoints
    debugger.breakpoint("process_data")
    debugger.breakpoint("send_notification")

    # Start execution
    execution = await debugger.run("test-workflow")

    # Wait for breakpoint
    await debugger.wait_for_break()

    # Inspect state
    state = debugger.get_state()
    print(f"Current state: {state}")

    # Modify variables
    debugger.set_variable("retry_count", 5)

    # Continue
    await debugger.continue_execution()
```

### 5. Performance Profiling

Profile workflow performance and identify bottlenecks.

**Enable Profiling:**

```bash
blazing sandbox run test-workflow \
  --sandbox my-sandbox \
  --profile
```

**Profiling Output:**

```
Workflow Execution Profile
==========================

Total Duration: 5.234s

Task Breakdown:
  process_data:       2.103s (40.2%)  ████████████
  validate_data:      1.521s (29.1%)  ████████
  send_notification:  0.821s (15.7%)  ████
  log_metrics:        0.789s (15.0%)  ████

Waiting Time: 0.532s (10.2%)

Top Bottlenecks:
  1. process_data: High CPU usage
  2. validate_data: Network latency
  3. Waiting for external API: 0.5s
```

**Detailed Profiling:**

```yaml
sandbox:
  profiling:
    enabled: true

    # Metrics to collect
    metrics:
      - cpu_usage
      - memory_usage
      - network_io
      - disk_io

    # Sampling rate
    sample_rate: 100ms

    # Export format
    export:
      format: json
      destination: s3://profiling-data
```

### 6. Mock External Services

Mock external APIs and services for testing.

**Define Mocks:**

```yaml
sandbox:
  mocks:
    # Mock HTTP endpoints
    - endpoint: "https://api.stripe.com/*"
      responses:
        - method: POST
          path: "/v1/charges"
          status: 200
          body:
            id: "ch_mock123"
            status: "succeeded"
          latency: 100ms

    # Mock with dynamic responses
    - endpoint: "https://api.example.com/*"
      handler: "./mocks/api-handler.py"

    # Mock failures
    - endpoint: "https://flaky-api.com/*"
      responses:
        - status: 500
          probability: 0.2  # 20% failure rate
        - status: 200
          probability: 0.8  # 80% success rate
```

**Mock Handler:**

```python
# mocks/api-handler.py
from blazing.mocks import MockHandler

handler = MockHandler()

@handler.route("POST", "/api/users")
async def create_user(request):
    """Mock user creation"""
    user_data = request.json()

    return {
        "id": f"mock-{uuid4()}",
        "email": user_data["email"],
        "created_at": datetime.now().isoformat()
    }, 201

@handler.route("GET", "/api/users/:id")
async def get_user(request, id):
    """Mock user retrieval"""
    return {
        "id": id,
        "email": f"user-{id}@example.com"
    }
```

### 7. Chaos Engineering

Inject failures to test resilience.

**Chaos Configuration:**

```yaml
sandbox:
  chaos:
    enabled: true

    # Failure injection
    failures:
      - type: task_timeout
        targets:
          - task: process_data
        rate: 0.1  # 10% of executions

      - type: network_latency
        targets:
          - service: external-api
        latency: 2s-5s  # Random latency between 2-5s

      - type: data_corruption
        targets:
          - state: user_data
        rate: 0.05

      - type: resource_exhaustion
        targets:
          - resource: memory
        threshold: 90%  # Exhaust memory to 90%
```

**Chaos Commands:**

```bash
# Run with chaos
blazing sandbox chaos test-workflow \
  --sandbox my-sandbox \
  --failure-rate 0.1

# Specific chaos scenarios
blazing sandbox chaos test-workflow \
  --inject timeout \
  --inject network-partition \
  --inject cpu-spike
```

### 8. Snapshot & Restore

Save and restore sandbox state for reproducible testing.

**Create Snapshot:**

```bash
# Create snapshot
blazing sandbox snapshot create my-sandbox \
  --name before-migration \
  --description "State before database migration"
```

**Restore Snapshot:**

```bash
# Restore to previous state
blazing sandbox snapshot restore my-sandbox \
  --snapshot before-migration
```

**Snapshot Management:**

```bash
# List snapshots
blazing sandbox snapshot list my-sandbox

# Compare snapshots
blazing sandbox snapshot diff \
  snapshot-1 snapshot-2

# Export snapshot
blazing sandbox snapshot export \
  before-migration \
  --output snapshot.tar.gz
```

### 9. Collaborative Testing

Share sandboxes with team members.

**Share Sandbox:**

```bash
# Share with team member
blazing sandbox share my-sandbox \
  --email teammate@example.com \
  --role developer

# Create shareable link
blazing sandbox link my-sandbox \
  --expires 7d
```

**Access Control:**

```yaml
sandbox:
  access:
    # Team members
    members:
      - email: developer@example.com
        role: developer
      - email: qa@example.com
        role: tester

    # Roles and permissions
    roles:
      developer:
        - deploy
        - execute
        - debug
      tester:
        - execute
        - view_logs
```

### 10. Metrics & Observability

Monitor sandbox execution with detailed metrics.

**Built-in Metrics:**

```bash
# View real-time metrics
blazing sandbox metrics my-sandbox --live

# Export metrics
blazing sandbox metrics export \
  --format prometheus \
  --output metrics.txt
```

**Custom Metrics:**

```python
from blazing import Flow, metrics

flow = Flow(name="test-workflow")

@flow.task
async def process_data(data):
    # Record custom metric
    metrics.counter("data_processed").inc()

    # Record timing
    with metrics.timer("processing_time"):
        result = await process(data)

    # Record gauge
    metrics.gauge("queue_size").set(len(queue))

    return result
```

**Visualization:**

```yaml
sandbox:
  metrics:
    enabled: true

    # Export to monitoring systems
    exporters:
      - type: prometheus
        endpoint: "http://prometheus:9090"

      - type: datadog
        api_key: "${DATADOG_API_KEY}"

      - type: grafana
        dashboard: "sandbox-metrics"
```

## Advanced Features

### A/B Testing

Test different workflow versions side-by-side:

```yaml
sandbox:
  ab_testing:
    enabled: true

    variants:
      - name: control
        workflow: workflow-v1.py
        traffic: 50

      - name: experiment
        workflow: workflow-v2.py
        traffic: 50

    metrics:
      - name: success_rate
        goal: maximize
      - name: latency
        goal: minimize
```

### Cost Analysis

Estimate production costs:

```bash
# Run cost analysis
blazing sandbox cost-estimate test-workflow \
  --sandbox my-sandbox \
  --duration 30d

Output:
Estimated Monthly Cost: $125.45
  Compute: $89.20
  Storage: $23.15
  Network: $13.10
```

### Integration Testing

Test integrations with external services:

```yaml
sandbox:
  integrations:
    # Test with real services in sandbox mode
    - service: stripe
      mode: test
      api_key: "${STRIPE_TEST_KEY}"

    - service: aws
      mode: sandbox
      region: us-east-1
      account: sandbox-account
```

## Next Steps

- [Try sandbox examples](/docs/sandbox-examples)
- [Get started with Flow Sandbox](/docs/quick-start)
- [Learn about Blazing Flow](/docs/flow-overview)


Explore Flow Sandbox features and capabilities

Features Overview

Practical examples and use cases for Flow Sandbox

Examples


Explore practical examples of using Flow Sandbox for development, testing, and debugging workflows.

## Example 1: Testing Payment Processing

Test a payment processing workflow with different scenarios.

### Workflow

```python
# payment_workflow.py
from blazing import Flow
import stripe

flow = Flow(name="payment-processing")

@flow.task
async def create_charge(order_id: str, amount: int):
    """Create Stripe charge"""
    charge = stripe.Charge.create(
        amount=amount,
        currency="usd",
        source="tok_visa",
        description=f"Order {order_id}"
    )
    return charge

@flow.task
async def update_order(order_id: str, charge_id: str):
    """Update order with charge ID"""
    await db.orders.update(
        order_id,
        status="paid",
        charge_id=charge_id
    )

@flow.task
async def send_confirmation(order_id: str):
    """Send confirmation email"""
    await email.send(
        to=get_customer_email(order_id),
        template="order_confirmation",
        data={"order_id": order_id}
    )
```

### Sandbox Configuration

```yaml
# sandbox.yaml
sandbox:
  name: payment-testing

  # Mock Stripe API
  mocks:
    - endpoint: "https://api.stripe.com/*"
      responses:
        # Successful charge
        - path: "/v1/charges"
          method: POST
          status: 200
          body:
            id: "ch_mock123"
            status: "succeeded"
          probability: 0.8

        # Card declined
        - path: "/v1/charges"
          method: POST
          status: 402
          body:
            error:
              type: "card_error"
              code: "card_declined"
          probability: 0.1

        # Network error
        - path: "/v1/charges"
          method: POST
          status: 500
          probability: 0.1
```

### Test Suite

```python
# test_payment.py
import pytest
from blazing.testing import SandboxClient

@pytest.fixture
async def sandbox():
    client = SandboxClient("payment-testing")
    await client.deploy("payment_workflow.py")
    yield client
    await client.cleanup()

async def test_successful_payment(sandbox):
    """Test successful payment flow"""

    result = await sandbox.run(
        "payment-processing",
        input={
            "order_id": "order-123",
            "amount": 5000
        }
    )

    assert result['status'] == 'completed'
    assert result['output']['charge_id'].startswith('ch_')

async def test_card_declined(sandbox):
    """Test card declined scenario"""

    # Force card decline with mock
    sandbox.mock_response(
        "https://api.stripe.com/v1/charges",
        status=402,
        body={"error": {"code": "card_declined"}}
    )

    result = await sandbox.run(
        "payment-processing",
        input={"order_id": "order-456", "amount": 5000}
    )

    # Should handle error gracefully
    assert result['status'] == 'failed'
    assert 'card_declined' in str(result['error'])

async def test_retry_logic(sandbox):
    """Test payment retry on temporary failures"""

    # First attempt fails, second succeeds
    sandbox.mock_responses(
        "https://api.stripe.com/v1/charges",
        [
            {"status": 500},  # First attempt fails
            {"status": 200, "body": {"id": "ch_retry", "status": "succeeded"}}  # Retry succeeds
        ]
    )

    result = await sandbox.run(
        "payment-processing",
        input={"order_id": "order-789", "amount": 5000}
    )

    # Should retry and succeed
    assert result['status'] == 'completed'
    assert result['retry_count'] == 1
```

## Example 2: Debugging a Production Issue

Reproduce and fix a production bug using sandbox replay.

### Capture Production Events

```bash
# Capture events from production issue
blazing events capture \
  --source production \
  --filter "order_id=order-12345" \
  --time "2024-01-15T10:00:00Z" to "2024-01-15T11:00:00Z" \
  --output production-issue.json
```

### Replay in Sandbox

```bash
# Create debug sandbox
blazing sandbox create debug-order-12345

# Deploy current code
blazing sandbox deploy workflow.py --sandbox debug-order-12345

# Replay the events
blazing sandbox replay production-issue.json \
  --sandbox debug-order-12345 \
  --debug
```

### Debug Session

```bash
# Start debugging
blazing sandbox debug \
  --sandbox debug-order-12345 \
  --execution <execution-id>

# Debug commands
> breakpoint process_payment
> run

# Execution stops at breakpoint
> state
{
  "order_id": "order-12345",
  "amount": 5000,
  "customer_id": "cust-789"
}

> step
# Executes process_payment task

> state
{
  "order_id": "order-12345",
  "charge_id": null,  # <- Issue: charge_id is null!
  "error": "Amount cannot be negative"
}

# Found the bug: amount is being calculated incorrectly
```

### Fix and Verify

```python
# Fixed workflow
@flow.task
async def calculate_amount(order):
    # Bug was here: missing abs()
    subtotal = sum(item.price * item.quantity for item in order.items)
    tax = subtotal * 0.1
    total = abs(subtotal + tax)  # Fixed: ensure positive
    return int(total * 100)  # Convert to cents
```

```bash
# Deploy fix
blazing sandbox deploy workflow.py --sandbox debug-order-12345

# Replay again to verify
blazing sandbox replay production-issue.json \
  --sandbox debug-order-12345

# Success! Issue resolved.
```

## Example 3: Load Testing

Test workflow performance under load.

### Load Test Configuration

```yaml
# loadtest.yaml
sandbox:
  name: load-test

  # Scale resources
  resources:
    cpu: 8
    memory: 16GB
    parallelism: 100

  # Load test settings
  load_test:
    duration: 10m
    ramp_up: 2m

    # Workload patterns
    patterns:
      - type: constant
        rate: 100  # 100 req/s
        duration: 5m

      - type: spike
        rate: 500  # Spike to 500 req/s
        duration: 1m

      - type: gradual
        start_rate: 100
        end_rate: 1000
        duration: 4m
```

### Run Load Test

```bash
# Start load test
blazing sandbox loadtest test-workflow \
  --sandbox load-test \
  --config loadtest.yaml
```

### Analyze Results

```
Load Test Results
=================

Duration: 10m 0s
Total Requests: 150,000

Success Rate: 99.2%
  Successful: 148,800
  Failed: 1,200

Latency:
  p50: 45ms
  p95: 123ms
  p99: 287ms
  max: 1,205ms

Throughput:
  Average: 250 req/s
  Peak: 487 req/s

Bottlenecks Identified:
  1. Task 'validate_data': High latency under load
  2. Database connections: Pool exhaustion at >300 req/s
  3. External API: Rate limiting at 400 req/s
```

## Example 4: Chaos Engineering

Test resilience with chaos experiments.

### Chaos Configuration

```yaml
# chaos.yaml
sandbox:
  name: chaos-testing

  chaos:
    enabled: true

    experiments:
      # Experiment 1: Network latency
      - name: "High Latency"
        duration: 5m
        failure:
          type: network_latency
          targets:
            - service: external-api
          latency: 2s-5s

      # Experiment 2: Service unavailable
      - name: "Service Down"
        duration: 3m
        failure:
          type: service_unavailable
          targets:
            - service: payment-api
          rate: 0.5  # 50% failure rate

      # Experiment 3: Resource exhaustion
      - name: "Memory Pressure"
        duration: 5m
        failure:
          type: memory_exhaustion
          threshold: 95%
```

### Run Chaos Experiments

```bash
# Run chaos test
blazing sandbox chaos test-workflow \
  --sandbox chaos-testing \
  --config chaos.yaml \
  --iterations 1000
```

### Results

```
Chaos Test Results
==================

Experiment: High Latency
  Success Rate: 98.5%
  Average Retries: 1.2
  Timeout Rate: 1.5%
  ✓ Workflow handled latency well

Experiment: Service Down
  Success Rate: 94.2%
  Fallback Triggered: 50%
  Failed: 5.8%
  ⚠ Some failures without fallback

Experiment: Memory Pressure
  Success Rate: 91.3%
  OOM Errors: 8.7%
  ✗ Needs better memory management

Recommendations:
  1. Implement fallback for payment-api
  2. Add memory limits to prevent OOM
  3. Consider circuit breaker pattern
```

## Example 5: A/B Testing Workflows

Compare two workflow versions.

### Setup A/B Test

```yaml
# ab-test.yaml
sandbox:
  name: ab-testing

  ab_testing:
    enabled: true

    variants:
      # Control group
      - name: current
        workflow: workflow-v1.py
        traffic: 50

      # Experiment group
      - name: optimized
        workflow: workflow-v2.py
        traffic: 50

    metrics:
      - name: success_rate
        goal: maximize
      - name: latency
        goal: minimize
      - name: cost
        goal: minimize

    duration: 1h
```

### Run A/B Test

```bash
# Start A/B test
blazing sandbox ab-test \
  --sandbox ab-testing \
  --config ab-test.yaml \
  --requests 10000
```

### Results

```
A/B Test Results
================

Variant: current (baseline)
  Success Rate: 97.2%
  Avg Latency: 245ms
  Cost per 1k: $0.52

Variant: optimized
  Success Rate: 98.8% (+1.6% ✓)
  Avg Latency: 189ms (-23% ✓)
  Cost per 1k: $0.41 (-21% ✓)

Statistical Significance: 99.9%

Recommendation: Deploy 'optimized' variant to production
```

## Example 6: Integration Testing

Test workflow with real external services in sandbox mode.

### Configuration

```yaml
# integration-test.yaml
sandbox:
  name: integration-testing

  integrations:
    # Use Stripe test mode
    - service: stripe
      mode: test
      api_key: "${STRIPE_TEST_KEY}"

    # Use real AWS but isolated account
    - service: aws
      mode: sandbox
      account: "sandbox-account"
      region: us-east-1

    # Mock other services
    - service: sendgrid
      mode: mock
```

### Integration Tests

```python
# test_integrations.py
import pytest
from blazing.testing import SandboxClient

@pytest.fixture
async def sandbox():
    client = SandboxClient("integration-testing")
    await client.deploy("workflow.py")
    yield client
    await client.cleanup()

async def test_stripe_integration(sandbox):
    """Test real Stripe integration in test mode"""

    result = await sandbox.run(
        "payment-workflow",
        input={"amount": 1000, "token": "tok_visa"}
    )

    assert result['status'] == 'completed'

    # Verify charge was created in Stripe test mode
    charge = stripe.Charge.retrieve(result['output']['charge_id'])
    assert charge.amount == 1000
    assert charge.paid is True

async def test_s3_upload(sandbox):
    """Test S3 upload to sandbox bucket"""

    result = await sandbox.run(
        "upload-workflow",
        input={"file": "test-file.txt", "content": "test data"}
    )

    # Verify file in sandbox S3 bucket
    s3 = boto3.client('s3')
    obj = s3.get_object(
        Bucket='sandbox-uploads',
        Key='test-file.txt'
    )
    assert obj['Body'].read() == b'test data'
```

## Example 7: Snapshot Testing

Use snapshots for regression testing.

### Create Baseline Snapshot

```bash
# Run workflow and create snapshot
blazing sandbox run test-workflow \
  --sandbox my-sandbox \
  --snapshot baseline
```

### Make Changes and Compare

```bash
# Deploy updated workflow
blazing sandbox deploy workflow-v2.py --sandbox my-sandbox

# Run and compare to baseline
blazing sandbox run test-workflow \
  --sandbox my-sandbox \
  --compare-snapshot baseline
```

### Snapshot Comparison

```
Snapshot Comparison
===================

Changed Tasks:
  ✗ process_data:
    Execution time: 123ms → 456ms (+270%)
    Output schema changed:
      - Added field: 'processed_at'
      - Removed field: 'legacy_id'

  ✓ send_notification:
    No changes

  ✓ log_metrics:
    Execution time: 45ms → 32ms (-29%)

Recommendation: Review process_data performance regression
```

## Next Steps

- [Get started with Flow Sandbox](/docs/quick-start)
- [Explore sandbox features](/docs/features-overview)
- [Learn about Blazing Flow deployment](/docs/flow-deployment)
