secploy 0.2.4__tar.gz → 0.2.6__tar.gz

{secploy-0.2.4 → secploy-0.2.6}/PKG-INFO

@@ -1,35 +1,32 @@
 Metadata-Version: 2.4
 Name: secploy
-Version: 0.2.4
-Summary: Python SDK for Secploy security monitoring and event tracking
-Author-email: Abdulsamad Abdulganiyu <agastronics@gmail.com>
-License: MIT License
-        
-        Copyright (c) 2025 AGASTRONICS
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
-Requires-Python: >=3.7
+Version: 0.2.6
+Summary: Event tracking and monitoring SDK for Python applications
+Home-page: https://github.com/agastronics/secploy-python-sdk
+Author: Agastronics
+Author-email: support@agastronics.com
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: requests>=2.20.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pyyaml>=5.1
+Requires-Dist: pydantic>=2.0.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
 Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
 
 <p align="center">
   <img src="https://secploy.vercel.app/logo.png" alt="Secploy Logo" width="180">
@@ -59,26 +56,31 @@ The Secploy SDK can be configured in multiple ways, providing flexibility for di
     client = SecployClient()
 
     config = SecployConfig(
-        api_key="your-key",
+        api_key="your-project-key",
+        environment_key="your-key"
+        organization_id="your-organization-id",
         environment="production",
         log_level=LogLevel.INFO,
         batch_size=100
     )
 
     client = SecployClient(config=config)
-    ```
+   ```
 
 2. **Configuration file** (.secploy or project-name.secploy)
 
 ```yaml
-api_key: your-api-key
+api_key: your-project-api-key
+environment_key: key
+organization_id: "your-organization-id",
 environment: production
 debug: true
-````
+```
 
 3. **Environment variables**
    ```bash
    export SECPLOY_API_KEY=your-api-key
+   export SECPLOY_ORGANIZATION_ID=your-organization-id
    export SECPLOY_ENVIRONMENT=production
    export SECPLOY_DEBUG=true
    ```
@@ -88,6 +90,7 @@ debug: true
 | Option               | Type             | Default                     | Description                                           |
 | -------------------- | ---------------- | --------------------------- | ----------------------------------------------------- |
 | `api_key`            | `str`            | Required                    | Your Secploy project API key                          |
+| `environment_key`    | `str`            | Required                    | Your Secploy environment API key                      |
 | `environment`        | `str`            | `"development"`             | Environment name (e.g., production, staging)          |
 | `ingest_url`         | `str`            | `"https://api.secploy.com"` | Secploy API endpoint                                  |
 | `heartbeat_interval` | `int`            | `30`                        | Seconds between heartbeat signals                     |
@@ -109,6 +112,7 @@ Create a `.secploy` file in your project root:
 ```yaml
 # Required settings
 api_key: your-api-key
+environment_key: key
 environment: production
 
 # Event batching
@@ -139,6 +143,7 @@ All configuration options can be set via environment variables with the `SECPLOY
 ```bash
 # Required settings
 SECPLOY_API_KEY=your-api-key
+SECPLOY_ENVIRONMENT_KEY=key
 SECPLOY_ENVIRONMENT=production
 
 # Event batching
@@ -286,6 +291,124 @@ Each environment has its own **API key** — use the matching key for the enviro
 | `heartbeat()`                                   | Send a heartbeat signal        |
 | `listen_status()`                               | Stream live project status     |
 | `set_environment(env_code)`                     | Switch environment dynamically |
+| `capture_logs(loggers, level)`                  | Start capturing logs           |
+| `stop_capturing_logs(loggers)`                  | Stop capturing specific logs   |
+
+## 📝 Structured Logging
+
+Secploy provides powerful structured logging capabilities that automatically format and send your logs with rich context.
+
+### Basic Log Capture
+
+```python
+import logging
+from secploy import SecployClient
+
+# Initialize client
+client = SecployClient()
+client.start()
+
+# Start capturing logs
+client.capture_logs(['your_app'], level=logging.INFO)
+
+# Your regular logging calls will now be captured
+logger = logging.getLogger('your_app')
+logger.info("User logged in", extra={
+    'user_id': 'user123',
+    'login_method': 'oauth'
+})
+```
+
+### Log Schema
+
+All captured logs are automatically structured in a consistent format:
+
+```json
+{
+  "timestamp": "2025-09-13T16:45:00Z",
+  "type": "error",
+  "message": "Unhandled exception in payment processor",
+  "context": {
+    "user_id": "usr_12345",
+    "session_id": "sess_abcd",
+    "http_method": "POST",
+    "http_url": "/api/payments/charge",
+    "http_status": 500,
+    "stacktrace": [
+      "File \"payment_service.py\", line 42, in process_charge",
+      "File \"stripe_gateway.py\", line 87, in create_charge",
+      "Exception: Card declined"
+    ],
+    "tags": {
+      "environment": "production",
+      "service": "payments",
+      "region": "us-east-1"
+    }
+  }
+}
+```
+
+### Example with Flask Application
+
+```python
+import logging
+from flask import Flask, request
+from secploy import SecployClient
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+# Initialize Flask and Secploy
+app = Flask(__name__)
+client = SecployClient()
+client.start()
+
+# Capture logs from all components
+client.capture_logs([
+    'flask.app',        # Flask framework logs
+    __name__,          # Main application logs
+    'payment_processor' # Component-specific logs
+], level=logging.INFO)
+
+@app.route('/api/payment', methods=['POST'])
+def process_payment():
+    try:
+        data = request.json
+        logger.info("Processing payment", extra={
+            'user_id': data.get('user_id'),
+            'http_method': request.method,
+            'http_url': request.path,
+            'amount': data.get('amount')
+        })
+        # Process payment...
+        return {"status": "success"}, 200
+    except Exception as e:
+        logger.error(
+            "Payment failed",
+            exc_info=True,  # This captures the stack trace
+            extra={
+                'user_id': data.get('user_id'),
+                'http_method': request.method,
+                'http_url': request.path,
+                'http_status': 500
+            }
+        )
+        return {"error": str(e)}, 500
+
+if __name__ == '__main__':
+    try:
+        app.run()
+    finally:
+        client.stop()
+```
+
+### Best Practices for Logging
+
+1. **Add Context**: Always include relevant context using the `extra` parameter
+2. **Use Proper Log Levels**: Choose appropriate levels (DEBUG, INFO, WARNING, ERROR)
+3. **Include Stack Traces**: Use `exc_info=True` when logging exceptions
+4. **Capture All Components**: Include all relevant loggers in your capture list
+5. **Start Early, Stop Late**: Initialize logging before your app starts and stop it in a finally block
 
 ---
 

secploy-0.2.4/secploy.egg-info/PKG-INFO → secploy-0.2.6/README.md

@@ -1,36 +1,3 @@
-Metadata-Version: 2.4
-Name: secploy
-Version: 0.2.4
-Summary: Python SDK for Secploy security monitoring and event tracking
-Author-email: Abdulsamad Abdulganiyu <agastronics@gmail.com>
-License: MIT License
-        
-        Copyright (c) 2025 AGASTRONICS
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-        
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests>=2.20.0
-Dynamic: license-file
-
 <p align="center">
   <img src="https://secploy.vercel.app/logo.png" alt="Secploy Logo" width="180">
 </p>
@@ -59,26 +26,31 @@ The Secploy SDK can be configured in multiple ways, providing flexibility for di
     client = SecployClient()
 
     config = SecployConfig(
-        api_key="your-key",
+        api_key="your-project-key",
+        environment_key="your-key"
+        organization_id="your-organization-id",
         environment="production",
         log_level=LogLevel.INFO,
         batch_size=100
     )
 
     client = SecployClient(config=config)
-    ```
+   ```
 
 2. **Configuration file** (.secploy or project-name.secploy)
 
 ```yaml
-api_key: your-api-key
+api_key: your-project-api-key
+environment_key: key
+organization_id: "your-organization-id",
 environment: production
 debug: true
-````
+```
 
 3. **Environment variables**
    ```bash
    export SECPLOY_API_KEY=your-api-key
+   export SECPLOY_ORGANIZATION_ID=your-organization-id
    export SECPLOY_ENVIRONMENT=production
    export SECPLOY_DEBUG=true
    ```
@@ -88,6 +60,7 @@ debug: true
 | Option               | Type             | Default                     | Description                                           |
 | -------------------- | ---------------- | --------------------------- | ----------------------------------------------------- |
 | `api_key`            | `str`            | Required                    | Your Secploy project API key                          |
+| `environment_key`    | `str`            | Required                    | Your Secploy environment API key                      |
 | `environment`        | `str`            | `"development"`             | Environment name (e.g., production, staging)          |
 | `ingest_url`         | `str`            | `"https://api.secploy.com"` | Secploy API endpoint                                  |
 | `heartbeat_interval` | `int`            | `30`                        | Seconds between heartbeat signals                     |
@@ -109,6 +82,7 @@ Create a `.secploy` file in your project root:
 ```yaml
 # Required settings
 api_key: your-api-key
+environment_key: key
 environment: production
 
 # Event batching
@@ -139,6 +113,7 @@ All configuration options can be set via environment variables with the `SECPLOY
 ```bash
 # Required settings
 SECPLOY_API_KEY=your-api-key
+SECPLOY_ENVIRONMENT_KEY=key
 SECPLOY_ENVIRONMENT=production
 
 # Event batching
@@ -286,6 +261,124 @@ Each environment has its own **API key** — use the matching key for the enviro
 | `heartbeat()`                                   | Send a heartbeat signal        |
 | `listen_status()`                               | Stream live project status     |
 | `set_environment(env_code)`                     | Switch environment dynamically |
+| `capture_logs(loggers, level)`                  | Start capturing logs           |
+| `stop_capturing_logs(loggers)`                  | Stop capturing specific logs   |
+
+## 📝 Structured Logging
+
+Secploy provides powerful structured logging capabilities that automatically format and send your logs with rich context.
+
+### Basic Log Capture
+
+```python
+import logging
+from secploy import SecployClient
+
+# Initialize client
+client = SecployClient()
+client.start()
+
+# Start capturing logs
+client.capture_logs(['your_app'], level=logging.INFO)
+
+# Your regular logging calls will now be captured
+logger = logging.getLogger('your_app')
+logger.info("User logged in", extra={
+    'user_id': 'user123',
+    'login_method': 'oauth'
+})
+```
+
+### Log Schema
+
+All captured logs are automatically structured in a consistent format:
+
+```json
+{
+  "timestamp": "2025-09-13T16:45:00Z",
+  "type": "error",
+  "message": "Unhandled exception in payment processor",
+  "context": {
+    "user_id": "usr_12345",
+    "session_id": "sess_abcd",
+    "http_method": "POST",
+    "http_url": "/api/payments/charge",
+    "http_status": 500,
+    "stacktrace": [
+      "File \"payment_service.py\", line 42, in process_charge",
+      "File \"stripe_gateway.py\", line 87, in create_charge",
+      "Exception: Card declined"
+    ],
+    "tags": {
+      "environment": "production",
+      "service": "payments",
+      "region": "us-east-1"
+    }
+  }
+}
+```
+
+### Example with Flask Application
+
+```python
+import logging
+from flask import Flask, request
+from secploy import SecployClient
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+# Initialize Flask and Secploy
+app = Flask(__name__)
+client = SecployClient()
+client.start()
+
+# Capture logs from all components
+client.capture_logs([
+    'flask.app',        # Flask framework logs
+    __name__,          # Main application logs
+    'payment_processor' # Component-specific logs
+], level=logging.INFO)
+
+@app.route('/api/payment', methods=['POST'])
+def process_payment():
+    try:
+        data = request.json
+        logger.info("Processing payment", extra={
+            'user_id': data.get('user_id'),
+            'http_method': request.method,
+            'http_url': request.path,
+            'amount': data.get('amount')
+        })
+        # Process payment...
+        return {"status": "success"}, 200
+    except Exception as e:
+        logger.error(
+            "Payment failed",
+            exc_info=True,  # This captures the stack trace
+            extra={
+                'user_id': data.get('user_id'),
+                'http_method': request.method,
+                'http_url': request.path,
+                'http_status': 500
+            }
+        )
+        return {"error": str(e)}, 500
+
+if __name__ == '__main__':
+    try:
+        app.run()
+    finally:
+        client.stop()
+```
+
+### Best Practices for Logging
+
+1. **Add Context**: Always include relevant context using the `extra` parameter
+2. **Use Proper Log Levels**: Choose appropriate levels (DEBUG, INFO, WARNING, ERROR)
+3. **Include Stack Traces**: Use `exc_info=True` when logging exceptions
+4. **Capture All Components**: Include all relevant loggers in your capture list
+5. **Start Early, Stop Late**: Initialize logging before your app starts and stop it in a finally block
 
 ---
 

secploy-0.2.6/secploy/__init__.py

@@ -0,0 +1,47 @@
+"""
+Secploy SDK - Event tracking and monitoring for Python applications
+"""
+
+from .client import SecployClient
+from .schemas import SecployConfig
+from .schemas import LogLevel
+
+__version__ = "0.2.5"
+__author__ = "Agastronics"
+__email__ = "support@agastronics.com"
+__description__ = "Event tracking and monitoring SDK for Python applications"
+
+__all__ = [
+    "SecployClient",
+    "SecployConfig",
+    "LogLevel",
+]
+
+def cli():
+    """Command-line interface for the Secploy SDK."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description=__description__)
+    parser.add_argument('--version', action='version', version=f'Secploy SDK v{__version__}')
+    parser.add_argument('--test-config', help='Test a configuration file', metavar='CONFIG_FILE')
+    
+    args = parser.parse_args()
+    
+    if args.test_config:
+        from .lib.config import load_config
+        try:
+            config = load_config(args.test_config)
+            print("Configuration loaded successfully:")
+            for key, value in config.items():
+                print(f"  {key}: {value}")
+        except Exception as e:
+            print(f"Error loading configuration: {e}")
+            return 1
+    else:
+        parser.print_help()
+    
+    return 0
+
+if __name__ == "__main__":
+    import sys
+    sys.exit(cli())

secploy-0.2.6/secploy/client.py

@@ -0,0 +1,166 @@
+import threading
+import logging
+from typing import Any, Dict, Optional, List, Union
+import queue
+
+from .lib import setup_logger, load_config, DEFAULT_CONFIG, secploy_logger
+from .schemas import SecployConfig, LogLevel
+from .log_capture import SecployLogCapturer
+from .events import EventHandler
+from .processor import EventProcessor
+
+class SecployClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        environment_key: Optional[str] = None,
+        organization_id: Optional[str] = None,
+        config_file: Optional[str] = None,
+        config: Optional[SecployConfig] = DEFAULT_CONFIG,
+        log_levels: Optional[List[Union[str, int]]] = None
+    ):
+        """
+        Initialize the Secploy client.
+
+        Args:
+            api_key: Optional API key to override configuration
+            environment_key: Optional Environment key to override configuration
+            organization_id: Optional Organization ID to override configuration
+            config_file: Optional path to configuration file
+            config: Configuration object, defaults to DEFAULT_CONFIG
+        
+        Raises:
+            ValueError: If required configuration is missing
+            TypeError: If configuration values have invalid types
+        """
+        # Load config from file if provided else it will load from default locations or find .secploy
+        config = load_config(config_file)
+        
+        if config is None:
+            secploy_logger.error("No valid configuration found")
+            return
+            
+        # Override api_key if provided directly
+        if api_key:
+            config.api_key = api_key
+        if environment_key:
+            config.environment_key = environment_key
+        if organization_id:
+            config.organization_id = organization_id
+
+        # Special handling for log_level if it's a string
+        if isinstance(config.get('log_level'), str):
+            try:
+                config['log_level'] = LogLevel(config['log_level'].upper())
+            except ValueError:
+                raise ValueError(
+                    f"Invalid log level: {config.get('log_level')}. Must be one of: "
+                    f"{', '.join(level.value for level in LogLevel)}"
+                )
+
+        # Validate required fields
+        if not config.get('api_key'):
+            raise ValueError("API key is required")
+        if not config.get('environment_key'):
+            raise ValueError("Environment key is required")
+        if not config.get('organization_id'):
+            raise ValueError("Organization ID is required")
+        if not config.get('ingest_url'):
+            raise ValueError("Ingest URL is required")
+
+        # Set instance attributes from config
+        self.api_key = config['api_key']
+        self.environment_key = config.get('environment_key')
+        self.organization_id = config.get('organization_id')
+        self.environment = config.get('environment', 'development')
+        self.sampling_rate = config.get('sampling_rate', 1.0)
+        self.ingest_url = config['ingest_url'].rstrip("/")
+        self.heartbeat_interval = config.get('heartbeat_interval', 60)
+        self.max_retry = config.get('max_retry', 5)
+        self.debug = config.get('debug', False)
+        self.log_level = config.get('log_level', 'INFO')
+        
+        # Batch processing configuration
+        self.batch_size = config.get('batch_size', 100)  # Max events per batch
+        self.flush_interval = config.get('flush_interval', 60)  # Max seconds between flushes
+
+        # Initialize internal state
+        self._event_queue = queue.Queue()
+        self._event_handler = EventHandler(self._event_queue)
+        
+        # Initialize event processor
+        self._event_processor = EventProcessor(
+            queue=self._event_queue,
+            ingest_url=self.ingest_url,
+            headers_callback=self._headers,
+            batch_size=self.batch_size,
+            flush_interval=self.flush_interval,
+            max_retry=self.max_retry
+        )
+        
+        # Setup logging
+        if self.debug:
+            setup_logger(log_level=self.log_level)
+        
+        # Initialize log capturer
+        self._log_capturer = SecployLogCapturer(self, levels=log_levels)
+    
+    def capture_logs(self, loggers: Union[str, List[str], None] = None):
+        """
+        Start capturing logs from specified loggers.
+        
+        Args:
+            loggers: Logger name(s) to capture. Can be:
+                    - None to capture the root logger
+                    - A string for a single logger
+                    - A list of logger names
+        """
+        self._log_capturer.start_capture(loggers)
+        secploy_logger.info(f"Started capturing logs from {loggers or 'root'}")
+        
+    def stop_capturing_logs(self, loggers: Union[str, List[str], None] = None):
+        """
+        Stop capturing logs from specified loggers.
+        
+        Args:
+            loggers: Logger name(s) to stop capturing
+        """
+        self._log_capturer.stop_capture(loggers)
+        secploy_logger.info(f"Stopped capturing logs from {loggers or 'root'}")
+    
+    def _headers(self):
+        return {
+            "X-API-Key": f"{self.api_key}",
+            "X-Environment-Key": f"{self.environment_key}",
+            "X-Organization-ID": f"{self.organization_id}",
+            "Content-Type": "application/json",
+        }
+
+    def send_event(self, event_type: str, payload: Dict[str, Any]) -> bool:
+        """
+        Queue an event for sending. Events are batched and sent periodically.
+        
+        Args:
+            event_type: Type of the event
+            payload: Event payload data
+        
+        Returns:
+            bool: True if event was queued successfully
+        """
+        return self._event_handler.send_event(event_type, payload)
+
+    def start(self):
+        """Start the client's event processing."""
+        secploy_logger.info("Starting Secploy client...")
+        self._event_processor.start()
+
+    def stop(self):
+        """Stop the client and wait for processing to finish."""
+        secploy_logger.info("Stopping Secploy client...")
+        
+        # Stop all log capturing
+        if hasattr(self, '_log_capturer'):
+            self._log_capturer.stop_all()
+        
+        # Stop event processing
+        self._event_processor.stop()

{secploy-0.2.4 → secploy-0.2.6}/secploy/enums.py

@@ -6,4 +6,5 @@ class LogLevel(str, Enum):
     INFO = "INFO"
     WARNING = "WARNING"
     ERROR = "ERROR"
-    CRITICAL = "CRITICAL"
+    CRITICAL = "CRITICAL"
+    RESET = "RESET"