Operations

This section covers operational aspects of using the Nexla SDK in production environments, including monitoring, observability, error handling, and troubleshooting.

Advanced Operations

For detailed observability setup, monitoring strategies, and advanced operational patterns, see the Observability & Tracing page in our Nexla SDK guides.

Observability & Monitoring

The SDK provides built-in observability features for production environments:

• OpenTelemetry Integration: Optional tracing for monitoring and debugging
• Comprehensive Metrics: Track pipeline performance and resource usage
• Error Tracking: Rich exception handling with context and retry hints
• Rate Limiting: Automatic handling of API rate limits with exponential backoff

Monitoring Flow Health

Flow Health Check

def check_flow_health():
    flows = client.flows.list(flows_only=True)
    
    status_count = {}
    for flow in flows:
        status = flow.status
        status_count[status] = status_count.get(status, 0) + 1
    
    print("🏥 Flow Health Summary:")
    for status, count in status_count.items():
        emoji = "✅" if status == "running" else "⚠️" if status == "paused" else "❌"
        print(f"   {emoji} {status.title()}: {count} flows")

check_flow_health()

Get Recent Notifications

Notification Monitoring

try:
    notifications = client.notifications.list()
    print(f"\n🔔 Recent Notifications ({len(notifications[:5])} shown):")
    
    for notif in notifications[:5]:
        print(f"  📝 {notif.type}: {notif.message}")
        print(f"     Time: {notif.created_time}")
        print(f"     Severity: {notif.severity}")
        print()
except Exception as e:
    print(f"ℹ️  Notifications not available: {e}")

Error Handling

The SDK provides comprehensive error handling with rich exception classes:

Error Handling Example

from nexla_sdk import NexlaClient
from nexla_sdk.exceptions import NexlaAPIError, AuthenticationError

client = NexlaClient()

try:
    # This might fail if flow doesn't exist
    flow = client.flows.get("non-existent-flow-id")
except AuthenticationError:
    print("❌ Authentication failed - check your credentials")
except NexlaAPIError as e:
    print(f"❌ API Error: {e.message}")
    print(f"Status Code: {e.status_code}")
except Exception as e:
    print(f"❌ Unexpected error: {e}")

Error Types

• 400 → ValidationError
• 401 → AuthenticationError
• 403 → AuthorizationError
• 404 → NotFoundError
• 409 → ResourceConflictError
• 429 → RateLimitError (with retry_after if available)
• 5xx → ServerError

Rate Limits & Retries

The SDK handles rate limiting automatically with exponential backoff:

Rate Limit Handling

from nexla_sdk.exceptions import RateLimitError

def list_sources_with_backoff(client: NexlaClient):
    try:
        return client.sources.list(per_page=100)
    except RateLimitError as exc:
        wait = exc.retry_after or 30
        print(f"Hit rate limit, retrying in {wait}s")
        raise

Retry Configuration

The underlying RequestsHttpClient configures automatic retries for transient HTTP status codes (429, 502, 503, 504) using urllib3 Retry.

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your service key or access token
   • Check if credentials have expired
   • Ensure proper permissions

2. Connection Errors

   • Verify network connectivity
   • Check API endpoint URL
   • Confirm firewall settings

3. Rate Limiting

   • Implement exponential backoff
   • Use pagination for large datasets
   • Monitor rate limit headers

Debugging Tips

Debug Configuration

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# Initialize client with debug info
client = NexlaClient()

Next Steps

• Error Handling - Detailed error management strategies
• Rate Limits & Retries - Best practices for API usage
• Troubleshooting - Common issues and solutions