Make external service clients optional

.github/workflows/python-app.yml

@@ -30,6 +30,33 @@ permissions:
   contents: read
 
 jobs:
+  core-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: "3.14"
+          prune-cache: true
+
+      - name: Build the wheel
+        run: uv build --wheel
+
+      - name: Install without extras
+        run: |
+          uv venv --python 3.14 .core-venv
+          uv pip install --python .core-venv/bin/python dist/*.whl
+
+      - name: Test the default installation
+        run: .core-venv/bin/python tests/core_install_smoke.py
+
   build:
     runs-on: ubuntu-latest
     strategy:

Dockerfile

@@ -59,8 +59,9 @@ COPY --from=builder /build/dist/*.whl /tmp/
 # Install the wheel and remove temporary artifacts.
 # With the slim runtime image this should resolve binary dependencies from
 # prebuilt wheels instead of compiling NumPy/SciPy from source.
-RUN uv pip install --system --no-cache /tmp/apache_otava-*.whl \
-    && rm /tmp/apache_otava-*.whl \
+RUN set -- /tmp/apache_otava-*.whl \
+    && uv pip install --system --no-cache "${1}[all]" \
+    && rm "${1}" \
     && rm /usr/local/bin/uv
 
 # Switch to otava user

README.md

@@ -34,6 +34,26 @@ integrated with a pull request.
 
 See the documentation in https://otava.apache.org/docs/overview/.
 
+## Installation
+
+The default package includes the Otava library and CLI, with support for CSV,
+JSON, and Graphite data:
+
+```bash
+pip install apache-otava
+```
+
+Install extras for additional integrations. Extras can be combined, or install
+`all` to enable every integration:
+
+```bash
+pip install 'apache-otava[bigquery]'
+pip install 'apache-otava[postgres,slack]'
+pip install 'apache-otava[all]'
+```
+
+See the [installation guide](docs/INSTALL.md) for the complete list of extras.
+
 ## Supported Python Versions
 
 Apache Otava is tested against Python 3.10, 3.11, 3.12, 3.13, and 3.14.

docs/BASICS.md

@@ -78,29 +78,28 @@ The results are simply concatenated.
 ### Example
 
 > [!TIP]
-> See [otava.yaml](../examples/csv/config/otava.yaml) for the full
-> example configuration and [local_samples.csv](../examples/csv/data/local_samples.csv)
+> See [otava-local.yaml](../examples/csv/config/otava-local.yaml) for the full
+> example configuration and [local_sample.csv](../examples/csv/data/local_sample.csv)
 > for the data.
 
-```
-$ otava analyze local.sample --since=2024-01-01
-INFO: Computing change points for test sample.csv...
-sample:
-time                         metric1    metric2
--------------------------  ---------  ---------
-2021-01-01 02:00:00 +0000     154023      10.43
-2021-01-02 02:00:00 +0000     138455      10.23
-2021-01-03 02:00:00 +0000     143112      10.29
-2021-01-04 02:00:00 +0000     149190      10.91
-2021-01-05 02:00:00 +0000     132098      10.34
-2021-01-06 02:00:00 +0000     151344      10.69
-                                      ·········
-                                         -12.9%
-                                      ·········
-2021-01-07 02:00:00 +0000     155145       9.23
-2021-01-08 02:00:00 +0000     148889       9.11
-2021-01-09 02:00:00 +0000     149466       9.13
-2021-01-10 02:00:00 +0000     148209       9.03
+```console
+$ otava analyze local.sample --since=2026-01-01T00:00:00Z
+INFO: Computing change points for test local.sample...
+time                       commit      metric1    metric2
+-------------------------  --------  ---------  ---------
+2026-01-01 02:00:00 +0000  aaa0         154023      10.43
+2026-01-02 02:00:00 +0000  aaa1         138455      10.23
+2026-01-03 02:00:00 +0000  aaa2         143112      10.29
+2026-01-04 02:00:00 +0000  aaa3         149190      10.91
+2026-01-05 02:00:00 +0000  aaa4         132098      10.34
+2026-01-06 02:00:00 +0000  aaa5         151344      10.69
+                                                ·········
+                                                   -12.9%
+                                                ·········
+2026-01-07 02:00:00 +0000  aaa6         155145       9.23
+2026-01-08 02:00:00 +0000  aaa7         148889       9.11
+2026-01-09 02:00:00 +0000  aaa8         149466       9.13
+2026-01-10 02:00:00 +0000  aaa9         148209       9.03
 ```
 
 ## Avoiding test definition duplication
@@ -223,4 +222,4 @@ The `--branch` option can also be set via the `BRANCH` environment variable:
 
 ```
 BRANCH=feature-xyz otava analyze my-product.test
-```
+```

docs/BIG_QUERY.md

@@ -19,6 +19,12 @@
 
 # BigQuery
 
+## Installation
+
+```bash
+pip install 'apache-otava[bigquery]'
+```
+
 ## Schema
 
 See [schema.sql](../examples/bigquery/schema.sql) for the example schema.

docs/CSV.md

@@ -56,25 +56,26 @@ per-test settings and defaults are unchanged.
 ## Example
 
 ```bash
-docker-compose -f examples/csv/docker-compose.yaml run --rm otava analyze local.sample
+docker-compose -f examples/csv/docker-compose.yaml run --rm otava \
+  analyze local.sample --since=2026-01-01T00:00:00Z
 ```
 
 Expected output:
 
-```bash
+```text
 time                       commit      metric1    metric2
 -------------------------  --------  ---------  ---------
-2024-01-01 02:00:00 +0000  aaa0         154023      10.43
-2024-01-02 02:00:00 +0000  aaa1         138455      10.23
-2024-01-03 02:00:00 +0000  aaa2         143112      10.29
-2024-01-04 02:00:00 +0000  aaa3         149190      10.91
-2024-01-05 02:00:00 +0000  aaa4         132098      10.34
-2024-01-06 02:00:00 +0000  aaa5         151344      10.69
+2026-01-01 02:00:00 +0000  aaa0         154023      10.43
+2026-01-02 02:00:00 +0000  aaa1         138455      10.23
+2026-01-03 02:00:00 +0000  aaa2         143112      10.29
+2026-01-04 02:00:00 +0000  aaa3         149190      10.91
+2026-01-05 02:00:00 +0000  aaa4         132098      10.34
+2026-01-06 02:00:00 +0000  aaa5         151344      10.69
                                                 ·········
                                                    -12.9%
                                                 ·········
-2024-01-07 02:00:00 +0000  aaa6         155145       9.23
-2024-01-08 02:00:00 +0000  aaa7         148889       9.11
-2024-01-09 02:00:00 +0000  aaa8         149466       9.13
-2024-01-10 02:00:00 +0000  aaa9         148209       9.03
+2026-01-07 02:00:00 +0000  aaa6         155145       9.23
+2026-01-08 02:00:00 +0000  aaa7         148889       9.11
+2026-01-09 02:00:00 +0000  aaa8         149466       9.13
+2026-01-10 02:00:00 +0000  aaa9         148209       9.03
 ```

docs/GETTING_STARTED.md

@@ -27,16 +27,36 @@ Otava requires Python 3.10 or later.
 pip install apache-otava
 ```
 
+This installs the Otava library and CLI with CSV, JSON, and Graphite
+support. Install the extra for any additional service you use, for example:
+
+```bash
+pip install 'apache-otava[postgres]'
+pip install 'apache-otava[bigquery,slack]'
+```
+
+See [Installation](INSTALL.md) for the complete list of extras.
+
 or
 
 ```bash
 docker pull apache/otava
 ```
 
+The Docker image includes all optional integrations.
+
 
 ## Setup
 
-Copy the main configuration file `resources/otava.yaml` to `~/.otava/otava.yaml` and adjust data source configuration.
+By default, Otava reads configuration from `~/.otava/otava.yaml`. Create that
+file and add the data sources and tests you want to analyze.
+
+To run the bundled CSV example from a source checkout, use its local
+configuration while running the commands in this guide:
+
+```bash
+export OTAVA_CONFIG=examples/csv/config/otava-local.yaml
+```
 
 > [!TIP]
 > See docs on specific data sources to learn more about their configuration - [CSV](CSV.md), [Graphite](GRAPHITE.md),
@@ -132,23 +152,22 @@ The results are simply concatenated.
 
 ## Example
 
-```
-$ otava analyze local.sample
-INFO: Computing change points for test sample.csv...
-sample:
-time                         metric1    metric2
--------------------------  ---------  ---------
-2021-01-01 02:00:00 +0000     154023      10.43
-2021-01-02 02:00:00 +0000     138455      10.23
-2021-01-03 02:00:00 +0000     143112      10.29
-2021-01-04 02:00:00 +0000     149190      10.91
-2021-01-05 02:00:00 +0000     132098      10.34
-2021-01-06 02:00:00 +0000     151344      10.69
-                                      ·········
-                                         -12.9%
-                                      ·········
-2021-01-07 02:00:00 +0000     155145       9.23
-2021-01-08 02:00:00 +0000     148889       9.11
-2021-01-09 02:00:00 +0000     149466       9.13
-2021-01-10 02:00:00 +0000     148209       9.03
+```console
+$ otava analyze local.sample --since=2026-01-01T00:00:00Z
+INFO: Computing change points for test local.sample...
+time                       commit      metric1    metric2
+-------------------------  --------  ---------  ---------
+2026-01-01 02:00:00 +0000  aaa0         154023      10.43
+2026-01-02 02:00:00 +0000  aaa1         138455      10.23
+2026-01-03 02:00:00 +0000  aaa2         143112      10.29
+2026-01-04 02:00:00 +0000  aaa3         149190      10.91
+2026-01-05 02:00:00 +0000  aaa4         132098      10.34
+2026-01-06 02:00:00 +0000  aaa5         151344      10.69
+                                                ·········
+                                                   -12.9%
+                                                ·········
+2026-01-07 02:00:00 +0000  aaa6         155145       9.23
+2026-01-08 02:00:00 +0000  aaa7         148889       9.11
+2026-01-09 02:00:00 +0000  aaa8         149466       9.13
+2026-01-10 02:00:00 +0000  aaa9         148209       9.03
 ```

docs/GRAFANA.md

@@ -19,6 +19,14 @@
 
 # Annotating Change Points in Grafana
 
+## Installation
+
+```bash
+pip install 'apache-otava[grafana]'
+```
+
+## Usage
+
 Change points found by `analyze` can be exported
 as Grafana annotations using the `--update-grafana` flag:
 
@@ -55,18 +63,17 @@ Start docker-compose with Graphite in one tab:
 
 ```bash
 docker-compose -f examples/graphite/docker-compose.yaml up --force-recreate --always-recreate-deps --renew-anon-volumes
-````
-
+```
 
 Run otava in another tab:
 
 ```bash
 docker-compose -f examples/graphite/docker-compose.yaml run --rm  otava analyze my-product.test --since=-10m --update-grafana
 ```
 
-Expected output:
+Example output (timestamps reflect when the example is run):
 
-```bash
+```text
 time                       run    branch    version    commit      throughput    response_time    cpu_usage
 -------------------------  -----  --------  ---------  --------  ------------  ---------------  -----------
 2024-12-14 22:45:10 +0000                                               61160               87          0.2

docs/GRAPHITE.md

@@ -100,17 +100,17 @@ Start docker-compose with Graphite in one tab:
 
 ```bash
 docker-compose -f examples/graphite/docker-compose.yaml up --force-recreate --always-recreate-deps --renew-anon-volumes
-````
+```
 
 Run otava in another tab:
 
 ```bash
 docker-compose -f examples/graphite/docker-compose.yaml run --rm otava analyze my-product.test --since=-10m
 ```
 
-Expected output:
+Example output (timestamps reflect when the example is run):
 
-```bash
+```text
 time                       run    branch    version    commit      throughput    response_time    cpu_usage
 -------------------------  -----  --------  ---------  --------  ------------  ---------------  -----------
 2024-12-14 22:45:10 +0000                                               61160               87          0.2

docs/INFLUXDB.md

@@ -24,6 +24,12 @@ Otava imports query results from InfluxDB 3 Core or Enterprise through the
 client. SQL is the default query language; set `query_language: influxql` for
 InfluxQL queries.
 
+## Installation
+
+```bash
+pip install 'apache-otava[influxdb]'
+```
+
 ## Connection
 
 ```yaml
@@ -46,7 +52,7 @@ storage, seeds deterministic latency data, and runs Otava against it:
 ```bash
 docker build -t apache/otava:latest .
 docker compose -f examples/influxdb/docker-compose.yaml run --rm otava \
-  analyze api_latency_sql --branch main --since 2025-01-01
+  analyze api_latency_sql --branch main --since 2025-01-01T00:00:00Z
 docker compose -f examples/influxdb/docker-compose.yaml down
 ```
 
@@ -92,7 +98,7 @@ when `--branch` is supplied.
 Run the analysis with:
 
 ```bash
-otava analyze api_latency_sql --branch main --last 100
+otava analyze api_latency_sql --branch main --since 2025-01-01T00:00:00Z --last 100
 ```
 
 InfluxDB is import-only in this release; Otava does not write change points

docs/INSTALL.md

@@ -27,10 +27,32 @@ Otava requires Python 3.10 or later.
 pip install apache-otava
 ```
 
+The default installation includes the Otava library and CLI, with support for CSV,
+JSON, and Graphite data. Install an extra when you need another service:
+
+| Extra | Adds support for |
+| --- | --- |
+| `bigquery` | Google BigQuery |
+| `postgres` | PostgreSQL |
+| `influxdb` | InfluxDB 3 |
+| `grafana` | Grafana annotations |
+| `slack` | Slack notifications |
+| `all` | All optional integrations |
+
+Extras are additive. For example:
+
+```bash
+pip install 'apache-otava[bigquery]'
+pip install 'apache-otava[bigquery,postgres]'
+pip install 'apache-otava[all]'
+```
+
 ## Install using Docker
 
 Pull the official Docker image:
 
 ```bash
 docker pull apache/otava
 ```
+
+The Docker image includes all optional integrations.