# SaneLog

> SaneLog is a log aggregation and alerting service. Teams can send it all their logs (syslog, application logs, cloud logs and more), then search and follow them live, save filters and set alerts. Coding agents can read the same logs through an MCP server and a read-only API. This page introduces SaneLog to an agent and links to the documentation, every page of which is served as Markdown.

**Glossary**

- **Alert** - watches a filter and notifies channels (email, Slack, Discord, Pushover, webhooks). Its type says when it fires: "Matching events occur" (a threshold within a window), "Matching events stop" (a heartbeat that fell silent) or "An expected event is late" (a schedule with a grace period). An alert of the type "Every matching event" forwards each match instead and records no incidents.
- **Attributes** - the structured fields of an event, sent as JSON or extracted from a JSON payload at the end of the message, addressed by a dotted path such as `context.order.id`.
- **Environment** - a tag on a source, such as `production` or `staging`. The logs usually mix several systems and environments, so scope every question to the environment it is about.
- **Event** - one log line: `time` (the sender's clock), `received_at` (when SaneLog received it), source, program, level, message and attributes.
- **Filter** - a saved search: a source scope (named sources, a name pattern, environments) plus conditions on level, program, message, message pattern and attributes. Any filter can be passed to the API by name.
- **Handoff** - one event or one incident with what happened around it across every source, given to an agent as a pasted Copy for agent block.
- **Incident** - one occurrence of an alert's condition holding, recorded with a narrative of what happened against what the filter usually does, the matching lines (or the last match) and links. It is resolved when the condition stops holding.
- **Level** - the severity of an event: debug, info, notice, warning, error, critical, alert, emergency, from least to most severe.
- **Log Explorer** - the page in SaneLog where people search and follow logs live. Links into it (`explorer_url`) are for the person you are working with, not for you to fetch.
- **Pattern** - a message with its numbers, ids, addresses and quoted values replaced by `?`, so similar lines count together. The API's `/summary` groups lines into patterns and compares them with the window before, as the Log Analysis page in SaneLog does.
- **Pending source** - a syslog sender new to the logs, waiting for a person to approve it. Its lines are left out of filters, alerts and the views across all sources until then.
- **Program** - what wrote a line: the syslog tag, or the program an application names.
- **Query expression** - conditions written as text, such as `program is nginx and level is error+`. The API's `q` parameter can take one.
- **Redaction marker** - a token such as `[email]`, `[card]` or `[token]` that replaced personal data or a credential before the line was stored. The original text cannot be recovered.
- **Retention** - how long events are kept, the same for every source. Anything older is gone.
- **Source** - one sender, usually a server named after its hostname, or an application, a script or an AWS forwarder sending over HTTPS. Each carries an environment and a description written by the people who set it up.

**How an agent can read SaneLog**

- A coding agent in an editor or a chat client can connect to the MCP server at `https://app.sanelog.com/mcp` with the URL alone, once a person approves it in the browser. The server's instructions carry the investigation method.
- A script, a pipeline or a headless agent can read the API at `https://app.sanelog.com/api/v1` with an account API token, created under Account > API tokens and kept in the environment as `SANELOG_API_TOKEN`. The [API reference](https://app.sanelog.com/docs/api-reference.md) has every endpoint and the investigation method.
- A person can hand an agent one event or one incident as a Copy for agent block pasted into the chat. [Agent handoffs](https://app.sanelog.com/docs/handoffs.md) describes what a handoff contains and how to read it. An alert email names its incident by uuid, which `/incidents?incident=<uuid>` (the `list_incidents` tool) returns.
- The MCP server and the API are read-only. Filters, alerts, sources and tokens can only be changed in the SaneLog web app.

**Documentation**

SaneLog's documentation is public, and every page is listed below as Markdown, in the same groups as on the documentation site at https://app.sanelog.com/docs. The same page without `.md` is the page for a person to read.

## Documentation: Start here

- [Getting started](https://app.sanelog.com/docs/getting-started.md): What SaneLog is, the steps from a new account to the first logs, and finding the way around.

## Documentation: Getting logs in

- [Sending logs](https://app.sanelog.com/docs/sending-logs.md): Syslog and sender approval, the HTTP ingest endpoint, and config sets.
- [Sources](https://app.sanelog.com/docs/sources.md): The sources list and a source's page, descriptions, environments, source tokens, arrival lag, merging and deleting.
- [AWS](https://app.sanelog.com/docs/aws.md): Forwarding CloudWatch Logs and EventBridge service events, step by step in the AWS console or the AWS CLI, with the forwarder code.

## Documentation: Working with logs

- [Log Explorer](https://app.sanelog.com/docs/log-explorer.md): Searching and narrowing events, moving through the stream, reading an event, display settings, Explain line and Copy for agent.
- [Query expressions](https://app.sanelog.com/docs/query-expressions.md): Event conditions written as text for advanced search, filter conditions and the API, with worked examples.
- [Filters](https://app.sanelog.com/docs/filters.md): Saved views of events: which sources a filter covers and the conditions a filter applies.
- [Alerts](https://app.sanelog.com/docs/alerts.md): Alert types, the channels notifications are sent to (with the webhook payload), and how alerts fire.
- [Log Analysis](https://app.sanelog.com/docs/log-analysis.md): Lines grouped into message patterns and clusters, compared with the window before, and zooming in from a count to the lines behind it.
- [Exports](https://app.sanelog.com/docs/exports.md): Downloading stored log lines as a zip: choosing the lines and days, how the files are laid out, the line format and how long an export is kept.
- [Reports](https://app.sanelog.com/docs/reports.md): Email reports on a period that has ended, compared with the period before, and how each person chooses which reports to receive.

## Documentation: Agents and API

- [Coding agents (MCP)](https://app.sanelog.com/docs/mcp.md): Connecting a coding agent to the MCP server, the setup for each client, what a connected agent can do, and managing the agents connected to the account.
- [Agent handoffs](https://app.sanelog.com/docs/handoffs.md): What Copy for agent hands a coding agent: the event or incident and the window around it, how an alert email names its incident for an agent, and how an agent reads a handoff.
- [API reference](https://app.sanelog.com/docs/api-reference.md): The read API for scripts, pipelines and headless agents: getting a token, the conventions, every endpoint with its parameters, example responses, the limits and the investigation method.

## Documentation: Account

- [Your settings](https://app.sanelog.com/docs/your-settings.md): Your profile, password, two-factor authentication, passkeys, sessions, devices and connected agents.
- [Account and users](https://app.sanelog.com/docs/account.md): Access options, managing users, account settings, API tokens and the audit log.
- [Redaction](https://app.sanelog.com/docs/redaction.md): Finding personal data and credentials in log lines as they arrive, counting them, and replacing them before the lines are stored.
- [Billing](https://app.sanelog.com/docs/billing.md): What a plan sets (sources, ingest allowance and retention), paying for a plan, invoices and the payment method.

## Documentation: Help

- [FAQ](https://app.sanelog.com/docs/faq.md): Situations with a non-obvious explanation, and setups for less common senders such as syslog-ng, Windows and Aurora Serverless.
- [Support](https://app.sanelog.com/docs/support.md): Contacting support, what to include in a message, and feature requests.