e6data-python-connector 2.3.11rc1__tar.gz → 2.3.12rc1__tar.gz

{e6data_python_connector-2.3.11rc1/e6data_python_connector.egg-info → e6data_python_connector-2.3.12rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: e6data-python-connector
-Version: 2.3.11rc1
+Version: 2.3.12rc1
 Summary: Client for the e6data distributed SQL Engine.
 Home-page: https://github.com/e6x-labs/e6data-python-connector
 Author: e6data, Inc.
@@ -39,7 +39,7 @@ Dynamic: summary
 
 # e6data Python Connector
 
-![version](https://img.shields.io/badge/version-2.3.11rc1-blue.svg)
+![version](https://img.shields.io/badge/version-2.3.12rc1-blue.svg)
 
 ## Introduction
 
@@ -124,6 +124,7 @@ The `Connection` class supports the following parameters:
 | `secure` | bool | No | False | Enable SSL/TLS for secure connections |
 | `auto_resume` | bool | No | True | Automatically resume cluster if suspended |
 | `grpc_options` | dict | No | None | Additional gRPC configuration options |
+| `debug` | bool | No | False | Enable debug logging for troubleshooting |
 
 #### Secure Connection Example
 
@@ -637,4 +638,58 @@ conn.close()
 - Graceful connection recovery and retry logic
 - Blue-green deployment support with automatic failover
 
+## Debugging and Troubleshooting
+
+### Enable Debug Mode
+
+Enable comprehensive debugging to troubleshoot connection and query issues:
+
+```python
+from e6data_python_connector import Connection
+
+conn = Connection(
+    host=host,
+    port=port,
+    username=username,
+    password=password,
+    database=database,
+    debug=True  # Enable debug logging
+)
+```
+
+When `debug=True`, the following features are enabled:
+- Python logging at DEBUG level for all operations
+- Blue-green strategy transition logging
+- Connection lifecycle logging
+- Query execution detailed logging
+
+### gRPC Network Tracing
+
+For low-level gRPC network debugging (HTTP/2 frames, TCP events), set environment variables **before** running your Python script:
+
+```bash
+# Enable gRPC network tracing
+export GRPC_VERBOSITY=DEBUG
+export GRPC_TRACE=client_channel,http2
+
+# For comprehensive tracing
+export GRPC_TRACE=api,call_error,channel,client_channel,connectivity_state,http,http2_stream,tcp,transport_security
+
+# Run your script
+python your_script.py
+```
+
+**Note**: These environment variables must be set before Python starts, as the gRPC C++ core reads them at module import time.
+
+### Common Issues and Solutions
+
+| Issue | Solution |
+|-------|----------|
+| Connection timeout | Check network connectivity, firewall rules, and ensure port 80/443 is open |
+| Authentication failure | Verify username (email) and access token are correct |
+| 503 Service Unavailable | Cluster may be suspended; enable `auto_resume=True` |
+| 456 Strategy Error | Automatic blue-green failover will handle this |
+| Memory issues with large results | Use `fetchall_buffer()` instead of `fetchall()` |
+| gRPC message size errors | Configure `grpc_options` with appropriate message size limits |
+
 See [TECH_DOC.md](TECH_DOC.md) for detailed technical documentation.

{e6data_python_connector-2.3.11rc1 → e6data_python_connector-2.3.12rc1}/README.md

@@ -1,6 +1,6 @@
 # e6data Python Connector
 
-![version](https://img.shields.io/badge/version-2.3.11rc1-blue.svg)
+![version](https://img.shields.io/badge/version-2.3.12rc1-blue.svg)
 
 ## Introduction
 
@@ -85,6 +85,7 @@ The `Connection` class supports the following parameters:
 | `secure` | bool | No | False | Enable SSL/TLS for secure connections |
 | `auto_resume` | bool | No | True | Automatically resume cluster if suspended |
 | `grpc_options` | dict | No | None | Additional gRPC configuration options |
+| `debug` | bool | No | False | Enable debug logging for troubleshooting |
 
 #### Secure Connection Example
 
@@ -598,4 +599,58 @@ conn.close()
 - Graceful connection recovery and retry logic
 - Blue-green deployment support with automatic failover
 
+## Debugging and Troubleshooting
+
+### Enable Debug Mode
+
+Enable comprehensive debugging to troubleshoot connection and query issues:
+
+```python
+from e6data_python_connector import Connection
+
+conn = Connection(
+    host=host,
+    port=port,
+    username=username,
+    password=password,
+    database=database,
+    debug=True  # Enable debug logging
+)
+```
+
+When `debug=True`, the following features are enabled:
+- Python logging at DEBUG level for all operations
+- Blue-green strategy transition logging
+- Connection lifecycle logging
+- Query execution detailed logging
+
+### gRPC Network Tracing
+
+For low-level gRPC network debugging (HTTP/2 frames, TCP events), set environment variables **before** running your Python script:
+
+```bash
+# Enable gRPC network tracing
+export GRPC_VERBOSITY=DEBUG
+export GRPC_TRACE=client_channel,http2
+
+# For comprehensive tracing
+export GRPC_TRACE=api,call_error,channel,client_channel,connectivity_state,http,http2_stream,tcp,transport_security
+
+# Run your script
+python your_script.py
+```
+
+**Note**: These environment variables must be set before Python starts, as the gRPC C++ core reads them at module import time.
+
+### Common Issues and Solutions
+
+| Issue | Solution |
+|-------|----------|
+| Connection timeout | Check network connectivity, firewall rules, and ensure port 80/443 is open |
+| Authentication failure | Verify username (email) and access token are correct |
+| 503 Service Unavailable | Cluster may be suspended; enable `auto_resume=True` |
+| 456 Strategy Error | Automatic blue-green failover will handle this |
+| Memory issues with large results | Use `fetchall_buffer()` instead of `fetchall()` |
+| gRPC message size errors | Configure `grpc_options` with appropriate message size limits |
+
 See [TECH_DOC.md](TECH_DOC.md) for detailed technical documentation.

{e6data_python_connector-2.3.11rc1 → e6data_python_connector-2.3.12rc1}/e6data_python_connector/cluster_manager.py

@@ -1,3 +1,4 @@
+import logging
 import threading
 import time
 import e6data_python_connector.cluster_server.cluster_pb2 as cluster_pb2
@@ -6,6 +7,8 @@ import grpc
 from grpc._channel import _InactiveRpcError
 import multiprocessing
 
+logger = logging.getLogger(__name__)
+
 from e6data_python_connector.strategy import _get_active_strategy, _set_active_strategy, _set_pending_strategy, \
     _get_grpc_header as _get_strategy_header
 
@@ -137,7 +140,7 @@ class ClusterManager:
     """
 
     def __init__(self, host: str, port: int, user: str, password: str, secure_channel: bool = False, timeout=60 * 5,
-                 cluster_uuid=None, grpc_options=None):
+                 cluster_uuid=None, grpc_options=None, debug=False):
         """
         Initializes a new instance of the ClusterManager class.
 
@@ -152,6 +155,7 @@ class ClusterManager:
                 defaults to 5 minutes.
             cluster_uuid (str, optional): The unique identifier for the target cluster;
                 defaults to None.
+            debug (bool, optional): Enable debug logging; defaults to False.
         """
 
         self._host = host
@@ -164,6 +168,7 @@ class ClusterManager:
         self._grpc_options = grpc_options
         if grpc_options is None:
             self._grpc_options = dict()
+        self._debug = debug
 
     @property
     def _get_connection(self):
@@ -191,20 +196,22 @@ class ClusterManager:
     def _try_cluster_request(self, request_type, payload=None):
         """
         Execute a cluster request with strategy fallback for 456 errors.
-        
+
         For efficiency:
         - If we have an active strategy, use it first
         - Only try authentication sequence (blue -> green) if no active strategy
         - On 456 error, switch to alternative strategy and update active strategy
-        
+
         Args:
             request_type: Type of request ('status' or 'resume')
             payload: Request payload (optional, will be created if not provided)
-            
+
         Returns:
             The response from the successful request
         """
         current_strategy = _get_active_strategy()
+        if self._debug:
+            logger.info(f"Attempting {request_type} request with current strategy: {current_strategy}")
 
         # Create payload if not provided
         if payload is None:
@@ -222,6 +229,8 @@ class ClusterManager:
         # If we have an active strategy, use it first
         if current_strategy is not None:
             try:
+                if self._debug:
+                    logger.info(f"Executing {request_type} with strategy '{current_strategy}'")
                 if request_type == "status":
                     response = self._get_connection.status(
                         payload,
@@ -239,16 +248,24 @@ class ClusterManager:
                 if hasattr(response, 'new_strategy') and response.new_strategy:
                     new_strategy = response.new_strategy.lower()
                     if new_strategy != current_strategy:
+                        if self._debug:
+                            logger.info(f"Server indicated strategy transition from '{current_strategy}' to '{new_strategy}'")
                         _set_pending_strategy(new_strategy)
 
+                if self._debug:
+                    logger.info(f"{request_type} request successful with strategy '{current_strategy}'")
                 return response
 
             except _InactiveRpcError as e:
                 if e.code() == grpc.StatusCode.UNKNOWN and 'status: 456' in e.details():
                     # 456 error - switch to alternative strategy
                     alternative_strategy = 'green' if current_strategy == 'blue' else 'blue'
+                    if self._debug:
+                        logger.info(f"Received 456 error with strategy '{current_strategy}', switching to '{alternative_strategy}'")
 
                     try:
+                        if self._debug:
+                            logger.info(f"Retrying {request_type} with alternative strategy '{alternative_strategy}'")
                         if request_type == "status":
                             response = self._get_connection.status(
                                 payload,
@@ -261,27 +278,39 @@ class ClusterManager:
                             )
 
                         # Update active strategy since the alternative worked
+                        if self._debug:
+                            logger.info(f"Successfully switched to strategy '{alternative_strategy}'")
                         _set_active_strategy(alternative_strategy)
 
                         # Check for new strategy in response
                         if hasattr(response, 'new_strategy') and response.new_strategy:
                             new_strategy = response.new_strategy.lower()
                             if new_strategy != alternative_strategy:
+                                if self._debug:
+                                    logger.info(f"Server indicated future strategy transition to '{new_strategy}'")
                                 _set_pending_strategy(new_strategy)
 
                         return response
 
                     except _InactiveRpcError as e2:
+                        if self._debug:
+                            logger.error(f"Failed with alternative strategy '{alternative_strategy}': {e2}")
                         raise e  # Raise the original error
                 else:
                     # Non-456 error - don't retry
+                    if self._debug:
+                        logger.info(f"Non-456 error received, not retrying: {e}")
                     raise e
 
         # No active strategy - start with authentication logic (blue first, then green)
         strategies_to_try = ['blue', 'green']
+        if self._debug:
+            logger.info("No active strategy found, trying authentication sequence: blue -> green")
 
         for i, strategy in enumerate(strategies_to_try):
             try:
+                if self._debug:
+                    logger.info(f"Trying {request_type} with strategy '{strategy}' (attempt {i+1}/{len(strategies_to_try)})")
 
                 if request_type == "status":
                     response = self._get_connection.status(
@@ -297,12 +326,16 @@ class ClusterManager:
                     raise ValueError(f"Unknown request type: {request_type}")
 
                 # Set the working strategy as active
+                if self._debug:
+                    logger.info(f"Successfully authenticated with strategy '{strategy}'")
                 _set_active_strategy(strategy)
 
                 # Check for new strategy in response
                 if hasattr(response, 'new_strategy') and response.new_strategy:
                     new_strategy = response.new_strategy.lower()
                     if new_strategy != strategy:
+                        if self._debug:
+                            logger.info(f"Server indicated strategy transition to '{new_strategy}'")
                         _set_pending_strategy(new_strategy)
 
                 return response
@@ -311,14 +344,22 @@ class ClusterManager:
                 if e.code() == grpc.StatusCode.UNKNOWN and 'status: 456' in e.details():
                     # 456 error - try next strategy
                     if i < len(strategies_to_try) - 1:
+                        if self._debug:
+                            logger.info(f"Strategy '{strategy}' returned 456 error, trying next strategy")
                         continue
                     else:
+                        if self._debug:
+                            logger.error(f"All strategies failed with 456 errors")
                         raise e
                 else:
                     # Non-456 error - don't retry
+                    if self._debug:
+                        logger.error(f"Strategy '{strategy}' failed with non-456 error: {e}")
                     raise e
 
         # If we get here, all strategies failed
+        if self._debug:
+            logger.error("All authentication strategies exhausted")
         raise e
 
     def _check_cluster_status(self):
@@ -326,8 +367,12 @@ class ClusterManager:
             try:
                 # Use the unified strategy-aware request method
                 response = self._try_cluster_request("status")
+                if self._debug:
+                    logger.info(f"Cluster status check returned: {response.status}")
                 yield response.status
-            except _InactiveRpcError:
+            except _InactiveRpcError as e:
+                if self._debug:
+                    logger.warning(f"Status check failed with error: {e}")
                 yield None
 
     def resume(self) -> bool:
@@ -357,38 +402,77 @@ class ClusterManager:
             - The operation is subject to the `_timeout` threshold;
               if the timeout expires, the method returns False.
         """
+        if self._debug:
+            logger.info(f"Starting auto-resume for cluster {self.cluster_uuid} at {self._host}:{self._port}")
 
         with status_lock as lock:
             if lock.is_active:
+                if self._debug:
+                    logger.info("Lock is already active, cluster appears to be running")
                 return True
 
             # Retrieve the current cluster status with strategy header
+            if self._debug:
+                logger.info("Checking current cluster status")
             try:
                 current_status = self._try_cluster_request("status")
-            except _InactiveRpcError:
+                if self._debug:
+                    logger.info(f"Current cluster status: {current_status.status}")
+            except _InactiveRpcError as e:
+                if self._debug:
+                    logger.error(f"Failed to get cluster status: {e}")
                 return False
+
             if current_status.status == 'suspended':
                 # Send the resume request with strategy header
+                if self._debug:
+                    logger.info("Cluster is suspended, sending resume request")
                 try:
                     response = self._try_cluster_request("resume")
-                except _InactiveRpcError:
+                    if self._debug:
+                        logger.info("Resume request sent successfully")
+                except _InactiveRpcError as e:
+                    if self._debug:
+                        logger.error(f"Failed to send resume request: {e}")
                     return False
             elif current_status.status == 'active':
+                if self._debug:
+                    logger.info("Cluster is already active, no action needed")
                 return True
             elif current_status.status != 'resuming':
                 """
-                 If cluster cannot be resumed due to its current state, 
+                 If cluster cannot be resumed due to its current state,
                  or already in a process of resuming, terminate the operation.
                  """
+                if self._debug:
+                    logger.warning(f"Cluster is in state '{current_status.status}' which cannot be resumed")
                 return False
 
+            if self._debug:
+                logger.info("Monitoring cluster status until it becomes active...")
+            check_count = 0
             for status in self._check_cluster_status():
+                check_count += 1
                 if status == 'active':
+                    if self._debug:
+                        logger.info(f"Cluster became active after {check_count} status checks")
                     return True
-                elif status == 'failed' or time.time() > self._timeout:
+                elif status == 'failed':
+                    if self._debug:
+                        logger.error(f"Cluster failed to resume after {check_count} status checks")
+                    return False
+                elif time.time() > self._timeout:
+                    if self._debug:
+                        logger.error(f"Resume operation timed out after {check_count} status checks")
                     return False
+
+                if self._debug:
+                    logger.info(f"Status check #{check_count}: {status}, waiting 5 seconds before next check")
                 # Wait for 5 seconds before the next status check
                 time.sleep(5)
+
+            if self._debug:
+                logger.warning("Resume operation completed without reaching active state")
             return False
 
     def suspend(self):

{e6data_python_connector-2.3.11rc1 → e6data_python_connector-2.3.12rc1}/e6data_python_connector/e6data_grpc.py

@@ -9,6 +9,7 @@ from __future__ import unicode_literals
 import datetime
 import logging
 import os
+
 import re
 import sys
 import time
@@ -114,6 +115,9 @@ class HiveParamEscaper(ParamEscaper):
 
 _escaper = HiveParamEscaper()
 
+# Logger for the module
+logger = logging.getLogger(__name__)
+
 # Thread-safe and process-safe storage for active deployment strategy
 _strategy_lock = threading.Lock()
 _strategy_manager = None
@@ -136,7 +140,7 @@ _debug_connections = set()
 def _strategy_debug_log(message):
     """Log strategy debug messages if any connection has debug enabled."""
     if _debug_connections:
-        print(f"[E6DATA_STRATEGY_DEBUG] {time.strftime('%Y-%m-%d %H:%M:%S')} - {message}")
+        logger.info(f"[E6DATA_STRATEGY_DEBUG] {time.strftime('%Y-%m-%d %H:%M:%S')} - {message}")
 
 
 def _get_shared_strategy():
@@ -384,6 +388,7 @@ class Connection(object):
         self._auto_resume = auto_resume
 
         self._grpc_options = grpc_options
+
         if self._grpc_options is None:
             self._grpc_options = dict()
         self.grpc_prepare_timeout = self._grpc_options.get('grpc_prepare_timeout') or 10 * 60  # 10 minutes
@@ -393,7 +398,15 @@ class Connection(object):
             The default maximum time on client side to wait for the cluster to resume is 5 minutes.
             """
             self.grpc_auto_resume_timeout_seconds = self._grpc_options.pop('grpc_auto_resume_timeout_seconds')
-        
+
+        self.timeout = 500
+        if 'timeout' in self._grpc_options:
+            """
+            The default maximum time on client side to wait for the cluster to resume is 5 minutes.
+            """
+            self.timeout = self._grpc_options.pop('timeout')
+
+
         # Store debug flag and register with debug connections
         self._debug = debug
         if self._debug:
@@ -409,21 +422,39 @@ class Connection(object):
                 force=True  # Force reconfiguration even if logging is already configured
             )
 
-            # Enable gRPC debug logging
-            os.environ['GRPC_VERBOSITY'] = 'DEBUG'
-            os.environ['GRPC_TRACE'] = 'all'
+            # Note: gRPC C++ core tracing (GRPC_VERBOSITY and GRPC_TRACE) must be set
+            # BEFORE the gRPC module is imported to take effect. Setting them at runtime
+            # will not enable HTTP/2 frame logs or low-level tracing.
+            #
+            # To enable full gRPC network tracing, set these environment variables
+            # before starting your Python script:
+            #   export GRPC_VERBOSITY=DEBUG
+            #   export GRPC_TRACE=client_channel,http2
+            #
+            # The following runtime settings only affect Python-level logging:
+
+            # Enable gRPC Python logging (this works at runtime)
+            os.environ['GRPC_PYTHON_LOG_LEVEL'] = 'DEBUG'
+            os.environ['GRPC_PYTHON_LOG_STDERR'] = '1'
 
             # Ensure gRPC logger is at DEBUG level
             grpc_logger = logging.getLogger('grpc')
             grpc_logger.setLevel(logging.DEBUG)
 
+            # Enable gRPC transport logger
+            grpc_transport_logger = logging.getLogger('grpc._channel')
+            grpc_transport_logger.setLevel(logging.DEBUG)
+
+            # Enable gRPC server logger
+            grpc_server_logger = logging.getLogger('grpc._server')
+            grpc_server_logger.setLevel(logging.DEBUG)
+
             # Set e6data connector logger to DEBUG
             e6data_logger = logging.getLogger('e6data_python_connector')
             e6data_logger.setLevel(logging.DEBUG)
 
             _strategy_debug_log(f"Debug mode enabled for connection {id(self)}")
-            _strategy_debug_log(f"Root logger level: {logging.getLogger().level}")
-            _strategy_debug_log(f"gRPC debugging enabled with GRPC_VERBOSITY=DEBUG and GRPC_TRACE=all")
+            _strategy_debug_log(f"GRPC_TRACE={os.environ.get('GRPC_TRACE')}")
 
         self._create_client()
 
@@ -578,7 +609,12 @@ class Connection(object):
                             _clear_strategy_cache()
                             active_strategy = None
                         else:
-                            raise e
+                            if self._perform_auto_resume(e):
+                                # Cluster resumed, retry with cached strategy
+                                _strategy_debug_log(f"Cluster resumed, retrying with cached strategy {active_strategy}")
+                                active_strategy = None  # Force retry
+                            else:
+                                raise e
                 elif pending_strategy:
                     # If there's a pending strategy, force re-authentication with new strategy
                     active_strategy = None
@@ -596,7 +632,7 @@ class Connection(object):
                         _strategy_debug_log(f"No cached strategy, will try strategies in order: {strategies}")
                     last_error = None
                     for strategy in strategies:
-                        _strategy_debug_log(f"Attempting authentication with strategy: {strategy}")
+                        _strategy_debug_log(f"Attempting authentication with strategy: {strategy}.")
                         try:
                             authenticate_response = self._client.authenticate(
                                 authenticate_request,
@@ -626,8 +662,13 @@ class Connection(object):
                                 last_error = e
                                 continue
                             else:
-                                # Different error, handle it normally
-                                raise e
+                                if self._perform_auto_resume(e):
+                                    # Cluster resumed successfully, retry authentication with current strategy
+                                    _strategy_debug_log(f"Cluster resumed, retrying authentication with {strategy}")
+                                    continue
+                                else:
+                                    # Auto-resume failed, raise the error
+                                    raise e
 
                     if not self._session_id and last_error:
                         # Neither strategy worked
@@ -636,30 +677,31 @@ class Connection(object):
                 if not self._session_id:
                     raise ValueError("Invalid credentials.")
             except _InactiveRpcError as e:
-                if self._auto_resume:
-                    if e.code() == grpc.StatusCode.UNAVAILABLE and 'status: 503' in e.details():
-                        status = ClusterManager(
-                            host=self._host,
-                            port=self._port,
-                            user=self.__username,
-                            password=self.__password,
-                            secure_channel=self._secure_channel,
-                            cluster_uuid=self.cluster_name,
-                            timeout=self.grpc_auto_resume_timeout_seconds
-                        ).resume()
-                        if status:
-                            return self.get_session_id
-                        else:
-                            raise e
-                    else:
-                        raise e
-                else:
-                    raise e
+                self._perform_auto_resume(e)
             except Exception as e:
                 self._channel.close()
                 raise e
         return self._session_id
 
+    def _perform_auto_resume(self, e: _InactiveRpcError):
+        if self._auto_resume:
+            if e.code() == grpc.StatusCode.UNAVAILABLE and 'status: 503' in e.details():
+                status = ClusterManager(
+                    host=self._host,
+                    port=self._port,
+                    user=self.__username,
+                    password=self.__password,
+                    secure_channel=self._secure_channel,
+                    cluster_uuid=self.cluster_name,
+                    timeout=self.grpc_auto_resume_timeout_seconds,
+                    debug=self._debug
+                ).resume()
+                return status  # Return boolean status directly
+            else:
+                return False  # Non-503 error, cannot auto-resume
+        else:
+            return False  # Auto-resume disabled
+
     def __enter__(self):
         """
         Enters the runtime context related to this object.
@@ -1410,13 +1452,14 @@ class Cursor(DBAPICursor):
         get_next_result_batch_request = e6x_engine_pb2.GetNextResultBatchRequest(
             engineIP=self._engine_ip,
             sessionId=self.connection.get_session_id,
-            queryId=self._query_id
+            queryId=self._query_id,
         )
         # Get fresh client after session access (may have been invalidated)
         client = self.connection.client
         get_next_result_batch_response = client.getNextResultBatch(
             get_next_result_batch_request,
-            metadata=self.metadata
+            metadata=self.metadata,
+            timeout=self.connection.timeout
         )
 
         # Check for new strategy in batch response

{e6data_python_connector-2.3.11rc1 → e6data_python_connector-2.3.12rc1/e6data_python_connector.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: e6data-python-connector
-Version: 2.3.11rc1
+Version: 2.3.12rc1
 Summary: Client for the e6data distributed SQL Engine.
 Home-page: https://github.com/e6x-labs/e6data-python-connector
 Author: e6data, Inc.
@@ -39,7 +39,7 @@ Dynamic: summary
 
 # e6data Python Connector
 
-![version](https://img.shields.io/badge/version-2.3.11rc1-blue.svg)
+![version](https://img.shields.io/badge/version-2.3.12rc1-blue.svg)
 
 ## Introduction
 
@@ -124,6 +124,7 @@ The `Connection` class supports the following parameters:
 | `secure` | bool | No | False | Enable SSL/TLS for secure connections |
 | `auto_resume` | bool | No | True | Automatically resume cluster if suspended |
 | `grpc_options` | dict | No | None | Additional gRPC configuration options |
+| `debug` | bool | No | False | Enable debug logging for troubleshooting |
 
 #### Secure Connection Example
 
@@ -637,4 +638,58 @@ conn.close()
 - Graceful connection recovery and retry logic
 - Blue-green deployment support with automatic failover
 
+## Debugging and Troubleshooting
+
+### Enable Debug Mode
+
+Enable comprehensive debugging to troubleshoot connection and query issues:
+
+```python
+from e6data_python_connector import Connection
+
+conn = Connection(
+    host=host,
+    port=port,
+    username=username,
+    password=password,
+    database=database,
+    debug=True  # Enable debug logging
+)
+```
+
+When `debug=True`, the following features are enabled:
+- Python logging at DEBUG level for all operations
+- Blue-green strategy transition logging
+- Connection lifecycle logging
+- Query execution detailed logging
+
+### gRPC Network Tracing
+
+For low-level gRPC network debugging (HTTP/2 frames, TCP events), set environment variables **before** running your Python script:
+
+```bash
+# Enable gRPC network tracing
+export GRPC_VERBOSITY=DEBUG
+export GRPC_TRACE=client_channel,http2
+
+# For comprehensive tracing
+export GRPC_TRACE=api,call_error,channel,client_channel,connectivity_state,http,http2_stream,tcp,transport_security
+
+# Run your script
+python your_script.py
+```
+
+**Note**: These environment variables must be set before Python starts, as the gRPC C++ core reads them at module import time.
+
+### Common Issues and Solutions
+
+| Issue | Solution |
+|-------|----------|
+| Connection timeout | Check network connectivity, firewall rules, and ensure port 80/443 is open |
+| Authentication failure | Verify username (email) and access token are correct |
+| 503 Service Unavailable | Cluster may be suspended; enable `auto_resume=True` |
+| 456 Strategy Error | Automatic blue-green failover will handle this |
+| Memory issues with large results | Use `fetchall_buffer()` instead of `fetchall()` |
+| gRPC message size errors | Configure `grpc_options` with appropriate message size limits |
+
 See [TECH_DOC.md](TECH_DOC.md) for detailed technical documentation.

{e6data_python_connector-2.3.11rc1 → e6data_python_connector-2.3.12rc1}/setup.py

@@ -12,7 +12,7 @@
 
 import setuptools
 
-VERSION = (2, 3, 11, 'rc1')
+VERSION = (2, 3, 12, 'rc1',)
 
 
 def get_long_desc():