Better Stack and ClickHouse logs

Let the agent search your logs in Better Stack (through its read-only SQL connection) or in ClickHouse and ClickStack, with a login that can only read them.

In the appPlatformSettingsLive systemBetter Stack or ClickHouse

With your logs, the agent can see what happened when the requester hit the problem: the error, the request, the time. If your logs are in Better Stack or in ClickHouse (ClickStack and HyperDX keep theirs there too), it searches them there.

The agent only reads logs. It writes only the words to search for. Cerberius Agents writes the whole query itself, so the agent's words never become part of it. It can search up to the last 7 days, and gets at most 1,000 entries per search. Values that look like secrets are removed from every entry before the agent sees it.

The log watcher uses the same connection.

One log source per platform

A platform reads its logs from one place: Loki, Elasticsearch, OpenSearch, Datadog, Better Stack, ClickHouse, Graylog, CloudWatch, Azure Monitor or Google Cloud Logging. To switch, click Disconnect under the one that is connected, then choose the other.

Connect Better Stack#

1
In Better Stack, open Integrations › Telemetry, and the SQL API tab. Create a connection. Copy its username and password: the password is shown only once.
2
Go to Settings › Live system. Click Connect a cluster or logs (or Connect another), and choose Better Stack. Its Logs row shows under the card.
3
Enter the connection's address, for example https://eu-nbg-2-connect.betterstackdata.com.
4
Enter the Source: the name on the connection's card under Query with, without _logs at its end. For example t123456_my_app.
5
Enter the Username and the Password.
6
Describe your logs in How your logs are labelled.
7
Click Save, under the fields.
8
Click Check connection.

Field	What it does
Connection address	The SQL connection's address. Only a `betterstackdata.com` address over https is taken.
Source	Your source's name, like `t123456_my_app`: lower-case letters, digits and `_`. Its recent logs and its older ones are both searched.
Username and Password	The SQL connection's. The password is stored encrypted and never shown again. Better Stack's SQL connection can only read.
Field names	Optional. Where each part of an entry is in its JSON, with dots for nested fields. A key whose own name has the dots (`"kubernetes.pod_name": …`) is read first; otherwise the nested one. The defaults fit Better Stack's Kubernetes integration: `message`, `level`, `kubernetes.namespace_name`, `kubernetes.pod_name`, `kubernetes.container_name`, `service` and `host`.
How your logs are labelled	Notes that help the agent write good searches.

Connect ClickHouse or ClickStack#

1
In ClickHouse, make a login that can only read the logs table. For example: CREATE USER cerberius IDENTIFIED BY '…' SETTINGS readonly = 1 and GRANT SELECT ON default.otel_logs TO cerberius.
2
Go to Settings › Live system. Click Connect a cluster or logs (or Connect another), and choose ClickHouse.
3
Enter its address: its HTTP address, for example https://abc123.eu-west-1.aws.clickhouse.cloud:8443. A server of your own often answers on port 8123.
4
Choose the Login, and enter the Username and the Password.
5
If your logs aren't in ClickStack's default.otel_logs, enter the Table, and its columns under Your table has other column names?
6
Click Save, then Check connection.

Field	What it does
ClickHouse address	Its base address. It must be reachable from the internet, unless your organisation may use internal addresses.
Login	Username and password, or None for a server with no password.
Table	Where the logs are, as `database.table`. Empty: ClickStack's `default.otel_logs`.
Column names	Optional. Which column holds the time, message, level, namespace, pod, container, service and host. A column, or one key of a map column, like `ResourceAttributes['k8s.pod.name']`. Leave one empty when the table has none; the time and the message must be named. The defaults fit ClickStack's OpenTelemetry table.
How your logs are labelled	Notes that help the agent write good searches.

Table and column names can hold only letters, digits, _ and . (and, inside a map key's quotes, also -, / and :). Anything else is refused when you save.

Namespaces#

If the platform lists namespaces (on the Kubernetes card of the same page), every search is also limited to them:

Better Stack: your source is already this platform's own, so only an entry that names another namespace is left out. Entries with no namespace stay.
ClickHouse: one table may hold other platforms' logs, so only entries of these namespaces are read. An entry that names no namespace is left out. So the table needs a namespace column: saving one with none is refused, and if namespaces are listed later, Check connection and every search say which column to name, instead of finding nothing.

What it can and can't do#

Every search is one SELECT that Cerberius Agents writes, from your source or your table only. The agent's words and your namespaces are sent as hex the query itself decodes, so no word can change the query.

Better Stack: its SQL connection only reads. Searches go only to the address you saved.
ClickHouse: every search is sent with readonly=1, so ClickHouse refuses any write, any change of a setting, and any table function that reads elsewhere. A login whose own settings are fixed refuses to have readonly set again: then it is asked with a GET, which ClickHouse always runs read-only.

Check connection counts this platform's entries of the last day (only its namespaces, as its searches read them) and finds the newest one, in one query. On Better Stack it reads only the recent store. On ClickHouse it also makes sure every column you named is there, without reading any row, and says which one ClickHouse didn't know.

An error is what the entry's level says. Words like "error" or "exception" count only when an entry has no level. Better Stack allows only a few searches at once, so there the log watcher makes one search each time it looks, and takes each error as it was logged.

With your own runner

When the agent runs on your own runner, the password is kept by you. Save the settings first. Then choose how it is kept: Scrambled for your runner or In your store. It needs runner 0.17.0 or later.

How the agent searches#

During an investigation, the agent searches with plain words or "quoted phrases". An entry must have all of them, in any case. On Better Stack the words can be anywhere in the entry; on ClickHouse, in its message. To keep to one source, it adds pod="api-1" (or namespace, container, service_name, host): these are matched with your fields or columns, not as words. A ticket from the log watcher suggests a search written that way. It picks the time range, up to the last 7 days, and up to 1,000 entries at a time. Every search shows in the agent's steps on the reply page.

Change or remove it#

Change any field and click Save. Another address removes the saved password when you save: enter it again. To stop using it, click Disconnect under it: its settings and password are removed from this platform.