# LogSentry

AI-powered, centralized log-monitoring and Q&A for a fleet of 90+ GCP Java (log4j) microservices.

LogSentry adds three things on top of Google Cloud Logging:

1. **MCP server** — read-only tools for log query, service health, and anomaly detection.
2. **AI monitoring agent** — scheduled loop that inspects logs via those tools and decides whether to alert.
3. **Google Chat integration** — pushes proactive alerts and answers support questions interactively.

Anomaly thresholds are fully parameter-driven (`config/thresholds.yaml` + env), so tuning needs no code change.

**New here?** Read **[SETUP.md](SETUP.md)** — a beginner-to-expert guide for local setup, local
testing with examples, and step-by-step Google Cloud deployment.

See [BUILD_SPEC.md](BUILD_SPEC.md) for the full specification.

## Tech stack

TypeScript (Node 20+) · `@modelcontextprotocol/sdk` · `@google-cloud/logging` + `@google-cloud/bigquery` ·
`@google-cloud/pubsub` · `@anthropic-ai/sdk` · `express` · `zod` + `dotenv` · `vitest` + `nock` ·
Cloud Run + Cloud Scheduler.

## Quick start (local, no cloud needed)

```bash
npm install
npm run build           # tsc strict, must be clean
npm test                # all unit + integration (mocked)
npm run test:cov        # coverage gate >85% on core modules
```

Copy `.env.example` to `.env` and fill in values for runtime use.

## Local smoke tests

**MCP (stdio):**
```bash
MCP_TRANSPORT=stdio npm run mcp
# another terminal:
npx @modelcontextprotocol/inspector node dist/mcp/server.js
```

**Chat bot:**
```bash
npm run dev
curl -s localhost:8080/health        # -> {"status":"ok"}
curl -s -X POST localhost:8080/chat -H 'content-type: application/json' \
  -d '{"type":"MESSAGE","message":{"text":"is payment-service healthy?"}}'
```

**Agent dry-run (read-only, safe):**
```bash
DRY_RUN=1 npm run monitor:once       # logs the decision, does NOT post to Chat
```

## Deployment

Scripts in `scripts/` are idempotent and support `DRY_RUN=1` (echo instead of execute). Run in order:

| Script | Purpose |
|---|---|
| `01-setup-logging-sink.sh` | BigQuery dataset + log sink routing `severity>=WARNING` to BigQuery (cost lever) |
| `02-setup-pubsub.sh` | Topic + sink for near-real-time agent triggering (optional) |
| `03-setup-bigquery.sh` | Dataset/table + view normalizing the export schema into the `LogEntry` shape |
| `04-deploy-cloudrun.sh` | Build container, create viewer-only runtime SA, deploy, print URL |
| `05-setup-scheduler.sh` | Cloud Scheduler job hitting `POST /monitor` every `MONITOR_INTERVAL_MINUTES` (OIDC) |

Full step-by-step deployment, including Google Chat bot registration, is in **[SETUP.md](SETUP.md)**.

## Safety guardrails

- **Read-only everywhere** — no tool, query, or script writes to production. `assertReadOnly` guards BigQuery.
- **Query caps** — `query_logs` hard-caps at `MAX_LOGS_PER_QUERY` (500) and windows at 24h.
- **Least-privilege SA** — `roles/logging.viewer`, `roles/bigquery.dataViewer`, `roles/bigquery.jobUser` only.
- **Alert dedup + cooldown** — prevents alert storms.
- **Log tiering** — only `severity>=WARNING` exported to BigQuery; INFO/DEBUG stay in the cheaper default bucket.
  Ultra-chatty INFO logs can be sampled at the log4j appender level if volume becomes a problem.