nui-python-shared-utils 1.3.0__py3-none-any.whl

nui_lambda_shared_utils/cli.py

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""
+CLI tools for AWS Lambda utilities and Slack workspace automation.
+"""
+import os
+import sys
+import logging
+from pathlib import Path
+
+import click
+
+from .slack_setup import ChannelCreator, load_channel_config
+from .slack_setup.channel_definitions import validate_channel_names, generate_serverless_config
+from .slack_setup.setup_helpers import (
+    SlackSetupHelper,
+    prompt_for_token,
+    print_channel_summary,
+    confirm_channel_creation,
+)
+
+# Set up logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+log = logging.getLogger(__name__)
+
+
+@click.group()
+@click.version_option(version='0.1.0')
+def cli():
+    """AWS Lambda utilities and Slack workspace automation."""
+    pass
+
+
+@cli.group()
+def slack():
+    """Slack workspace automation commands."""
+    pass
+
+
+@slack.command("setup-channels")
+@click.option("--config", required=True, type=click.Path(exists=True), help="Path to channel configuration YAML file")
+@click.option("--token", envvar="SLACK_BOT_TOKEN", help="Slack bot token (or use SLACK_BOT_TOKEN env var)")
+@click.option("--check-only", is_flag=True, help="Only check existing channels, do not create")
+@click.option("--dry-run", is_flag=True, help="Preview changes without creating channels")
+@click.option("--output", type=click.Path(), help="Output file for environment variable configuration")
+@click.option(
+    "--output-format",
+    type=click.Choice(["yaml", "env"], case_sensitive=False),
+    default="yaml",
+    help="Output format for configuration",
+)
+@click.option("--no-interactive", is_flag=True, help="Skip interactive confirmations")
+@click.option("--validate-only", is_flag=True, help="Only validate channel names, do not create")
+@click.option("--test-access", is_flag=True, help="Test bot access to created channels")
+def setup_channels(config, token, check_only, dry_run, output, output_format, no_interactive, validate_only, test_access):
+    """Set up Slack channels from YAML configuration.
+
+    Automates channel creation, topic/purpose configuration, user invitations,
+    and bot setup for team workspaces.
+
+    \b
+    Examples:
+      # Create channels from config
+      slack-channel-setup --config channels.yaml
+
+      # Check existing channels only
+      slack-channel-setup --config channels.yaml --check-only
+
+      # Generate environment variables
+      slack-channel-setup --config channels.yaml --output channels.env --output-format env
+
+      # Use specific token
+      SLACK_BOT_TOKEN=xoxb-... slack-channel-setup --config channels.yaml
+    """
+    try:
+        # Load channel configuration
+        log.info(f"Loading configuration from {config}")
+        definitions = load_channel_config(config)
+
+        if not definitions:
+            click.echo(click.style("❌ No channel definitions found in config", fg="red"), err=True)
+            sys.exit(1)
+
+        # Extract service/project name from first definition or config path
+        service_name = definitions[0].service or Path(config).parent.parent.name
+
+        click.echo(f"\n🚀 Slack Channel Setup for {service_name}")
+        click.echo("=" * 60)
+
+        # Validate channel names
+        errors = validate_channel_names(definitions)
+        if errors:
+            click.echo(click.style("Channel name validation failed:", fg="red"), err=True)
+            for error in errors:
+                click.echo(f"  ❌ {error}")
+            sys.exit(1)
+
+        if validate_only:
+            click.echo(click.style("✅ All channel names are valid", fg="green"))
+            return
+
+        # Get Slack token
+        if not token and not check_only:
+            token = prompt_for_token()
+            os.environ["SLACK_BOT_TOKEN"] = token
+
+        # Initialize channel creator
+        creator = ChannelCreator(token)
+        helper = SlackSetupHelper(token)
+
+        # Check bot authentication
+        auth_info = helper.validate_bot_permissions()
+        if auth_info.get("authenticated"):
+            click.echo(f"\n✅ Authenticated as: {auth_info['bot_name']} (@{auth_info['bot_id']})")
+            click.echo(f"   Team: {auth_info['team']}")
+        else:
+            click.echo(
+                click.style(f"❌ Authentication failed: {auth_info.get('error')}", fg="red"),
+                err=True
+            )
+            sys.exit(1)
+
+        # Check existing channels
+        channel_names = [d.name for d in definitions]
+        existing_channels = creator.check_existing_channels(channel_names)
+
+        click.echo("\n📊 Channel Status:")
+        for name, channel_id in existing_channels.items():
+            if channel_id:
+                click.echo(click.style(f"  ✅ #{name} exists (ID: {channel_id})", fg="green"))
+            else:
+                click.echo(click.style(f"  ❌ #{name} does not exist", fg="yellow"))
+
+        if check_only or dry_run:
+            if dry_run:
+                click.echo("\n🔍 Dry run - showing what would be created:")
+                for definition in definitions:
+                    exists = existing_channels.get(definition.name)
+                    if exists:
+                        click.echo(f"  • #{definition.name} - Would update (exists)")
+                    else:
+                        click.echo(f"  • #{definition.name} - Would create (new)")
+                click.echo("\nNo changes made (dry run mode)")
+            return
+
+        # Confirm creation
+        if not no_interactive:
+            if not confirm_channel_creation(definitions, existing_channels):
+                click.echo("\nChannel creation cancelled")
+                return
+
+        # Create/configure channels
+        click.echo("\n🔨 Setting up channels...")
+        with click.progressbar(
+            definitions,
+            label="Creating channels",
+            item_show_func=lambda d: f"#{d.name}" if d else ""
+        ) as bar:
+            channel_map = {}
+            for definition in bar:
+                try:
+                    channel_id = creator._create_or_get_channel(definition)
+                    if channel_id:
+                        channel_map[definition.name] = channel_id
+                        creator._bot_join_channel(channel_id, definition.name)
+                        creator._configure_channel(channel_id, definition)
+                        if definition.invite_users:
+                            creator._invite_users(channel_id, definition.invite_users, definition.name)
+                        creator._post_welcome_message(channel_id, definition)
+                except Exception as e:
+                    click.echo(click.style(f"\n  ⚠️  Error setting up #{definition.name}: {e}", fg="yellow"))
+
+        if not channel_map:
+            click.echo(click.style("❌ No channels were created", fg="red"), err=True)
+            sys.exit(1)
+
+        # Test access if requested
+        if test_access:
+            click.echo("\n🧪 Testing channel access...")
+            test_results = helper.test_channel_access(list(channel_map.values()))
+            for channel_id, success in test_results.items():
+                channel_name = [k for k, v in channel_map.items() if v == channel_id][0]
+                if success:
+                    click.echo(click.style(f"  ✅ Can post to #{channel_name}", fg="green"))
+                else:
+                    click.echo(click.style(f"  ❌ Cannot post to #{channel_name}", fg="red"))
+
+        # Generate configuration
+        if output or not no_interactive:
+            config_output = generate_serverless_config(channel_map, service_name, output_format)
+
+            if output:
+                with open(output, "w") as f:
+                    f.write(config_output)
+                click.echo(click.style(f"\n✅ Configuration written to {output}", fg="green"))
+            else:
+                click.echo("\n" + "=" * 60)
+                click.echo("Configuration Output:")
+                click.echo("=" * 60)
+                click.echo(config_output)
+
+        # Print summary
+        print_channel_summary(channel_map, service_name)
+
+    except FileNotFoundError as e:
+        click.echo(click.style(f"❌ Configuration file not found: {e}", fg="red"), err=True)
+        sys.exit(1)
+    except ValueError as e:
+        click.echo(click.style(f"❌ Configuration error: {e}", fg="red"), err=True)
+        sys.exit(1)
+    except KeyboardInterrupt:
+        click.echo("\n\n⚠️  Setup cancelled by user")
+        sys.exit(130)
+    except Exception as e:
+        click.echo(click.style(f"❌ Unexpected error: {e}", fg="red"), err=True)
+        log.error("Unexpected error", exc_info=True)
+        sys.exit(1)
+
+
+def main():
+    """Entry point for CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

nui_lambda_shared_utils/cloudwatch_metrics.py

@@ -0,0 +1,367 @@
+"""
+CloudWatch metrics publishing utilities for Lambda services.
+Provides efficient batching and standardized metric publishing patterns.
+"""
+
+import os
+import time
+import logging
+from typing import Dict, List, Optional, Union
+from datetime import datetime
+from collections import defaultdict
+import boto3
+from botocore.exceptions import ClientError
+
+log = logging.getLogger(__name__)
+
+
+class MetricsPublisher:
+    """
+    Efficient CloudWatch metrics publisher with batching support.
+
+    Example:
+        publisher = MetricsPublisher('Application')
+        publisher.put_metric('RecordsProcessed', 150, unit='Count')
+        publisher.put_metric('ResponseTime', 245.5, unit='Milliseconds')
+        publisher.flush()  # Send all metrics
+    """
+
+    def __init__(
+        self,
+        namespace: str,
+        dimensions: Optional[Dict[str, str]] = None,
+        auto_flush_size: int = 20,
+        region: Optional[str] = None,
+    ):
+        """
+        Initialize metrics publisher.
+
+        Args:
+            namespace: CloudWatch namespace for metrics
+            dimensions: Default dimensions to apply to all metrics
+            auto_flush_size: Automatically flush when batch reaches this size
+            region: AWS region (uses default if not specified)
+        """
+        self.namespace = namespace
+        self.default_dimensions = dimensions or {}
+        self.auto_flush_size = auto_flush_size
+        self.client = boto3.client("cloudwatch", region_name=region)
+        self.metric_buffer: List[Dict] = []
+
+    def put_metric(
+        self,
+        metric_name: str,
+        value: Union[int, float],
+        unit: str = "None",
+        timestamp: Optional[datetime] = None,
+        dimensions: Optional[Dict[str, str]] = None,
+        storage_resolution: int = 60,
+    ) -> None:
+        """
+        Add a metric to the buffer.
+
+        Args:
+            metric_name: Name of the metric
+            value: Metric value
+            unit: CloudWatch unit (Count, Milliseconds, Bytes, etc.)
+            timestamp: Metric timestamp (defaults to now)
+            dimensions: Additional dimensions for this metric
+            storage_resolution: 1 for high-resolution, 60 for standard
+        """
+        metric_data = {
+            "MetricName": metric_name,
+            "Value": float(value),
+            "Unit": unit,
+            "Timestamp": timestamp or datetime.utcnow(),
+            "StorageResolution": storage_resolution,
+        }
+
+        # Merge dimensions
+        all_dimensions = {**self.default_dimensions}
+        if dimensions:
+            all_dimensions.update(dimensions)
+
+        if all_dimensions:
+            metric_data["Dimensions"] = [{"Name": k, "Value": str(v)} for k, v in all_dimensions.items()]
+
+        self.metric_buffer.append(metric_data)
+
+        # Auto-flush if buffer is full
+        if len(self.metric_buffer) >= self.auto_flush_size:
+            self.flush()
+
+    def put_metric_with_statistics(
+        self,
+        metric_name: str,
+        values: List[Union[int, float]],
+        unit: str = "None",
+        timestamp: Optional[datetime] = None,
+        dimensions: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """
+        Add a metric with statistical values.
+
+        Args:
+            metric_name: Name of the metric
+            values: List of values to calculate statistics from
+            unit: CloudWatch unit
+            timestamp: Metric timestamp
+            dimensions: Additional dimensions
+        """
+        if not values:
+            return
+
+        # Calculate statistics
+        sorted_values = sorted(values)
+        count = len(values)
+        sum_value = sum(values)
+        min_value = sorted_values[0]
+        max_value = sorted_values[-1]
+
+        metric_data = {
+            "MetricName": metric_name,
+            "StatisticValues": {"SampleCount": count, "Sum": sum_value, "Minimum": min_value, "Maximum": max_value},
+            "Unit": unit,
+            "Timestamp": timestamp or datetime.utcnow(),
+        }
+
+        # Merge dimensions
+        all_dimensions = {**self.default_dimensions}
+        if dimensions:
+            all_dimensions.update(dimensions)
+
+        if all_dimensions:
+            metric_data["Dimensions"] = [{"Name": k, "Value": str(v)} for k, v in all_dimensions.items()]
+
+        self.metric_buffer.append(metric_data)
+
+        if len(self.metric_buffer) >= self.auto_flush_size:
+            self.flush()
+
+    def flush(self) -> bool:
+        """
+        Send all buffered metrics to CloudWatch.
+
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        if not self.metric_buffer:
+            return True
+
+        try:
+            # CloudWatch allows max 20 metrics per request
+            for i in range(0, len(self.metric_buffer), 20):
+                batch = self.metric_buffer[i : i + 20]
+                self.client.put_metric_data(Namespace=self.namespace, MetricData=batch)
+
+            log.info(f"Published {len(self.metric_buffer)} metrics to {self.namespace}")
+            self.metric_buffer = []
+            return True
+
+        except ClientError as e:
+            log.error(f"Failed to publish metrics: {e}")
+            return False
+
+    def __enter__(self):
+        """Context manager support."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Ensure metrics are flushed on exit."""
+        self.flush()
+
+
+class MetricAggregator:
+    """
+    Aggregate metrics over time before publishing.
+    Useful for high-frequency metrics that need aggregation.
+    """
+
+    def __init__(self, publisher: MetricsPublisher):
+        self.publisher = publisher
+        self.aggregates: Dict[str, List[float]] = defaultdict(list)
+        self.counters: Dict[str, float] = defaultdict(float)
+
+    def add_value(self, metric_name: str, value: Union[int, float]) -> None:
+        """Add a value to be aggregated."""
+        self.aggregates[metric_name].append(float(value))
+
+    def increment_counter(self, metric_name: str, value: Union[int, float] = 1) -> None:
+        """Increment a counter metric."""
+        self.counters[metric_name] += value
+
+    def publish_aggregates(self, unit: str = "None", dimensions: Optional[Dict[str, str]] = None) -> None:
+        """Publish all aggregated metrics with statistics."""
+        # Publish aggregated values
+        for metric_name, values in self.aggregates.items():
+            if values:
+                self.publisher.put_metric_with_statistics(metric_name, values, unit=unit, dimensions=dimensions)
+
+        # Publish counters
+        for metric_name, value in self.counters.items():
+            self.publisher.put_metric(metric_name, value, unit="Count", dimensions=dimensions)
+
+        # Clear aggregates
+        self.aggregates.clear()
+        self.counters.clear()
+
+
+# Standard metric names for consistency across services
+class StandardMetrics:
+    """Standard metric names used across application services."""
+
+    # Service health metrics
+    SERVICE_HEALTH = "ServiceHealth"
+    ERROR_RATE = "ErrorRate"
+    RESPONSE_TIME = "ResponseTime"
+    REQUEST_COUNT = "RequestCount"
+
+    # Business metrics
+    RECORDS_CREATED = "RecordsCreated"
+    RECORDS_PROCESSED = "RecordsProcessed"
+    USERS_ACTIVE = "ActiveUsers"
+    REVENUE_PROCESSED = "RevenueProcessed"
+
+    # Lambda metrics
+    LAMBDA_DURATION = "LambdaDuration"
+    LAMBDA_ERRORS = "LambdaErrors"
+    LAMBDA_THROTTLES = "LambdaThrottles"
+    LAMBDA_COLD_STARTS = "LambdaColdStarts"
+
+    # Database metrics
+    DB_QUERY_TIME = "DatabaseQueryTime"
+    DB_CONNECTION_ERRORS = "DatabaseConnectionErrors"
+    DB_ACTIVE_CONNECTIONS = "DatabaseActiveConnections"
+
+    # Elasticsearch metrics
+    ES_QUERY_TIME = "ElasticsearchQueryTime"
+    ES_QUERY_ERRORS = "ElasticsearchQueryErrors"
+    ES_DOCUMENT_COUNT = "ElasticsearchDocumentCount"
+
+    # External API metrics
+    API_CALL_DURATION = "ExternalAPICallDuration"
+    API_CALL_ERRORS = "ExternalAPICallErrors"
+    API_RATE_LIMIT_HITS = "APIRateLimitHits"
+
+
+def track_lambda_performance(namespace: str = "Application"):
+    """
+    Decorator to automatically track Lambda function performance.
+
+    Example:
+        @track_lambda_performance()
+        def handler(event, context):
+            # Your Lambda logic
+            return response
+    """
+
+    def decorator(func):
+        def wrapper(event, context):
+            start_time = time.time()
+            cold_start = not hasattr(context, "is_warm")
+
+            publisher = MetricsPublisher(
+                namespace,
+                dimensions={"FunctionName": context.function_name, "Environment": os.environ.get("STAGE", "dev")},
+            )
+
+            try:
+                # Mark as warm for next invocation
+                context.is_warm = True
+
+                # Track cold start
+                if cold_start:
+                    publisher.put_metric(StandardMetrics.LAMBDA_COLD_STARTS, 1, unit="Count")
+
+                # Execute function
+                result = func(event, context)
+
+                # Track success metrics
+                duration = (time.time() - start_time) * 1000  # Convert to milliseconds
+                publisher.put_metric(StandardMetrics.LAMBDA_DURATION, duration, unit="Milliseconds")
+                publisher.put_metric(StandardMetrics.REQUEST_COUNT, 1, unit="Count")
+
+                return result
+
+            except Exception:
+                # Track error
+                publisher.put_metric(StandardMetrics.LAMBDA_ERRORS, 1, unit="Count")
+                raise
+
+            finally:
+                # Ensure metrics are published
+                publisher.flush()
+
+        return wrapper
+
+    return decorator
+
+
+def create_service_dimensions(service_name: str, environment: Optional[str] = None) -> Dict[str, str]:
+    """
+    Create standard dimensions for service metrics.
+
+    Args:
+        service_name: Name of the service
+        environment: Environment (defaults to STAGE env var)
+
+    Returns:
+        Dict of dimensions
+    """
+    dimensions = {"ServiceName": service_name, "Environment": environment or os.environ.get("STAGE", "dev")}
+
+    # Add region if available
+    region = os.environ.get("AWS_REGION", os.environ.get("AWS_DEFAULT_REGION"))
+    if region:
+        dimensions["Region"] = region
+
+    return dimensions
+
+
+def publish_health_metric(service_name: str, is_healthy: bool, namespace: str = "Application") -> None:
+    """
+    Publish a simple health metric for a service.
+
+    Args:
+        service_name: Name of the service
+        is_healthy: Whether the service is healthy
+        namespace: CloudWatch namespace
+    """
+    publisher = MetricsPublisher(namespace, dimensions=create_service_dimensions(service_name))
+
+    publisher.put_metric(StandardMetrics.SERVICE_HEALTH, 1 if is_healthy else 0, unit="None")
+
+    publisher.flush()
+
+
+class TimedMetric:
+    """
+    Context manager for timing operations and publishing metrics.
+
+    Example:
+        publisher = MetricsPublisher('MyApp')
+        with TimedMetric(publisher, 'DatabaseQuery', unit='Milliseconds'):
+            # Perform database query
+            results = db.query("SELECT * FROM records")
+    """
+
+    def __init__(
+        self,
+        publisher: MetricsPublisher,
+        metric_name: str,
+        unit: str = "Milliseconds",
+        dimensions: Optional[Dict[str, str]] = None,
+    ):
+        self.publisher = publisher
+        self.metric_name = metric_name
+        self.unit = unit
+        self.dimensions = dimensions
+        self.start_time = None
+
+    def __enter__(self):
+        self.start_time = time.time()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        duration = (time.time() - self.start_time) * 1000  # Convert to milliseconds
+        self.publisher.put_metric(self.metric_name, duration, unit=self.unit, dimensions=self.dimensions)