### GET /ui/v1/sources/{slug}/contextColumnsData

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

For Docker sources, returns available containers for log selection.

```APIDOC
## GET /ui/v1/sources/{slug}/contextColumnsData

### Description
For Docker sources, this endpoint returns available containers for log selection.

### Method
GET

### Endpoint
`/ui/v1/sources/<slug>/contextColumnsData`

### Parameters
None

### Request Example
`curl -X GET http://localhost:8000/ui/v1/sources/docker-logs/contextColumnsData -H "Cookie: sessionid=YOUR_SESSION"`

### Response
#### Success Response (200)
- **result** (boolean) - Indicates if the request was successful.
- **data** (object) - The container data.
  - **containers** (array) - An array of container objects.
    - **name** (string) - The name of the container.
    - **short_id** (string) - The short ID of the container.
    - **status** (string) - The status of the container.
    - **labels** (object) - Any labels associated with the container.

#### Response Example
```json
{
  "result": true,
  "data": {
    "containers": [
      {"name": "web-app", "short_id": "abc123", "status": "running", "labels": {}},
      {"name": "redis", "short_id": "def456", "status": "running", "labels": {}}
    ]
  }
}
```
```

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

### Python Service Layer - SourceService Examples

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

Demonstrates the usage of the SourceService class for managing data sources. It covers initializing the service, retrieving a source by its slug, listing all accessible sources, creating a new source with detailed configuration, granting roles on a source to a user, and deleting a source. It also shows how to handle potential validation errors during source creation.

```python
from telescope.services.source import SourceService
from telescope.services.exceptions import SerializerValidationError
from django.contrib.auth.models import User

# Initialize service
source_srv = SourceService()

# Get a source by slug (requires Source.READ permission)
user = User.objects.get(username="admin")
source_data = source_srv.get(user=user, slug="app-logs")
print(f"Source: {source_data['name']}, Kind: {source_data['kind']}")

# List all accessible sources
sources = source_srv.list(user=user)
for src in sources:
    print(f"- {src['slug']}: {src['name']}")

# Create a new source (requires Global.CREATE_SOURCE permission)
new_source_data = {
    "kind": "clickhouse",
    "slug": "new-logs",
    "name": "New Application Logs",
    "description": "Logs from new service",
    "connection": {"connection_id": 1},
    "time_column": "timestamp",
    "date_column": "date",
    "uniq_column": "id",
    "severity_column": "level",
    "columns": {
        "timestamp": {
            "display_name": "Time",
            "type": "DateTime64",
            "jsonstring": False,
            "autocomplete": False,
            "suggest": True,
            "group_by": False,
            "values": []
        }
    },
    "default_chosen_columns": ["timestamp"]
}

try:
    result = source_srv.create(user=user, data=new_source_data, raise_is_valid=True)
    print(f"Created source with slug: {result['slug']}")
except SerializerValidationError as e:
    print(f"Validation error: {e.serializer.errors}")

# Grant role on source (requires Source.GRANT permission)
from django.contrib.auth.models import User as DjangoUser
target_user = DjangoUser.objects.get(username="developer")
binding, created = source_srv.grant_role(
    user=user,
    slug="app-logs",
    role="user",
    target_user=target_user
)
print(f"Role granted: {created}")

# Delete source (requires Source.DELETE permission)
source_srv.delete(user=user, slug="old-logs")

```

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

### Create Kubernetes Secrets for Telescope

Source: https://github.com/iamtelescope/telescope/blob/main/helm/templates/NOTES.txt

Commands to create a Kubernetes secret containing sensitive configuration values such as Django secret keys, GitHub OAuth secrets, and database passwords. The command dynamically includes fields based on the enabled application features.

```bash
kubectl create namespace iamtelescope
kubectl create secret generic {{ .Values.secretName }} \
  --namespace iamtelescope \
  --from-literal=DJANGO_SECRET_KEY="your-django-secret-key"{{- if .Values.config.auth.providers.github.enabled }} \
  --from-literal=GITHUB_SECRET="your-github-oauth-secret"{{- end }}{{- if eq .Values.database.type "postgresql" }} \
  --from-literal=DATABASE_PASSWORD="your-database-password"{{- end }}
```

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

### Get Docker Containers for Selection

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

Retrieves a list of available Docker containers for log selection within a Docker log source. This endpoint provides information such as container name, ID, status, and labels, enabling users to filter logs by specific containers.

```shell
curl -X GET http://localhost:8000/ui/v1/sources/docker-logs/contextColumnsData \
  -H "Cookie: sessionid=YOUR_SESSION"
```

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

### Get Autocomplete Suggestions for a Field

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

Provides value suggestions for fields that have autocomplete enabled. This endpoint helps users discover possible values for a given field within a specified time range and partial value match. The response includes a list of suggested items.

```shell
curl -X POST http://localhost:8000/ui/v1/sources/app-logs/autocomplete \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ \
    "column": "service_name", \
    "from": 1704067200000, \
    "to": 1704153600000, \
    "value": "api" \
  }'
```

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

### Retrieve Telescope Service Access URL

Source: https://github.com/iamtelescope/telescope/blob/main/helm/templates/NOTES.txt

This Helm template logic determines the appropriate command to retrieve the application URL based on the configured Kubernetes service type (NodePort, LoadBalancer, or ClusterIP). It outputs the necessary environment variables and commands to access the service.

```helm
{{- if contains "NodePort" .Values.service.type }}
  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "telescope.fullname" . }})
  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
  echo http://$NODE_IP:$NODE_PORT
{{- else if contains "LoadBalancer" .Values.service.type }}
  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "telescope.fullname" . }} --template "{{ "{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}" }}")
  echo http://$SERVICE_IP:{{ .Values.service.port }}
{{- else if contains "ClusterIP" .Values.service.type }}
  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "telescope.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
  export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
  echo "Visit http://127.0.0.1:8080 to use your application"
  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT
{{- end }}
```

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

### Get Specific Saved View

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

Retrieves the details of a single saved view using its unique identifier. This is useful for loading a specific saved query configuration.

```shell
curl -X GET http://localhost:8000/ui/v1/sources/app-logs/savedViews/error-investigation-abc123 \
  -H "Cookie: sessionid=YOUR_SESSION"
```

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

### Get Graph Data Grouped by Log Level

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

Retrieves aggregated data for histogram visualization, grouped by log level. This endpoint is useful for understanding the distribution of log severities over time. It requires specifying a time range and grouping criteria.

```shell
curl -X POST http://localhost:8000/ui/v1/sources/app-logs/graphData \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "level = \"ERROR\" or level = \"WARN\"", \
    "from": 1704067200000, \
    "to": 1704153600000, \
    "group_by": [ \
      {"name": "level", "root_name": "level", "jsonstring": false} \
    ], \
    "context_columns": {} \
  }'
```

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

### Development and Deployment Commands

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

Provides common shell commands for setting up the development environment, running backend and frontend services, and deploying via Docker.

```bash
git clone https://github.com/iamtelescope/telescope.git
cd telescope
make venv
make run-backend
make run-ui
cd backend && make test
cd backend && make fmt
cd ui && make fmt
docker run -p 8000:8000 \
  -e TELESCOPE_CONFIG_FILE=/config.yaml \
  -v ./config.yaml:/config.yaml \
  iamtelescope/telescope:latest
```

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

### Querying and Evaluating Logs with FlyQL

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

Demonstrates how to parse FlyQL queries, convert them into ClickHouse SQL, and perform in-memory log matching. It requires the flyql library and defines columns to map query fields to database schemas.

```python
from flyql.core.parser import parse, ParserError
from flyql.generators.clickhouse.generator import to_sql, Column
from flyql.matcher.evaluator import Evaluator
from flyql.matcher.record import Record

# Parse a FlyQL query
try:
    parser = parse('level = "ERROR" and message contains "timeout"')
    ast = parser.root
except ParserError as e:
    print(f"Parse error: {e.message}")

# Convert to ClickHouse SQL
columns = {
    "level": Column(name="level", jsonstring=False, _type="String", values=[]),
    "message": Column(name="message", jsonstring=False, _type="String", values=[]),
}
sql_where = to_sql(ast, columns=columns)
print(f"SQL WHERE: {sql_where}")

# In-memory matching for Docker/Kubernetes logs
evaluator = Evaluator()
record = Record(data={
    "level": "ERROR",
    "message": "Connection timeout after 30s"
})
if evaluator.evaluate(ast, record):
    print("Record matches query")
```

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

### Manage Kubernetes source context and logs

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

Provides endpoints to fetch cluster contexts and namespaces, filter pods using labels or fields, and execute log queries against specific Kubernetes resources.

```bash
curl -X GET http://localhost:8000/ui/v1/sources/k8s-logs/contextColumnsData \
  -H "Cookie: sessionid=YOUR_SESSION"

curl -X POST http://localhost:8000/ui/v1/sources/k8s-logs/contextColumnData \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "column": "pods",
    "params": {
      "contexts": ["production-cluster"],
      "namespaces": ["app-namespace"],
      "pods_label_selector": "app=web",
      "pods_field_selector": "status.phase=Running",
      "pods_flyql_filter": ""
    }
  }'

curl -X POST http://localhost:8000/ui/v1/sources/k8s-logs/dataAndGraph \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "namespace = \"app-namespace\" and pod contains \"web\"",
    "from": 1704067200000,
    "to": 1704153600000,
    "limit": 100,
    "columns": [],
    "group_by": [],
    "context_columns": {
      "contexts": ["production-cluster"],
      "namespaces": ["app-namespace"],
      "pods_label_selector": "app=web"
    }
  }'
```

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

### Manage RBAC Permissions in Python

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

Demonstrates how to use the RBACManager to verify user permissions, retrieve authorized sources, and assign roles to users or groups within the Telescope system.

```python
from telescope.rbac.manager import RBACManager
from telescope.rbac import permissions
from telescope.rbac.roles import SourceRole, GlobalRole
from django.contrib.auth.models import User, Group

rbac = RBACManager()
user = User.objects.get(username="developer")

try:
    rbac.require_global_permissions(user, [permissions.Global.CREATE_SOURCE.value])
    print("User can create sources")
except PermissionError:
    print("User lacks CREATE_SOURCE permission")

source = rbac.get_source(
    user=user,
    source_slug="app-logs",
    required_permissions=[permissions.Source.USE.value],
    fetch_connection=True
)

rbac.grant_source_role(
    source=source,
    role=SourceRole.USER.value,
    user=user
)

try:
    rbac.require_connection_permissions(
        user=user,
        connection_id=1,
        required_permissions=[permissions.Connection.USE.value]
    )
    print("User can use this connection")
except PermissionError:
    print("Access denied")
```

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

### POST /ui/v1/sources/{slug}/data

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

Query logs using FlyQL filters or raw SQL.

```APIDOC
## POST /ui/v1/sources/{slug}/data

### Description
Query logs with FlyQL filter or raw SQL WHERE clause.

### Method
POST

### Endpoint
`/ui/v1/sources/<slug>/data`

### Parameters
#### Request Body
- **query** (string) - Optional - The FlyQL query string.
- **raw_query** (string) - Optional - The raw SQL WHERE clause (requires RAW_QUERY permission).
- **from** (integer) - Required - The start timestamp in milliseconds.
- **to** (integer) - Required - The end timestamp in milliseconds.
- **limit** (integer) - Optional - The maximum number of results to return.
- **columns** (array) - Optional - An array of column objects to display.
  - **name** (string) - Required - The name of the column.
  - **display_name** (string) - Optional - The display name for the column.
- **context_columns** (object) - Optional - Additional context columns.

### Request Example (FlyQL)
```json
{
  "query": "level = \"ERROR\" and message contains \"timeout\"",
  "from": 1704067200000,
  "to": 1704153600000,
  "limit": 100,
  "columns": [
    {"name": "timestamp", "display_name": "Time"},
    {"name": "level", "display_name": "Level"},
    {"name": "message", "display_name": "Message"}
  ],
  "context_columns": {}
}
```

### Request Example (Raw SQL)
```json
{
  "query": "",
  "raw_query": "JSONExtractString(metadata, '\''service''') = '\''api''
  "from": 1704067200000,
  "to": 1704153600000,
  "limit": 50,
  "columns": [],
  "context_columns": {}
}
```

### Response
#### Success Response (200)
- **result** (boolean) - Indicates if the query was successful.
- **data** (object) - The query results.
  - **columns** (array) - The columns returned.
  - **rows** (array) - The rows of data.
    - **data** (object) - The data for a row.
    - **time** (object) - The timestamp information for a row.
  - **message** (string) - Any messages related to the query.

#### Response Example
```json
{
  "result": true,
  "data": {
    "columns": [...],
    "rows": [
      {
        "data": {"timestamp": "2024-01-01 12:00:00", "level": "ERROR", "message": "Connection timeout"},
        "time": {"datetime": "2024-01-01 12:00:00", "unixtime": 1704110400000}
      }
    ],
    "message": null
  }
}
```
```

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

### Get Graph Data Grouped by JSON Field

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

Retrieves aggregated data for histogram visualization, grouped by a nested JSON field. This allows for analyzing trends based on specific attributes within log metadata, such as service names. It requires specifying the field path and whether it's a JSON string.

```shell
curl -X POST http://localhost:8000/ui/v1/sources/app-logs/graphData \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "", \
    "from": 1704067200000, \
    "to": 1704153600000, \
    "group_by": [ \
      {"name": "metadata.service", "root_name": "metadata", "jsonstring": true} \
    ], \
    "context_columns": {} \
  }'
```

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

### Test service connections

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

Validates connection parameters for external services like ClickHouse, Kubernetes, and Docker before saving them to the configuration.

```bash
curl -X POST http://localhost:8000/ui/v1/services/testConnection/clickhouse \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "clickhouse.example.com",
    "port": 8443,
    "user": "telescope",
    "password": "secret",
    "ssl": true,
    "verify": true
  }'

curl -X POST http://localhost:8000/ui/v1/services/testConnection/kubernetes \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "kubeconfig": "apiVersion: v1\nkind: Config\n...",
    "context_filter": "name contains \"prod\""
  }'

curl -X POST http://localhost:8000/ui/v1/services/testConnection/docker \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "unix:///var/run/docker.sock"
  }'
```

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

### Connection Management API

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

Manage database and service connections for ClickHouse, StarRocks, Docker, or Kubernetes. Requires authentication via API token.

```APIDOC
## POST /api/v1/connections

### Description
Creates a new database or service connection.

### Method
POST

### Endpoint
/api/v1/connections

### Parameters
#### Headers
- **Authorization** (string) - Required - API token for authentication.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **kind** (string) - Required - Type of connection (e.g., `clickhouse`, `starrocks`, `docker`, `kubernetes`).
- **name** (string) - Required - A human-readable name for the connection.
- **description** (string) - Optional - A detailed description of the connection.
- **data** (object) - Required - Connection-specific configuration details.
  - **host** (string) - Required - The hostname or IP address of the service.
  - **port** (integer) - Required - The port number for the service.
  - **user** (string) - Optional - Username for authentication.
  - **password** (string) - Optional - Password for authentication.
  - **ssl** (boolean) - Optional - Whether to use SSL/TLS.
  - **verify** (boolean) - Optional - Whether to verify the SSL certificate.

### Request Example
```json
{
  "kind": "clickhouse",
  "name": "Production ClickHouse",
  "description": "Main logging database",
  "data": {
    "host": "clickhouse.example.com",
    "port": 8443,
    "user": "telescope",
    "password": "secret",
    "ssl": true,
    "verify": true
  }
}
```

### Response
#### Success Response (201 Created)
- **id** (integer) - The unique identifier for the newly created connection.

#### Response Example
```json
{
  "id": 1
}
```

---

## GET /api/v1/connections

### Description
Retrieves a list of all configured connections.

### Method
GET

### Endpoint
/api/v1/connections

### Parameters
#### Headers
- **Authorization** (string) - Required - API token for authentication.

### Response
#### Success Response (200 OK)
- **connections** (array) - A list of connection objects.
  - Each object contains `id`, `kind`, `name`, `description`, and `data` fields.

### Request Example
```bash
curl -X GET http://localhost:8000/api/v1/connections \
  -H "Authorization: Token YOUR_API_TOKEN"
```

---

## GET /api/v1/connections/{id}

### Description
Retrieves details for a specific connection by its ID.

### Method
GET

### Endpoint
/api/v1/connections/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the connection to retrieve.

#### Headers
- **Authorization** (string) - Required - API token for authentication.

### Response
#### Success Response (200 OK)
- **connection** (object) - The connection object with all its details.

### Request Example
```bash
curl -X GET http://localhost:8000/api/v1/connections/1 \
  -H "Authorization: Token YOUR_API_TOKEN"
```

---

## PATCH /api/v1/connections/{id}

### Description
Updates an existing connection identified by its ID.

### Method
PATCH

### Endpoint
/api/v1/connections/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the connection to update.

#### Headers
- **Authorization** (string) - Required - API token for authentication.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **kind** (string) - Optional - Type of connection.
- **name** (string) - Optional - A human-readable name for the connection.
- **description** (string) - Optional - A detailed description of the connection.
- **data** (object) - Optional - Connection-specific configuration details.

### Request Example
```json
{
  "kind": "clickhouse",
  "name": "Updated Production ClickHouse",
  "description": "Main logging database - updated",
  "data": {
    "host": "clickhouse.example.com",
    "port": 8443,
    "user": "telescope",
    "password": "new_secret",
    "ssl": true,
    "verify": true
  }
}
```

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message of the update.

#### Response Example
```json
{
  "message": "Connection updated successfully."
}
```

---

## DELETE /api/v1/connections/{id}

### Description
Deletes a connection by its ID.

### Method
DELETE

### Endpoint
/api/v1/connections/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the connection to delete.

#### Headers
- **Authorization** (string) - Required - API token for authentication.

### Response
#### Success Response (204 No Content)
- No response body.

### Request Example
```bash
curl -X DELETE http://localhost:8000/api/v1/connections/1 \
  -H "Authorization: Token YOUR_API_TOKEN"
```
```

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

### Kubernetes Source Context Columns API

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

APIs for retrieving Kubernetes context information and filtering pods.

```APIDOC
## GET /ui/v1/sources/k8s-logs/contextColumnsData

### Description
Retrieves available Kubernetes contexts and namespaces.

### Method
GET

### Endpoint
/ui/v1/sources/k8s-logs/contextColumnsData

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
```bash
curl -X GET http://localhost:8000/ui/v1/sources/k8s-logs/contextColumnsData \
  -H "Cookie: sessionid=YOUR_SESSION"
```

### Response
#### Success Response (200)
- **result** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains lists of available contexts and namespaces.
  - **contexts** (array of strings) - List of Kubernetes contexts.
  - **namespaces** (array of strings) - List of Kubernetes namespaces.

#### Response Example
```json
{
  "result": true,
  "data": {
    "contexts": ["production-cluster", "staging-cluster"],
    "namespaces": ["default", "kube-system", "app-namespace"]
  }
}
```

## POST /ui/v1/sources/k8s-logs/contextColumnData

### Description
Retrieves a list of pods based on specified filtering parameters.

### Method
POST

### Endpoint
/ui/v1/sources/k8s-logs/contextColumnData

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **column** (string) - Required - The column to retrieve data for (e.g., "pods").
- **params** (object) - Required - Filtering parameters.
  - **contexts** (array of strings) - Optional - List of contexts to filter by.
  - **namespaces** (array of strings) - Optional - List of namespaces to filter by.
  - **pods_label_selector** (string) - Optional - Label selector for pods.
  - **pods_field_selector** (string) - Optional - Field selector for pods.
  - **pods_flyql_filter** (string) - Optional - FlyQL filter for pods.

### Request Example
```json
{
  "column": "pods",
  "params": {
    "contexts": ["production-cluster"],
    "namespaces": ["app-namespace"],
    "pods_label_selector": "app=web",
    "pods_field_selector": "status.phase=Running",
    "pods_flyql_filter": ""
  }
}
```

### Response
#### Success Response (200)
- **result** (boolean) - Indicates if the operation was successful.
- **data** (object) - The filtered list of pods.

#### Response Example
```json
{
  "result": true,
  "data": { ... }
}
```

## POST /ui/v1/sources/k8s-logs/dataAndGraph

### Description
Queries Kubernetes logs with various filtering options including context, namespace, and pod selection.

### Method
POST

### Endpoint
/ui/v1/sources/k8s-logs/dataAndGraph

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **query** (string) - Required - The query string to filter logs.
- **from** (integer) - Required - The start timestamp in milliseconds.
- **to** (integer) - Required - The end timestamp in milliseconds.
- **limit** (integer) - Optional - The maximum number of log entries to return.
- **columns** (array) - Optional - Columns to include in the response.
- **group_by** (array) - Optional - Fields to group the results by.
- **context_columns** (object) - Optional - Contextual filtering, e.g., `{"contexts": ["production-cluster"], "namespaces": ["app-namespace"], "pods_label_selector": "app=web"}`.

### Request Example
```json
{
  "query": "namespace = \"app-namespace\" and pod contains \"web\"",
  "from": 1704067200000,
  "to": 1704153600000,
  "limit": 100,
  "columns": [],
  "group_by": [],
  "context_columns": {
    "contexts": ["production-cluster"],
    "namespaces": ["app-namespace"],
    "pods_label_selector": "app=web"
  }
}
```

### Response
#### Success Response (200)
- **result** (boolean) - Indicates if the operation was successful.
- **data** (object) - The log data and graph information.

#### Response Example
```json
{
  "result": true,
  "data": { ... }
}
```
```

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

### POST /ui/v1/sources/{slug}/autocomplete

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

Provides value suggestions for fields marked with `autocomplete: true`.

```APIDOC
## POST /ui/v1/sources/{slug}/autocomplete

### Description
Provides value suggestions for fields marked with `autocomplete: true`.

### Method
POST

### Endpoint
`/ui/v1/sources/<slug>/autocomplete`

### Parameters
#### Request Body
- **column** (string) - Required - The name of the column to get suggestions for.
- **from** (integer) - Required - The start timestamp in milliseconds.
- **to** (integer) - Required - The end timestamp in milliseconds.
- **value** (string) - Optional - The prefix to filter suggestions by.

### Request Example
```json
{
  "column": "service_name",
  "from": 1704067200000,
  "to": 1704153600000,
  "value": "api"
}
```

### Response
#### Success Response (200)
- **result** (boolean) - Indicates if the request was successful.
- **data** (object) - The suggestion data.
  - **items** (array) - An array of suggested values.
  - **incomplete** (boolean) - Indicates if the suggestions are incomplete.

#### Response Example
```json
{
  "result": true,
  "data": {
    "items": ["api-gateway", "api-users", "api-payments"],
    "incomplete": false
  }
}
```
```

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

### Implement Custom Data Source Fetcher in Python

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

Defines the interface for integrating new data sources into Telescope. Developers must implement methods for query validation, connection testing, schema definition, and data retrieval.

```python
from telescope.fetchers.fetcher import BaseFetcher
from telescope.fetchers.request import DataRequest, GraphDataRequest
from telescope.fetchers.response import DataResponse, GraphDataResponse, AutocompleteResponse
from telescope.fetchers.models import Row

class CustomFetcher(BaseFetcher):
    @classmethod
    def validate_query(cls, source, query):
        if not query:
            return True, None
        try:
            return True, None
        except Exception as e:
            return False, str(e)

    @classmethod
    def test_connection(cls, data: dict):
        response = ConnectionTestResponse()
        try:
            response.reachability["result"] = True
            response.schema["result"] = True
            response.schema["data"] = cls.get_schema(data)
        except Exception as e:
            response.reachability["error"] = str(e)
        return response

    @classmethod
    def get_schema(cls, data: dict):
        from telescope.utils import get_telescope_column
        return [
            get_telescope_column("time", "datetime"),
            get_telescope_column("level", "string"),
            get_telescope_column("message", "string"),
        ]

    @classmethod
    def fetch_data(cls, request: DataRequest, tz):
        rows = []
        for record in query_your_source(request):
            row = Row(
                source=request.source,
                selected_columns=["time", "level", "message"],
                values=[record.timestamp, record.level, record.message],
                tz=tz
            )
            rows.append(row)
        return DataResponse(rows=rows[:request.limit])

    @classmethod
    def fetch_graph_data(cls, request: GraphDataRequest):
        timestamps = []
        data = {"Rows": []}
        total = 0
        return GraphDataResponse(timestamps=timestamps, data=data, total=total)

    @classmethod
    def autocomplete(cls, source, column, time_from, time_to, value):
        items = []
        return AutocompleteResponse(items=items, incomplete=len(items) >= 500)
```

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

### Query Logs with Raw SQL WHERE Clause

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

Queries application logs using a raw SQL WHERE clause, which requires the RAW_QUERY permission. This allows for more complex filtering directly in SQL. The response includes query results.

```shell
curl -X POST http://localhost:8000/ui/v1/sources/app-logs/data \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "", \
    "raw_query": "JSONExtractString(metadata, '\''service'\'') = '\''api'\''", \
    "from": 1704067200000, \
    "to": 1704153600000, \
    "limit": 50, \
    "columns": [], \
    "context_columns": {} \
  }'
```

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

### Manage Log Sources via REST API

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

Endpoints to define and manage log sources, including schema mapping and display configuration. Sources are linked to existing connections to enable structured log querying.

```bash
# Create a ClickHouse source
curl -X POST http://localhost:8000/api/v1/sources \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "clickhouse",
    "slug": "app-logs",
    "name": "Application Logs",
    "description": "Production application logs",
    "connection": {
      "connection_id": 1
    },
    "time_column": "timestamp",
    "date_column": "date",
    "uniq_column": "trace_id",
    "severity_column": "level",
    "columns": {
      "timestamp": {
        "display_name": "Time",
        "type": "DateTime64",
        "jsonstring": false,
        "autocomplete": false,
        "suggest": true,
        "group_by": false,
        "values": []
      },
      "level": {
        "display_name": "Level",
        "type": "String",
        "jsonstring": false,
        "autocomplete": true,
        "suggest": true,
        "group_by": true,
        "values": ["DEBUG", "INFO", "WARN", "ERROR"]
      },
      "message": {
        "display_name": "Message",
        "type": "String",
        "jsonstring": false,
        "autocomplete": false,
        "suggest": true,
        "group_by": false,
        "values": []
      }
    },
    "default_chosen_columns": ["timestamp", "level", "message"]
  }'

# List all sources
curl -X GET http://localhost:8000/api/v1/sources \
  -H "Authorization: Token YOUR_API_TOKEN"

# Get specific source by slug
curl -X GET http://localhost:8000/api/v1/sources/app-logs \
  -H "Authorization: Token YOUR_API_TOKEN"

# Delete source
curl -X DELETE http://localhost:8000/api/v1/sources/app-logs \
  -H "Authorization: Token YOUR_API_TOKEN"
```

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

### Create a Saved View

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

Creates a new saved view, which stores a specific query configuration including filters, columns, and time range. Saved views can be personal or shared at the source level, aiding in reproducible analysis.

```shell
curl -X POST http://localhost:8000/ui/v1/sources/app-logs/savedViews \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ \
    "name": "Error Investigation", \
    "description": "View for investigating error logs", \
    "scope": "personal", \
    "shared": false, \
    "data": { \
      "query": "level = \"ERROR\"", \
      "columns": ["timestamp", "level", "message", "trace_id"], \
      "timeRange": {"type": "relative", "value": "1h"} \
    } \
  }'
```

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

### CSS: Global Styles and Typography

Source: https://github.com/iamtelescope/telescope/blob/main/backend/telescope/templates/auth.html

These CSS rules define global styles for the page, including font imports, background color, text color, font size, and font family. It sets up the foundational visual elements for the entire application.

```css
@import url('https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300..800;1,300..800&display=swap');
body {
  background-color: #141919;
  color: #333;
  font-size: 13px;
  font-family: "Open Sans";
}
```

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

### Manage RBAC roles for sources

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

Allows granting, revoking, and listing role bindings for users or groups on specific data sources. Supports various roles such as admin, owner, editor, viewer, and user.

```bash
curl -X POST http://localhost:8000/ui/v1/sources/app-logs/grantRole \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "viewer",
    "subject": {
      "kind": "user",
      "name": "john.doe"
    }
  }'

curl -X GET http://localhost:8000/ui/v1/sources/app-logs/roleBindings \
  -H "Cookie: sessionid=YOUR_SESSION"

curl -X POST http://localhost:8000/ui/v1/sources/app-logs/revokeRole \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "viewer",
    "subject": {
      "kind": "user",
      "name": "john.doe"
    }
  }'
```

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

### Query Logs with FlyQL Filter

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

Queries application logs using the FlyQL query language with specified filters, time range, and desired columns. The response includes query results and metadata.

```shell
curl -X POST http://localhost:8000/ui/v1/sources/app-logs/data \
  -H "Cookie: sessionid=YOUR_SESSION" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": "level = \"ERROR\" and message contains \"timeout\"", \
    "from": 1704067200000, \
    "to": 1704153600000, \
    "limit": 100, \
    "columns": [ \
      {"name": "timestamp", "display_name": "Time"}, \
      {"name": "level", "display_name": "Level"}, \
      {"name": "message", "display_name": "Message"} \
    ], \
    "context_columns": {} \
  }'
```

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

### POST /ui/v1/sources/docker-logs/dataAndGraph

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

Queries Docker logs with a container filter. Allows specifying a time range, limit, and context columns for filtering.

```APIDOC
## POST /ui/v1/sources/docker-logs/dataAndGraph

### Description
Queries Docker logs with a container filter. Allows specifying a time range, limit, and context columns for filtering.

### Method
POST

### Endpoint
/ui/v1/sources/docker-logs/dataAndGraph

### Parameters
#### Query Parameters
None

#### Request Body
- **query** (string) - Required - The query string to filter logs.
- **from** (integer) - Required - The start timestamp in milliseconds.
- **to** (integer) - Required - The end timestamp in milliseconds.
- **limit** (integer) - Optional - The maximum number of log entries to return.
- **columns** (array) - Optional - Columns to include in the response.
- **group_by** (array) - Optional - Fields to group the results by.
- **context_columns** (object) - Optional - Contextual filtering, e.g., `{"container": ["web-app", "redis"]}`.

### Request Example
```json
{
  "query": "stream = \"stderr\"",
  "from": 1704067200000,
  "to": 1704153600000,
  "limit": 100,
  "columns": [],
  "group_by": [],
  "context_columns": {
    "container": ["web-app", "redis"]
  }
}
```

### Response
#### Success Response (200)
- **result** (boolean) - Indicates if the operation was successful.
- **data** (object) - The log data and graph information.

#### Response Example
```json
{
  "result": true,
  "data": { ... }
}
```
```