Getting started

What SaneLog is

SaneLog collects the logs from your servers, applications and cloud services in one place. You can search them, follow them live, and have an alert notify you by email, Slack, Discord, Pushover or a webhook when something needs attention. Your plan sets how long the logs are kept.

The building blocks

Account. Everything you see belongs to your account: its sources, events, users and settings. Nothing from one account is ever visible to another account.

Sources. A source is one thing that sends logs, usually a server named after its hostname. A source comes to exist in one of two ways:

• A server that sends syslog to your account's port becomes a source by itself the first time it sends.
• An application, a script or an AWS forwarder sends over HTTPS with a source token. You create its source first, with Add source on the All sources page.

Events. Every log line becomes an event. An event has a timestamp, a severity level, the program that wrote it, the message, and any structured attributes that were sent with it or extracted from it. Events are what you search, follow and alert on.

Filters. A filter is a saved view of your events: the sources it covers and the conditions an event must meet. You can pick a filter in the Log Explorer to narrow the stream, and every alert watches a filter.

Alerts. An alert watches a filter and notifies its channels, which deliver by email, Slack, Discord, Pushover or a webhook. Depending on its type, an alert fires when matching events occur, when they stop, when an expected event is late, or for every matching event.

Retention. Your plan sets how long events are kept. The period is the same for every source in the account.

The one exception is a sender that is waiting for approval: its logs are kept for seven days until someone approves it. Approving senders explains how.

Where things live

• The Dashboard shows whether anything needs attention: events and errors over the last 24 hours, alerts and incidents, sources, senders waiting for approval, and recent errors.
• The Log Explorer is where you search and follow events.
• Sources, Filters and Alerts each have their own entry in the sidebar. Agents is where you connect a coding agent.
• Account administration (users, account settings, redaction, API tokens and the audit log) is in the Account group of the sidebar, and billing is in the Billing group. Each group appears only for people whose access options include it.
• Your own settings (profile, password, two-factor authentication, passkeys, devices and connected agents) are in the user menu at the right of the top bar. Your settings describes each page.

Read Finding your way around for a tour of the screen, or go straight to Your first logs to start sending.

Your first logs

This guide takes a new account from nothing to live events in the Log Explorer. It uses syslog from a Linux server, which is the most common way to send logs. Sending logs covers the other ways.

1. Switch on syslog and find your endpoint

Open Sources in the sidebar and choose All sources. On a new account, a panel at the top of the page is headed Syslog is off. Choose Switch on syslog to give the account its own port.

The panel is then replaced by the Syslog endpoint callout, which shows the hostname and port. The ready-made sender configurations are listed under it.

About the port:

• The port belongs to your account alone, for as long as the account exists.
• The port accepts syslog over TLS only. It also accepts UDP and plain TCP while Accept unencrypted syslog is on in Account > Settings.
• Anyone who can open All sources can switch syslog on, except a Read Only user. The same button is on the dashboard's Getting started panel.

You can skip this step if you only send over HTTPS (the HTTP API or an AWS forwarder), since those need no port.

2. Configure the sender

Under the endpoint, open rsyslog configuration (TLS) and copy it. The configuration already contains your hostname and port.

If the account also accepts unencrypted syslog, the TLS configuration is labelled rsyslog configuration (TLS, recommended) and a plain TCP configuration for private networks is listed beside it. Use TLS for anything that crosses the public internet.

On the server, install rsyslog's TLS driver, paste the configuration into /etc/rsyslog.d/60-sanelog.conf and restart rsyslog. On Debian and Ubuntu:

sudo apt install rsyslog-gnutls
sudo nano /etc/rsyslog.d/60-sanelog.conf   # paste the snippet
sudo systemctl restart rsyslog

On RHEL, Rocky and Fedora, install the driver with sudo dnf install rsyslog-gnutls instead. A server that runs syslog-ng, or Windows, is covered in the FAQ.

Two settings in the configuration are worth knowing about:

• preserveFQDN="on" sends the server's full hostname, so two machines with the same short name stay separate sources. It is a global rsyslog setting, so local log files show the full hostname too.
• The queue settings keep lines on disk (up to 100 MB) while the connection is down, and send them when the connection comes back.

The TLS configuration needs rsyslog 8.2108 or newer (Ubuntu 22.04 and Debian 12 have it). The comments in the configuration say which line to change on an older version.

3. Send something

logger -t demo "hello sanelog"

Within a few seconds the server appears under Senders waiting for approval, above the sources list and at the top of the dashboard. The source is named after the server's hostname and marked Pending.

Choose Approve to confirm that the server is yours. Its address is then trusted, and any other server that sends from the same address is approved as soon as it appears.

Until the server is approved:

• Its lines are stored for seven days.
• Its lines are left out of filters, alerts and the Log Explorer's All sources view.
• You can still see its lines by picking the server in the Log Explorer's source picker, where its name is followed by "(pending)".

If Approve new syslog sources automatically is on in Account > Settings, every new server is approved as it appears. Approving senders explains both decisions and the sender rules they create.

4. Look at it

Open Log Explorer. New events appear at the bottom of the stream as they arrive.

To narrow the stream, type a word in the search box to see only messages that contain it, or choose levels in the level picker to see only those severities. The Log Explorer section covers everything the page can do.

5. What to do next

The dashboard's Getting started panel lists the steps below and ticks each one off when the account completes it.

You can close the panel at any time. Closing it hides it for you only. The panel also disappears by itself once every step is done, and this page stays in the documentation.

• Get logs in. Point the rest of your servers at the same endpoint with the same configuration. Each server becomes its own source. Applications, scripts and AWS send with a source's token instead. Sending logs covers both.
• Watch the first events arrive. The Log Explorer shows events as they arrive. A word in the search box or a level narrows the list. Open an event and choose Filter for this value or Exclude this value beside any attribute to show or hide the events with that value.
• Invite the team. Open Account > Users and choose Add user. Every seat is included. Each person has their own login, timezone and access options, and the audit log shows who made each change. Access options describes what each option allows.
• Set up an alert. Save a filter for the events you care about most, then add an alert that watches it. An alert can notify you by email, Slack, Discord, Pushover or a webhook when matching events arrive, or when they stop. Every plan includes unlimited alerts.
• Connect a coding agent. Claude Code, Codex, Cursor and other MCP clients can read the account's logs and investigate an incident from your editor. Open Agents in the sidebar for the command to run. Connecting takes that one command and one approval in the browser.

Two more steps are worth taking early, though the panel does not list them:

• Tag environments. Give each source an environment such as production or staging, so you can look at one environment at a time.
• Describe each source. A short description of what each source is makes Explain line and coding agents more useful.

Finding your way around

Every page has the same layout: a sidebar on the left, a bar across the top, and the page itself in between.

The sidebar

The sidebar starts with the product pages: Dashboard, Log Explorer, Sources, Filters, Alerts and Agents.

• Sources opens to All sources, Config sets and Sender rules. A red count beside All sources (and a red dot on the Sources icon) shows how many senders are waiting for approval.
• Alerts opens to All alerts and Channels.
• Log Analysis and Reports appear among the product pages for people who have them switched on.

Below the product pages are two groups for managing the account:

Group	Pages
Account	Settings, Redaction, Users, Audit log, API tokens
Billing	Plan, Payment method, Invoices

Each page in these groups appears only for people whose access options allow it. Someone with no management access sees neither group.

The groups with pages under them (Sources, Alerts, Account and Billing) open and close like this:

• Click a group's row to open or close it. The group stays that way as you move from page to page.
• Going to one of a group's pages from outside the group opens it.
• Every group is closed when you log in.

At the bottom of the sidebar are two more items:

• Got an idea? opens a box where you can send us an idea or other feedback from any page.
• Documentation opens this documentation in a new tab.

The menu button at the left of the top bar collapses the sidebar to a column of icons on a desktop, and opens the sidebar as a drawer on a phone.

A Billing Only user's sidebar holds only the Billing group, Reports (when switched on for them) and the two items above. Plan is the first page they see after they log in.

The top bar

The left of the top bar shows the name of the page, or a breadcrumb trail on detail pages.

The right of the top bar holds a button with your name above the account's name (on a phone, only a person icon). Choose it to open the user menu, which has:

• The appearance: Light mode, Dark mode or Match system.
• A color for the sidebar and top bar: Gray, Stone, Slate, Blueberry, Forest or Midnight.
• User settings: links to your own settings pages, described under Your settings.
• Log out.

The appearance and color are remembered in the browser you chose them in.