DuckWatch

A minimalist observability tool for MotherDuck

---

DuckWatch shows you what your MotherDuck account is doing and what it is costing you.

Key Features

• Cost estimates (per query, per user, per Duckling size, per query shape, etc.)
• Insights about queries (including finding anti-patterns such as select *, cross joins, missing filters, etc.)
• Latency and failure reports

Show more screenshots

---

Getting Started

Important

To run and use DuckWatch as described here, you need to have Docker installed on your machine. Additionally, you need a MotherDuck account on the Business or Enterprise plan, and a read-only service token created under a role with the view query history permission. The Admin and Builder preset roles include that permission by default. The Lite plan does not include query history, so DuckWatch cannot read anything on it.

1. Create a docker-compose.yml File

Save the text below as docker-compose.yml in an empty directory.

services:
    db:
        image: postgres:18-alpine
        environment:
            POSTGRES_PASSWORD: postgres
        volumes:
            - duckwatch-db:/var/lib/postgresql
        healthcheck:
            test: [ "CMD-SHELL", "pg_isready -U postgres" ]
            interval: 5s
            timeout: 5s
            retries: 5
        restart: unless-stopped

    backend:
        image: ghcr.io/cogitatortech/duck-watch-backend:latest
        environment:
            DATABASE_URL: postgres://postgres:postgres@db:5432/postgres?sslmode=disable
            TOKEN_ENCRYPTION_KEY: ${TOKEN_ENCRYPTION_KEY:?run the key command below first}
        depends_on:
            db:
                condition: service_healthy
        restart: unless-stopped

    web:
        image: ghcr.io/cogitatortech/duck-watch-web:latest
        ports:
            - "3000:80"
        depends_on:
            - backend
        restart: unless-stopped

volumes:
    duckwatch-db:

2. Encryption Key

Generate and write an encryption key into a .env file beside docker-compose.yml.

printf 'TOKEN_ENCRYPTION_KEY="%s"\n' "$(openssl rand -base64 32)" > .env

3. Starting DuckWatch

Run docker compose up -d in the directory where docker-compose.yml is, and open http://localhost:3000 in your browser.

Managing DuckWatch Containers

You can use docker compose commands to manage the DuckWatch containers:

docker compose up -d      # Start DuckWatch
docker compose stop       # Stop DuckWatch (data is kept)
docker compose down -v    # Remove everything, including the database
docker compose logs -f    # Check the log stream

---

Contributing

See CONTRIBUTING.md for details on how to make a contribution.

License

DuckWatch is licensed under the Apache License, Version 2.0 (see LICENSE).