chore: add queries to fetch tool logs from clickhouse (#1029)

We want to expose logs from Clickhouse to our dashboard (and any users
that might want them). This adds a query to fetch the logs with basic
filtering and pagination.

SQLC doesn't support clickhouse so I tried to keep something consistent
with our SQLC definitions:

- We still write CH queries in a `queries.sql` file
- We can then ask Claude to autogenerate the code for us

It's not ideal, but it's a way to still keep something consistent while
taking advantage of some code generation.

I've added a readme and instructions so Claude can work nicely with it.

Note: the folder structure isn't very consistent with the rest of our
codebase, but I'm going to refactor this (adding `repo` folder and
moving the `impl.go` logic from `log/` to here).

Author: tgmendes

CLAUDE.md

@@ -151,6 +151,79 @@ You are an expert AI programming assistant specializing in building APIs with Go
   - Always call out when making a backwards incompatible schema change.
   - Suggest running `mise db:diff <migration-name>` after making schema changes to generate a migration file. Replace `<migration-name>` with a clear snake-case migration id such as `users-add-email-column`.
 
+## ClickHouse Queries (Telemetry Package)
+
+The `server/internal/telemetry` package uses ClickHouse for high-performance analytics queries. Unlike PostgreSQL queries, **ClickHouse queries are NOT auto-generated by sqlc** (sqlc doesn't support ClickHouse), but we follow sqlc conventions for consistency.
+
+### File Structure
+
+- **`queries.sql`**: Human-readable SQL queries with sqlc-style `-- name:` comments
+- **`queries.sql.go`**: Manual Go implementations following sqlc patterns
+- **`README.md`**: Detailed documentation and patterns specific to ClickHouse
+
+### Adding ClickHouse Queries
+
+When asked to add a new ClickHouse query to the telemetry package:
+
+1. **Add the query to `queries.sql`** with sqlc formatting:
+   ```sql
+   -- name: GetMetrics :many
+   select * from metrics where project_id = ? limit ?;
+   ```
+
+2. **Implement in `queries.sql.go`** following the pattern:
+   ```go
+   const getMetrics = `-- name: GetMetrics :many
+   select * from metrics where project_id = ? limit ?
+   `
+
+   type GetMetricsParams struct {
+       ProjectID string
+       Limit     int
+   }
+
+   func (q *Queries) GetMetrics(ctx context.Context, arg GetMetricsParams) ([]Metric, error) {
+       // Implementation following existing patterns
+   }
+   ```
+
+3. **Follow ClickHouse-specific patterns**:
+   - Use `?` placeholders (not `$1, $2, ...`)
+   - For optional filters: `(? = '' or field = ?)` pattern, pass value twice
+   - For cursor pagination: Use nil UUID sentinel (`00000000-0000-0000-0000-000000000000`)
+   - For UUIDv7 cursors: Use `UUIDv7ToDateTime(toUUID(?))` to extract timestamp
+   - No short-circuit evaluation: Use `IF()` function instead of `OR` when needed
+
+### Example: Optional Filters
+
+```sql
+where project_id = ?
+  and (? = '' or deployment_id = ?)  -- Pass empty string or value twice
+```
+
+```go
+arg.DeploymentID, arg.DeploymentID  // Pass twice for the pattern
+```
+
+### Example: Cursor Pagination
+
+```sql
+and if(
+    toUUID(?) = toUUID('00000000-0000-0000-0000-000000000000'),
+    true,
+    if(? = 'ASC', timestamp > UUIDv7ToDateTime(toUUID(?)), timestamp < UUIDv7ToDateTime(toUUID(?)))
+)
+```
+
+### Testing ClickHouse Queries
+
+- Use `testenv.Launch()` in `TestMain` for infrastructure setup
+- Add `time.Sleep(100 * time.Millisecond)` after inserts (ClickHouse eventual consistency)
+- Use table-driven tests with descriptive "it" prefix names
+- Create helper functions for test data insertion
+
+See `server/internal/telemetry/README.md` for comprehensive documentation.
+
 # Schema design rules
 
 ## Change tracking

server/internal/telemetry/README.md

@@ -0,0 +1,108 @@
+# Telemetry Package
+
+This package handles telemetry data storage and retrieval using ClickHouse for high-performance analytics queries.
+
+## ClickHouse Queries
+
+Unlike PostgreSQL queries in other packages, ClickHouse queries are **not auto-generated** by sqlc since sqlc doesn't support ClickHouse. However, we follow sqlc conventions for consistency.
+
+### Query Files
+
+- **`queries.sql`**: Human-readable SQL queries following sqlc conventions with `-- name:` comments
+- **`queries.sql.go`**: Manual Go implementations of the queries
+
+### Adding a New Query
+
+1. **Add the query to `queries.sql`** with sqlc-style formatting:
+   ```sql
+   -- name: GetSomething :one
+   select * from table where id = ?;
+   ```
+
+2. **Implement the function in `queries.sql.go`**:
+   - Extract the query as a const with the sqlc comment
+   - Create a params struct (if needed) right before the function
+   - Implement the function following existing patterns
+
+3. **Ask Claude Code to generate the implementation** - it will follow the sqlc conventions established in this package.
+
+### Example Pattern
+
+**In `queries.sql`:**
+```sql
+-- name: ListItems :many
+select id, name from items where project_id = ? limit ?;
+```
+
+**In `queries.sql.go`:**
+```go
+const listItems = `-- name: ListItems :many
+select id, name from items where project_id = ? limit ?
+`
+
+type ListItemsParams struct {
+    ProjectID string
+    Limit     int
+}
+
+func (q *Queries) ListItems(ctx context.Context, arg ListItemsParams) ([]Item, error) {
+    rows, err := q.conn.Query(ctx, listItems, arg.ProjectID, arg.Limit)
+    // ... implementation
+}
+```
+
+## Pagination
+
+This package uses cursor-based pagination with the "limit + 1" pattern:
+
+1. Client requests N items per page
+2. Query fetches N+1 items
+3. If N+1 items returned → `hasNextPage = true`, return only N items
+4. If ≤N items returned → `hasNextPage = false`, return all items
+5. Cursor is the ID of the last returned item
+
+### ClickHouse-Specific Patterns
+
+#### Nil UUID Sentinel
+ClickHouse doesn't support short-circuit evaluation in OR expressions, so we use the nil UUID (`00000000-0000-0000-0000-000000000000`) as a sentinel value to indicate "no cursor" (first page):
+
+```sql
+and if(
+    toUUID(?) = toUUID('00000000-0000-0000-0000-000000000000'),
+    true,
+    -- cursor comparison logic
+)
+```
+
+#### Optional Filters
+Use the pattern `(? = '' or field = ?)` to make filters optional:
+
+```sql
+and (? = '' or deployment_id = ?)
+```
+
+Pass empty string when filter is not needed, or pass the value twice when filtering:
+```go
+arg.DeploymentID, arg.DeploymentID  // pass twice for the pattern above
+```
+
+#### UUIDv7 Timestamp Extraction
+Use `UUIDv7ToDateTime(toUUID(?))` to extract the embedded timestamp from UUIDv7 for cursor-based pagination:
+
+```sql
+timestamp > UUIDv7ToDateTime(toUUID(?))
+```
+
+## Testing
+
+Tests use testcontainers to spin up a real ClickHouse instance. See `list_tool_logs_test.go` for examples.
+
+Key testing patterns:
+- Use `testenv.Launch()` in `TestMain` to set up infrastructure
+- Create helper functions for inserting test data
+- Use table-driven tests with descriptive names
+- Add `time.Sleep(100 * time.Millisecond)` after inserts to allow ClickHouse to make data available
+
+## Data Models
+
+See `models.go` for struct definitions with ClickHouse field tags (`ch:"field_name"`).