adjoint-lgtm-observe 0.1.0
Observability CLI for agentic workflows and event-driven systems. Query LGTM stack + Kafka from your terminal.
License: Apache-2.0
Requires Python: >=3.10
Keywords: agentic, ai-agents, cli, distributed-tracing, event-driven, grafana, kafka, lgtm, loki, observability, prometheus, tempo

# lgtm-observe

**Observability CLI for agentic workflows and event-driven systems.**

Trace requests across distributed services, debug Kafka consumers, and correlate logs with traces - all from your terminal.

Built for teams running AI agents, Kafka pipelines, and microservices on the LGTM stack (Loki, Grafana, Tempo, Prometheus).

## Why?

When debugging agentic workflows, you need to:
- **Trace a request** across multiple services (agent → tool → API → database)
- **Check Kafka lag** to see if consumers are keeping up
- **Correlate logs with traces** to find where things went wrong
- **Do it fast** without clicking through Grafana dashboards

Existing tools are siloed:
- `logcli` - Loki only
- `promtool` - Prometheus only
- `tempo-cli` - Tempo only

**lgtm-observe**: All of them + Kafka in one tool. Optimized for the workflow of debugging distributed systems.

## Install

```bash
# Core (logs, traces, metrics)
pip install adjoint-lgtm-observe

# With Kafka support
pip install adjoint-lgtm-observe[kafka]

# Development
pip install -e ".[dev,kafka]"
```

## Quick Start

```bash
# Configure endpoints (pick one method)

# Option 1: Environment variables
export LOKI_URL=http://localhost:3100
export TEMPO_URL=http://localhost:3200
export PROMETHEUS_URL=http://localhost:9090
export KAFKA_BOOTSTRAP=localhost:9093

# Option 2: Config file
cat > ~/.lgtm-observe.json << 'EOF'
{
  "loki_url": "http://localhost:3100",
  "tempo_url": "http://localhost:3200",
  "prometheus_url": "http://localhost:9090",
  "kafka_bootstrap": "localhost:9093"
}
EOF

# Check status
lgtm-observe status

# Query logs
lgtm-observe logs
lgtm-observe logs --service myapp --limit 50

# Get traces
lgtm-observe traces --service myapp
lgtm-observe trace abc123def456

# Query metrics
lgtm-observe metrics 'up'
lgtm-observe metrics 'rate(http_requests_total[5m])'

# Kafka state
lgtm-observe kafka topics
lgtm-observe kafka consumers
lgtm-observe kafka lag
```

## Commands

| Command | Description |
|---------|-------------|
| `status` | Health check all systems |
| `config` | Show current configuration |
| `logs` | Query logs from Loki |
| `trace <id>` | Get a specific trace |
| `traces` | Search recent traces |
| `metrics <query>` | Query Prometheus |
| `kafka topics` | List topics with message counts |
| `kafka consumers` | List consumer groups |
| `kafka lag` | Show consumer lag |

## Development

```bash
# Using uv (recommended)
uv sync --all-extras --dev
uv run pytest
uv run ruff check src/

# Or with pip
pip install -e ".[dev,kafka]"
pytest
ruff check src/
```

## Publishing

This package uses [uv](https://docs.astral.sh/uv/) and PyPI Trusted Publishers for secure, token-free releases.

1. Create a GitHub release with a version tag (e.g., `v0.1.0`)
2. GitHub Actions automatically builds and publishes to PyPI

### First-time PyPI setup

Add a Trusted Publisher on PyPI:
- Go to https://pypi.org/manage/project/adjoint-lgtm-observe/settings/publishing/
- Add GitHub as trusted publisher:
  - Owner: `Adjoint-uk`
  - Repository: `lgtm-observe`
  - Workflow: `publish.yml`
  - Environment: `pypi`

## License

Apache 2.0 - [Adjoint Ltd](https://adjoint.uk)