Better Stack Logging

Overview

Better Stack Logs (formerly Logtail) provides centralized log management with structured log ingestion, real-time search, and log-based alerting. MSPs use it to aggregate logs from client infrastructure, investigate incidents, and set up proactive alerting on error patterns.

Anti-triggers

• Azure Log Analytics and KQL — different store, different query language; use azure-mcp-observability.
• Threat hunting or security event analysis — these are application logs, not a SIEM; use huntress-signals or blumira.
• Uptime history for a monitor — check results are not log records; use betterstack-monitors.

Key Concepts

Log Sources

Sources define where logs come from and how they're ingested:

• Platform sources - AWS, Azure, GCP, Heroku, Vercel, etc.
• Language sources - Node.js, Python, Ruby, Go, etc.
• Infrastructure sources - Docker, Kubernetes, syslog, HTTP
• Each source gets a unique source token for authentication

Log Structure

Logs in Better Stack are structured JSON documents:

• dt - Timestamp (ISO 8601)
• level - Log level (info, warn, error, debug, fatal)
• message - Log message text
• Any additional custom fields (request_id, user_id, service, etc.)

Query Language

Better Stack supports SQL-like queries for log searching:

• Field-based filters: level:error, service:api
• Text search: "connection refused"
• Time ranges: dt:[2026-03-27T00:00:00Z TO 2026-03-27T23:59:59Z]
• Boolean operators: AND, OR, NOT
• Wildcards: host:prod-*

Log-Based Alerts

Create alerts that trigger when log patterns match:

• Error rate thresholds (e.g., more than 10 errors in 5 minutes)
• Specific error message patterns
• Absence of expected log entries (heartbeat-style)

API Patterns

Query Logs

betterstack_query_logs

Parameters:

• query - Search query string (required)
• source_id - Filter to a specific source
• from - Start time (ISO 8601)
• to - End time (ISO 8601)
• batch_size - Number of results to return (default 100)
• order - Sort order: newest_first or oldest_first

Example response:

{
  "data": [
    {
      "dt": "2026-03-27T10:15:30.123Z",
      "level": "error",
      "message": "Connection refused to database at 10.0.1.5:5432",
      "service": "api-gateway",
      "host": "prod-api-01",
      "request_id": "req-abc-123"
    },
    {
      "dt": "2026-03-27T10:15:29.456Z",
      "level": "error",
      "message": "Health check failed for postgres pool",
      "service": "api-gateway",
      "host": "prod-api-01"
    }
  ]
}

List Log Sources

betterstack_list_sources

Parameters:

• page - Pagination cursor

Example response:

{
  "data": [
    {
      "id": "src-789",
      "type": "source",
      "attributes": {
        "name": "Production API",
        "platform": "node",
        "token": "xxxx...xxxx",
        "ingesting_paused": false,
        "records_count": 1500000
      }
    }
  ]
}

Create Log Source

betterstack_create_source

Parameters:

• name - Source name (required)
• platform - Platform type: node, python, ruby, go, docker, kubernetes, syslog, http, etc.

Common Workflows

Incident Log Investigation

1. Get the incident details and identify the affected monitor/service
2. Call betterstack_query_logs with the service name and time range around the incident
3. Filter for error and fatal level logs
4. Look for patterns: connection errors, timeout spikes, OOM events
5. Trace request IDs across services for distributed issues
6. Summarize findings with root cause analysis

Error Rate Monitoring

1. Query logs for level:error over the last hour
2. Group by service to identify which services have elevated errors
3. Compare error counts against baseline
4. Drill into the highest-error services for specific error messages
5. Correlate with uptime monitor incidents

Setting Up Logging for a New Client

1. Create log sources for each client service (API, web, workers)
2. Distribute source tokens for log ingestion configuration
3. Verify logs are flowing with a test query
4. Set up log-based alerts for critical error patterns
5. Create saved queries for common investigation patterns

Security Log Review

1. Search for authentication failures: "authentication failed" OR "invalid token" OR "unauthorized"
2. Look for unusual access patterns: level:warn AND "rate limit"
3. Check for privilege escalation attempts
4. Review admin action logs
5. Document findings for compliance reporting

Error Handling

Source Not Found

Cause: Invalid source ID or source was deleted Solution: List sources to verify the correct ID

Query Syntax Error

Cause: Invalid query syntax Solution: Verify query follows the supported syntax (field:value, boolean operators, quotes for phrases)

No Results

Cause: No logs match the query for the given time range Solution: Broaden the time range, check source ID, verify logs are being ingested

Best Practices

• Use structured logging with consistent field names across services
• Include request IDs for distributed tracing across services
• Query with specific time ranges to improve performance
• Use source filters to scope queries to relevant services
• Create saved queries for common investigation patterns
• Set up log-based alerts for critical error patterns
• Use log levels consistently: error for failures, warn for degradation, info for operations
• Include contextual fields (user_id, tenant_id, request_id) for efficient filtering

Related Skills

• api-patterns - Pagination and error handling
• monitors - Monitors correlated with log data
• incidents - Incident investigation with logs
• status-pages - Status context from log analysis