logdash 0.1.0__tar.gz → 0.2.0__tar.gz

{logdash-0.1.0 → logdash-0.2.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 LogDash
+Copyright (c) 2024 logdash
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

logdash-0.2.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: logdash
+Version: 0.2.0
+Summary: Python SDK for logdash logging and metrics service
+Home-page: https://logdash.io
+Author: logdash
+Author-email: info@logdash.io
+Keywords: logging,metrics,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: colorama>=0.4.4
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# logdash - Python SDK
+
+Logdash is a zero-config observability platform. This package serves as a Python interface to use it.
+
+## Pre-requisites
+
+Setup your free project in less than 2 minutes at [logdash.io](https://logdash.io/)
+
+## Installation
+
+```bash
+pip install logdash
+```
+
+## Logging
+
+```python
+from logdash import create_logdash
+
+# Initialize with your API key
+logdash = create_logdash({
+    # optional, but recommended to see your logs in the dashboard
+    "api_key": "<your-api-key>",
+})
+
+# Access the logger
+logger = logdash.logger
+
+logger.info("Application started successfully")
+logger.error("An unexpected error occurred")
+logger.warn("Low disk space warning")
+```
+
+## Metrics
+
+```python
+from logdash import create_logdash
+
+# Initialize with your API key
+logdash = create_logdash({
+    # optional, but recommended as metrics are only hosted remotely
+    "api_key": "<your-api-key>",
+})
+
+# Access metrics
+metrics = logdash.metrics
+
+# to set absolute value
+metrics.set("users", 0)
+
+# to modify existing metric
+metrics.mutate("users", 1)
+```
+
+## View
+
+To see the logs or metrics, go to your project dashboard
+
+![logs](docs/logs.png)
+![delta](docs/delta.png)
+
+## License
+
+This project is licensed under the MIT License.
+
+## Contributing
+
+Contributions are welcome! Feel free to open issues or submit pull requests.
+
+## Support
+
+If you encounter any issues, please open an issue on GitHub or let us know at [contact@logdash.io](mailto:contact@logdash.io).

logdash-0.2.0/README.md

@@ -0,0 +1,72 @@
+# logdash - Python SDK
+
+Logdash is a zero-config observability platform. This package serves as a Python interface to use it.
+
+## Pre-requisites
+
+Setup your free project in less than 2 minutes at [logdash.io](https://logdash.io/)
+
+## Installation
+
+```bash
+pip install logdash
+```
+
+## Logging
+
+```python
+from logdash import create_logdash
+
+# Initialize with your API key
+logdash = create_logdash({
+    # optional, but recommended to see your logs in the dashboard
+    "api_key": "<your-api-key>",
+})
+
+# Access the logger
+logger = logdash.logger
+
+logger.info("Application started successfully")
+logger.error("An unexpected error occurred")
+logger.warn("Low disk space warning")
+```
+
+## Metrics
+
+```python
+from logdash import create_logdash
+
+# Initialize with your API key
+logdash = create_logdash({
+    # optional, but recommended as metrics are only hosted remotely
+    "api_key": "<your-api-key>",
+})
+
+# Access metrics
+metrics = logdash.metrics
+
+# to set absolute value
+metrics.set("users", 0)
+
+# to modify existing metric
+metrics.mutate("users", 1)
+```
+
+## View
+
+To see the logs or metrics, go to your project dashboard
+
+![logs](docs/logs.png)
+![delta](docs/delta.png)
+
+## License
+
+This project is licensed under the MIT License.
+
+## Contributing
+
+Contributions are welcome! Feel free to open issues or submit pull requests.
+
+## Support
+
+If you encounter any issues, please open an issue on GitHub or let us know at [contact@logdash.io](mailto:contact@logdash.io).

logdash-0.2.0/examples/basic_usage.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""
+Basic usage example for the logdash SDK.
+"""
+
+import time
+from logdash import create_logdash
+
+
+def main():
+    """Main function demonstrating logdash usage."""
+    # Initialize logdash with your API key
+    # For testing without an API key, logs will only be printed locally
+    logdash = create_logdash({
+        "api_key": "your-api-key",  # Replace with your actual API key
+        "host": "https://api.logdash.io",
+        "verbose": True,  # Enable verbose mode for development
+    })
+
+    # Get the logger instance
+    logger = logdash.logger
+    
+    # Get the metrics instance
+    metrics = logdash.metrics
+    
+    # Log messages at different levels
+    logger.info("Application started")
+    logger.debug("Debug information")
+    logger.warn("Warning message")
+    logger.error("Error occurred")
+    logger.http("HTTP request processed")
+    logger.verbose("Verbose details")
+    
+    # Track metrics
+    for i in range(5):
+        # Set absolute values
+        metrics.set("active_users", 100 + i * 10)
+        
+        # Mutate values (increment/decrement)
+        metrics.mutate("requests_count", 1)
+        
+        logger.info(f"Iteration {i+1}/5 completed")
+        time.sleep(1)
+        
+    logger.info("Example completed")
+
+
+if __name__ == "__main__":
+    main() 

logdash-0.2.0/logdash/__init__.py

@@ -0,0 +1,12 @@
+"""
+logdash Python SDK for logging and metrics.
+
+This package provides utilities for logging and metrics collection.
+"""
+
+from logdash.core import create_logdash
+from logdash.logger import Logger
+from logdash.metrics import MetricOperation
+
+__all__ = ["create_logdash", "Logger", "MetricOperation"]
+__version__ = "0.2.0" 

logdash-0.2.0/logdash/constants.py

@@ -0,0 +1,33 @@
+"""Constants used throughout the logdash SDK."""
+
+from enum import Enum
+from colorama import Fore
+
+
+class LogLevel(str, Enum):
+    """Log levels supported by logdash."""
+    ERROR = "error"
+    WARN = "warning"
+    INFO = "info"
+    HTTP = "http"
+    VERBOSE = "verbose"
+    DEBUG = "debug"
+    SILLY = "silly"
+
+
+class MetricOperation(str, Enum):
+    """Metric operations supported by logdash."""
+    SET = "set"
+    CHANGE = "change"
+
+
+# Color mapping for log levels in terminal output
+LOG_LEVEL_COLORS = {
+    LogLevel.ERROR: Fore.RED,
+    LogLevel.WARN: Fore.YELLOW,
+    LogLevel.INFO: Fore.BLUE,
+    LogLevel.HTTP: Fore.CYAN,
+    LogLevel.VERBOSE: Fore.GREEN,
+    LogLevel.DEBUG: Fore.LIGHTGREEN_EX,
+    LogLevel.SILLY: Fore.LIGHTBLACK_EX,
+} 

logdash-0.2.0/logdash/core.py

@@ -0,0 +1,73 @@
+"""Core functionality for the logdash SDK."""
+
+from datetime import datetime
+from typing import Dict, Optional, Any
+
+from logdash.logger import Logger
+from logdash.metrics.base import BaseMetrics
+from logdash.metrics.factory import create_metrics
+from logdash.sync.factory import create_log_sync
+from logdash.constants import LogLevel
+
+
+class logdash:
+    def __init__(self, api_key: Optional[str] = None, host: str = "https://api.logdash.io", verbose: bool = False):
+        """
+        Initialize a new logdash instance.
+        
+        Args:
+            api_key: Your logdash API key
+            host: logdash API host (defaults to https://api.logdash.io)
+            verbose: Enable verbose mode
+        """
+        # Ensure we have an API key (or empty string)
+        self._api_key = api_key or ""
+        self._host = host
+        self._verbose = verbose
+        
+        # Create log sync and metrics instances
+        self._log_sync = create_log_sync(self._api_key, self._host, self._verbose)
+        self._metrics_instance = create_metrics(self._api_key, self._host, self._verbose)
+
+        # Initialize logger
+        def on_log(level: LogLevel, message: str) -> None:
+            self._log_sync.send(message, level, datetime.now().isoformat())
+            
+        self._logger_instance = Logger(log_method=print, on_log=on_log)
+    
+    @property
+    def logger(self) -> Logger:
+        """Get the logger instance."""
+        return self._logger_instance
+    
+    @property
+    def metrics(self) -> BaseMetrics:
+        """Get the metrics instance."""
+        return self._metrics_instance
+
+
+def create_logdash(params: Optional[Dict[str, Any]] = None) -> logdash:
+    """
+    Create a new logdash instance with logger and metrics.
+    
+    Args:
+        params: Optional dictionary with configuration parameters:
+               - api_key: Your logdash API key
+               - host: logdash API host (defaults to https://api.logdash.io)
+               - verbose: Enable verbose mode
+               
+    Returns:
+        A logdash instance with logger and metrics properties
+    """
+    # Initialize with default values
+    api_key = None
+    host = "https://api.logdash.io"
+    verbose = False
+    
+    # Override with provided params if any
+    if params is not None:
+        api_key = params.get("api_key", api_key)
+        host = params.get("host", host)
+        verbose = params.get("verbose", verbose)
+    
+    return logdash(api_key, host, verbose) 

logdash-0.2.0/logdash/internal.py

@@ -0,0 +1,6 @@
+"""Internal logging utilities for the logdash SDK."""
+
+from logdash.logger import Logger
+
+# Create a singleton logger instance for internal use
+internal_logger = Logger() 

logdash-0.2.0/logdash/logger.py

@@ -0,0 +1,96 @@
+"""Logger implementation for logdash."""
+
+from datetime import datetime
+from typing import Any, Callable, Optional
+
+from colorama import Style, init
+
+from logdash.constants import LogLevel, LOG_LEVEL_COLORS
+
+# Initialize colorama for cross-platform terminal colors
+init()
+
+
+class Logger:
+    """
+    A flexible logger for terminal output and remote logging.
+    
+    The Logger provides methods for different log levels and can 
+    both print locally and send logs to a remote service.
+    """
+    
+    def __init__(
+        self,
+        log_method: Callable = print,
+        prefix: Optional[Callable[[LogLevel], str]] = None,
+        on_log: Optional[Callable[[LogLevel, str], None]] = None,
+    ):
+        """
+        Initialize a new Logger instance.
+        
+        Args:
+            log_method: Function to use for local logging (default: print)
+            prefix: Optional function to generate log level prefix
+            on_log: Optional callback for when logs are generated
+        """
+        self.log_method = log_method
+        self.prefix = prefix or (lambda level: f"{level.value.upper()} ")
+        self.on_log = on_log
+
+    def error(self, *data: Any) -> None:
+        """Log an error message."""
+        self._log(LogLevel.ERROR, " ".join(str(item) for item in data))
+
+    def warn(self, *data: Any) -> None:
+        """Log a warning message."""
+        self._log(LogLevel.WARN, " ".join(str(item) for item in data))
+
+    def info(self, *data: Any) -> None:
+        """Log an info message."""
+        self._log(LogLevel.INFO, " ".join(str(item) for item in data))
+
+    def log(self, *data: Any) -> None:
+        """Alias for info()."""
+        self.info(*data)
+
+    def http(self, *data: Any) -> None:
+        """Log an HTTP-related message."""
+        self._log(LogLevel.HTTP, " ".join(str(item) for item in data))
+
+    def verbose(self, *data: Any) -> None:
+        """Log a verbose message."""
+        self._log(LogLevel.VERBOSE, " ".join(str(item) for item in data))
+
+    def debug(self, *data: Any) -> None:
+        """Log a debug message."""
+        self._log(LogLevel.DEBUG, " ".join(str(item) for item in data))
+
+    def silly(self, *data: Any) -> None:
+        """Log a silly message (lowest priority)."""
+        self._log(LogLevel.SILLY, " ".join(str(item) for item in data))
+
+    def _log(self, level: LogLevel, message: str) -> None:
+        """
+        Internal method to format and output a log message.
+        
+        Args:
+            level: The log level
+            message: The message to log
+        """
+        # Format with color
+        color = LOG_LEVEL_COLORS[level]
+        timestamp = datetime.now().isoformat()
+        
+        # Format the message with timestamp and level prefix
+        formatted_message = (
+            f"\033[90m[{timestamp}]\033[0m "
+            f"{color}{self.prefix(level)}\033[0m"
+            f"{message}"
+        )
+
+        # Output to configured log method
+        self.log_method(formatted_message)
+        
+        # Call the callback if configured
+        if self.on_log:
+            self.on_log(level, message) 

logdash-0.2.0/logdash/metrics/__init__.py

@@ -0,0 +1,8 @@
+"""Metrics tracking package for logdash."""
+
+from logdash.metrics.base import BaseMetrics
+from logdash.metrics.impl import Metrics
+from logdash.metrics.noop import NoopMetrics
+from logdash.constants import MetricOperation
+
+__all__ = ["BaseMetrics", "Metrics", "NoopMetrics", "MetricOperation"] 

logdash-0.2.0/logdash/metrics/base.py

@@ -0,0 +1,29 @@
+"""Base class for metrics implementations."""
+
+from abc import ABC, abstractmethod
+
+
+class BaseMetrics(ABC):
+    """Abstract base class for metrics implementations."""
+    
+    @abstractmethod
+    def set(self, name: str, value: float) -> None:
+        """
+        Set a metric to an absolute value.
+        
+        Args:
+            name: The metric name
+            value: The value to set
+        """
+        pass
+    
+    @abstractmethod
+    def mutate(self, name: str, value: float) -> None:
+        """
+        Change a metric by a relative value.
+        
+        Args:
+            name: The metric name
+            value: The amount to change by
+        """
+        pass 

logdash-0.2.0/logdash/metrics/factory.py

@@ -0,0 +1,29 @@
+"""Factory function for creating metrics instances."""
+
+from logdash.metrics.base import BaseMetrics
+from logdash.metrics.impl import Metrics
+from logdash.metrics.noop import NoopMetrics
+from logdash.internal import internal_logger
+
+
+def create_metrics(api_key: str, host: str, verbose: bool = False) -> BaseMetrics:
+    """
+    Create a metrics instance based on the provided parameters.
+    
+    Args:
+        api_key: logdash API key
+        host: logdash API host
+        verbose: Enable verbose mode
+        
+    Returns:
+        A BaseMetrics instance
+    """
+    if not api_key:
+        if verbose:
+            internal_logger.warn("No API key provided, using NoopMetrics")
+        return NoopMetrics()
+    
+    if verbose:
+        internal_logger.verbose(f"Creating Metrics with host {host}")
+    
+    return Metrics(api_key, host, verbose) 

logdash-0.2.0/logdash/metrics/impl.py

@@ -0,0 +1,85 @@
+"""HTTP-based metrics implementation."""
+
+import requests
+
+from logdash.metrics.base import BaseMetrics
+from logdash.constants import MetricOperation
+from logdash.internal import internal_logger
+
+
+class Metrics(BaseMetrics):
+    """
+    HTTP-based metrics implementation.
+    
+    Sends metrics to the logdash API via HTTP.
+    """
+    
+    def __init__(self, api_key: str, host: str, verbose: bool = False):
+        """
+        Initialize a metrics instance.
+        
+        Args:
+            api_key: logdash API key
+            host: logdash API host
+            verbose: Enable verbose mode
+        """
+        self.api_key = api_key
+        self.host = host
+        self.verbose = verbose
+
+    def set(self, name: str, value: float) -> None:
+        """
+        Set a metric to an absolute value.
+        
+        Args:
+            name: The metric name
+            value: The value to set
+        """
+        if self.verbose:
+            internal_logger.verbose(f"Setting metric {name} to {value}")
+
+        self._send_metric(name, value, MetricOperation.SET)
+
+    def mutate(self, name: str, value: float) -> None:
+        """
+        Change a metric by a relative value.
+        
+        Args:
+            name: The metric name
+            value: The amount to change by
+        """
+        if self.verbose:
+            internal_logger.verbose(f"Mutating metric {name} by {value}")
+
+        self._send_metric(name, value, MetricOperation.CHANGE)
+        
+    def _send_metric(self, name: str, value: float, operation: MetricOperation) -> None:
+        """
+        Send a metric to the logdash API.
+        
+        Args:
+            name: The metric name
+            value: The metric value
+            operation: The operation to perform
+        """
+        # Skip if no API key is provided
+        if not self.api_key:
+            return
+            
+        try:
+            requests.put(
+                f"{self.host}/metrics",
+                headers={
+                    "Content-Type": "application/json",
+                    "project-api-key": self.api_key,
+                },
+                json={
+                    "name": name,
+                    "value": value,
+                    "operation": operation,
+                },
+                timeout=5,  # Add timeout to prevent blocking
+            )
+        except requests.RequestException:
+            # Silently fail for now - future: add retry queue
+            pass 

logdash-0.2.0/logdash/metrics/noop.py

@@ -0,0 +1,32 @@
+"""No-operation metrics implementation."""
+
+from logdash.metrics.base import BaseMetrics
+
+
+class NoopMetrics(BaseMetrics):
+    """
+    No-operation metrics implementation.
+    
+    This implementation does nothing when metrics are set or mutated.
+    Useful for testing or when no remote metrics collection is needed.
+    """
+    
+    def set(self, name: str, value: float) -> None:
+        """
+        Do nothing with the metric.
+        
+        Args:
+            name: The metric name
+            value: The value to set
+        """
+        pass
+    
+    def mutate(self, name: str, value: float) -> None:
+        """
+        Do nothing with the metric.
+        
+        Args:
+            name: The metric name
+            value: The amount to change by
+        """
+        pass 

logdash-0.2.0/logdash/sync/__init__.py

@@ -0,0 +1,7 @@
+"""Log synchronization package for logdash."""
+
+from logdash.sync.base import LogSync
+from logdash.sync.http import HttpLogSync
+from logdash.sync.noop import NoopLogSync
+
+__all__ = ["LogSync", "HttpLogSync", "NoopLogSync"] 

logdash-0.2.0/logdash/sync/base.py

@@ -0,0 +1,21 @@
+"""Base class for log synchronization implementations."""
+
+from abc import ABC, abstractmethod
+
+from logdash.constants import LogLevel
+
+
+class LogSync(ABC):
+    """Abstract base class for log synchronization implementations."""
+    
+    @abstractmethod
+    def send(self, message: str, level: LogLevel, created_at: str) -> None:
+        """
+        Send a log message to the remote service.
+        
+        Args:
+            message: The log message content
+            level: The log level
+            created_at: ISO-formatted timestamp when the log was created
+        """
+        pass