// v0.3.2 · MIT

Documentation

Everything runs from one pip install. No agent, no server, no account - detection happens on your machine.

Installation

Install from PyPI. Python 3.9+.

$ pip install loglensai

Deep (AI semantic) mode pulls a transformer backbone. Install the extra when you want it:

$ pip install "loglensai[deep]"

Docker

Prefer containers? Pull the official multi-arch image (loglensai/loglens) - runs non-root, air-gap friendly, $0/GB.

# pull the official image (multi-arch: amd64 + arm64)
$ docker pull loglensai/loglens
# analyze a mounted log file
$ docker run --rm -v "$PWD:/data" loglensai/loglens analyze --source app.log
# live-watch a running container
$ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock:ro \
    loglensai/loglens watch "docker logs -f my-api" --rca

Available tags:

tag	image
latest	Slim image, current release.
0.3	Slim, pinned to the minor version.
0.3.x	Slim, pinned to an exact patch.
deep	Adds the neural (semantic) mode backbone.

Quickstart

Point it at any log file - the format is auto-detected. Add --deep for the best precision.

# analyze any log file - format auto-detected
$ loglens analyze --source app.log
# AI semantic mode (best precision)
$ loglens analyze --source app.log --deep

Commands

loglens analyze

The core command. Scans a log, detects anomalies, groups them into incident families.

flag	what it does
--source PATH	Log file (or stdin) to analyze.
--deep	AI semantic embeddings - best precision.
--turbo	Optimized statistical engine - fastest throughput.
--rca	Attach an AI root-cause narrative (BYO key).
--html FILE	Write a self-contained offline HTML report.
--limit N	Cap the number of lines scanned.
--explain	Show the full reason breakdown per anomaly.

# full workflow: turbo scan + AI root-cause + HTML report
$ loglens analyze --source app.log --turbo --rca --html report.html

ask · benchmark · bench

# ask a plain-English question about a log
$ loglens ask "why did the payment service start timing out?" --source app.log
# reproducible accuracy benchmark (fails under threshold)
$ loglens benchmark labeled.log --min-f1 0.90
# quick speed benchmark on the bundled demo
$ loglens bench

Live watch

Wrap any log-producing command. LogLens tails the stream and surfaces only the anomalies as they happen.

# docker
$ loglens watch "docker logs -f my-api"
# kubernetes
$ loglens watch "kubectl logs -f deploy/api"
# journald
$ loglens watch "journalctl -f -u my.service"
# enrich live incidents + write a report as you go
$ loglens watch "docker logs -f my-api" --rca --html-report report.html

Python SDK

Call detection directly from your code. Results carry the anomalies, and can enrich or export in one line.

from loglens import analyze, analyze_async
result = analyze("app.log")
for a in result.anomalies:
    print(a.level, a.score, a.message, a.reasons)
# enrich + export
print(result.rca().report)      # AI root-cause (BYO key)
print(result.ask("why did checkout fail?"))
result.save_html("report.html")
result.save_rca("rca.md")

A logging handler and a streaming detector are included too:

import logging
from loglens import LogLensHandler, LiveDetector
logging.getLogger().addHandler(LogLensHandler(app_name="checkout-api"))
det = LiveDetector()
for line in stream:
    hit = det.feed(line)
    if hit:
        print(hit.level, hit.message)

Always-on monitoring

One line in your main.py turns LogLens into a Sentry-style watcher - it alerts you on serious events, including crashes.

import loglens
loglens.init(app_name="checkout-api")   # → Slack / Teams / Email on serious events

Channels are configured through environment variables (a .env works):

LOGLENS_SLACK_WEBHOOK=https://hooks.slack.com/services/...
LOGLENS_TEAMS_WEBHOOK=https://outlook.office.com/webhook/...
LOGLENS_SMTP_HOST=smtp.example.com
LOGLENS_SMTP_TO=oncall@example.com
LOGLENS_MIN_ALERT_LEVEL=ERROR

Anti-spam is built in: repeated anomalies are collapsed into incident families and rate-limited, so you get one alert per problem - not one per line. LOGLENS_MIN_ALERT_LEVEL sets the severity floor.

AI (LLM) configuration

Root-cause narratives and ask use your own LLM key. Providers: OpenAI, Azure, Groq.

LOGLENS_LLM_PROVIDER=openai        # openai | azure | groq
LOGLENS_LLM_API_KEY=sk-...
LOGLENS_LLM_MODEL=gpt-4o-mini

🔒

Privacy: only grouped incident summaries are sent to the LLM - never your full logs. Detection itself is always 100% local. Skip the key entirely and everything except the AI narrative still works.