### Quick Start: Running Telescope with Docker (Bash)

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

This bash script pulls the latest Docker image, downloads SQLite database and config templates, and starts the container with volume mounts for configuration. Requires Docker and wget; uses host network for local access. Access the setup interface at http://localhost:9898 after running, but note limitations with realpath on some systems.

```bash
# Download the latest Docker image
docker pull ghcr.io/iamtelescope/telescope:latest

# Create directory and download templates
mkdir ~/.telescope/
wget -O ~/.telescope/db.sqlite3 "https://raw.githubusercontent.com/iamtelescope/telescope/refs/heads/main/dev/db.sqlite3"
wget -O ~/.telescope/config.yaml "https://raw.githubusercontent.com/iamtelescope/telescope/refs/heads/main/dev/config.yaml"

# Start the container
docker run \
    -e TELESCOPE_CONFIG_FILE="/config.yaml" \
    -v $(realpath ~/.telescope/config.yaml):/config.yaml \
    -v $(realpath ~/.telescope/db.sqlite3):/db.sqlite3 \
    --network host \
    ghcr.io/iamtelescope/telescope:latest

# Access the application at http://localhost:9898/setup to create superuser
```

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

### Start Vector and Verify ClickHouse Integration

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Commands to start Vector log generator, verify log flow into ClickHouse, and configure Telescope connections. Includes instructions for creating ClickHouse connection and log source in Telescope UI. Requires Vector CLI and clickhouse-client installed.

```bash
# Step 3: Start Vector
vector --config vector.yaml

# Step 4: Verify logs are flowing
clickhouse-client --query "SELECT count() FROM logs.logs"

# Step 5: Create connection in Telescope UI at /connections/new
# - Name: "Local ClickHouse Demo"
# - Host: localhost
# - Port: 8123
# - User: default
# - Password: (empty)
# - SSL: disabled

# Step 6: Create source in Telescope UI at /sources/new
# - Name: "Demo Web Server Logs"
# - Connection: Select "Local ClickHouse Demo"
# - Database: logs
# - Table: logs
# - Time field: timestamp
# - Severity field: level

# Step 7: Navigate to explorer and start querying!
```

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

### Build and Deploy Astro Documentation Site

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Commands to install dependencies, start development server, build production version, and optionally integrate Google Analytics for the Astro documentation site. Uses npm ci for reproducible builds and supports environment variables for analytics configuration. Requires Node.js 18+ and npm.

```bash
# Install dependencies
npm ci

# Start development server
npm run dev
# Access at http://localhost:4321

# Build for production
npm run build

# Preview production build
npm run preview

# Build with Google Analytics
ENABLE_GA=true GA_MEASUREMENT_ID=G-XXXXXXXXXX npm run build
```

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

### Django Development Server Commands

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/setup/development.md

Commands to run database migrations and start the Django development server. Includes configuration setup through environment variable and model synchronization. Handles authentication and serves static files.

```shell
cd ./backend
export TELESCOPE_CONFIG_FILE=${HOME}/.telescope/config.yaml
python manage.py migrate
python manage.py runserver
```

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

### Python Environment Setup for Telescope Backend

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/setup/development.md

Sets up the Python virtual environment and installs backend dependencies. Creates isolated Python environment and installs required packages from requirements.txt. Requires Python 3.12+ and proper file structure.

```shell
python -m venv venv
source venv/bin/activate
cd ./backend
pip install -r requirements.txt
```

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

### Setting Up ClickHouse Connection Parameters (Python)

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Python dictionary examples define connection details for ClickHouse using HTTP/HTTPS via clickhouse-connect library, including SSL options for secure production setups. Inputs include host, port, credentials; outputs reusable connection objects for multiple sources. Limitations: HTTP-only protocol, requires proper SSL certs for verification.

```python
# Example ClickHouse connection parameters
connection = {
    "name": "Production ClickHouse",
    "type": "clickhouse",
    "host": "clickhouse.prod.com",
    "port": 8123,  # 8123 for HTTP, 8443 for HTTPS
    "user": "telescope_user",
    "password": "secure_password",
    "ssl": True,
    "ssl_options": {
        "verify": True,
        "ca_certs": "/path/to/ca.pem",
        "certfile": "/path/to/client-cert.pem",
        "keyfile": "/path/to/client-key.pem",
        "server_hostname": "clickhouse.prod.com",
        "alt_hosts": "clickhouse-backup.prod.com:8443"
    }
}

# For local development without SSL
dev_connection = {
    "name": "Local ClickHouse",
    "type": "clickhouse",
    "host": "localhost",
    "port": 8123,
    "user": "default",
    "password": "",
    "ssl": False
}
```

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

### Node.js Environment Setup for Telescope Frontend

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/setup/development.md

Installs Node.js dependencies for the Vue.js frontend application. Uses npm to install all required packages defined in package.json. Requires Node.js 20+ and proper file structure.

```shell
cd ./ui
npm install
```

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

### Configuring Telescope with YAML File

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

YAML configuration example defines authentication providers, Django settings, Gunicorn server options, user limits, frontend URLs, and logging levels. Set the file path using TELESCOPE_CONFIG_FILE environment variable; supports GitHub auth and SQLite. Limitations include unlimited saved views when set to 0 and debug mode disabled by default.

```yaml
# Complete Telescope configuration example
auth:
  providers:
    github:
      enabled: false
      default_group: null
      client_id: 'your-github-client-id'
      key: 'your-github-key'
      secret: 'your-github-secret'
      organizations: ['my-org']
  force_github_auth: false
  enable_testing_auth: false
  testing_auth_username: telescope

django:
  CSRF_TRUSTED_ORIGINS:
    - http://localhost:9898
  DATABASES:
    default:
      ENGINE: django.db.backends.sqlite3
      NAME: telescope-default-db.sqlite3
  DEBUG: false

gunicorn:
  bind: 127.0.0.1:9898
  max_requests: 50
  max_requests_jitter: 50
  timeout: 120
  workers: 8

limits:
  max_saved_views_per_user: 0  # 0 = unlimited

frontend:
  show_github_url: true
  github_url: "https://github.com/yourorg/yourrepo"
  show_docs_url: true
  docs_url: "https://docs.example.com"
  base_url: ""

logging:
  format: default  # Options: default, dev, json
  levels:
    all: DEBUG
    django: DEBUG
    django.request: DEBUG
    django.template: INFO
    django.utils.autoreload: INFO
    telescope: DEBUG
```

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

### Configuring Local Docker Connection (Python)

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Python dictionary example sets up a local Docker connection via Unix socket for streaming container logs. Depends on Docker daemon access; suitable for development environments. Limitations: Local only, no remote TCP in this example, requires socket permissions.

```python
# Local Docker connection (Unix socket)
local_docker = {
    "name": "Local Docker",
    "type": "docker",
    "address": "unix:///var/run/docker.sock"
}

```

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

### Astro Configuration with Starlight Integration

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Complete Astro configuration file for the Telescope documentation site. Configures Starlight theme with custom branding, social links, sidebar navigation structure, and includes sitemap generation. The site is set to deploy at https://docs.iamtelescope.net with organized documentation sections for introduction, setup, and concepts.

```javascript
// astro.config.mjs configuration
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import sitemap from "@astrojs/sitemap";

export default defineConfig({
  site: "https://docs.iamtelescope.net",
  integrations: [
    starlight({
      title: "Telescope",
      description: "Telescope log exploration interface documentation",
      logo: {
        src: "./src/assets/telescope-logo.png",
        replacesTitle: false,
      },
      social: [
        {
          icon: "github",
          label: "GitHub",
          href: "https://github.com/iamtelescope/telescope",
        },
      ],
      sidebar: [
        { label: "Introduction", slug: "index" },
        {
          label: "Setup",
          items: [
            { label: "Development", slug: "setup/development" },
            { label: "Configuration", slug: "setup/config" },
          ],
        },
        {
          label: "Concepts",
          items: [
            { label: "Authentication & authorization", slug: "concepts/auth" },
            { label: "Connections", slug: "concepts/connection" },
            { label: "Data sources", slug: "concepts/source" },
            { label: "Querying data", slug: "concepts/querying" },
          ],
        },
      ],
    }),
    sitemap(),
  ],
});
```

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

### Vue.js Development Server Command

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/setup/development.md

Starts the Vue.js development server for frontend development. Runs on port 8080 and provides hot reloading for development. Requires Django server to be running for authentication.

```shell
cd ui
npm run serve
```

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

### Create and manage saved views

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Demonstrates how to create, load, and manage saved views in the Data Explorer. Includes setting up public/private visibility and handling view limits.

```javascript
// Creating a saved view
const savedView = {
  "name": "Production Errors - Last Hour",
  "source_id": 456,
  "fields": ["timestamp", "level", "message", "service", "host"],
  "time_range": {
    "type": "relative",
    "value": "1h"
  },
  "filters": [
    {
      "field": "level",
      "operator": "IN",
      "value": ["ERROR", "FATAL"]
    },
    {
      "field": "service",
      "operator": "STARTS_WITH",
      "value": "prod-"
    }
  ],
  "limit": 500,
  "graph_config": {
    "enabled": true,
    "group_by": "service"
  },
  "is_public": false  // Private to user or shared with others
};

// Loading a saved view
// 1. Click saved views dropdown
// 2. Select view name from list
// 3. All query parameters are restored
// 4. Click Search to execute

// Managing saved views
// - Create: Fill query parameters, click Save View
// - Update: Load view, modify parameters, click Update View
// - Delete: Select view, click Delete
// - Share: Toggle public/private visibility

// View limit configuration (from config.yaml)
// limits:
//   max_saved_views_per_user: 0  # 0 = unlimited, >0 = specific limit
```

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

### Configure Vector Log Generator for ClickHouse

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Configures Vector to generate demo JSON logs and transform them for ClickHouse ingestion. Sets up API endpoint, demo log source, log level mapping based on HTTP status codes, and ClickHouse sink. Requires Vector installation and ClickHouse server at localhost:8123.

```yaml
# Step 2: Configure Vector (vector.toml or vector.yaml)
# Install Vector from https://vector.dev/docs/setup/quickstart/

api:
  enabled: true

sources:
  access:
    type: demo_logs
    format: json
    interval: 1

transforms:
  prepare_level:
    type: remap
    inputs:
      - access
    source: |
      .service = "web-server"
      .level = "UNKNOWN"
      .rest = parse_json!(.message)
      .message = "[" + .rest.datetime + "] " + .rest.host + " " + .rest.method + " " + .rest.request + " " + .rest.referer
      code = parse_int!(.rest.status)
      if code < 200 {
        .level = "TRACE"
      } else if code >= 200 && code < 300 {
        .level = "DEBUG"
      } else if code >= 300 && code < 400 {
        .level = "INFO"
      } else if code >= 400 && code < 500 {
        .level = "WARN"
      } else {
        .level = "ERROR"
      }
      .rest.status = code

  prepare_timestamp:
    type: remap
    inputs:
      - prepare_level
    source: |
      .timestamp = format_timestamp!(.timestamp, "%s%f")

sinks:
  clickhouse:
    type: clickhouse
    endpoint: http://localhost:8123
    database: logs
    table: logs
    auth:
      strategy: basic
      user: default
      password: ""
    inputs:
      - prepare_timestamp
    encoding:
      timestamp_format: rfc3339
```

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

### Create ClickHouse Database and Table

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/howto/demologs.md

SQL statements to create a database named 'logs' and a table named 'logs' within it. The table schema is optimized for log data with specific codecs and partitioning for efficient storage and retrieval. It also includes TTL settings for data retention.

```sql
CREATE DATABASE logs.logs;
CREATE TABLE logs.logs
(
    `timestamp` DateTime64(9, 'UTC') CODEC(Delta(8), ZSTD(1)),
    `host` String CODEC(ZSTD(7)),
    `service` String CODEC(ZSTD(7)),
    `message` String CODEC(ZSTD(7)),
    `source_type` String CODEC(ZSTD(7)),
    `level` Enum8('UNKNOWN' = 0, 'FATAL' = 1, 'ERROR' = 2, 'WARN' = 3, 'INFO' = 4, 'DEBUG' = 5, 'TRACE' = 6),
    `rest` String CODEC(ZSTD(7))
)
ENGINE = MergeTree
PARTITION BY toStartOfHour(timestamp)
PRIMARY KEY (service, timestamp)
ORDER BY (service, timestamp)
TTL toDateTime(timestamp) + toIntervalWeek(1)
SETTINGS index_granularity = 1024;
```

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

### Docker Build and Run Documentation Site

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Commands to build and run the Telescope documentation site using Docker. The first command builds a Docker image tagged as telescope-docs, and the second command runs the container mapping port 8080 to the internal port 80.

```shell
docker build -t telescope-docs .
```

```shell
docker run -p 8080:80 telescope-docs
```

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

### Build query in Data Explorer UI

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Illustrates how to construct a query using JavaScript in the web interface. Includes time range, selected fields, filters, result limit, and graph configuration.

```javascript
// Example: Building a query in the UI

// 1. Select time range
const timeRange = {
  type: "relative",
  value: "30m"  // Options: 5m, 15m, 30m, 1h, 3h, 6h, 12h, 24h, 7d
};

// 2. Select fields to display
const selectedFields = [
  "timestamp",
  "level",
  "message",
  "service",
  "host"
];

// 3. Build filters using query input
const filters = `
level IN (ERROR, FATAL) AND
service = "payment-service" AND
message CONTAINS "transaction failed"
`;

// 4. Set result limit
const limit = 500;

// 5. Configure graph grouping
const graphSetup = {
  enabled: true,
  groupBy: "service"  // Group graph by service field
};

// 6. Click Search button to execute
// Results display in table with:
// - Color-coded rows based on severity
// - Graph showing log volume over time
// - Detailed view on row click with flattened JSON paths
```

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

### Containerize Documentation with Docker Multi-Stage

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Multi-stage Docker build for documentation deployment. First stage builds the Astro site with optional Google Analytics using Node.js Alpine, second stage serves with Nginx. Includes custom Nginx configuration and port exposure. Requires Docker and build-time arguments for analytics configuration.

```dockerfile
# Docker deployment (multi-stage build)
# Stage 1: Build documentation
FROM node:18-alpine as builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ARG ENABLE_GA=false
ARG GA_MEASUREMENT_ID=""
ENV ENABLE_GA=$ENABLE_GA
ENV GA_MEASUREMENT_ID=$GA_MEASUREMENT_ID
RUN npm run build

# Stage 2: Serve with Nginx
FROM nginx:alpine
RUN rm /etc/nginx/conf.d/default.conf
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

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

### Download Telescope Config and Database Files

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/index.mdx

This shell script creates a local directory for Telescope and downloads the SQLite database template and config YAML file using wget. It depends on wget being available and assumes the repository URLs are accessible. Outputs are the saved files in ~/.telescope/. Limits apply if URLs are unreachable or wget is not installed.

```sh
mkdir ~/.telescope/
wget -O ~/.telescope/db.sqlite3 "https://raw.githubusercontent.com/iamtelescope/telescope/refs/heads/main/dev/db.sqlite3"
wget -O ~/.telescope/config.yaml "https://raw.githubusercontent.com/iamtelescope/telescope/refs/heads/main/dev/config.yaml"
```

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

### Create ClickHouse Database Schema for Logs

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Sets up ClickHouse database and table with optimized compression and partitioning for log storage. Creates logs database with MergeTree engine, hourly partitioning, and TTL-based data retention. Requires ClickHouse server running on localhost:8123.

```sql
-- Step 1: Create ClickHouse database and table
CREATE DATABASE logs;

CREATE TABLE logs.logs
(
    `timestamp` DateTime64(9, 'UTC') CODEC(Delta(8), ZSTD(1)),
    `host` String CODEC(ZSTD(7)),
    `service` String CODEC(ZSTD(7)),
    `message` String CODEC(ZSTD(7)),
    `source_type` String CODEC(ZSTD(7)),
    `level` Enum8('UNKNOWN' = 0, 'FATAL' = 1, 'ERROR' = 2, 'WARN' = 3, 'INFO' = 4, 'DEBUG' = 5, 'TRACE' = 6),
    `rest` String CODEC(ZSTD(7))
)
ENGINE = MergeTree
PARTITION BY toStartOfHour(timestamp)
PRIMARY KEY (service, timestamp)
ORDER BY (service, timestamp)
TTL toDateTime(timestamp) + toIntervalWeek(1)
SETTINGS index_granularity = 1024;
```

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

### Rebuild Static Files Script

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/setup/development.md

Bash script that rebuilds static files by running npm build and Django collectstatic. Resolves missing static file issues and TemplateDoesNotExist errors. Requires activated virtual environment and proper Django configuration.

```shell
./rebuild_static.bash
```

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

### Telescope YAML Configuration Example

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/setup/config.md

This YAML snippet defines the configuration for a Telescope instance, covering authentication (GitHub provider, testing auth), Django database and debug settings, Gunicorn server bindings and worker options, user limits for saved views, frontend UI customizations like URLs, and logging formats and levels. It uses default values that can be overridden; dependencies include Django, Gunicorn, and allauth for auth. Inputs are YAML keys; outputs affect application behavior; limitations include requiring existing groups for auth and no validation in the file itself.

```yaml
auth:
  providers:
    github:
      # Enable or disable login via GitHub (https://github.com/iamtelescope/telescope/blob/main/backend/base/settings.py#L143-L154)
      enabled: false
      # Add users to the specified group on login (the group must exist)
      default_group: null
      # client_id, key, and secret should be obtained from GitHub (https://docs.allauth.org/en/dev/socialaccount/providers/github.html)
      client_id: ''
      key: ''
      secret: ''
      # If specified, users must belong to one of these organizations to log in.
      organizations: []
  # If set to true, forces login page to redirect to github auth (only available when github auth provider is enabled)
  force_github_auth: false
  # If set to true, the user is always authenticated without any conditions
  enable_testing_auth: false
  # If enable_testing_auth is set true, defines the username of the logged-in user
  testing_auth_username: telescope

django:
  CSRF_TRUSTED_ORIGINS:
  - http://localhost:9898
  DATABASES:
    default:
      ENGINE: django.db.backends.sqlite3
      NAME: telescope-default-db.sqlite3
  DEBUG: false

gunicorn:
  bind: 127.0.0.1:9898
  max_requests: 50
  max_requests_jitter: 50
  timeout: 120
  workers: 8

limits:
  # Specifies the maximum number of saved views a single user can create. If set to `0`, the limit is disabled and users can create unlimited views.
  max_saved_views_per_user: 0
  
frontend:
    show_github_url: true  # show or not github url on top panel
    github_url: ""
    show_docs_url: true  # show or not docs url on top panel
    docs_url: ""
    base_url: "" # base url path ie "/telescope"

logging:
  # Options: default, dev, or json
  format: default
  # Setup for log levels of different handlers
  levels:
    all: DEBUG
    django: DEBUG
    django.request: DEBUG
    django.template: INFO
    django.utils.autoreload: INFO
    telescope: DEBUG
```

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

### Build advanced query with raw WHERE clause

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Creates an advanced query using a custom raw WHERE clause for complex filtering. Requires appropriate permissions for raw query execution.

```python
advanced_query = {
    "source_id": 456,
    "fields": ["timestamp", "level", "message", "rest"],
    "time_range": {
        "type": "relative",
        "value": "24h"
    },
    "limit": 100,
    "filters": [
        {
            "field": "level",
            "operator": "EQUALS",
            "value": "ERROR"
        }
    ],
    "raw_where_clause": "JSONExtractString(rest, 'user_id') = '12345' AND message LIKE '%timeout%'"
}
```

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

### ClickHouse Data Source Configuration (Python)

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Complete ClickHouse source configuration for accessing log data including database connection, table selection, field mappings, and special field roles for timestamp and severity handling. Supports autocomplete and suggestions for better user experience.

```python
# Complete ClickHouse source configuration
source = {
    "name": "Production Application Logs",
    "connection_id": 123,  # Reference to existing connection
    "type": "clickhouse",
    "database": "logs",
    "table": "application_logs",
    "time_field": "timestamp",
    "severity_field": "level",
    "default_chosen_fields": ["timestamp", "level", "message", "service"],
    "fields": [
        {
            "name": "timestamp",
            "display_name": "Time",
            "type": "DateTime64",
            "autocomplete": False,
            "suggestions": False
        },
        {
            "name": "level",
            "display_name": "Severity",
            "type": "Enum8",
            "enum_values": ["DEBUG", "INFO", "WARN", "ERROR", "FATAL"],
            "autocomplete": True,
            "suggestions": True
        },
        {
            "name": "message",
            "display_name": "Message",
            "type": "String",
            "autocomplete": False,
            "suggestions": False
        },
        {
            "name": "service",
            "display_name": "Service Name",
            "type": "String",
            "autocomplete": True,
            "suggestions": True
        },
        {
            "name": "host",
            "display_name": "Hostname",
            "type": "String",
            "autocomplete": True,
            "suggestions": True
        },
        {
            "name": "rest",
            "display_name": "Additional Data",
            "type": "String",
            "is_json": True
        }
    ]
}
```

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

### Query nested JSON fields

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Demonstrates how to access nested JSON fields in a query. Allows filtering based on nested data structures within log entries.

```python
json_query = {
    "source_id": 456,
    "fields": ["timestamp", "message", "rest:user_id", "rest:request:method"],
    "time_range": {
        "type": "relative",
        "value": "1h"
    },
    "limit": 200,
    "filters": [
        {
            "field": "rest:response:status_code",
            "operator": "GREATER_THAN",
            "value": 400
        }
    ]
}
```

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

### Configure Vector Agent for Demo Logs and ClickHouse Sink

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/howto/demologs.md

YAML configuration for the Vector agent to generate demo logs and process them before sending to ClickHouse. It defines a 'demo_logs' source, remap transforms to prepare log data (service, level, message parsing, and timestamp formatting), and a ClickHouse sink to ingest the processed logs.

```yaml
api:
  enabled: true
sources:
  access:
    type: demo_logs
    format: json
    interval: 1
transforms:
  prepare_level:
    type: remap
    inputs:
      - access
    source: |
      .service = "web-server"
      .level = "UNKNOWN"
      .rest = parse_json!(.message)
      .message, _ = "[" + .rest.datetime + "] " + .rest.host + " " + .rest.method + " " + .rest.request + " " + .rest.referer
      code = parse_int!(.rest.status)
      if code < 200 {
        .level = "TRACE"
      } else if code >= 200 && code < 300 {
        .level = "DEBUG"
      } else if code >= 300 && code < 400 {
        .level = "INFO"
      } else if code >= 400  && code < 500 {
        .level = "WARN"
      } else {
        .level = "ERROR"
      }
      .rest.status = code
  prepare_timestamp:
    type: remap
    inputs:
      - prepare_level
    source: |
      .timestamp = format_timestamp!(.timestamp, "%s%f")
sinks:
  clickhouse:
    type: clickhouse
    endpoint: http://localhost:8123
    database: logs
    table: logs
    auth:
      strategy: basic
      user: default
      password: ""
    inputs:
      - prepare_timestamp
    encoding:
      timestamp_format: rfc3339
```

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

### Create basic query with relative time range

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Defines a query structure with relative time range, selected fields, limit, and filters. Suitable for querying recent logs with ERROR or FATAL levels from a specific service.

```python
query = {
    "source_id": 456,
    "fields": ["timestamp", "level", "message", "service", "host"],
    "time_range": {
        "type": "relative",
        "value": "1h"  # Last 1 hour
    },
    "limit": 500,
    "filters": [
        {
            "field": "level",
            "operator": "IN",
            "value": ["ERROR", "FATAL"]
        },
        {
            "field": "service",
            "operator": "EQUALS",
            "value": "api-gateway"
        }
    ]
}
```

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

### Create query with absolute time range

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Constructs a query with an absolute time range, selecting specific fields, limit, and filters. Useful for querying logs within a specific date-time window.

```python
query_absolute = {
    "source_id": 456,
    "fields": ["timestamp", "level", "message"],
    "time_range": {
        "type": "absolute",
        "start": "2025-11-06T00:00:00Z",
        "end": "2025-11-06T23:59:59Z"
    },
    "limit": 1000,
    "filters": [
        {
            "field": "host",
            "operator": "STARTS_WITH",
            "value": "prod-"
        }
    ]
}
```

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

### Apply slice modifier to extract substring

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Extracts substring based on specified range. Usage: `slice(from[,to])` where `from` is starting index and `to` is optional ending index.

```plaintext
message|slice(5,10)
```

```plaintext
message|slice(5)
```

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

### Apply chars modifier to limit text length

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Limits the text to a specified number of characters. Usage: `chars(from[,to])` where `from` is the starting index and `to` is optional ending index.

```plaintext
message|chars(25)
```

```plaintext
message|chars(5,10)
```

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

### Apply lines modifier to extract specific lines

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Extracts lines from text based on specified range. Usage: `lines(from[,to])` where `from` is starting line index and `to` is optional ending index.

```plaintext
message|lines(2,5)
```

```plaintext
message|lines(3)
```

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

### Pull Telescope Docker Image

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/index.mdx

This shell command pulls the latest Telescope Docker image from GitHub Container Registry. It requires Docker to be installed on the system. The output is the downloaded image, and there's no specific limitation beyond network availability.

```sh
docker pull ghcr.io/iamtelescope/telescope:latest
```

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

### RBAC Permission System Implementation (Python)

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Three-tier role-based access control implementation with Global Roles, Connection Roles, and Source Roles. Includes permission checking functions for source creation and log querying. Supports both user and group-based permissions with granular control over read, edit, use, delete, and grant actions.

```python
# Example: Granting permissions to users and groups

# Global Admin role (system-wide)
# Automatically has all permissions across all resources
admin_user = {
    "username": "alice",
    "global_role": "Admin"
}

# Connection-level permissions
connection_permissions = {
    "connection_id": 123,
    "role_bindings": [
        {
            "user": "bob",
            "role": "Owner",  # Full control: read, edit, delete, use, grant
        },
        {
            "user": "charlie",
            "role": "User",  # Can read and use in sources
        },
        {
            "group": "developers",
            "role": "Viewer"  # Read-only access
        }
    ]
}

# Source-level permissions
source_permissions = {
    "source_id": 456,
    "role_bindings": [
        {
            "user": "bob",
            "role": "Owner",  # Full control including raw queries
        },
        {
            "user": "dave",
            "role": "Raw Query User",  # Can execute custom SQL
        },
        {
            "group": "analytics_team",
            "role": "User"  # Can query logs but no raw SQL
        },
        {
            "group": "observers",
            "role": "Viewer"  # Read-only, no querying
        }
    ]
}

# Permission check example
def can_user_create_source(user, connection):
    """
    User needs:
    1. global_create_source permission OR
    2. connection_use permission on the target connection
    """
    has_global = user.has_permission("global_create_source")
    has_connection_use = user.has_connection_permission(
        connection.id,
        "connection_use"
    )
    return has_global and has_connection_use

def can_user_query_logs(user, source):
    """
    User needs both source_read AND source_use permissions
    """
    has_read = user.has_source_permission(source.id, "source_read")
    has_use = user.has_source_permission(source.id, "source_use")
    return has_read and has_use
```

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

### Remote Docker Host Configuration (TCP)

Source: https://context7.com/iamtelescope/telescope-docs/llms.txt

Configure remote Docker hosts for Telescope connections using TCP protocol. Supports both standard and TLS-secured connections. TCP connections allow distributed Docker environments to be accessed remotely.

```yaml
remote_docker = {
    "name": "Remote Docker Host",
    "type": "docker",
    "address": "tcp://docker-host.example.com:2375"
}

# Secure remote Docker with TLS
secure_remote_docker = {
    "name": "Secure Remote Docker",
    "type": "docker",
    "address": "tcp://docker-host.example.com:2376"
}
```

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

### Run Telescope Docker Container

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/index.mdx

This shell command runs the Telescope Docker container with mounted volumes for config and database files, using host networking. It requires Docker and the previously downloaded files. The service outputs on localhost port 9898 for setup. Limitations include host network dependency and volume mount requirements.

```sh
docker run \
    -e TELESCOPE_CONFIG_FILE="/config.yaml" \
    -v $(realpath ~/.telescope/config.yaml):/config.yaml \
    -v $(realpath ~/.telescope/db.sqlite3):/db.sqlite3 \
    --network host \
    ghcr.io/iamtelescope/telescope:latest
```

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

### Connection Management API

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/concepts/connection.md

Provides information about managing Connections through the Telescope UI.

```APIDOC
## Connection Management API

### Description
Provides information about managing Connections through the Telescope UI.

### Method
N/A - UI Operations

### Endpoint
- `/connections/new` - Create a new connection
- `/connections` - List available connections
- `/connections/:id/edit` - Modify connection parameters

### Parameters
#### Path Parameters
- `:id` (integer) - The ID of the connection to edit

#### Query Parameters
- N/A

#### Request Body
- N/A (Typically JSON for create/edit, handled by the UI)

### Request Example
N/A

### Response
#### Success Response (200)
- N/A

#### Response Example
N/A
```

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

### Docker Connection

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/concepts/connection.md

Describes how to configure a Docker connection in Telescope for log streaming.

```APIDOC
## Docker Connection

### Description
Describes how to configure a Docker connection in Telescope for log streaming.

### Method
N/A - Configuration Documentation

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- `address` (string) - Required - Docker daemon socket URL
  - Local: `unix:///var/run/docker.sock`
  - Remote: `tcp://<host>:<port>`

### Request Example
{
  "address": "unix:///var/run/docker.sock"
}

### Response
#### Success Response (200)
- N/A

#### Response Example
{
  "message": "Docker connection created successfully"
}
```

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

### ClickHouse Connection

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/concepts/connection.md

Describes how to configure a ClickHouse connection in Telescope. As of version 0.0.19, Telescope only supports HTTP(S) connections to ClickHouse.

```APIDOC
## ClickHouse Connection

### Description
Describes how to configure a ClickHouse connection in Telescope. As of version 0.0.19, Telescope only supports HTTP(S) connections to ClickHouse.

### Method
N/A - Configuration Documentation

### Endpoint
N/A

### Parameters
#### Path Parameters
- N/A

#### Query Parameters
- N/A

#### Request Body
- `host` (string) - Required - ClickHouse server host (e.g., `localhost`)
- `port` (integer) - Optional - HTTP(S) port (default: `8123` for HTTP, `8443` for HTTPS)
- `user` (string) - Optional - Username for authentication
- `password` (string) - Optional - Password for authentication
- `ssl` (boolean) - Optional - Enable HTTPS connection

#### SSL Options (when SSL is enabled):
- `verify` (boolean) - Optional - Whether to validate certificates (default: True)
- `ca_certs` (string) - Optional - CA certificate file path
- `certfile` (string) - Optional - Client certificate file
- `keyfile` (string) - Optional - Client key file
- `server_hostname` (string) - Optional - SNI hostname for SSL
- `alt_hosts` (string) - Optional - Alternative hosts for failover

### Request Example
{
  "host": "localhost",
  "port": 8443,
  "user": "telescope",
  "password": "securepassword",
  "ssl": true,
  "verify": false,
  "ca_certs": "/path/to/ca.pem"
}

### Response
#### Success Response (200)
- N/A

#### Response Example
{
  "message": "ClickHouse connection created successfully"
}
```

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

### Convert text to single line

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Removes all line breaks from text, converting it to a single continuous line of text.

```plaintext
message|oneline
```

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

### Apply lastline and chars modifiers sequentially

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Extracts the last line of text and then limits it to a specified number of characters. Modifiers are applied in sequence.

```plaintext
message|lastline|chars(25)
```

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

### Complex modifier chain for JSON processing

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Splits text, extracts element, joins, formats as JSON, and applies syntax highlighting. Useful for processing tab-separated logs with JSON content.

```plaintext
message|split(\t)|slice(-1)|join|format(json)|highlight(json)
```

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

### Extract first line of text

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Simple modifier that extracts just the first line from a multi-line text field.

```plaintext
message|firstline
```

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

### Extract element from Array field

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Accesses Array elements by index using colon delimiter. Supports one level of nesting.

```plaintext
errors:0
```

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

### Extract value from Map field

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Accesses Map-type field values using key name with colon delimiter. Supports one level of nesting.

```plaintext
metadata:request_id
```

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

### Extract nested value from JSON field

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/fields.md

Navigates JSON structure using colon-delimited path to extract nested value. Returns empty string if key doesn't exist.

```plaintext
rest:app:request:bytes
```

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

### Configure Saved Views Limits - YAML

Source: https://github.com/iamtelescope/telescope-docs/blob/main/src/content/docs/ui/explorer/saved_views.md

Administrative configuration for limiting the number of saved views per user. The YAML configuration shows the default setting with no restrictions (max_saved_views_per_user: 0).

```yaml
limits:
  max_saved_views_per_user: 0
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.