Concepts

The data model every other page assumes. Read this once; the rest of the handbook is reference.

How data flows

Data reaches Sondar three ways, and then one pipeline takes over:

The agent — a lightweight collector installed on your machines. It runs collection tasks: each task is a pipeline of readers → transformers → senders. Readers pull data in (tail a log file, poll a database, scrape a Prometheus endpoint); transformers parse and enrich it; senders push it to Sondar (or elsewhere). See Log collection sources and Transformers.
Listening collection — the Sondar server itself listens on a port (HTTP, TCP/UDP, FTP) and accepts data pushed to it by anything that cannot run an agent. See Listening collection.
File upload — drop a file in through the UI for a quick look.

Whichever path it took, data ends up in an index as a stream of events.

Events and fields

An event is the fundamental unit: one log line, one metric sample, one trace span. Every event carries a set of built-in fields:

field	meaning
`_raw`	the original line, verbatim
`_time`	the event timestamp
`_indexTime`	when it became searchable
`host`	the reporting host
`origin`	source path or collector
`repo`	the index it lives in
`sourcetype`	its declared format

Everything beyond these must be parsed out — Sondar does not guess structure at write time. That parsing is the job of transformers (in the agent) or field extraction (see below).

Indexes (a.k.a. repos)

An index is where events live. Internally, and in some API payloads, it is called a repo — the two words mean the same thing. In SonQL queries index= is an alias for repo=.

An index has a name (permanent — lowercase letters, digits, underscores) and a retention policy (by age, by size, or both). Name by retention and access, not by service: app_logs_30d encodes what matters, checkout_service does not. Cold data can be archived to S3-compatible storage and still queried at higher latency. See Indexes.

Sourcetypes

A sourcetype is a named format declaration — it tells Sondar how to break a stream into events, extract the timestamp, and parse fields. The same index can hold several sourcetypes; a sourcetype is how you keep “nginx access logs” and “app JSON logs” distinct even in one index.

Field extraction

Full-text search works out of the box — a bare term matches the raw line. But to group, filter or chart on a field, it has to be extracted. There are two modes:

Search-time extraction — the rule runs when you query, parsing _raw on demand. No extra storage; slower queries.
Field acceleration (index-time) — the rule runs at write time and the fields are stored. Faster queries, but it takes storage, and events written before you turn acceleration on do not have the field.

The distinction matters when you change a rule later. See Indexes and field extraction for the full picture.

The four data types

type	what it is	where it lands
Logs	timestamped lines of text	any index, via agent or listening collection
Metrics	numeric time series	metric indexes, via the agent’s telegraf readers or the metric system
Traces	spans of a request through your services	the APM surface, via OpenTelemetry (OTLP)
Events	discrete alerts or changes from other systems	the incident surface, via webhooks or the agent’s event server

They share the search language and the alerting engine but have different surfaces and lifecycles. See Metrics, APM and Events.

Apps

An app is a packaged integration: a database, a middleware, a web server, or a whole monitoring surface. Installing an app from the catalog drops in its collection templates, dashboards, repos and alert prototypes together — this is the fast path to “I’m monitoring Postgres now.” See Database sources, Middleware and Web servers and load balancers.

The query language

SonQL is the query language for search — a pipeline of commands joined by |:

search2 repo="app_logs" ERROR
| stats count() as errors by service
| sort by errors desc

There are two engines, search (search1) and search2 (newer, used for sorting, pattern recognition and metric rules). A fresh install persists search2 as the global default, so that is what an unqualified query runs on — see Search for the exact rule and the one case that still resolves to search1. They are not quite the same language, so name the engine explicitly in anything you save. See Search and SonQL reference.

Permissions

Access is role-based. Users are assigned roles; roles grant functions — search on this index, create alert rules, manage agents, and so on. Owners are assigned per object (an index, a dashboard, an alert rule) and can transfer or share them. See User settings.