phlo-clickstack 0.1.0__py3-none-any.whl

phlo_clickstack/__init__.py

@@ -0,0 +1 @@
+"""ClickStack service package for Phlo."""

phlo_clickstack/cli.py

@@ -0,0 +1,113 @@
+"""CLI commands for querying ClickStack's bundled ClickHouse service."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from shutil import which
+from subprocess import TimeoutExpired
+
+import click
+
+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.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _read_query(*, query: str | None, file: Path | None) -> str:
+    """Return SQL text from inline query or file input."""
+    if query and file:
+        raise click.ClickException("Use either an inline query or --file, not both.")
+    if file is not None:
+        try:
+            sql = file.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise click.ClickException(f"Failed to read SQL file: {file}") from exc
+        if sql.strip():
+            return sql
+        raise click.ClickException(f"SQL file is empty: {file}")
+    if query and query.strip():
+        return query
+    raise click.ClickException("Provide a SQL query argument or --file.")
+
+
+def _ensure_phlo_dir() -> Path:
+    """Return the local .phlo directory or exit with a clear error."""
+    phlo_dir = Path.cwd() / ".phlo"
+    if phlo_dir.exists():
+        return phlo_dir
+    raise click.ClickException(".phlo directory not found. Run 'phlo services init' first.")
+
+
+def _require_docker() -> None:
+    """Validate that Docker is installed and responsive."""
+    if which("docker") is None:
+        raise click.ClickException("docker command not found.")
+    try:
+        result = run_command(
+            ["docker", "info"],
+            timeout_seconds=10,
+            capture_output=True,
+            check=False,
+        )
+    except TimeoutExpired as exc:
+        raise click.ClickException("docker info timed out.") from exc
+    if result.returncode == 0:
+        return
+    raise click.ClickException("Docker is not running.")
+
+
+@click.group(name="clickstack")
+def clickstack_group() -> None:
+    """Query and inspect the ClickStack service."""
+
+
+@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."""
+    _require_docker()
+    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/cli_plugin.py

@@ -0,0 +1,26 @@
+"""CLI plugin for ClickStack commands."""
+
+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."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for ClickStack CLI registration."""
+        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."""
+        return [clickstack_group]

phlo_clickstack/plugin.py

@@ -0,0 +1,31 @@
+"""ClickStack service plugin."""
+
+from __future__ import annotations
+
+from importlib import resources
+from typing import Any
+
+import yaml
+
+from phlo.plugins import PluginMetadata, ServicePlugin
+
+
+class ClickStackServicePlugin(ServicePlugin):
+    """Service plugin for ClickStack."""
+
+    @property
+    def metadata(self) -> PluginMetadata:
+        """Return plugin metadata for ClickStack service registration."""
+        return PluginMetadata(
+            name="clickstack",
+            version="0.1.0",
+            description="ClickStack all-in-one observability backend",
+            author="Phlo Team",
+            tags=["observability", "logs", "metrics", "traces"],
+        )
+
+    @property
+    def service_definition(self) -> dict[str, Any]:
+        """Load and return the ClickStack service definition."""
+        service_path = resources.files("phlo_clickstack").joinpath("service.yaml")
+        return yaml.safe_load(service_path.read_text(encoding="utf-8"))

phlo_clickstack/service.yaml

@@ -0,0 +1,60 @@
+name: clickstack
+description: ClickStack all-in-one observability backend
+category: observability
+default: false
+profile: observability
+
+image: ${CLICKSTACK_IMAGE:-docker.hyperdx.io/hyperdx/hyperdx-all-in-one}
+
+compose:
+  restart: unless-stopped
+  user: "0"
+  ports:
+    - "${CLICKSTACK_PORT:-8080}:8080"
+    - "${CLICKSTACK_OTLP_GRPC_PORT:-4317}:4317"
+    - "${CLICKSTACK_OTLP_HTTP_PORT:-4318}:4318"
+    - "${CLICKSTACK_NATIVE_PORT:-9000}:9000"
+  volumes:
+    - ./volumes/clickstack:/var/lib/clickhouse
+  healthcheck:
+    test:
+      [
+        "CMD",
+        "wget",
+        "--quiet",
+        "--tries=1",
+        "--spider",
+        "http://127.0.0.1:8080",
+      ]
+    interval: 10s
+    timeout: 5s
+    retries: 10
+
+env_vars:
+  CLICKSTACK_IMAGE:
+    default: "docker.hyperdx.io/hyperdx/hyperdx-all-in-one"
+    description: Official ClickStack all-in-one image reference
+  CLICKSTACK_PORT:
+    default: 8080
+    description: ClickStack UI port
+  CLICKSTACK_OTLP_GRPC_PORT:
+    default: 4317
+    description: ClickStack OTLP gRPC ingest port
+  CLICKSTACK_OTLP_HTTP_PORT:
+    default: 4318
+    description: ClickStack OTLP HTTP ingest port
+  CLICKSTACK_NATIVE_PORT:
+    default: 9000
+    description: ClickHouse native port exposed by the all-in-one image
+  CLICKSTACK_PUBLIC_URL:
+    default: ""
+    description: Public ClickStack base URL used by observability links
+  CLICKSTACK_LOGS_PATH:
+    default: "/"
+    description: Path used to build ClickStack log links
+  CLICKSTACK_METRICS_PATH:
+    default: "/"
+    description: Path used to build ClickStack metric links
+  CLICKSTACK_DASHBOARDS_PATH:
+    default: "/"
+    description: Path used to build ClickStack dashboard links

phlo_clickstack-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: phlo-clickstack
+Version: 0.1.0
+Summary: clickstack service plugin for Phlo
+Author-email: Phlo Team <team@phlo.dev>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/plain
+Requires-Dist: phlo>=0.1.0
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+clickstack service plugin for Phlo.

phlo_clickstack-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+phlo_clickstack/__init__.py,sha256=APKW-ntAzXdaxXBzCUVg-uvjHcISeMRQtQs_w8jxfpc,43
+phlo_clickstack/cli.py,sha256=y0gQL9EtZL-m0Ls0JHNjXQF4OBsW3dwWIy7j59BsLps,3665
+phlo_clickstack/cli_plugin.py,sha256=arbOB891SJsJNM7eIOfzQWRQ0quc3aB-DfrIn4ZaMaI,729
+phlo_clickstack/plugin.py,sha256=qgChkWVerUU6FJApMoN8ZivYOYCu1az_MZYbTBqXo1I,970
+phlo_clickstack/service.yaml,sha256=mhB0l5ZiZost6U56osPRUMSvudb0FNBP0zyM0abMcVk,1682
+phlo_clickstack-0.1.0.dist-info/METADATA,sha256=p4S1dFH2lpZocCAQa9RPDDvXG5brm4-JXz3HcgXXC4I,416
+phlo_clickstack-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+phlo_clickstack-0.1.0.dist-info/entry_points.txt,sha256=FRjuN5Qxr1_6cKOKg-8qcVtvLMMQMkiujbxrjDhg12Q,164
+phlo_clickstack-0.1.0.dist-info/top_level.txt,sha256=DP-XglbAvZvgxLt9MXVcx5x-6oM3zA5S8UiGwbZFGb4,16
+phlo_clickstack-0.1.0.dist-info/RECORD,,

phlo_clickstack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

phlo_clickstack-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[phlo.plugins.cli]
+clickstack = phlo_clickstack.cli_plugin:ClickStackCliPlugin
+
+[phlo.plugins.services]
+clickstack = phlo_clickstack.plugin:ClickStackServicePlugin

phlo_clickstack-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+phlo_clickstack