Better Stack

Overview

Better Stack (formerly Logtail) is a modern log management platform. With Sazabi's Better Stack backend, you can query your Better Stack logs directly from Chat without duplicating data.

When configured, Sazabi creates on-demand ClickHouse connections to your Better Stack account, allowing Chat to run SQL queries against your log data in real-time.

What you can query

When Better Stack is configured as a backend, Chat can access:

Logs: Search and analyze logs stored in Better Stack
Sources: Query logs from specific sources within your team
Time-series data: Aggregate logs over time intervals for analysis

Prerequisites

Before you begin, make sure you have:

A Better Stack account with at least one configured log source
A Better Stack API token with read permissions
Your Better Stack team ID

Setup

Generate a Better Stack API token

Create an API token in your Better Stack account:

Go to Better Stack Settings
Navigate to API Tokens
Click Create API Token
Give it a descriptive name like "Sazabi Integration"
Copy the token and store it securely

The API token needs read access to list sources and create query connections. Better Stack API tokens are scoped to your account and can access all teams you belong to.

Find your team ID

Locate your Better Stack team ID:

Go to Better Stack Settings
Look for Team ID in the team settings page
Copy the numeric team ID (for example, 123456)

The team ID scopes queries to logs from sources belonging to that team.

Backends Settings

Select Better Stack from the list of available backends.

Enter credentials

Fill in the required fields:

API Token: Your Better Stack API token from step 1
Team ID: Your numeric team ID from step 2
Data Region (optional): Select the region where your data is stored (US East, US West, Germany, or Singapore)

Test and save

Click Test Connection to verify your credentials. Sazabi will:

Validate your API token against the Better Stack API
Verify that the team ID has accessible log sources
Confirm the connection can be established

If the test succeeds, click Save to complete the setup.

Required permissions

The Better Stack API token requires the following access:

Permission	Purpose
Read sources	List available log sources for the team
Create connections	Generate on-demand ClickHouse query connections

Better Stack API tokens inherit your account permissions. If you can view logs in the Better Stack dashboard, your token can query them through Sazabi.

How connections work

Unlike other backends that use persistent credentials, Better Stack uses ephemeral ClickHouse connections:

When you ask Chat a question, Sazabi creates a short-lived connection to Better Stack's ClickHouse endpoint
The connection is scoped to your team and expires after one hour
Sazabi automatically cleans up connections after use

This approach keeps your credentials secure while enabling real-time queries.

Source selection

When you connect Better Stack, Sazabi automatically discovers all log sources associated with your team. Chat queries across all sources using Better Stack's remote() table function.

Each source maps to a table named t{team_id}_{source_name}_logs. The assistant handles this mapping automatically based on your configured team ID.

Query capabilities

Chat can run SQL queries against your Better Stack logs with the following capabilities:

Supported fields

Field	Description
`body`	Log message content
`severity_text`	Log level (INFO, WARN, ERROR, etc.)
`service_name`	Service that generated the log
`timestamp`	When the log was recorded

Supported operations

Filtering: By severity, service, time range, or message content
Searching: Case-insensitive text search in log messages
Aggregation: Count, group by, and time-series queries
Sorting: Order by timestamp (ascending or descending)

Time-series intervals

When querying time-series data, the following intervals are supported:

Interval	Maximum multiplier
Minutes	59
Hours	23
Days	28

For example, 5 MINUTE, 12 HOUR, or 7 DAY are valid intervals.

Limitations

Read-only: Only SELECT queries are supported
No environment dimension: Better Stack does not store an environment field, so filtering by environment is not available
Single team: Each backend configuration is scoped to one team
Connection lifecycle: Connections expire after one hour and are recreated as needed

Troubleshooting

Invalid API token

If the connection test fails with an authentication error, verify your API token is correct and has not expired. Generate a new token in Better Stack settings if needed.

No sources found for team

This error means the team ID is valid but has no log sources configured. Check that you have created at least one source in Better Stack and that it belongs to the specified team.

Team ID must be a number

The team ID should be a numeric value (for example, 123456), not a slug or name. Find the numeric ID in your Better Stack team settings.

Connection timeout

Better Stack connections are ephemeral and may time out after one hour. If queries fail after extended idle time, Sazabi will automatically create a new connection on the next request.

Query returns no results

Verify that logs exist within your query time range. Better Stack queries default to the last 7 days if no time range is specified. Also confirm the source contains data matching your filter criteria.

Data Sources - Forward logs from other platforms to Sazabi
MCP Connectors - Connect additional tools to Chat