provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/cli/commands/logs/query.py

@@ -0,0 +1,174 @@
+"""
+Query logs command for Foundation CLI.
+"""
+
+try:
+    import click
+
+    _HAS_CLICK = True
+except ImportError:
+    click = None
+    _HAS_CLICK = False
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+if _HAS_CLICK:
+
+    @click.command("query")
+    @click.option(
+        "--sql",
+        help="SQL query to execute (if not provided, builds from other options)",
+    )
+    @click.option(
+        "--current-trace",
+        is_flag=True,
+        help="Query logs for the current active trace",
+    )
+    @click.option(
+        "--trace-id",
+        help="Query logs for a specific trace ID",
+    )
+    @click.option(
+        "--level",
+        type=click.Choice(["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "CRITICAL"]),
+        help="Filter by log level",
+    )
+    @click.option(
+        "--service",
+        help="Filter by service name",
+    )
+    @click.option(
+        "--last",
+        help="Time range (e.g., 1h, 30m, 5m)",
+        default="1h",
+    )
+    @click.option(
+        "--stream",
+        default="default",
+        help="Stream to query",
+    )
+    @click.option(
+        "--size",
+        "-n",
+        type=int,
+        default=100,
+        help="Number of results",
+    )
+    @click.option(
+        "--format",
+        "-f",
+        type=click.Choice(["json", "log", "table", "csv", "summary"]),
+        default="log",
+        help="Output format",
+    )
+    @click.pass_context
+    def query_command(
+        ctx, sql, current_trace, trace_id, level, service, last, stream, size, format
+    ):
+        """Query logs from OpenObserve.
+
+        Examples:
+            # Query recent logs
+            foundation logs query --last 30m
+
+            # Query errors
+            foundation logs query --level ERROR --last 1h
+
+            # Query by current trace
+            foundation logs query --current-trace
+
+            # Query by specific trace
+            foundation logs query --trace-id abc123def456
+
+            # Query by service
+            foundation logs query --service auth-service --last 15m
+
+            # Custom SQL query
+            foundation logs query --sql "SELECT * FROM default WHERE duration_ms > 1000"
+        """
+        from provide.foundation.observability.openobserve import (
+            format_output,
+            search_logs,
+        )
+
+        client = ctx.obj.get("client")
+        if not client:
+            click.echo("Error: OpenObserve not configured.", err=True)
+            return 1
+
+        # Build SQL query if not provided
+        if not sql:
+            # Handle current trace
+            if current_trace:
+                try:
+                    # Try OpenTelemetry first
+                    from opentelemetry import trace
+
+                    current_span = trace.get_current_span()
+                    if current_span and current_span.is_recording():
+                        span_context = current_span.get_span_context()
+                        trace_id = f"{span_context.trace_id:032x}"
+                    else:
+                        # Try Foundation tracer
+                        from provide.foundation.tracer.context import (
+                            get_current_trace_id,
+                        )
+
+                        trace_id = get_current_trace_id()
+                        if not trace_id:
+                            click.echo("No active trace found.", err=True)
+                            return 1
+                except ImportError:
+                    click.echo("Tracing not available.", err=True)
+                    return 1
+
+            # Build WHERE clause
+            conditions = []
+            if trace_id:
+                conditions.append(f"trace_id = '{trace_id}'")
+            if level:
+                conditions.append(f"level = '{level}'")
+            if service:
+                conditions.append(f"service = '{service}'")
+
+            where_clause = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+            sql = f"SELECT * FROM {stream} {where_clause} ORDER BY _timestamp DESC LIMIT {size}"
+
+        # Execute query
+        try:
+            response = search_logs(
+                sql=sql,
+                start_time=f"-{last}" if last else "-1h",
+                end_time="now",
+                size=size,
+                client=client,
+            )
+
+            # Format and display results
+            if response.total == 0:
+                click.echo("No logs found matching the query.")
+            else:
+                output = format_output(response, format_type=format)
+                click.echo(output)
+
+                # Show summary for non-summary formats
+                if format != "summary":
+                    click.echo(
+                        f"\n📊 Found {response.total} logs, showing {len(response.hits)}"
+                    )
+
+        except Exception as e:
+            click.echo(f"Query failed: {e}", err=True)
+            return 1
+
+else:
+
+    def query_command(*args, **kwargs):
+        """Query command stub when click is not available."""
+        raise ImportError(
+            "CLI commands require optional dependencies. "
+            "Install with: pip install 'provide-foundation[cli]'"
+        )

provide/foundation/cli/commands/logs/send.py

@@ -0,0 +1,166 @@
+"""
+Send logs command for Foundation CLI.
+"""
+
+import json
+import sys
+
+try:
+    import click
+
+    _HAS_CLICK = True
+except ImportError:
+    click = None
+    _HAS_CLICK = False
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+if _HAS_CLICK:
+
+    @click.command("send")
+    @click.option(
+        "--message",
+        "-m",
+        help="Log message to send (reads from stdin if not provided)",
+    )
+    @click.option(
+        "--level",
+        "-l",
+        type=click.Choice(["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "CRITICAL"]),
+        default="INFO",
+        help="Log level",
+    )
+    @click.option(
+        "--service",
+        "-s",
+        help="Service name (uses config default if not provided)",
+    )
+    @click.option(
+        "--json",
+        "-j",
+        "json_attrs",
+        help="Additional attributes as JSON",
+    )
+    @click.option(
+        "--attr",
+        "-a",
+        multiple=True,
+        help="Additional attributes as key=value pairs",
+    )
+    @click.option(
+        "--trace-id",
+        help="Explicit trace ID to use",
+    )
+    @click.option(
+        "--span-id",
+        help="Explicit span ID to use",
+    )
+    @click.option(
+        "--otlp/--bulk",
+        "use_otlp",
+        default=True,
+        help="Use OTLP (default) or bulk API",
+    )
+    @click.pass_context
+    def send_command(
+        ctx, message, level, service, json_attrs, attr, trace_id, span_id, use_otlp
+    ):
+        """Send a log entry to OpenObserve.
+
+        Examples:
+            # Send a simple log
+            foundation logs send -m "User logged in" -l INFO
+
+            # Send with attributes
+            foundation logs send -m "Payment processed" --attr user_id=123 --attr amount=99.99
+
+            # Send from stdin
+            echo "Application started" | foundation logs send -l INFO
+
+            # Send with JSON attributes
+            foundation logs send -m "Error occurred" -j '{"error_code": 500, "path": "/api/users"}'
+        """
+        from provide.foundation.observability.openobserve.otlp import send_log
+
+        # Get message from stdin if not provided
+        if not message:
+            if sys.stdin.isatty():
+                click.echo(
+                    "Error: No message provided. Use -m or pipe input.", err=True
+                )
+                return 1
+            message = sys.stdin.read().strip()
+            if not message:
+                click.echo("Error: Empty message from stdin.", err=True)
+                return 1
+
+        # Build attributes
+        attributes = {}
+
+        # Add JSON attributes
+        if json_attrs:
+            try:
+                attributes.update(json.loads(json_attrs))
+            except json.JSONDecodeError as e:
+                click.echo(f"Error: Invalid JSON attributes: {e}", err=True)
+                return 1
+
+        # Add key=value attributes
+        for kv in attr:
+            if "=" not in kv:
+                click.echo(
+                    f"Error: Invalid attribute format '{kv}'. Use key=value.", err=True
+                )
+                return 1
+            key, value = kv.split("=", 1)
+            # Try to parse value as number
+            try:
+                if "." in value:
+                    value = float(value)
+                else:
+                    value = int(value)
+            except ValueError:
+                pass  # Keep as string
+            attributes[key] = value
+
+        # Add explicit trace/span IDs if provided
+        if trace_id:
+            attributes["trace_id"] = trace_id
+        if span_id:
+            attributes["span_id"] = span_id
+
+        # Send the log
+        try:
+            client = ctx.obj.get("client")
+            success = send_log(
+                message=message,
+                level=level,
+                service=service,
+                attributes=attributes if attributes else None,
+                prefer_otlp=use_otlp,
+                client=client,
+            )
+
+            if success:
+                click.echo(
+                    f"✅ Log sent successfully via {'OTLP' if use_otlp else 'bulk API'}"
+                )
+            else:
+                click.echo("❌ Failed to send log", err=True)
+                return 1
+
+        except Exception as e:
+            click.echo(f"Error: {e}", err=True)
+            return 1
+
+else:
+
+    def send_command(*args, **kwargs):
+        """Send command stub when click is not available."""
+        raise ImportError(
+            "CLI commands require optional dependencies. "
+            "Install with: pip install 'provide-foundation[cli]'"
+        )

provide/foundation/cli/commands/logs/tail.py

@@ -0,0 +1,112 @@
+"""
+Tail logs command for Foundation CLI.
+"""
+
+try:
+    import click
+
+    _HAS_CLICK = True
+except ImportError:
+    click = None
+    _HAS_CLICK = False
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+if _HAS_CLICK:
+
+    @click.command("tail")
+    @click.option(
+        "--stream",
+        "-s",
+        default="default",
+        help="Stream to tail",
+    )
+    @click.option(
+        "--filter",
+        "-f",
+        "filter_sql",
+        help="SQL WHERE clause for filtering",
+    )
+    @click.option(
+        "--lines",
+        "-n",
+        type=int,
+        default=10,
+        help="Number of initial lines to show",
+    )
+    @click.option(
+        "--follow/--no-follow",
+        "-F/-N",
+        default=True,
+        help="Follow mode (like tail -f)",
+    )
+    @click.option(
+        "--format",
+        type=click.Choice(["log", "json"]),
+        default="log",
+        help="Output format",
+    )
+    @click.pass_context
+    def tail_command(ctx, stream, filter_sql, lines, follow, format):
+        """Tail logs in real-time (like 'tail -f').
+
+        Examples:
+            # Tail all logs
+            foundation logs tail
+
+            # Tail error logs only
+            foundation logs tail --filter "level='ERROR'"
+
+            # Tail specific service
+            foundation logs tail --filter "service='auth-service'"
+
+            # Show last 20 lines and exit
+            foundation logs tail -n 20 --no-follow
+
+            # Tail with JSON output
+            foundation logs tail --format json
+        """
+        from provide.foundation.observability.openobserve import (
+            format_output,
+            tail_logs,
+        )
+
+        client = ctx.obj.get("client")
+        if not client:
+            click.echo("Error: OpenObserve not configured.", err=True)
+            return 1
+
+        try:
+            click.echo(f"📡 Tailing logs from stream '{stream}'...")
+            if filter_sql:
+                click.echo(f"   Filter: {filter_sql}")
+            click.echo("   Press Ctrl+C to stop\n")
+
+            # Tail logs
+            for log_entry in tail_logs(
+                stream=stream,
+                filter_sql=filter_sql,
+                follow=follow,
+                lines=lines,
+                client=client,
+            ):
+                output = format_output(log_entry, format_type=format)
+                click.echo(output)
+
+        except KeyboardInterrupt:
+            click.echo("\n✋ Stopped tailing logs.")
+        except Exception as e:
+            click.echo(f"Tail failed: {e}", err=True)
+            return 1
+
+else:
+
+    def tail_command(*args, **kwargs):
+        """Tail command stub when click is not available."""
+        raise ImportError(
+            "CLI commands require optional dependencies. "
+            "Install with: pip install 'provide-foundation[cli]'"
+        )

provide/foundation/cli/decorators.py

@@ -0,0 +1,262 @@
+"""Standard CLI decorators for consistent option handling."""
+
+from collections.abc import Callable
+import functools
+from pathlib import Path
+import sys
+from typing import Any, TypeVar
+
+try:
+    import click
+except ImportError:
+    click = None
+
+from provide.foundation.context import Context
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Standard log level choices
+LOG_LEVELS = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+def logging_options(f: F) -> F:
+    """
+    Add standard logging options to a Click command.
+
+    Adds:
+    - --log-level/-l: Set logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+    - --log-file: Write logs to file
+    - --log-format: Choose log output format (json, text, key_value)
+    """
+    f = click.option(
+        "--log-level",
+        "-l",
+        type=click.Choice(LOG_LEVELS, case_sensitive=False),
+        default=None,
+        envvar="PROVIDE_LOG_LEVEL",
+        help="Set the logging level",
+    )(f)
+    f = click.option(
+        "--log-file",
+        type=click.Path(dir_okay=False, writable=True, path_type=Path),
+        default=None,
+        envvar="PROVIDE_LOG_FILE",
+        help="Write logs to file",
+    )(f)
+    f = click.option(
+        "--log-format",
+        type=click.Choice(["json", "text", "key_value"], case_sensitive=False),
+        default="key_value",
+        envvar="PROVIDE_LOG_FORMAT",
+        help="Log output format",
+    )(f)
+    return f
+
+
+def config_options(f: F) -> F:
+    """
+    Add configuration file options to a Click command.
+
+    Adds:
+    - --config/-c: Path to configuration file
+    - --profile/-p: Configuration profile to use
+    """
+    f = click.option(
+        "--config",
+        "-c",
+        type=click.Path(exists=True, dir_okay=False, path_type=Path),
+        default=None,
+        envvar="PROVIDE_CONFIG_FILE",
+        help="Path to configuration file",
+    )(f)
+    f = click.option(
+        "--profile",
+        "-p",
+        default=None,
+        envvar="PROVIDE_PROFILE",
+        help="Configuration profile to use",
+    )(f)
+    return f
+
+
+def output_options(f: F) -> F:
+    """
+    Add output formatting options to a Click command.
+
+    Adds:
+    - --json: Output in JSON format
+    - --no-color: Disable colored output
+    - --no-emoji: Disable emoji in output
+    """
+    f = click.option(
+        "--json",
+        "json_output",
+        is_flag=True,
+        default=None,
+        envvar="PROVIDE_JSON_OUTPUT",
+        help="Output in JSON format",
+    )(f)
+    f = click.option(
+        "--no-color",
+        is_flag=True,
+        default=False,
+        envvar="PROVIDE_NO_COLOR",
+        help="Disable colored output",
+    )(f)
+    f = click.option(
+        "--no-emoji",
+        is_flag=True,
+        default=False,
+        envvar="PROVIDE_NO_EMOJI",
+        help="Disable emoji in output",
+    )(f)
+    return f
+
+
+def flexible_options(f: F) -> F:
+    """
+    Apply flexible CLI options that can be used at any command level.
+
+    Combines logging_options and config_options for consistent
+    control at both group and command levels.
+    """
+    f = logging_options(f)
+    f = config_options(f)
+    return f
+
+
+def standard_options(f: F) -> F:
+    """
+    Apply all standard CLI options.
+
+    Combines logging_options, config_options, and output_options.
+
+    Note: Consider using flexible_options for better granular control.
+    This decorator is maintained for backward compatibility.
+    """
+    f = logging_options(f)
+    f = config_options(f)
+    f = output_options(f)
+    return f
+
+
+def error_handler(f: F) -> F:
+    """
+    Decorator to handle errors consistently in CLI commands.
+
+    Catches exceptions and formats them appropriately based on
+    debug mode and output format.
+    """
+
+    @functools.wraps(f)
+    def wrapper(*args, **kwargs):
+        click.get_current_context()
+        debug = kwargs.get("debug", False)
+        json_output = kwargs.get("json_output", False)
+
+        try:
+            return f(*args, **kwargs)
+        except click.ClickException:
+            # Let Click handle its own exceptions
+            raise
+        except KeyboardInterrupt:
+            if not json_output:
+                click.secho("\nInterrupted by user", fg="yellow", err=True)
+            sys.exit(130)  # Standard exit code for SIGINT
+        except Exception as e:
+            if debug:
+                # In debug mode, show full traceback
+                raise
+
+            if json_output:
+                import json
+
+                error_data = {
+                    "error": str(e),
+                    "type": type(e).__name__,
+                }
+                click.echo(json.dumps(error_data), err=True)
+            else:
+                click.secho(f"Error: {e}", fg="red", err=True)
+
+            sys.exit(1)
+
+    return wrapper
+
+
+def pass_context(f: F) -> F:
+    """
+    Decorator to pass the foundation Context to a command.
+
+    Creates or retrieves a Context from Click's context object
+    and passes it as the first argument to the decorated function.
+    """
+
+    @functools.wraps(f)
+    @click.pass_context
+    def wrapper(ctx: click.Context, *args, **kwargs):
+        # Get or create foundation context
+        if not hasattr(ctx, "obj") or ctx.obj is None:
+            ctx.obj = Context()
+        elif not isinstance(ctx.obj, Context):
+            # If obj exists but isn't a Context, wrap it
+            if isinstance(ctx.obj, dict):
+                ctx.obj = Context.from_dict(ctx.obj)
+            else:
+                # Store existing obj and create new Context
+                old_obj = ctx.obj
+                ctx.obj = Context()
+                ctx.obj._cli_data = old_obj
+
+        # Update context from command options
+        if kwargs.get("log_level"):
+            ctx.obj.log_level = kwargs["log_level"]
+        if kwargs.get("log_file"):
+            # Ensure log_file is a Path object, as expected by Context
+            ctx.obj.log_file = Path(kwargs["log_file"])
+        if "log_format" in kwargs and kwargs["log_format"] is not None:
+            ctx.obj.log_format = kwargs["log_format"]
+        if "json_output" in kwargs and kwargs["json_output"] is not None:
+            ctx.obj.json_output = kwargs["json_output"]
+        if "no_color" in kwargs and kwargs["no_color"] is not None:
+            ctx.obj.no_color = kwargs["no_color"]
+        if "no_emoji" in kwargs and kwargs["no_emoji"] is not None:
+            ctx.obj.no_emoji = kwargs["no_emoji"]
+        if kwargs.get("profile"):
+            ctx.obj.profile = kwargs["profile"]
+        if kwargs.get("config"):
+            ctx.obj.load_config(kwargs["config"])
+
+        # Remove these from kwargs to avoid duplicate arguments
+        for key in [
+            "log_level",
+            "log_file",
+            "log_format",
+            "json_output",
+            "no_color",
+            "no_emoji",
+            "profile",
+            "config",
+        ]:
+            kwargs.pop(key, None)
+
+        return f(ctx.obj, *args, **kwargs)
+
+    return wrapper
+
+
+def version_option(version: str | None = None, prog_name: str | None = None):
+    """
+    Add a --version option to display version information.
+
+    Args:
+        version: Version string to display
+        prog_name: Program name to display
+    """
+
+    def decorator(f: F) -> F:
+        return click.version_option(
+            version=version, prog_name=prog_name, message="%(prog)s version %(version)s"
+        )(f)
+
+    return decorator