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

# 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

# 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

Development

# 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 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