> ## Documentation Index
> Fetch the complete documentation index at: https://docs.civic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Better Stack

> Uptime monitoring, incident management, on-call scheduling, log querying, metrics, dashboards, and error tracking

## Overview

Better Stack comprises two MCP servers: **Uptime** (monitoring, incidents, on-call, status pages) and **Telemetry** (logs, metrics, dashboards, error tracking). Both share the same team/org context but require separate auth tokens.

## How to Add Better Stack

<Steps>
  <Step title="Add to Civic">
    Add the Better Stack Uptime and/or Better Stack Telemetry servers to your Civic environment through the server directory. These are two separate servers — add whichever you need (or both).
  </Step>

  <Step title="Authorize">
    On first use, you will be redirected to [Better Stack](https://betterstack.com) to authorize the connection. No API keys or secrets to manage manually.

    <Info>
      **Two separate authorizations** — Uptime and Telemetry are independent products. You will need to authorize each one separately the first time you use it.
    </Info>
  </Step>

  <Step title="Test Connection">
    * For **Uptime**: try `"List all monitors"` or `"Who is currently on-call?"`
    * For **Telemetry**: try `"List all log sources"` or `"List all dashboards"`
  </Step>
</Steps>

## What You Can Do

<CardGroup cols={2}>
  <Card title="Uptime Monitoring" icon="heart-pulse">
    Manage monitors, view response times and availability, track incidents and heartbeats
  </Card>

  <Card title="Incident Management" icon="triangle-exclamation">
    List, acknowledge, resolve, escalate, and comment on incidents with full timeline access
  </Card>

  <Card title="On-Call & Escalation" icon="phone">
    View on-call schedules, escalation policies, and severity notification channels
  </Card>

  <Card title="Status Pages" icon="signal">
    List status pages, manage resources, create incident reports, and post status updates
  </Card>

  <Card title="Log Querying" icon="magnifying-glass">
    Query logs via ClickHouse, explore sources, extract JSON fields, and group by patterns
  </Card>

  <Card title="Metrics & Dashboards" icon="chart-line">
    List metrics, check cardinality, build queries, create and arrange dashboard charts
  </Card>

  <Card title="Error Tracking" icon="bug">
    List applications, query errors, resolve or ignore error patterns, and view session replays
  </Card>

  <Card title="Heartbeat Monitoring" icon="clock">
    Monitor cron jobs and scheduled tasks — incidents trigger automatically on missed pings
  </Card>
</CardGroup>

## Use Cases

### Uptime & Incidents

* **Monitor Health**: `"Show current status of all monitors"`
* **Availability Reports**: `"Get availability for the API monitor for March 2026"`
* **Incident Triage**: `"List all open incidents"` → `"Acknowledge incident 1234"` → `"Resolve incident 1234"`
* **Incident Timeline**: `"Show the timeline for incident 1234"`
* **On-Call Check**: `"Who is currently on-call?"`
* **Status Page Updates**: `"Create an incident report: title 'API Degradation', message 'Investigating elevated error rates'"`

### Telemetry & Logs

* **Log Search**: `"Show the last 50 error logs from my-app"`
* **Error Patterns**: `"Find the most common error patterns in the last 24 hours"`
* **Slow Requests**: `"Show slow API requests over 1 second from today"`
* **Metrics Exploration**: `"List available metrics for source 12345"`
* **Dashboard Management**: `"List all dashboards"` → `"Add a line chart showing log volume per hour"`
* **Error Tracking**: `"List recent unresolved errors"` → `"Resolve error pattern NullPointerException in UserService"`

***

## Available Tools

### Uptime — Monitors & Heartbeats

<AccordionGroup>
  <Accordion title="list_monitors">
    `list_monitors` — List all monitors and their current status
  </Accordion>

  <Accordion title="get_monitor_response_times">
    `get_monitor_response_times` — Get response times broken down by region and phase (DNS, connect, TLS, transfer). Returns \~24h of data in 15-min buckets.
  </Accordion>

  <Accordion title="get_monitor_availability">
    `get_monitor_availability` — Get availability percentage for a monitor over a date range
  </Accordion>

  <Accordion title="list_heartbeats">
    `list_heartbeats` — List all heartbeat monitors for cron jobs and scheduled tasks
  </Accordion>

  <Accordion title="get_heartbeat_availability">
    `get_heartbeat_availability` — Get availability for a heartbeat over a date range
  </Accordion>
</AccordionGroup>

### Uptime — Incidents

<AccordionGroup>
  <Accordion title="list_incidents">
    `list_incidents` — List incidents with filtering by status, monitor, heartbeat, and date range
  </Accordion>

  <Accordion title="acknowledge_incident">
    `acknowledge_incident` — Acknowledge an open incident
  </Accordion>

  <Accordion title="resolve_incident">
    `resolve_incident` — Resolve an incident
  </Accordion>

  <Accordion title="reopen_incident">
    `reopen_incident` — Reopen a resolved incident (within 24 hours of resolution only)
  </Accordion>

  <Accordion title="escalate_incident">
    `escalate_incident` — Escalate to a user, team, schedule, or policy. Call `get_incident_escalation_options` first to discover valid targets.
  </Accordion>

  <Accordion title="add_incident_comment">
    `add_incident_comment` — Add a comment to an incident timeline
  </Accordion>

  <Accordion title="get_incident_timeline">
    `get_incident_timeline` — Full audit trail of state changes, notifications, and acknowledgements
  </Accordion>

  <Accordion title="get_incident_escalation_options">
    `get_incident_escalation_options` — Discover valid escalation targets (User, Team, Schedule, Policy)
  </Accordion>
</AccordionGroup>

### Uptime — On-Call & Status Pages

<AccordionGroup>
  <Accordion title="list_on_call_calendars">
    `list_on_call_calendars` — List on-call rotations and events
  </Accordion>

  <Accordion title="list_escalation_policies">
    `list_escalation_policies` — List all escalation policies
  </Accordion>

  <Accordion title="list_status_pages">
    `list_status_pages` — List all status pages and their resources
  </Accordion>

  <Accordion title="get_status_page_resources">
    `get_status_page_resources` — Show monitors and resources on a status page
  </Accordion>

  <Accordion title="create_incident_report">
    `create_incident_report` — Create a public incident report with affected resources
  </Accordion>

  <Accordion title="post_status_update">
    `post_status_update` — Post a status update to an incident report with optional subscriber notification
  </Accordion>
</AccordionGroup>

### Telemetry — Sources & Logs

<AccordionGroup>
  <Accordion title="list_sources">
    `list_sources` — List all log sources
  </Accordion>

  <Accordion title="get_source_details">
    `get_source_details` — Get ingestion token, host URL, table name, and retention settings for a source
  </Accordion>

  <Accordion title="get_source_fields">
    `get_source_fields` — Get available fields for a source (returns nothing if source has no recent data)
  </Accordion>

  <Accordion title="telemetry_build_explore_query_tool">
    `telemetry_build_explore_query_tool` — Generate a ClickHouse query from plain English
  </Accordion>

  <Accordion title="telemetry_query">
    `telemetry_query` — Execute a direct ClickHouse query (requires cloud connection credentials)
  </Accordion>

  <Accordion title="create_source">
    `create_source` — Create a new log source with a specified platform type
  </Accordion>
</AccordionGroup>

### Telemetry — Metrics & Dashboards

<AccordionGroup>
  <Accordion title="list_metrics">
    `list_metrics` — List available metrics for a source
  </Accordion>

  <Accordion title="get_metrics_and_cardinality">
    `get_metrics_and_cardinality` — Show cardinality for all metrics
  </Accordion>

  <Accordion title="get_metric_query_instructions">
    `get_metric_query_instructions` — Get correct aggregation functions and example queries for a metric
  </Accordion>

  <Accordion title="list_dashboards">
    `list_dashboards` — List all dashboards
  </Accordion>

  <Accordion title="get_dashboard_layout">
    `get_dashboard_layout` — Show the layout and charts of a dashboard
  </Accordion>

  <Accordion title="add_chart">
    `add_chart` — Add a chart to a dashboard
  </Accordion>

  <Accordion title="edit_chart">
    `edit_chart` — Edit an existing chart
  </Accordion>

  <Accordion title="move_charts">
    `move_charts` — Rearrange chart positions on a dashboard (validates layout atomically)
  </Accordion>

  <Accordion title="export_dashboard">
    `export_dashboard` — Export a dashboard as JSON
  </Accordion>

  <Accordion title="import_dashboard">
    `import_dashboard` — Import a dashboard from JSON
  </Accordion>

  <Accordion title="get_chart_building_instructions">
    `get_chart_building_instructions` — Documentation for supported chart types, units, axes, and layout rules
  </Accordion>

  <Accordion title="telemetry_chart">
    `telemetry_chart` — Preview chart queries with automatic error surfacing
  </Accordion>
</AccordionGroup>

### Telemetry — Error Tracking

<AccordionGroup>
  <Accordion title="list_applications">
    `list_applications` — List all error-tracking applications
  </Accordion>

  <Accordion title="create_application">
    `create_application` — Create a new error-tracking application with a platform type (e.g. `javascript_errors`, `python_errors`)
  </Accordion>

  <Accordion title="get_errors_query_instructions">
    `get_errors_query_instructions` — Get the query schema for error tracking (different from logs)
  </Accordion>

  <Accordion title="update_error_state">
    `update_error_state` — Set error state to `resolved`, `ignored`, or `unresolved`. When ignoring, `ignore_next_count` must be 10, 100, or 1000.
  </Accordion>

  <Accordion title="create_cloud_connection">
    `create_cloud_connection` — Create direct ClickHouse credentials for raw SQL queries. Connections expire after 1 hour.
  </Accordion>
</AccordionGroup>

***

<Note>
  **Two separate auth tokens** — Uptime and Telemetry are independent products, each requiring separate authorization.

  **Team ID required** for most create/list operations. Use `list_teams` to find it.

  **Log query tips:**

  * Use `remote(<table_name>)` for recent data (\<30 min); use `s3Cluster(primary, <table_name_s3>)` with `_row_type = 1` for historical.
  * All log fields live inside the `raw` JSON column. Extract with `JSONExtract(raw, 'field', 'Nullable(String)')`.
  * Group noisy logs by `_pattern` to surface recurring message structures.

  **Dashboard grid** is 12 columns wide. Use `{{source}}`, `{{start_time}}`, `{{end_time}}`, and `{{time}}` variables in dashboard queries.

  **No cross-tool linking** — Uptime incidents and Telemetry logs are not automatically correlated.
</Note>

***

## Guardrails

This server is covered by the [14 universal guardrails](/civic/concepts/guardrails). Server-specific guardrails are coming soon.

<Tip>
  Configure guardrails via the Civic UI or ask the Configurator Agent: "Add guardrails to my Better Stack server."
</Tip>