logalizer 0.1.0__tar.gz

logalizer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install --upgrade pip
+      - name: Test
+        run: python -m unittest discover -s tests

logalizer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # required for setuptools-scm to see tags
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build
+        run: python -m pip install --upgrade build
+      - name: Build sdist + wheel
+        run: python -m build
+      - name: Store artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/logalizer
+    permissions:
+      id-token: write  # required for trusted publishing (OIDC)
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

logalizer-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 0.2.0)"
+        required: true
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create and push tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag "v${{ github.event.inputs.version }}"
+          git push origin "v${{ github.event.inputs.version }}"

logalizer-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+
+.omo/
+docs/
+uv.lock

logalizer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 isdmx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

logalizer-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: logalizer
+Version: 0.1.0
+Summary: Export Kibana logs as CSV from the command line via the Kibana Reporting API.
+Author: isdmx
+License: MIT
+Project-URL: Homepage, https://github.com/isdmx/logalizer
+Project-URL: Repository, https://github.com/isdmx/logalizer
+Keywords: kibana,elasticsearch,csv,logs,export,cli
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# logalizer
+
+Export Kibana logs as CSV from the command line — via the Kibana 7.17
+Reporting API. No third-party dependencies (pure Python stdlib).
+
+`logalizer` authenticates to Kibana with basic auth, submits a CSV reporting
+job, polls until it completes, and writes the result to stdout or a file. It is
+built for both humans and scripts: clean exit codes and a strict stdout/stderr
+separation so `logalizer ... > out.csv` always yields only CSV on stdout.
+
+## Install
+
+    pip install logalizer
+
+Requires Python 3.10+.
+
+## Configure
+
+    logalizer --init
+
+Interactive wizard that validates your credentials and lets you pick a space and
+index pattern from live lists. Or set environment variables:
+
+    export KIBANA_URL=https://...
+    export KIBANA_USERNAME=...
+    export KIBANA_PASSWORD=...
+
+## Usage
+
+    # test connectivity and configuration
+    logalizer --ping
+
+    # discover what's available
+    logalizer --list-spaces
+    logalizer --list-indices --space <space>
+    logalizer --list-fields --index '<pattern>'
+
+    # export logs as CSV
+    logalizer -i '<index-pattern>' --query 'level:error' --last 24h \
+        --fields '@timestamp,level,msg' -o errors.csv
+
+Run `logalizer --help` for the full reference and `logalizer --help-json` for a
+machine-readable flag schema.
+
+## Release
+
+Publishing is automated via GitHub Actions Trusted Publishing.
+
+One-time setup on PyPI: project settings → Publishing → add a "pending
+publisher" with owner `isdmx`, repository `logalizer`, workflow `publish.yml`,
+environment `pypi`.
+
+To cut a release, either use the GitHub Actions UI (Actions → "Release" → "Run
+workflow", enter a version like 0.1.0) or from a local checkout:
+
+    git tag v0.1.0
+    git push --tags
+
+Either way, CI builds the sdist + wheel and uploads them to PyPI automatically.
+
+## License
+
+MIT

logalizer-0.1.0/README.md

@@ -0,0 +1,63 @@
+# logalizer
+
+Export Kibana logs as CSV from the command line — via the Kibana 7.17
+Reporting API. No third-party dependencies (pure Python stdlib).
+
+`logalizer` authenticates to Kibana with basic auth, submits a CSV reporting
+job, polls until it completes, and writes the result to stdout or a file. It is
+built for both humans and scripts: clean exit codes and a strict stdout/stderr
+separation so `logalizer ... > out.csv` always yields only CSV on stdout.
+
+## Install
+
+    pip install logalizer
+
+Requires Python 3.10+.
+
+## Configure
+
+    logalizer --init
+
+Interactive wizard that validates your credentials and lets you pick a space and
+index pattern from live lists. Or set environment variables:
+
+    export KIBANA_URL=https://...
+    export KIBANA_USERNAME=...
+    export KIBANA_PASSWORD=...
+
+## Usage
+
+    # test connectivity and configuration
+    logalizer --ping
+
+    # discover what's available
+    logalizer --list-spaces
+    logalizer --list-indices --space <space>
+    logalizer --list-fields --index '<pattern>'
+
+    # export logs as CSV
+    logalizer -i '<index-pattern>' --query 'level:error' --last 24h \
+        --fields '@timestamp,level,msg' -o errors.csv
+
+Run `logalizer --help` for the full reference and `logalizer --help-json` for a
+machine-readable flag schema.
+
+## Release
+
+Publishing is automated via GitHub Actions Trusted Publishing.
+
+One-time setup on PyPI: project settings → Publishing → add a "pending
+publisher" with owner `isdmx`, repository `logalizer`, workflow `publish.yml`,
+environment `pypi`.
+
+To cut a release, either use the GitHub Actions UI (Actions → "Release" → "Run
+workflow", enter a version like 0.1.0) or from a local checkout:
+
+    git tag v0.1.0
+    git push --tags
+
+Either way, CI builds the sdist + wheel and uploads them to PyPI automatically.
+
+## License
+
+MIT

logalizer-0.1.0/logalizer/__init__.py

@@ -0,0 +1,8 @@
+"""logalizer — export Kibana logs as CSV via the Reporting API."""
+
+try:
+    from importlib.metadata import version as _version
+
+    __version__ = _version("logalizer")
+except Exception:  # pragma: no cover - fallback for uninstalled source tree
+    __version__ = "0.0.0"

logalizer-0.1.0/logalizer/__main__.py

@@ -0,0 +1,4 @@
+from logalizer.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

logalizer-0.1.0/logalizer/cli.py

@@ -0,0 +1,284 @@
+"""Command-line interface for logalizer."""
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+
+from logalizer import reporting, indexpatterns
+from logalizer import init, ping
+from logalizer.client import Client, ClientError
+from logalizer.config import build_settings, config_file_path, load_config
+
+
+class UsageError(Exception):
+    pass
+
+
+_DURATION_RE = re.compile(r"^(\d+)([smhd])$")
+_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+
+def parse_duration(text):
+    m = _DURATION_RE.match(text)
+    if not m:
+        raise ValueError(f"invalid duration: {text!r} (expected like 15m, 1h, 24h, 7d)")
+    return timedelta(seconds=int(m.group(1)) * _UNIT_SECONDS[m.group(2)])
+
+
+def _iso(dt):
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+def build_time_filter(from_iso, to_iso, last):
+    if from_iso and to_iso:
+        gte, lte = from_iso, to_iso
+    elif from_iso or to_iso:
+        raise UsageError("--from and --to must be used together")
+    else:
+        now = datetime.now(timezone.utc)
+        delta = parse_duration(last or "24h")
+        gte, lte = _iso(now - delta), _iso(now)
+    return {
+        "meta": {"field": "@timestamp", "params": {}},
+        "query": {"range": {"@timestamp": {
+            "format": "strict_date_optional_time",
+            "gte": gte, "lte": lte}}},
+    }
+
+
+HELP_TEXT = """\
+logalizer — export Kibana logs as CSV (Kibana 7.17 Reporting API)
+
+USAGE
+    logalizer [export] [OPTIONS]                 # export CSV (default action)
+    logalizer --list-spaces                      # print available spaces
+    logalizer --list-indices [--space SPACE]     # print index patterns
+    logalizer --list-fields --index PATTERN      # print fields (best-effort)
+    logalizer --help-json                        # machine-readable help
+    logalizer --init                             # write config.ini (wizard)
+    logalizer --init --url URL --username U --password P [--space S] [--index P] [--insecure]
+    logalizer --ping                             # test config + connectivity
+
+EXAMPLES (copy-paste ready)
+    # Last 24h of errors from brain service, clean columns
+    logalizer --index 'logs-*' --query 'level:error' --last 24h \\
+        --fields '@timestamp,level,msg,logger' -o brain-errors.csv
+
+    # Absolute time window, match a correlation id (your real query shape)
+    logalizer -i 'app-logs-*' \\
+        --query '"00000000-0000-0000-0000-000000000000"' \\
+        --from 2026-08-25T10:00:00Z --to 2026-08-25T14:00:00Z
+
+    # Everything from an index, all fields, streamed to stdout for piping
+    logalizer -i 'agent-logs-*' --last 1h | grep 'status:500'
+
+    # Discover what's available
+    logalizer --list-spaces
+    logalizer --list-indices --space default
+    logalizer --list-fields --index 'logs-*'
+
+QUERY OPTIONS
+    -q, --query KQL        KQL query (default: "" = match all)
+                           Examples: 'level:error'
+                                     'status:500 AND url:*api*'
+                                     'session_id:"01a03931-..."'
+    -i, --index PATTERN    index pattern (REQUIRED for export), e.g. 'logs-*'
+    -s, --space SPACE      Kibana space (default: from config, else default)
+    --last DURATION        relative range: 30s, 15m, 1h, 24h, 7d
+    --from ISO --to ISO    absolute range (ISO 8601). Overrides --last.
+                           Use both, or neither.
+    --fields LIST          comma-separated columns, in order.
+                           Omit to export ALL fields (wide, includes internals).
+
+OUTPUT OPTIONS
+    -o, --out PATH         write CSV to file (default: stdout)
+    --timeout SECONDS      max wait for the async job (default: 120)
+    --insecure             skip TLS cert verification (self-signed servers)
+    -v, --verbose          progress messages to stderr
+
+DISCOVERY OPTIONS (exit 0; print to stdout, one per line)
+    --list-spaces          list spaces
+    --list-indices         list index patterns in --space
+    --list-fields          list fields for --index (best-effort, may be partial)
+
+
+CONFIGURATION & DIAGNOSTICS
+    --init                write ~/.config/logalizer/config.ini (0600).
+                          Interactive wizard when url/username/password omitted;
+                          non-interactive when all three are given via flags.
+    --ping                health check: config -> TLS -> auth -> space -> index.
+                          Prints one line per check; exit 0 all good, else first
+                          failure (2 config, 3 auth, 5 network).
+    --url, --username, --password   used only by --init (never for export).
+
+CREDENTIALS (never pass on command line)
+    KIBANA_URL, KIBANA_USERNAME, KIBANA_PASSWORD   # env vars (recommended)
+    or ~/.config/logalizer/config.ini              # 0600 perms
+
+I/O CONTRACT
+    stdout = CSV data (or discovery output). stderr = all logs/errors.
+    Safe to run:  logalizer ... > out.csv   (diagnostics never pollute CSV)
+
+EXIT CODES
+    0  success
+    2  usage error (bad flags / missing required)
+    3  auth or permission failure (check KIBANA_USERNAME/PASSWORD, space)
+    4  job failed or timed out (see stderr for Kibana's error)
+    5  network / connection error
+
+GOTCHAS
+    - CSV export is capped by xpack.reporting.csv.maxSizeBytes (10 MB default).
+      Very large exports will fail the job; narrow --query or --last.
+    - Omitting --fields exports EVERY field (including _id, _index, _score,
+      _type, @version, agent.*). Usually you want an explicit --fields list.
+    - --list-fields may be incomplete for read-only roles; you can still pass
+      any field name directly.
+"""
+
+
+def help_json():
+    return {
+        "name": "logalizer",
+        "summary": "Export Kibana logs as CSV via the Kibana 7.17 Reporting API",
+        "flags": [
+            {"flag": "--query", "alias": "-q", "type": "string", "format": "KQL",
+             "default": "\"\"", "example": "level:error"},
+            {"flag": "--index", "alias": "-i", "type": "string", "format": "index-pattern",
+             "required": True, "example": "logs-*"},
+            {"flag": "--last", "type": "duration", "format": "30s|15m|1h|24h|7d",
+             "default": "24h", "example": "1h"},
+            {"flag": "--fields", "type": "csv-list", "default": "all fields",
+             "example": "@timestamp,level,msg"},
+            {"flag": "--out", "alias": "-o", "type": "path", "default": "stdout"},
+            {"flag": "--space", "alias": "-s", "type": "string", "default": "default"},
+            {"flag": "--init", "type": "bool", "default": "false"},
+            {"flag": "--ping", "type": "bool", "default": "false"},
+            {"flag": "--url", "type": "string", "used_by": "--init"},
+            {"flag": "--username", "type": "string", "used_by": "--init"},
+            {"flag": "--password", "type": "string", "used_by": "--init"},
+        ],
+        "exit_codes": {"0": "success", "2": "usage", "3": "auth/permission",
+                       "4": "job failed/timeout", "5": "network"},
+        "io_contract": {"stdout": "CSV data", "stderr": "diagnostics"},
+        "env": ["KIBANA_URL", "KIBANA_USERNAME", "KIBANA_PASSWORD"],
+    }
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="logalizer",
+        description="Export Kibana logs as CSV (Kibana 7.17 Reporting API)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=HELP_TEXT,
+    )
+    p.add_argument("-q", "--query", default="", help="KQL query (default: match all)")
+    p.add_argument("-i", "--index", help="index pattern, e.g. 'logs-*'")
+    p.add_argument("-s", "--space", help="Kibana space (default: from config, else default)")
+    p.add_argument("--last", default="24h", help="relative range: 30s/15m/1h/24h/7d (default 24h)")
+    p.add_argument("--from", dest="from_iso", help="absolute range start (ISO 8601)")
+    p.add_argument("--to", dest="to_iso", help="absolute range end (ISO 8601)")
+    p.add_argument("--fields", help="comma-separated columns (omit = all fields)")
+    p.add_argument("-o", "--out", help="write CSV to file (default: stdout)")
+    p.add_argument("--timeout", type=int, help="max job wait in seconds (default 120)")
+    p.add_argument("--insecure", action="store_true", help="skip TLS verification")
+    p.add_argument("-v", "--verbose", action="store_true", help="progress to stderr")
+    p.add_argument("--list-spaces", action="store_true", help="list spaces")
+    p.add_argument("--list-indices", action="store_true", help="list index patterns")
+    p.add_argument("--list-fields", action="store_true", help="list fields for --index")
+    p.add_argument("--help-json", action="store_true", help="machine-readable help")
+    p.add_argument("--init", action="store_true", help="configure and write config.ini")
+    p.add_argument("--ping", action="store_true", help="test config + connectivity")
+    p.add_argument("--url", help="Kibana URL (for --init)")
+    p.add_argument("--username", help="username (for --init)")
+    p.add_argument("--password", help="password (for --init)")
+    return p
+
+
+def _err(msg, code):
+    print(f"logalizer: {msg}", file=sys.stderr)
+    return code
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+
+    if args.help_json:
+        print(json.dumps(help_json(), indent=2))
+        return 0
+
+    try:
+        cfg = load_config()
+        settings = build_settings(
+            os.environ, cfg, space=args.space, index=args.index, fields=args.fields,
+            timeout=args.timeout, insecure=(True if args.insecure else None),
+        )
+
+        if args.init:
+            return init.run_init(args, os.environ, config_path=None)
+
+        if args.ping:
+            return ping.run_ping(settings, config_file_path())
+
+        if not settings.url or not settings.username or not settings.password:
+            return _err(
+                "missing credentials. Set KIBANA_URL/KIBANA_USERNAME/KIBANA_PASSWORD "
+                "or ~/.config/logalizer/config.ini. Exit code 2.", 2)
+
+        client = Client(settings.url, settings.username, settings.password,
+                        insecure=settings.insecure)
+
+        if args.list_spaces:
+            for s in indexpatterns.list_spaces(client):
+                print(s)
+            return 0
+        if args.list_indices:
+            for t in indexpatterns.list_index_patterns(client, settings.space):
+                print(t)
+            return 0
+        if args.list_fields:
+            if not settings.index:
+                return _err("--list-fields requires --index PATTERN", 2)
+            for f in indexpatterns.list_fields(client, settings.space, settings.index):
+                print(f)
+            return 0
+
+        # export
+        if not settings.index:
+            return _err("--index is required for export", 2)
+        index_id = indexpatterns.resolve_index_pattern(
+            client, settings.space, settings.index)
+        if not index_id:
+            return _err(
+                f"index pattern {settings.index!r} not found in space "
+                f"{settings.space!r}. Use --list-indices to see available patterns.", 2)
+
+        time_filter = build_time_filter(args.from_iso, args.to_iso, args.last)
+        columns = [c.strip() for c in settings.fields.split(",") if c.strip()] if settings.fields else None
+
+        if args.verbose:
+            print(f"submitting CSV job (index={settings.index}, space={settings.space})...",
+                  file=sys.stderr)
+        job_id = reporting.submit(client, settings.space, index_id,
+                                  args.query, time_filter, columns)
+        if args.verbose:
+            print(f"job {job_id} submitted, waiting...", file=sys.stderr)
+        reporting.poll(client, job_id, timeout=settings.timeout)
+        if args.verbose:
+            print("job completed, downloading...", file=sys.stderr)
+        csv_text = reporting.download(client, job_id)
+
+        if args.out:
+            with open(args.out, "w", encoding="utf-8") as fh:
+                fh.write(csv_text)
+        else:
+            sys.stdout.write(csv_text)
+        return 0
+
+    except ClientError as e:
+        return _err(str(e) + f" Exit code {e.exit_code}.", e.exit_code)
+    except UsageError as e:
+        return _err(str(e) + " Exit code 2.", 2)
+    except (ValueError, OSError) as e:
+        return _err(str(e) + " Exit code 2.", 2)

logalizer-0.1.0/logalizer/client.py

@@ -0,0 +1,58 @@
+"""HTTP layer: basic auth + kbn-xsrf header, urllib-backed."""
+import base64
+import json
+import ssl
+import urllib.error
+import urllib.request
+
+
+class ClientError(Exception):
+    def __init__(self, message, exit_code):
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def raise_for_status(status, body, what):
+    if status == 401:
+        raise ClientError("authentication failed (401). Check KIBANA_USERNAME/KIBANA_PASSWORD.", 3)
+    if status == 403:
+        raise ClientError("permission denied (403). Role lacks access to this space.", 3)
+    if status >= 400:
+        raise ClientError(f"{what} failed ({status}): {body}", 5)
+
+
+class Client:
+    def __init__(self, url, username, password, insecure=False, timeout=30):
+        self.base = (url or "").rstrip("/")
+        self.auth = "Basic " + base64.b64encode(
+            f"{username}:{password}".encode("utf-8")
+        ).decode("ascii")
+        self.insecure = insecure
+        self.timeout = timeout
+
+    def _context(self):
+        if self.insecure:
+            ctx = ssl.create_default_context()
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+            return ctx
+        return None
+
+    def request(self, method, path, body=None):
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {"Authorization": self.auth}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(
+            self.base + path, data=data, method=method, headers=headers
+        )
+        req.headers["kbn-xsrf"] = "true"
+        try:
+            with urllib.request.urlopen(req, context=self._context(),
+                                        timeout=self.timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                return resp.status, raw
+        except urllib.error.HTTPError as e:
+            return e.code, e.read().decode("utf-8")
+        except urllib.error.URLError as e:
+            raise ClientError(f"network error: {e.reason}", 5)