Telescope: a self-hosted log viewer that queries ClickHouse, StarRocks, Docker and Kubernetes from one UI

The gap Telescope fills between a log database and the people who need to read it

If your logs already sit in ClickHouse or StarRocks, you have a fast query engine and no interface a support engineer can use without writing SQL. Telescope puts a web UI on top of that storage. The README describes it as a web application providing an interface for exploring log data, with ClickHouse and StarRocks as the primary backends for structured log storage. The intended user is someone who needs to filter and read logs, not someone who wants to model them. The second audience is narrower and more interesting: teams running Docker or Kubernetes who want to read container and pod logs through the same interface they use for the database-backed sources. The README frames that support as convenient for local development, ephemeral environments or cloud-native deployments, which is an honest way of saying it is a convenience path rather than a retention strategy. Nothing in the material suggests Telescope ingests or stores logs itself. It reads from sources you already operate.

Source connections, field metadata and permissions are the actual product

The mechanism that matters is source configuration. You create a connection to a ClickHouse or StarRocks database, a Docker daemon, or a Kubernetes cluster, and Telescope queries it. Each source carries field-level configuration: the README states you define which fields from a source should be used, and configure which ones are suggested, hidden, or support autocompletion. That metadata layer is what turns a raw table into something a non-SQL user can navigate, and it is per source. Access control sits on the same object. You configure which users and groups have access to a source and define their permissions. Authentication runs through GitHub, with the option to enforce organization membership as a gate. The data explorer then layers filtering, a time and date selector with relative ranges, column selection and graph grouping on top, including grouping by nested fields such as JSON strings, Maps or Arrays. The architecture implied by the repository topics is a Django backend with a Vue single-page frontend, which matches the split between server-side source connectors and a browser-side query builder. The most consequential detail is RAW SQL filtering: Telescope accepts a WHERE clause written in ClickHouse or StarRocks SQL expressions and passes it to the backend. That is the escape hatch for anything the UI cannot express, and it is also the sharpest edge in the product.

Getting an instance running from the documented quickstart

The README points to two entry points: the documentation site at docs.iamtelescope.net and a Docker quickstart linked from the whale icon section, described as running locally using Docker. A live demo instance exists at demo.iamtelescope.net with GitHub login, and the README notes that it does not expose administrative features, so you cannot evaluate source configuration there. That matters, because source configuration is where the work is. The material does not include the compose file contents, environment variable names or the exact command, so I cannot give you a verified invocation. What the README does establish is the shape of the setup: run the application, log in with GitHub, then create source connections for ClickHouse, StarRocks, Docker or Kubernetes and assign users and groups to them. Two constraints follow from that. First, GitHub is the only authentication method described, and the README marks SAML and other methods as decided against for the stable release. Second, the Docker path is presented as the local option, so plan on reading the documentation site for the production topology rather than treating the quickstart as a deployment guide.

The beta label is not boilerplate, and the missing pieces are the ones operators ask for first

Telescope's README carries a warning that the project is in beta, listing incomplete features, components that may behave inconsistently, bugs, and a system that may not yet offer full convenience or polish from a development and operational perspective. That is more specific than the usual disclaimer. The 1.0.0 milestone makes the gaps concrete: display records in context, snapshot storage for long-term retention of log records to prevent data loss due to rotation, live log trailing, a Helm chart, and an audit log for changes inside the system are all listed as future work. Two entries were struck through as deliberately dropped: server-side modifiers using ClickHouse functions, and SAML support. Read that list as a boundary. There is no live tail, so Telescope is a search tool, not a monitoring console you leave open during an incident. There is no snapshot storage, so your retention window is whatever ClickHouse or StarRocks keeps, and Docker or Kubernetes rotation can take logs out from under you. There is no audit log, so changes to source configuration and permissions are not recorded by the system itself. The absence of a Helm chart means Kubernetes deployment is manual for now. None of these are defects in a pre-1.0 project. They are reasons to check whether your workflow depends on them before you commit.

Where RAW SQL filtering changes your threat model

The README advertises advanced queries with RAW SQL filtering using a WHERE clause with ClickHouse or StarRocks SQL expressions. The permission model described in the README is per-source: users and groups get access to a source, and that access is defined by role. What the material does not describe is any restriction on the SQL that reaches the backend once a user has access to a source. If the WHERE expression is forwarded as written, then the effective security boundary is your ClickHouse or StarRocks user's grants, not Telescope's role model. A read-only database user with a narrow table scope keeps that contained. A broadly privileged connection turns every user with source access into a broadly privileged SQL client. I cannot confirm from the README whether Telescope parses, rewrites or sandboxes the expression, and I am not going to guess. This is the first thing to verify in the documentation or the source before you point Telescope at a production cluster. The same question applies to Docker and Kubernetes sources, where the daemon or cluster credentials Telescope holds determine what any authenticated user can read.

Telescope against Grafana and Kibana on the same logs

The obvious alternative for ClickHouse-backed logs is Grafana with the ClickHouse data source plugin. Grafana is a general dashboarding tool that happens to query logs; Telescope is a log viewer that happens to support four source types. The difference in approach shows up in configuration. Grafana asks you to write queries and build panels, and its access control is organized around dashboards, folders and data source permissions. Telescope asks you to describe a source's fields once (which are suggested, hidden, autocompleting) and then hands the user a filter UI built around that description. For a team whose logs live in ClickHouse and whose readers are not comfortable in a query editor, Telescope's field metadata is the feature Grafana does not have an equivalent for. For a team that also wants metrics, alerting and dashboards from the same pane, Grafana covers more ground and Telescope covers one. Kibana is the other reference point, and it is the wrong comparison unless you already run Elasticsearch, because Telescope's primary backends are ClickHouse and StarRocks. If you are on Elasticsearch, Telescope does not read it. If you are on ClickHouse and want a log-shaped UI rather than a dashboard-shaped one, the source model is the reason to look here.

What you inherit when you run Telescope: MIT licence, beta cadence, no upgrade path documented

Telescope is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and licence text are preserved. That is permissive and unremarkable, and I am not going to read more into it than that; if you fork it or ship it internally, keep the notice intact and get your own advice on anything beyond that. Maintenance cost is harder to pin down from the material. The release history shows v0.0.25 in February 2026, v0.0.26 in March, and v0.0.27 in May, so roughly monthly point releases on a 0.0.x version line. That cadence is a signal about churn, not quality. Nothing in the README or release notes describes a migration procedure between versions, a database schema Telescope maintains for its own configuration, or a supported upgrade path. Since source definitions and permissions are the state you accumulate, back up whatever stores them before you upgrade, and confirm from the documentation whether that state lives in the application database or in configuration files. The beta warning plus a 0.0.x version line means you should expect breaking changes and plan your deployment accordingly.

Editorial conclusion

Adopt Telescope if you already keep logs in ClickHouse or StarRocks and want a read-only query UI with per-source permissions without building one. Do not adopt it if you need live tailing, long-term snapshot retention or an audit trail, because the README lists all three as unimplemented future work. Before deploying, verify how your ClickHouse user is scoped, since RAW SQL filtering passes WHERE expressions straight to the backend, and check the docker-compose quickstart against your own source credentials.

Official sources

1. iamtelescope/telescope on GitHub
2. License: MIT
3. Project website
4. README
5. Releases