### Manual Installation of Development Tools (just, sqlc)

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

This code shows how to install the `just` command runner and the `sqlc` SQL code generator manually. `just` can be installed via Cargo or Go, while `sqlc` is installed using `go install`.

```bash
# just - command runner
# Option 1: Using Cargo
cargo install just
# OR
# Option 2: Using Go
go install github.com/casey/just@latest

# sqlc - SQL code generator
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest
```

--------------------------------

### Install Logchef with Docker

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/getting-started/quickstart.mdx

This snippet shows how to download the Docker Compose file and start the Logchef services using Docker. It assumes Docker is installed and configured.

```bash
# Download the compose file
curl -LO https://raw.githubusercontent.com/mr-karan/logchef/refs/heads/main/deployment/docker/docker-compose.yml

# Start the services
docker compose up -d
```

--------------------------------

### Manual Go Installation (1.24+)

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

This snippet demonstrates how to manually install Go version 1.24 or later on a Linux system by downloading the archive, extracting it to `/usr/local`, and updating the PATH environment variable.

```bash
wget https://go.dev/dl/go1.24.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin
```

--------------------------------

### Install Logchef with Pre-built Binaries

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/getting-started/quickstart.mdx

This snippet demonstrates downloading pre-built binaries for Logchef, extracting them, making the binary executable, and setting up a basic configuration file. It's suitable for production deployments or environments without Docker.

```bash
# Download the latest release for your platform (example for Linux amd64)
# Check latest version at https://github.com/mr-karan/logchef/releases
curl -L -O https://github.com/mr-karan/logchef/releases/download/v0.2.1/logchef_0.2.1_linux_amd64.tar.gz

# Extract the archive
tar xzf logchef_0.2.1_linux_amd64.tar.gz

# Make the binary executable
chmod +x logchef

# Create a basic configuration file
curl -L -O https://github.com/mr-karan/logchef/raw/main/config.toml

# Edit the config file to match your environment
# You'll need to update the OIDC settings and database path

# Run Logchef with your config
./logchef -config config.toml
```

--------------------------------

### Logchef Query Examples

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/getting-started/quickstart.mdx

These examples demonstrate basic Logchef query syntax for filtering logs. They show how to search by namespace, severity, and specific text within the log body. These queries are executed within the Logchef Explore page.

```logql
namespace="syslog"
```

```logql
namespace="syslog" and severity_text!="INFO"
```

```logql
namespace="syslog" and body="error"
```

--------------------------------

### Development Setup for LogChef

Source: https://github.com/mr-karan/logchef/blob/main/README.md

This snippet outlines the development setup process for contributing to LogChef. It includes commands for entering the development environment, generating SQL code, starting a development Docker instance, building the project, and running checks.

```bash
nix develop
just sqlc-generate
just dev-docker
just build
just check
```

--------------------------------

### Start LogChef Development Infrastructure

Source: https://github.com/mr-karan/logchef/blob/main/dev/README.md

Initiates the core infrastructure services for LogChef development, including ClickHouse, Dex, and Alertmanager, using the 'just' task runner. This is typically the first step in the local setup process.

```bash
just dev-docker
```

--------------------------------

### Node.js and pnpm Installation via nvm

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

This sequence installs Node.js version 22 and pnpm using nvm (Node Version Manager). It first installs nvm, then installs and uses Node.js 22, and finally installs pnpm globally using npm.

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

npm install -g pnpm
```

--------------------------------

### Troubleshoot SQLC Generation Failures

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

This section provides guidance on troubleshooting SQLC generation issues. It suggests verifying the `sqlc` installation and version, and ensuring the Nix development shell is active if Nix is being used.

```bash
# Verify sqlc installation:
sqlc version

# If using Nix, ensure you are in the dev shell:
nix develop
```

--------------------------------

### Start Development Services with Just

Source: https://github.com/mr-karan/logchef/blob/main/dev/alertmanager/README.md

Launches necessary services like ClickHouse, Dex, Alertmanager, and a Webhook Receiver using the 'just dev-docker' command. This is a bash script command.

```bash
just dev-docker

```

--------------------------------

### Set Up Development Environment with Nix

Source: https://github.com/mr-karan/logchef/blob/main/CONTRIBUTING.md

Clones the LogChef repository and enters the Nix development environment. This is the recommended way to get started, ensuring all dependencies are correctly managed.

```bash
git clone https://github.com/mr-karan/logchef.git
cd logchef
nix develop
```

--------------------------------

### Build Logchef from Source

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/getting-started/quickstart.mdx

This snippet outlines the steps to build Logchef from its source code. It involves cloning the repository, building the frontend and backend, and running the application with the default configuration. This method requires Git and the 'just' build tool.

```bash
# Clone the repository
git clone https://github.com/mr-karan/logchef.git
cd logchef

# Build the frontend and backend
just build

# Run with the default config
just run
```

--------------------------------

### Build and Analyze Bundle Size (Bash)

Source: https://github.com/mr-karan/logchef/blob/main/frontend/OPTIMIZE.md

Commands to build the project with bundle analyzer visualization and then run the analyzer script to get optimization recommendations. The first command generates a `stats.html` file for visual inspection.

```bash
pnpm build:analyze
pnpm analyze
```

--------------------------------

### Alertmanager Configuration Example

Source: https://github.com/mr-karan/logchef/blob/main/dev/alertmanager/README.md

An example of Alertmanager's configuration file (`alertmanager.yml`) detailing receiver settings, routing rules, and notification timings. This is a YAML configuration.

```yaml
receivers:
  - name: 'webhook-receiver'
    webhook_configs:
      - url: 'http://webhook-receiver:8080/webhook'
    email_configs:
      - to: 'alerts@example.com'
        from: 'alertmanager@example.com'
        smarthost: 'smtp.example.com:587'
        auth_username: 'alerts@example.com'
        auth_password: 'your-password'

```

--------------------------------

### Frontend Development Commands

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

These commands are used for frontend development within the LogChef project. They include starting a development server with hot reloading, performing type checking, and building the application for production.

```bash
cd frontend/

# Development server with hot reload
pnpm dev

# Type checking
pnpm typecheck

# Build for production
pnpm build
```

--------------------------------

### Docker Development and Deployment

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

Commands for building the LogChef Docker image and running the application using Docker Compose for deployment scenarios. This allows for containerized development and testing.

```bash
# Build Docker image
just build-docker

# Run with Docker Compose
docker compose -f deployment/docker/docker-compose.yml up
```

--------------------------------

### Docker Compose for LogChef Quick Start

Source: https://github.com/mr-karan/logchef/blob/main/README.md

This snippet demonstrates how to quickly set up and run LogChef using Docker Compose. It involves downloading a Docker Compose file and starting the services, providing immediate access to the Logchef interface.

```shell
curl -LO https://raw.githubusercontent.com/mr-karan/logchef/refs/heads/main/deployment/docker/docker-compose.yml
docker compose up -d
```

--------------------------------

### LogChef Quick Start Commands

Source: https://github.com/mr-karan/logchef/blob/main/CONTRIBUTING.md

A set of commands to quickly set up and run the LogChef application in a development environment. This includes generating database code, starting infrastructure, building, and running the application.

```bash
# Generate database code
just sqlc-generate

# Start development infrastructure (ClickHouse, Dex OIDC)
just dev-docker

# Build the application
just build

# Run with development config
just CONFIG=dev/config.toml run
```

--------------------------------

### Run LogChef Application

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

This command runs the LogChef application using the development configuration file. It can be run directly or by starting the backend and frontend separately in different terminals.

```bash
# Run with development config
just CONFIG=dev/config.toml run

# Or run backend/frontend separately
just run-backend
just run-frontend  # In another terminal
```

--------------------------------

### PromQL Example: ClickHouse Health Monitoring

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/operations/metrics.mdx

This example demonstrates how to monitor ClickHouse health using PromQL by identifying sources with connection issues and calculating the connection failure rate. It relies on metrics like `logchef_clickhouse_connection_status` and `logchef_clickhouse_connection_validation_total`.

```promql
# Sources with connection issues
logchef_clickhouse_connection_status == 0

# Connection failure rate
rate(logchef_clickhouse_connection_validation_total{result="failure"}[5m])
```

--------------------------------

### Build LogChef Application

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

These commands use the `just` task runner to build the LogChef application. You can build both the backend and frontend together or separately.

```bash
# Build backend + frontend
just build

# Or build separately
just build-backend
just build-frontend
```

--------------------------------

### PromQL Example: Track User Activity

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/operations/metrics.mdx

This example shows how to track user activity by identifying the most active users based on query volume and monitoring the authentication failure rate per user. It uses metrics like `logchef_query_total` and `logchef_auth_attempts_total`.

```promql
# Most active users by query volume
topk(10, sum by (user_email) (rate(logchef_query_total[1h])))

# Authentication failure rate by user
rate(logchef_auth_attempts_total{result="failure"}[5m]) by (user_email)
```

--------------------------------

### Check Port Usage for Troubleshooting

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

These commands help identify which processes are using specific ports, which is useful for troubleshooting 'port already in use' errors. Examples are provided for the LogChef backend (8125) and ClickHouse (9000, 8123).

```bash
# Check backend port (8125)
lsof -i :8125

# Check ClickHouse ports (9000, 8123)
lsof -i :9000
lsof -i :8123
```

--------------------------------

### LogChef Environment Variable Configuration Examples (Bash)

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/getting-started/configuration.md

Illustrates how to override or set LogChef configuration options using environment variables. This is particularly useful for sensitive data and containerized deployments, following the LOGCHEF_SECTION__KEY format.

```bash
export LOGCHEF_SERVER__PORT=8125
export LOGCHEF_OIDC__PROVIDER_URL="http://dex.example.com/dex"
export LOGCHEF_AUTH__ADMIN_EMAILS="admin@example.com,ops@example.com"
export LOGCHEF_AI__API_KEY="sk-your_actual_api_key_here"
export LOGCHEF_AI__ENABLED=true
export LOGCHEF_AI__MODEL="gpt-4o"

```

--------------------------------

### Basic Logchef Query Examples

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/tutorials/nginx-logs.mdx

A collection of example Logchef queries for analyzing NGINX access logs. These examples cover filtering by status codes, request time, response size, request URI, IP address, and date ranges. They assume a standard NGINX log schema is ingested into ClickHouse.

```sql
# Find all server errors
status >= 500

# Find slow requests (taking more than 1 second)
request_time > 1.0

# Find large responses
bytes_sent > 1000000

# Find specific API endpoints
request_uri:"/api/users"

# Combine multiple conditions
status=404 AND remote_addr="192.168.0.1"

# Time-based queries
timestamp > '2025-04-20 00:00:00' AND timestamp < '2025-04-25 23:59:59'
```

--------------------------------

### Run LogChef Backend Service

Source: https://github.com/mr-karan/logchef/blob/main/dev/README.md

Starts the LogChef backend application in a separate terminal. This command is essential for the application's core logic and API operations to function during development.

```bash
just run-backend
```

--------------------------------

### Natural Language to SQL Query Example

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/features/ai-sql-generation.mdx

Illustrates how a natural language query can be translated into a ClickHouse SQL query by the LogChef AI assistant. This example shows a request for error logs within a specific time frame.

```sql
SELECT *
FROM logs_table
WHERE severity_text = 'ERROR'
  AND timestamp >= now() - INTERVAL 6 HOUR
ORDER BY timestamp DESC
LIMIT 100
```

--------------------------------

### Lazy Load Vue Components (JavaScript)

Source: https://github.com/mr-karan/logchef/blob/main/frontend/OPTIMIZE.md

Example demonstrating how to lazily load Vue components using dynamic imports instead of direct imports. This improves initial load times by only loading components when they are actually needed by the user.

```javascript
// Instead of
// import HeavyComponent from "@/components/HeavyComponent.vue";

// Use
const HeavyComponent = () => import("@/components/HeavyComponent.vue");
```

--------------------------------

### Alertmanager Authentication Example

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/features/alerting.mdx

This example demonstrates how to configure Alertmanager authentication using HTTP Basic Auth within the URL. It shows the format for including username and password.

```text
# Basic authentication
https://admin:secretpass@alertmanager.internal:9093

```

--------------------------------

### Frontend Development Commands

Source: https://github.com/mr-karan/logchef/blob/main/CONTRIBUTING.md

Commands for navigating to the frontend directory and running development tasks such as starting the development server, performing type checking, and building the application.

```bash
cd frontend/

# Development server
pnpm dev

# Type checking
pnpm typecheck

# Build
pnpm build
```

--------------------------------

### Identify Disk Space Warnings

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/guide/examples.md

Alerts administrators to potential storage issues by finding 'system_metrics' logs where the free disk space percentage is below 15%.

```LogchefQL
type="system_metrics" and disk_free_percent<15
```

```sql
SELECT *
FROM logs.app
WHERE type = 'system_metrics'
  AND disk_free_percent < 15
ORDER BY timestamp DESC
LIMIT 100
```

--------------------------------

### Select Specific Columns from Logs

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/guide/examples.md

Demonstrates how to select specific fields from log entries, similar to SQL's SELECT statement. This is useful for reducing data volume and focusing on relevant information. The example filters for 'error' level logs.

```LogchefQL
level="error" | timestamp service level message
```

```sql
SELECT timestamp, service, level, message
FROM logs.app
WHERE level = 'error'
ORDER BY timestamp DESC
LIMIT 100
```

--------------------------------

### Run LogChef Frontend Service

Source: https://github.com/mr-karan/logchef/blob/main/dev/README.md

Launches the LogChef frontend user interface in a new terminal. This command is necessary to interact with the LogChef application through its web interface.

```bash
just run-frontend
```

--------------------------------

### Test Webhook Functionality

Source: https://github.com/mr-karan/logchef/blob/main/dev/README.md

Executes a test to confirm that the webhook receiver is operational and can accept incoming requests. This command is part of the alert testing workflow.

```bash
just dev-test-webhook
```

--------------------------------

### Configure Direnv for Automatic Nix Environment

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

These commands configure direnv to automatically activate the Nix development environment when entering the LogChef project directory. This involves installing direnv, hooking it into the shell, and creating a `.envrc` file.

```bash
# For NixOS:
environment.systemPackages = [ pkgs.direnv ];

# For other systems:
nix-env -i direnv

# Hook direnv into your shell (e.g., ~/.bashrc or ~/.zshrc):
eval "$(direnv hook bash)"  # or zsh

# Create .envrc in the project root:
echo "use flake" > .envrc
direnv allow
```

--------------------------------

### Set Up First Alert using LogChefQL

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/features/alerting.mdx

This workflow demonstrates how to set up your first alert using LogChefQL, the recommended query language. It covers defining the alert name, filter conditions, aggregation, lookback period, threshold, frequency, and severity.

```LogChefQL
severity_text = "ERROR"
count(*)
5 minutes
Greater than 50
60 seconds
Warning
```

--------------------------------

### Set Up First Alert using SQL Mode

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/features/alerting.mdx

This workflow outlines the steps to set up an alert using direct SQL queries. It explains how to switch to SQL mode, write a SQL query to count errors within a specific time window, and configure threshold, frequency, and severity.

```SQL
SELECT count(*) as value FROM logs WHERE severity_text = 'ERROR' AND timestamp >= now() - toIntervalSecond(300)
```

--------------------------------

### Build LogChef MCP Server from Source

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/integration/mcp-server.mdx

Instructions for building the LogChef MCP server binary from its source code using Go. This requires having the Go toolchain installed and cloning the repository.

```bash
git clone https://github.com/mr-karan/logchef-mcp.git
cd logchef-mcp
go build -o logchef-mcp ./cmd/logchef-mcp
```

--------------------------------

### Generate SQLC Database Code

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

This command utilizes the `just` task runner to execute the `sqlc-generate` command, which is responsible for generating Go code from SQL query definitions.

```bash
just sqlc-generate
```

--------------------------------

### PromQL Example: Monitor Query Performance by Source

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/operations/metrics.mdx

This snippet demonstrates how to monitor query performance by calculating the average query duration and success rate per source using PromQL. It relies on metrics like `logchef_query_duration_seconds_sum`, `logchef_query_duration_seconds_count`, and `logchef_query_total`.

```promql
# Average query duration per source
rate(logchef_query_duration_seconds_sum[5m]) / rate(logchef_query_duration_seconds_count[5m])

# Query success rate by source
rate(logchef_query_total{result="success"}[5m]) / rate(logchef_query_total[5m])
```

--------------------------------

### Example Alert Payload Structure

Source: https://github.com/mr-karan/logchef/blob/main/dev/alertmanager/README.md

Demonstrates the JSON structure of an alert payload as received by a webhook endpoint, including status, alerts details, labels, annotations, and timestamps. This is a JSON object.

```json
{
  "receiver": "webhook-receiver",
  "status": "firing",
  "alerts": [
    {
      "status": "firing",
      "labels": {
        "alertname": "high_error_rate",
        "alert_id": "1",
        "severity": "critical",
        "team": "Production Team",
        "team_id": "1",
        "source": "Main API Logs",
        "source_id": "1",
        "status": "triggered"
      },
      "annotations": {
        "description": "High error rate detected",
        "query": "SELECT count(*) as value FROM logs WHERE severity_text = 'ERROR'",
        "threshold": "gt 10.0000",
        "value": "42.0000"
      },
      "startsAt": "2025-01-17T12:00:00Z",
      "generatorURL": "http://localhost:5173/logs/alerts/1?team=1&source=1"
    }
  ],
  "groupLabels": {
    "alertname": "high_error_rate",
    "severity": "critical",
    "team": "Production Team",
    "source": "Main API Logs"
  }
}

```

--------------------------------

### Open Alertmanager User Interface

Source: https://github.com/mr-karan/logchef/blob/main/dev/README.md

Launches the Alertmanager's web UI in the default browser. This allows users to view and manage alerts configured within the LogChef system.

```bash
just dev-alertmanager-ui
```

--------------------------------

### Troubleshoot Frontend Build Errors

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

Instructions for resolving frontend build errors by clearing the pnpm cache and reinstalling dependencies. This is a common step when encountering unexpected build issues.

```bash
cd frontend/
rm -rf node_modules .pnpm-store
pnpm install
```

--------------------------------

### LogChef Development Workflow Commands

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

A collection of common commands for the LogChef development workflow, managed by the `just` task runner. These include running checks, tests, formatting, linting, and code vetting.

```bash
# Run all checks (format, vet, lint, sqlc, tests)
just check

# Run tests with coverage
just test

# Run tests without coverage (faster)
just test-short

# Format code
just fmt

# Lint code
just lint

# Vet code
just vet
```

--------------------------------

### Ingest Sample Logs with Vector

Source: https://github.com/mr-karan/logchef/blob/main/dev/README.md

Uses the Vector tool to ingest sample logs into ClickHouse. Two configurations are provided: one for HTTP access logs and another for syslog format logs. This step is crucial for testing log processing capabilities.

```bash
cd dev && vector -c http.toml
```

```bash
cd dev && vector -c syslog.toml
```

--------------------------------

### Troubleshoot Docker Permission Issues

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/contributing/setup.md

This provides commands to resolve Docker permission issues by adding the current user to the `docker` group. This is often necessary for users to interact with the Docker daemon without `sudo`.

```bash
sudo usermod -aG docker $USER
newgrp docker
```

--------------------------------

### Alerting Example: Authentication Failures (YAML)

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/operations/metrics.mdx

This YAML configuration sets up an alert for high authentication failure rates. The alert fires if more than 5 authentication attempts fail per second for 1 minute, including severity and descriptive annotations.

```yaml
- alert: HighAuthFailureRate
  expr: rate(logchef_auth_attempts_total{result="failure"}[5m]) > 5
  for: 1m
  labels:
    severity: critical
  annotations:
    summary: "High authentication failure rate"
    description: "{{ $value }} failed authentication attempts per second"
```

--------------------------------

### Alertmanager Configuration Example (YAML)

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/features/alerting.mdx

This is a standard Alertmanager configuration file that defines global settings, routing rules for alerts based on severity, and receiver configurations for PagerDuty and Slack. It demonstrates how to group alerts and specify notification channels.

```yaml
global:
  resolve_timeout: 5m

route:
  receiver: 'default-receiver'
  group_by: ['alertname', 'severity', 'team', 'source']
  group_wait: 10s
  group_interval: 30s
  repeat_interval: 12h

  routes:
    # Critical alerts to PagerDuty
    - match:
        severity: critical
      receiver: 'pagerduty'
      continue: true

    # Warning alerts to Slack
    - match:
        severity: warning
      receiver: 'slack-oncall'

receivers:
  - name: 'default-receiver'
    webhook_configs:
      - url: 'http://webhook-receiver:8080/alerts'

  - name: 'pagerduty'
    pagerduty_configs:
      - service_key: 'YOUR_SERVICE_KEY'

  - name: 'slack-oncall'
    slack_configs:
      - api_url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL'
        channel: '#alerts'
        title: 'LogChef Alert: {{ .GroupLabels.alertname }}'

```

--------------------------------

### Find All Errors (LogchefQL & SQL)

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/guide/examples.md

This query finds all log entries with a level of 'error' across all services. It's useful for getting a general overview of system health. The SQL equivalent selects all columns from the 'logs.app' table where the 'level' column is 'error', ordered by timestamp.

```logql
level="error"
```

```sql
SELECT *
FROM logs.app
WHERE level = 'error'
ORDER BY timestamp DESC
LIMIT 100
```

--------------------------------

### Context-Aware SQL Enhancement Example

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/features/ai-sql-generation.mdx

Demonstrates the AI assistant's ability to enhance an existing SQL query based on a natural language prompt. The AI considers the current query and adds the requested filter for errors in the last hour.

```sql
SELECT *
FROM logs
WHERE service = 'api-gateway'
  AND severity_text = 'ERROR'
  AND timestamp >= now() - INTERVAL 1 HOUR
ORDER BY timestamp DESC
```

--------------------------------

### Manually Initialize ClickHouse Tables

Source: https://github.com/mr-karan/logchef/blob/main/dev/README.md

Runs the SQL script to create necessary tables in ClickHouse if they were not created automatically on the first startup. This is a troubleshooting step for table creation issues.

```bash
just dev-init-tables
```

--------------------------------

### LogChef: Execute Log Queries (Go)

Source: https://context7.com/mr-karan/logchef/llms.txt

This Go code illustrates how to query logs using LogChef's internal packages. It demonstrates initializing database connections (SQLite and ClickHouse), defining query parameters including raw SQL, executing the query, and processing the results. The `clickhouse.LogQueryParams` struct is used to specify query details, and the `core.QueryLogs` function performs the actual retrieval.

```go
package main

import (
    "context"
    "log/slog"

    "github.com/mr-karan/logchef/internal/clickhouse"
    "github.com/mr-karan/logchef/internal/core"
    "github.com/mr-karan/logchef/internal/sqlite"
    "github.com/mr-karan/logchef/pkg/models"
)

func queryLogs() {
    ctx := context.Background()
    logger := slog.Default()

    // Initialize database connections
    db, _ := sqlite.New("logchef.db")
    chManager, _ := clickhouse.NewManager(logger)

    sourceID := models.SourceID(1)

    // Query with raw SQL
    params := clickhouse.LogQueryParams{
        RawSQL: "SELECT * FROM default.logs WHERE level = 'error' AND timestamp >= now() - INTERVAL 1 HOUR ORDER BY timestamp DESC LIMIT 100",
        Limit:  100,
    }

    result, err := core.QueryLogs(ctx, db, chManager, logger, sourceID, params)
    if err != nil {
        logger.Error("query failed", "error", err)
        return
    }

    logger.Info("query completed",
        "rows_returned", len(result.Logs),
        "execution_time_ms", result.Stats.ExecutionTimeMs,
        "rows_read", result.Stats.RowsRead)

    // Process log results
    for _, log := range result.Logs {
        timestamp := log["timestamp"]
        message := log["message"]
        logger.Info("log entry", "timestamp", timestamp, "message", message)
    }
}
```

--------------------------------

### LogChef Commit Message Examples

Source: https://github.com/mr-karan/logchef/blob/main/CONTRIBUTING.md

Examples of conventional commit messages used in LogChef. These follow a structure that includes a type (feat, fix, docs, refactor) and a concise description.

```bash
feat: add AI-powered query suggestions
fix: resolve race condition in connection pooling
docs: update Nix setup instructions
refactor: simplify user authentication flow
```

--------------------------------

### Custom Alert Annotations Example (JSON)

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/features/alerting.mdx

This JSON object shows examples of custom annotations that can be added to alerts to provide additional context. These include links to runbooks, dashboards, and instructions for handling the alert.

```json
{
  "runbook": "https://wiki.example.com/runbooks/high-error-rate",
  "dashboard": "https://grafana.example.com/d/logs-overview",
  "playbook": "Check database connection pool and recent deployments"
}

```

--------------------------------

### Verify ClickHouse Tables Exist

Source: https://github.com/mr-karan/logchef/blob/main/dev/README.md

Queries ClickHouse via its HTTP interface to list all available tables. This command helps confirm that the necessary tables (`http`, `syslogs`) have been successfully created.

```bash
curl "http://localhost:8123/?query=SHOW+TABLES"
```

--------------------------------

### Alertmanager Configuration Example

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/features/alerting.mdx

Example Alertmanager configuration snippet to set up Slack notifications for API alerts. This configuration defines a receiver named 'slack-alerts' and specifies the Slack webhook URL and channel for sending messages.

```yaml
receivers:
  - name: 'slack-alerts'
    slack_configs:
      - api_url: 'https://hooks.slack.com/services/YOUR/WEBHOOK'
        channel: '#api-alerts'
```

--------------------------------

### LogChef Alerting Configuration (Environment Variables)

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/getting-started/configuration.md

Shows how to configure LogChef's alerting features using environment variables. This method is useful for dynamic configuration and in containerized environments.

```bash
export LOGCHEF_ALERTS__ENABLED=true
export LOGCHEF_ALERTS__ALERTMANAGER_URL="http://alertmanager:9093"
export LOGCHEF_ALERTS__FRONTEND_URL="https://logchef.example.com"

```

--------------------------------

### Extract Nested Values from Logs

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/guide/examples.md

Shows how to access and select values from nested JSON structures within log data, aliasing them for clarity. This is crucial for analyzing complex log payloads. The example filters for 'prod' namespace logs.

```LogchefQL
namespace="prod" | timestamp log_attributes.user_id log_attributes.request_id body
```

```sql
SELECT 
  timestamp, 
  log_attributes['user_id'] AS log_attributes_user_id, 
  log_attributes['request_id'] AS log_attributes_request_id, 
  body
FROM logs.app
WHERE namespace = 'prod'
ORDER BY timestamp DESC
LIMIT 100
```

--------------------------------

### Enriched Logchef Query Examples

Source: https://github.com/mr-karan/logchef/blob/main/docs/src/content/docs/tutorials/nginx-logs.mdx

These Logchef query examples demonstrate how to leverage added enrichment fields in ClickHouse for more specific log analysis. They show filtering logs by environment and status category, and by API version.

```sql
# Find all errors in production
environment="production" AND status_category="error"

# Find v2 API calls
api_version="2"
```