Metadata-Version: 2.4
Name: kubelog
Version: 0.1.0
Summary: Docker and Kubernetes log aggregation, inspection, export, and preview toolkit.
Author: shazeus
License-Expression: MIT
Project-URL: Homepage, https://github.com/shazeus/kubelog
Project-URL: Repository, https://github.com/shazeus/kubelog
Project-URL: Issues, https://github.com/shazeus/kubelog/issues
Keywords: kubernetes,docker,logs,observability,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: flask>=3.0
Requires-Dist: rich>=13.7
Dynamic: license-file

<p align="center">
  <h1 align="center">Kubelog</h1>
  <p align="center">Docker and Kubernetes log aggregation, inspection, export, and preview toolkit.</p>
  <p align="center">
    <a href="https://pypi.org/project/kubelog/"><img alt="PyPI" src="https://img.shields.io/pypi/v/kubelog.svg"></a>
    <a href="https://pypi.org/project/kubelog/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/kubelog.svg"></a>
    <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
    <a href="https://github.com/shazeus/kubelog/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/shazeus/kubelog.svg?style=social"></a>
  </p>
</p>

---

Kubelog is a terminal-first log aggregation tool for teams that need to inspect container logs without standing up a full observability stack. It reads Docker JSON logs, Kubernetes CRI/containerd logs, structured JSON logs, plain text logs, directories of log files, and stdin; normalizes them into one schema; then provides Rich terminal summaries, search, severity filtering, time bucketing, exports, comparisons, and a local Flask preview dashboard.

- **Multi-format ingestion** - Parse Docker JSON, Kubernetes CRI/containerd, JSON application logs, plain text logs, directories, and pipes.
- **Log aggregation** - Group by level, source, parser, namespace, pod, container, service, stream, or time bucket.
- **Search and filtering** - Filter by query, severity, minimum severity, namespace, pod, container, service, and time range.
- **Export workflows** - Write normalized logs as JSONL, CSV, or a self-contained HTML report.
- **Preview server** - Launch a local Flask dashboard with HTML views and JSON APIs for logs, summary, and time buckets.
- **Dataset comparison** - Compare two log captures by severity or Kubernetes metadata to spot regressions quickly.

## Installation

```bash
pip install kubelog
```

## Usage

Inspect a Docker JSON log:

```bash
kubelog inspect /var/lib/docker/containers/app/app-json.log
```

Aggregate Kubernetes pod logs by severity:

```bash
kubelog aggregate /var/log/pods --by level
```

Search for errors in piped logs:

```bash
kubectl logs deploy/api --all-containers | kubelog search "timeout" -
```

Export normalized logs:

```bash
kubelog export ./logs --format csv --out build/logs.csv --min-level WARN
kubelog export ./logs --format html --out build/report.html
```

Serve a local dashboard:

```bash
kubelog serve ./logs --port 8765
```

Compare two captures:

```bash
kubelog compare before.log after.log --by level
```

## Commands

| Command | Description |
| --- | --- |
| `kubelog inspect [paths...]` | Inspect source types, parsers, levels, services, top messages, and time range. |
| `kubelog collect [paths...]` | Normalize and print logs from files, directories, or stdin. |
| `kubelog aggregate [paths...]` | Aggregate logs by severity, source, Kubernetes metadata, or time bucket. |
| `kubelog search <query> [paths...]` | Search normalized log messages and source paths. |
| `kubelog tail [paths...]` | Print newest entries and optionally follow appended file logs. |
| `kubelog export [paths...]` | Export logs as JSONL, CSV, or HTML. |
| `kubelog serve [paths...]` | Start a local Flask dashboard and JSON API server. |
| `kubelog compare <left> <right>` | Compare two log captures by severity or metadata field. |

## Configuration

Kubelog works without a config file. Use command flags to control parsing, filtering, and output:

```bash
kubelog collect ./logs \
  --source auto \
  --min-level WARN \
  --namespace production \
  --since 2h \
  --limit 200
```

Supported parser hints are `auto`, `docker`, `kubernetes`, `k8s`, `cri`, `containerd`, `json`, and `plain`. Relative time filters accept `15m`, `2h`, and `1d`; ISO timestamps are also supported.

## License

MIT License. See [LICENSE](LICENSE).

