phlo-clickstack 0.2.3__tar.gz → 0.3.1__tar.gz

{phlo_clickstack-0.2.3 → phlo_clickstack-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phlo-clickstack
-Version: 0.2.3
+Version: 0.3.1
 Summary: clickstack service plugin for Phlo
 Author-email: Phlo Team <team@phlo.dev>
 License: MIT

{phlo_clickstack-0.2.3 → phlo_clickstack-0.3.1}/README.md

@@ -5,8 +5,7 @@ ClickStack observability service for Phlo.
 ## Overview
 
 `phlo-clickstack` packages the official ClickStack all-in-one image so Phlo can
-ship a single OpenTelemetry-native observability target with logs, metrics, and
-traces in one UI.
+query ClickHouse-backed observability data and link to the HyperDX UI.
 
 ## Installation
 
@@ -27,11 +26,6 @@ phlo services start --service clickstack
 phlo clickstack query "SELECT count() FROM default.otel_logs"
 ```
 
-Point `phlo-otel` at ClickStack:
-
-```bash
-export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-export OTEL_TRACES_EXPORTER=otlp
-export OTEL_METRICS_EXPORTER=otlp
-export OTEL_LOGS_EXPORTER=otlp
-```
+The bundled all-in-one image exposes the HyperDX UI and ClickHouse query ports.
+Use Alloy or another collector for OTLP ingest; this service does not publish
+OTLP ports by default because the image does not listen on those ports.

{phlo_clickstack-0.2.3 → phlo_clickstack-0.3.1}/pyproject.toml

@@ -13,7 +13,7 @@ dependencies = [
 description = "clickstack service plugin for Phlo"
 name = "phlo-clickstack"
 requires-python = ">=3.11"
-version = "0.2.3"
+version = "0.3.1"
 
 [[project.authors]]
 email = "team@phlo.dev"
@@ -22,6 +22,9 @@ name = "Phlo Team"
 [project.entry-points."phlo.plugins.cli"]
 clickstack = "phlo_clickstack.cli_plugin:ClickStackCliPlugin"
 
+[project.entry-points."phlo.plugins.resources"]
+clickstack = "phlo_clickstack.resource_provider:ClickStackResourceProvider"
+
 [project.entry-points."phlo.plugins.services"]
 clickstack = "phlo_clickstack.plugin:ClickStackServicePlugin"
 

phlo_clickstack-0.3.1/src/phlo_clickstack/__init__.py

@@ -0,0 +1,21 @@
+"""Phlo ClickStack package for observability backend.
+
+This package provides a ClickStack service plugin for Phlo, bundling
+ClickHouse for observability data storage and querying.
+
+Exports:
+    ClickStackServicePlugin: Service plugin for ClickStack.
+    ClickStackCliPlugin: CLI plugin for ClickStack commands.
+    ClickStackSurfaceAdapter: Regulated surface adapter for ClickStack CLI.
+    get_clickstack_adapter: Get the ClickStack surface adapter singleton.
+"""
+
+from phlo_clickstack.authorization import (
+    ClickStackSurfaceAdapter,
+    get_adapter as get_clickstack_adapter,
+)
+
+__all__ = [
+    "ClickStackSurfaceAdapter",
+    "get_clickstack_adapter",
+]

phlo_clickstack-0.3.1/src/phlo_clickstack/authorization.py

@@ -0,0 +1,166 @@
+"""Regulated surface adapter for ClickStack CLI.
+
+This module provides the regulated surface adapter for the ClickStack CLI,
+declaring mutation commands that require authorization and enforcing
+through core enforcement.
+
+Mutation commands (require authorization):
+- clickstack.query
+
+Read commands (no authorization):
+- (none currently)
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any
+
+from phlo.cli.authorization import CliPrincipalResolver
+from phlo.logging import get_logger
+from phlo.security.adapters import (
+    EnforcementResult,
+    SurfaceOperation,
+)
+from phlo.security.enforcement import enforce
+
+logger = get_logger(__name__)
+
+SURFACE_NAME = "phlo-clickstack"
+FRAMEWORK_TYPE = "cli"
+
+MUTATION_COMMANDS: frozenset[str] = frozenset(
+    {
+        "clickstack.query",
+    }
+)
+
+READ_COMMANDS: frozenset[str] = frozenset()
+
+COMMAND_RESOURCE_MAP: dict[str, str] = {
+    "clickstack.query": "dataset",
+}
+
+COMMAND_ACTION_MAP: dict[str, str] = {
+    "clickstack.query": "dataset.write",
+}
+
+
+class ClickStackSurfaceAdapter:
+    """Regulated surface adapter for ClickStack CLI.
+
+    Declares mutation commands and enforces authorization through core
+    enforcement for privileged operations.
+    """
+
+    _instance: ClickStackSurfaceAdapter | None = None
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._resolver = CliPrincipalResolver()
+
+    @classmethod
+    def get_instance(cls) -> ClickStackSurfaceAdapter:
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    @property
+    def surface_name(self) -> str:
+        return SURFACE_NAME
+
+    @property
+    def framework_type(self) -> str:
+        return FRAMEWORK_TYPE
+
+    def list_operations(self) -> list[SurfaceOperation]:
+        operations: list[SurfaceOperation] = []
+        for command in MUTATION_COMMANDS:
+            resource_type = COMMAND_RESOURCE_MAP.get(command, "dataset")
+            action = COMMAND_ACTION_MAP.get(command, f"clickstack.{command}")
+            operations.append(
+                SurfaceOperation(
+                    action=action,
+                    resource_type=resource_type,
+                    operation_name=command,
+                    resource_id_strategy=None,
+                    framework_metadata={"command": command},
+                )
+            )
+        return operations
+
+    def is_active(self, runtime: Any) -> bool:
+        return True
+
+    def install(self, runtime: Any) -> None:
+        pass
+
+    def enforce_mutation(self, command: str, resource_id: str | None = None) -> EnforcementResult:
+        """Enforce authorization for a mutation command."""
+        if command not in MUTATION_COMMANDS:
+            return EnforcementResult.allow()
+
+        action = COMMAND_ACTION_MAP.get(command, f"clickstack.{command}")
+        resource_type = COMMAND_RESOURCE_MAP.get(command, "dataset")
+        resource_id_final = resource_id or f"clickstack:{command}"
+
+        principal = self._resolver.resolve()
+
+        from phlo.capabilities.interfaces import ResourceRef
+
+        resource = ResourceRef(
+            resource_type=resource_type,
+            resource_id=resource_id_final,
+        )
+
+        request_id = os.environ.get("PHLO_REQUEST_ID")
+
+        result = enforce(
+            principal=principal,
+            action=action,
+            resource=resource,
+            context=None,
+            request_id=request_id,
+            surface=SURFACE_NAME,
+        )
+
+        logger.debug(
+            "clickstack_mutation_enforcement_result",
+            command=command,
+            action=action,
+            result=result.variant,
+            subject=principal.subject,
+        )
+
+        return result
+
+    def check_command_authorization(self, command_path: str) -> EnforcementResult:
+        """Check if a command is authorized to run."""
+        if command_path in READ_COMMANDS:
+            return EnforcementResult.allow()
+
+        if command_path in MUTATION_COMMANDS:
+            return self.enforce_mutation(command_path)
+
+        logger.warning(
+            "clickstack_unknown_command_classification",
+            command=command_path,
+        )
+        return EnforcementResult.deny(
+            reason_code="unknown_command",
+            explanation=f"Command '{command_path}' is not classified as read or mutation",
+        )
+
+
+_adapter: ClickStackSurfaceAdapter | None = None
+
+
+def get_adapter() -> ClickStackSurfaceAdapter:
+    """Get the singleton ClickStack surface adapter."""
+    global _adapter
+    if _adapter is None:
+        _adapter = ClickStackSurfaceAdapter()
+    return _adapter

phlo_clickstack-0.3.1/src/phlo_clickstack/cli.py

@@ -0,0 +1,167 @@
+"""CLI commands for querying ClickStack's bundled ClickHouse service.
+
+This module provides Click CLI commands for executing SQL queries against
+the running ClickStack ClickHouse container. It includes utilities for
+validating container backend availability, reading SQL from files or inline arguments,
+and executing queries with configurable formatting.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from subprocess import TimeoutExpired
+
+import click
+
+from phlo.cli.commands.services import utils as services_utils
+from phlo.cli.infrastructure.command import CommandError, run_command
+from phlo.cli.infrastructure.compose import compose_base_cmd
+from phlo.cli.infrastructure.utils import get_project_name
+from phlo.cli.output import (
+    empty_file_error,
+    exclusive_options_error,
+    file_read_error,
+    missing_phlo_project_error,
+    missing_query_error,
+)
+from phlo.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _read_query(*, query: str | None, file: Path | None) -> str:
+    """Read and validate SQL query from inline argument or file.
+
+    Accepts either an inline SQL query string or a path to a SQL file.
+    Validates that exactly one input source is provided and that the
+    content is non-empty.
+
+    Args:
+        query: Inline SQL query string, or None if reading from file.
+        file: Path to SQL file, or None if using inline query.
+
+    Returns:
+        str: The SQL query text to execute.
+
+    Raises:
+        click.ClickException: If both query and file are provided.
+        click.ClickException: If file cannot be read.
+        click.ClickException: If file is empty or contains only whitespace.
+        click.ClickException: If neither query nor file is provided.
+
+    """
+    if query and file:
+        raise exclusive_options_error("an inline query", "--file")
+    if file is not None:
+        try:
+            sql = file.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise file_read_error(file) from exc
+        if sql.strip():
+            return sql
+        raise empty_file_error(file)
+    if query and query.strip():
+        return query
+    raise missing_query_error(command_hint='phlo clickstack query "SELECT 1"')
+
+
+def _ensure_phlo_dir() -> Path:
+    """Locate and return the local .phlo directory.
+
+    Searches for a .phlo directory in the current working directory.
+    This directory is required for Docker Compose project configuration.
+
+    Returns:
+        Path: Path to the .phlo directory.
+
+    Raises:
+        click.ClickException: If .phlo directory does not exist.
+
+    """
+    phlo_dir = Path.cwd() / ".phlo"
+    if phlo_dir.exists():
+        return phlo_dir
+    raise missing_phlo_project_error()
+
+
+def _require_container_backend() -> None:
+    """Validate that the selected container backend is available."""
+    services_utils.require_container_backend()
+
+
+@click.group(name="clickstack")
+def clickstack_group() -> None:
+    """Query and inspect the ClickStack service.
+
+    Provides commands for interacting with the ClickStack ClickHouse
+    container, including executing SQL queries.
+    """
+
+
+@clickstack_group.command(name="query")
+@click.argument("query", required=False)
+@click.option("--file", "query_file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--format", "output_format", default="TabSeparatedRaw", show_default=True)
+@click.option("--timeout", "timeout_seconds", default=30, show_default=True, type=int)
+def clickstack_query(
+    query: str | None,
+    query_file: Path | None,
+    output_format: str,
+    timeout_seconds: int,
+) -> None:
+    """Execute a ClickHouse query against the running ClickStack service.
+
+    Runs a SQL query via clickhouse-client inside the ClickStack container.
+    Accepts SQL either as a command argument or from a file. Requires Docker
+    and a running phlo services stack with ClickStack enabled.
+
+    Args:
+        query: SQL query string to execute.
+        query_file: Path to file containing SQL query.
+        output_format: ClickHouse output format (default: TabSeparatedRaw).
+        timeout_seconds: Query execution timeout in seconds.
+
+    Raises:
+        click.ClickException: If Docker is unavailable.
+        click.ClickException: If .phlo directory is missing.
+        click.ClickException: If both query and file options provided.
+        click.ClickException: If query file cannot be read.
+        click.ClickException: If query execution fails.
+        click.ClickException: If query times out.
+
+    """
+    _require_container_backend()
+    phlo_dir = _ensure_phlo_dir()
+    project_name = get_project_name()
+    sql = _read_query(query=query, file=query_file)
+
+    cmd = compose_base_cmd(phlo_dir=phlo_dir, project_name=project_name)
+    cmd.extend(
+        [
+            "exec",
+            "-T",
+            "clickstack",
+            "clickhouse-client",
+            "--multiquery",
+            "--format",
+            output_format,
+            "--query",
+            sql,
+        ]
+    )
+
+    try:
+        result = run_command(
+            cmd,
+            timeout_seconds=timeout_seconds,
+            capture_output=True,
+            check=True,
+        )
+    except CommandError as exc:
+        stderr = exc.stderr.strip()
+        raise click.ClickException(stderr or str(exc)) from exc
+    except TimeoutExpired as exc:
+        raise click.ClickException(f"Query timed out after {timeout_seconds} seconds.") from exc
+
+    if result.stdout:
+        click.echo(result.stdout, nl=False)

phlo_clickstack-0.3.1/src/phlo_clickstack/cli_plugin.py

@@ -0,0 +1,49 @@
+"""CLI plugin for ClickStack commands.
+
+This module defines the ClickStackCliPlugin class which registers CLI commands
+for interacting with the ClickStack ClickHouse service.
+"""
+
+from __future__ import annotations
+
+import click
+
+from phlo.plugins.base import CliCommandPlugin, PluginMetadata
+
+from phlo_clickstack.cli import clickstack_group
+
+
+class ClickStackCliPlugin(CliCommandPlugin):
+    """Register ClickStack CLI commands.
+
+    This plugin provides CLI commands for querying and managing the
+    ClickStack ClickHouse service instance.
+
+    Example:
+        Registered automatically when phlo_clickstack is installed.
+        Use `phlo clickstack --help` to see available commands.
+
+    """
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for ClickStack CLI registration.
+
+        Returns:
+            PluginMetadata: Metadata including name, version, and description.
+
+        """
+        return PluginMetadata(
+            name="clickstack",
+            version="0.1.0",
+            description="CLI commands for ClickStack query access",
+        )
+
+    def get_cli_commands(self) -> list[click.Command]:
+        """Return ClickStack CLI commands.
+
+        Returns:
+            list[click.Command]: List of Click commands provided by this plugin.
+
+        """
+        return [clickstack_group]

phlo_clickstack-0.3.1/src/phlo_clickstack/observability_backend.py

@@ -0,0 +1,148 @@
+"""ClickStack-backed observability capability provider."""
+
+from __future__ import annotations
+
+import json
+import os
+
+import requests
+
+from phlo.capabilities import (
+    CapabilitySupport,
+    DefaultObservabilityBackend,
+    ObservabilityBackendSpec,
+    TraceSpan,
+    TraceSpanFilter,
+)
+
+_CLICKSTACK_QUERY_URL_ENV = "CLICKSTACK_QUERY_URL"
+_CLICKSTACK_QUERY_USER_ENV = "CLICKSTACK_QUERY_USER"
+_CLICKSTACK_QUERY_PASSWORD_ENV = "CLICKSTACK_QUERY_PASSWORD"
+_CLICKSTACK_HTTP_PORT_ENV = "CLICKSTACK_HTTP_PORT"
+_DEFAULT_CLICKSTACK_HTTP_PORT = "8123"
+_CONTAINER_CLICKSTACK_QUERY_URL = f"http://clickstack:{_DEFAULT_CLICKSTACK_HTTP_PORT}"
+
+
+class ClickStackObservabilityBackend(DefaultObservabilityBackend):
+    """Observability backend with OTEL span queries backed by ClickStack."""
+
+    def run_trace_spans(self, run_id: str, limit: int = 500) -> list[TraceSpan]:
+        return self.trace_spans(TraceSpanFilter(run_id=run_id, limit=limit))
+
+    def trace_spans(self, filters: TraceSpanFilter) -> list[TraceSpan]:
+        query_url = self._resolve_clickstack_query_url()
+        query = _build_trace_spans_query(filters)
+        response = requests.post(
+            query_url,
+            data=query.encode("utf-8"),
+            auth=self._resolve_clickstack_query_auth(),
+            timeout=10,
+        )
+        response.raise_for_status()
+        spans: list[TraceSpan] = []
+        for line in response.text.splitlines():
+            if not line.strip():
+                continue
+            spans.append(TraceSpan(**json.loads(line)))
+        return spans
+
+    def _resolve_clickstack_query_url(self) -> str:
+        query_url = os.environ.get(_CLICKSTACK_QUERY_URL_ENV)
+        if query_url:
+            return query_url.rstrip("/")
+        if _running_in_container():
+            return _CONTAINER_CLICKSTACK_QUERY_URL
+        port = os.environ.get(_CLICKSTACK_HTTP_PORT_ENV, _DEFAULT_CLICKSTACK_HTTP_PORT)
+        return f"http://127.0.0.1:{port}"
+
+    def _resolve_clickstack_query_auth(self) -> tuple[str, str] | None:
+        user = os.environ.get(_CLICKSTACK_QUERY_USER_ENV)
+        password = os.environ.get(_CLICKSTACK_QUERY_PASSWORD_ENV)
+        if user is None:
+            return None
+        return (user, password or "")
+
+
+def _build_trace_spans_query(filters: TraceSpanFilter) -> str:
+    where_clauses = _trace_where_clauses(filters)
+    where_sql = f"WHERE {' AND '.join(where_clauses)}" if where_clauses else ""
+    limit = _bounded_limit(filters.limit)
+    return f"""
+SELECT
+    toString(Timestamp) AS timestamp,
+    TraceId AS trace_id,
+    SpanId AS span_id,
+    nullIf(ParentSpanId, '') AS parent_span_id,
+    SpanName AS span_name,
+    ServiceName AS service_name,
+    SpanKind AS span_kind,
+    round(Duration / 1000000, 3) AS duration_ms,
+    StatusCode AS status_code,
+    SpanAttributes AS span_attributes,
+    ResourceAttributes AS resource_attributes
+FROM default.otel_traces
+{where_sql}
+ORDER BY Timestamp ASC
+LIMIT {limit}
+FORMAT JSONEachRow
+""".strip()
+
+
+def _trace_where_clauses(filters: TraceSpanFilter) -> list[str]:
+    clauses: list[str] = []
+    _append_span_attribute_clause(clauses, "phlo.run_id", filters.run_id)
+    _append_span_attribute_clause(clauses, "phlo.asset_key", filters.asset_key)
+    _append_span_attribute_clause(clauses, "phlo.job_name", filters.job_name)
+    _append_exact_clause(clauses, "ServiceName", filters.service_name)
+    _append_exact_clause(clauses, "SpanName", filters.span_name)
+    _append_exact_clause(clauses, "StatusCode", filters.status_code)
+    if filters.start_time:
+        clauses.append(
+            f"Timestamp >= parseDateTimeBestEffort('{_escape_clickhouse_string(filters.start_time)}')"
+        )
+    if filters.end_time:
+        clauses.append(
+            f"Timestamp <= parseDateTimeBestEffort('{_escape_clickhouse_string(filters.end_time)}')"
+        )
+    return clauses
+
+
+def _append_span_attribute_clause(clauses: list[str], key: str, value: str | None) -> None:
+    if value:
+        clauses.append(f"SpanAttributes['{key}'] = '{_escape_clickhouse_string(value)}'")
+
+
+def _append_exact_clause(clauses: list[str], column: str, value: str | None) -> None:
+    if value:
+        clauses.append(f"{column} = '{_escape_clickhouse_string(value)}'")
+
+
+def _bounded_limit(limit: int) -> int:
+    return min(max(limit, 1), 5000)
+
+
+def build_clickstack_observability_spec() -> ObservabilityBackendSpec:
+    """Build the ClickStack observability capability spec."""
+    return ObservabilityBackendSpec(
+        name="default",
+        provider=ClickStackObservabilityBackend(),
+        metadata={
+            "default_stack": ["phlo-otel", "phlo-clickstack"],
+            "service_dependencies": ["clickstack"],
+            "backend": "clickstack",
+        },
+        support=CapabilitySupport(
+            supports_metrics=True,
+            supports_logs=True,
+            supports_dashboards=True,
+            supports_alerts=True,
+        ),
+    )
+
+
+def _escape_clickhouse_string(value: str) -> str:
+    return value.replace("\\", "\\\\").replace("'", "\\'")
+
+
+def _running_in_container() -> bool:
+    return os.path.exists("/.dockerenv")

phlo_clickstack-0.3.1/src/phlo_clickstack/plugin.py

@@ -0,0 +1,44 @@
+"""ClickStack service plugin.
+
+This module defines the ClickStackServicePlugin class which provides
+service registration and definition for the ClickStack observability
+backend service.
+"""
+
+from __future__ import annotations
+
+from phlo.plugins import PackageYamlServicePlugin, PluginMetadata
+
+
+class ClickStackServicePlugin(PackageYamlServicePlugin):
+    """Service plugin for ClickStack.
+
+    Provides ClickStack (ClickHouse-based observability backend) as a
+    managed service within the Phlo services framework. The service
+    definition is loaded from the bundled service.yaml file.
+
+    Example:
+        Plugin is automatically discovered via entry points.
+        Service is started with `phlo services start clickstack`.
+
+    Attributes:
+        service_definition: ClickStack Docker Compose configuration.
+
+    """
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for ClickStack service registration.
+
+        Returns:
+            PluginMetadata: Metadata including name, version, description,
+                author, and tags for discovery.
+
+        """
+        return PluginMetadata(
+            name="clickstack",
+            version="0.1.0",
+            description="ClickStack all-in-one observability backend",
+            author="Phlo Team",
+            tags=["observability", "logs", "metrics", "traces"],
+        )

phlo_clickstack-0.3.1/src/phlo_clickstack/resource_provider.py

@@ -0,0 +1,26 @@
+"""Resource provider for ClickStack observability capabilities."""
+
+from __future__ import annotations
+
+from phlo.plugins import PluginMetadata, ResourceProviderPlugin
+
+from phlo_clickstack.observability_backend import build_clickstack_observability_spec
+
+
+class ClickStackResourceProvider(ResourceProviderPlugin):
+    """Expose ClickStack as the default observability backend capability."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        return PluginMetadata(
+            name="clickstack",
+            version="0.1.0",
+            description="ClickStack observability capability provider",
+            tags=["observability", "logs", "metrics", "traces"],
+        )
+
+    def get_resources(self) -> list:
+        return []
+
+    def get_observability_backends(self):
+        return [build_clickstack_observability_spec()]