kat

README

kat - Kubernetes Attach & Tail

kat provides real-time log streaming from Kubernetes containers across specified namespaces. It automatically:

• Detects and attaches to new pods
• Captures logs from all containers
• Removes terminated pods from monitoring

Installation

go install github.com/frobware/kat/cmd/kat@latest

Usage

% go run cmd/kat.go --help
  -allow-existing
        Allow logging to an existing directory (default: false)
  -burst int
        Kubernetes client burst (default 1000)
  -d
        Automatically create a temporary directory for logs
  -kubeconfig string
        Path to kubeconfig
  -qps float
        Kubernetes client QPS (default 500)
  -silent
        Disable console output for log lines
  -since duration
        Show logs since duration (e.g., 5m) (default 1m0s)
  -tee string
        Directory to write logs to (optional)

Flags

• -allow-existing: Allow kat to log to an existing directory without aborting. Use this flag with -tee to continue logging into an existing directory.
• -burst: The maximum burst size for the Kubernetes client rate limiter. Increase this for higher throughput.
• -d: Automatically create a temporary directory for logs in the format /tmp/kat-.
• -kubeconfig: Path to the Kubernetes kubeconfig file. Defaults to ~/.kube/config if not specified.
• -qps: Queries per second (QPS) for the Kubernetes client. Increase this value for higher throughput.
• -silent: Suppress console output for log lines. Progress messages (e.g., log file creation) will still be displayed.
• -since: Show logs from the specified duration (e.g., 5m for logs from the last 5 minutes). Defaults to 1m.
• -tee: Write logs to the specified directory. If combined with -allow-existing, logs will be appended to an existing directory.

Examples

Stream logs to the console for multiple namespaces:

$ kat openshift-ingress openshift-ingress-operator

Stream logs and write to a specific directory:

$ kat --tee /tmp/logs openshift-ingress openshift-ingress-operator

Stream logs and automatically create a temporary directory:

kat -d openshift-ingress
Output: Using temporary log directory: /tmp/kat-2025-01-06T15:30:00

Stream logs to an existing directory:

kat --tee /tmp/logs --allow-existing openshift-ingress

Suppress console output and write logs to a directory:

kat --tee /tmp/logs --silent openshift-ingress

Notes

• By default, if no namespace is specified, kat streams logs from the current Kubernetes namespace.
• If --silent is used, container logs are not printed to the console, but progress messages (e.g., “Started streaming logs”) are still displayed.
• Logs are written lazily, meaning directories and files are only created when log entries are received.

Documentation

Overview

kat (Kubernetes Attach & Tail) follows and streams logs from every container in every pod across specified namespaces in real-time. It automatically attaches to new pods as they start up and detaches when they terminate. Think of it as cat(1) and tail(1) combined, but for watching all container logs in your selected Kubernetes namespaces simultaneously.

Index

• type Callbacks
• type Kat
  • func New(clientset *kubernetes.Clientset, outputConfig *OutputConfig, ...) *Kat
  • func (k *Kat) StartStreaming(ctx context.Context, namespaces []string, since time.Duration) error
  • func (k *Kat) StopStreaming() error
• type OutputConfig

Types

type Callbacks

type Callbacks struct {
	OnError       func(err error)
	OnFileClosed  func(filePath string)
	OnFileCreated func(filePath string)
	OnLogLine     func(namespace, podName, containerName, line string)
	OnStreamStart func(namespace, podName, containerName string)
	OnStreamStop  func(namespace, podName, containerName string)
}

Callbacks provides hooks for progress updates.

type Kat

type Kat struct {
	// contains filtered or unexported fields
}

Kat represents the main structure for managing POD log streaming.

func New

func New(clientset *kubernetes.Clientset, outputConfig *OutputConfig, callbacks *Callbacks) *Kat

New creates a new Kat instance.

func (*Kat) StartStreaming

func (k *Kat) StartStreaming(ctx context.Context, namespaces []string, since time.Duration) error

StartStreaming begins streaming logs for the specified namespaces.

func (*Kat) StopStreaming

func (k *Kat) StopStreaming() error

StopStreaming stops all active log streams and closes open files.

type OutputConfig

type OutputConfig struct {
	TeeDir string // Directory to write logs (optional).
	Silent bool   // Suppress console log output.
}

OutputConfig encapsulates configuration for controlling log output.