phlo-clickstack 0.1.0__tar.gz

phlo_clickstack-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,37 @@
+# phlo-clickstack
+
+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.
+
+## Installation
+
+```bash
+pip install phlo-clickstack
+# or
+phlo plugin install clickstack
+```
+
+## Profile
+
+Part of the `observability` profile.
+
+## Usage
+
+```bash
+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
+```

phlo_clickstack-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "phlo-clickstack"
+version = "0.1.0"
+description = "clickstack service plugin for Phlo"
+readme = {text = "clickstack service plugin for Phlo.", content-type = "text/plain"}
+requires-python = ">=3.11"
+authors = [
+    {name = "Phlo Team", email = "team@phlo.dev"},
+]
+license = {text = "MIT"}
+dependencies = [
+    "phlo>=0.1.0",
+    "pyyaml>=6.0.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.1.0",
+]
+
+[project.entry-points."phlo.plugins.services"]
+clickstack = "phlo_clickstack.plugin:ClickStackServicePlugin"
+
+[project.entry-points."phlo.plugins.cli"]
+clickstack = "phlo_clickstack.cli_plugin:ClickStackCliPlugin"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+phlo_clickstack = ["service.yaml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

phlo_clickstack-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

phlo_clickstack-0.1.0/src/phlo_clickstack/__init__.py

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

phlo_clickstack-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/phlo_clickstack.egg-info/PKG-INFO

@@ -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/src/phlo_clickstack.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/phlo_clickstack/__init__.py
+src/phlo_clickstack/cli.py
+src/phlo_clickstack/cli_plugin.py
+src/phlo_clickstack/plugin.py
+src/phlo_clickstack/service.yaml
+src/phlo_clickstack.egg-info/PKG-INFO
+src/phlo_clickstack.egg-info/SOURCES.txt
+src/phlo_clickstack.egg-info/dependency_links.txt
+src/phlo_clickstack.egg-info/entry_points.txt
+src/phlo_clickstack.egg-info/requires.txt
+src/phlo_clickstack.egg-info/top_level.txt
+tests/test_clickstack_cli.py
+tests/test_clickstack_plugin.py

phlo_clickstack-0.1.0/src/phlo_clickstack.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

phlo_clickstack-0.1.0/src/phlo_clickstack.egg-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/src/phlo_clickstack.egg-info/requires.txt

@@ -0,0 +1,6 @@
+phlo>=0.1.0
+pyyaml>=6.0.1
+
+[dev]
+pytest>=7.0
+ruff>=0.1.0

phlo_clickstack-0.1.0/src/phlo_clickstack.egg-info/top_level.txt

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

phlo_clickstack-0.1.0/tests/test_clickstack_cli.py

@@ -0,0 +1,120 @@
+"""Tests for ClickStack CLI commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from subprocess import CompletedProcess, TimeoutExpired
+
+from click.testing import CliRunner
+
+from phlo_clickstack.cli import clickstack_group
+from phlo_clickstack.cli_plugin import ClickStackCliPlugin
+
+
+def test_clickstack_cli_plugin_metadata() -> None:
+    """Validate ClickStack CLI plugin metadata."""
+    plugin = ClickStackCliPlugin()
+
+    assert plugin.metadata.name == "clickstack"
+    assert plugin.get_cli_commands()[0].name == "clickstack"
+
+
+def test_clickstack_query_runs_clickhouse_client(monkeypatch) -> None:
+    """Query command should execute clickhouse-client in the ClickStack container."""
+
+    def _run_command(cmd, **_kwargs):
+        if cmd[:2] == ["docker", "info"]:
+            return CompletedProcess(cmd, 0, stdout="", stderr="")
+        assert cmd[-7:] == [
+            "clickstack",
+            "clickhouse-client",
+            "--multiquery",
+            "--format",
+            "JSONEachRow",
+            "--query",
+            "SELECT 1",
+        ]
+        return CompletedProcess(cmd, 0, stdout='{"1":1}\n', stderr="")
+
+    monkeypatch.setattr("phlo_clickstack.cli._ensure_phlo_dir", lambda: Path("/tmp/project/.phlo"))
+    monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
+    monkeypatch.setattr("phlo_clickstack.cli.which", lambda _name: "/usr/bin/docker")
+    monkeypatch.setattr(
+        "phlo_clickstack.cli.compose_base_cmd",
+        lambda **_kwargs: ["docker", "compose", "-p", "demo"],
+    )
+    monkeypatch.setattr("phlo_clickstack.cli.run_command", _run_command)
+
+    result = CliRunner().invoke(clickstack_group, ["query", "--format", "JSONEachRow", "SELECT 1"])
+
+    assert result.exit_code == 0
+    assert result.output == '{"1":1}\n'
+
+
+def test_clickstack_query_supports_file(monkeypatch, tmp_path) -> None:
+    """Query command should read SQL from a file."""
+    sql_file = tmp_path / "query.sql"
+    sql_file.write_text("SELECT 42", encoding="utf-8")
+
+    def _run_command(cmd, **_kwargs):
+        if cmd[:2] == ["docker", "info"]:
+            return CompletedProcess(cmd, 0, stdout="", stderr="")
+        assert cmd[-1] == "SELECT 42"
+        return CompletedProcess(cmd, 0, stdout="42\n", stderr="")
+
+    monkeypatch.setattr("phlo_clickstack.cli._ensure_phlo_dir", lambda: Path("/tmp/project/.phlo"))
+    monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
+    monkeypatch.setattr("phlo_clickstack.cli.which", lambda _name: "/usr/bin/docker")
+    monkeypatch.setattr(
+        "phlo_clickstack.cli.compose_base_cmd",
+        lambda **_kwargs: ["docker", "compose", "-p", "demo"],
+    )
+    monkeypatch.setattr("phlo_clickstack.cli.run_command", _run_command)
+
+    result = CliRunner().invoke(clickstack_group, ["query", "--file", str(sql_file)])
+
+    assert result.exit_code == 0
+    assert result.output == "42\n"
+
+
+def test_clickstack_query_rejects_missing_input(monkeypatch) -> None:
+    """Query command should fail clearly when no SQL is provided."""
+    monkeypatch.setattr("phlo_clickstack.cli._ensure_phlo_dir", lambda: Path("/tmp/project/.phlo"))
+    monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
+    monkeypatch.setattr("phlo_clickstack.cli.which", lambda _name: "/usr/bin/docker")
+    monkeypatch.setattr(
+        "phlo_clickstack.cli.run_command",
+        lambda cmd, **_kwargs: (
+            CompletedProcess(cmd, 0, stdout="", stderr="")
+            if cmd[:2] == ["docker", "info"]
+            else CompletedProcess(cmd, 0, stdout="", stderr="")
+        ),
+    )
+
+    result = CliRunner().invoke(clickstack_group, ["query"])
+
+    assert result.exit_code != 0
+    assert "Provide a SQL query argument or --file." in result.output
+
+
+def test_clickstack_query_surfaces_timeout(monkeypatch) -> None:
+    """Query command should surface timeouts as click exceptions."""
+
+    def _run_command(cmd, **_kwargs):
+        if cmd[:2] == ["docker", "info"]:
+            return CompletedProcess(cmd, 0, stdout="", stderr="")
+        raise TimeoutExpired(cmd=cmd, timeout=30)
+
+    monkeypatch.setattr("phlo_clickstack.cli._ensure_phlo_dir", lambda: Path("/tmp/project/.phlo"))
+    monkeypatch.setattr("phlo_clickstack.cli.get_project_name", lambda: "demo")
+    monkeypatch.setattr("phlo_clickstack.cli.which", lambda _name: "/usr/bin/docker")
+    monkeypatch.setattr(
+        "phlo_clickstack.cli.compose_base_cmd",
+        lambda **_kwargs: ["docker", "compose", "-p", "demo"],
+    )
+    monkeypatch.setattr("phlo_clickstack.cli.run_command", _run_command)
+
+    result = CliRunner().invoke(clickstack_group, ["query", "SELECT 1"])
+
+    assert result.exit_code != 0
+    assert "Query timed out after 30 seconds." in result.output

phlo_clickstack-0.1.0/tests/test_clickstack_plugin.py

@@ -0,0 +1,21 @@
+"""Tests for ClickStack service plugin."""
+
+from phlo_clickstack.plugin import ClickStackServicePlugin
+
+
+def test_clickstack_service_definition() -> None:
+    """Validate ClickStack service definition defaults."""
+    plugin = ClickStackServicePlugin()
+    defn = plugin.service_definition
+
+    assert defn["name"] == "clickstack"
+    assert defn["profile"] == "observability"
+
+
+def test_clickstack_plugin_metadata() -> None:
+    """Validate ClickStack plugin metadata."""
+    plugin = ClickStackServicePlugin()
+    meta = plugin.metadata
+
+    assert meta.name == "clickstack"
+    assert "observability" in meta.tags