Apache Otava 0.8.0 介绍与入门指南

目标：介绍 Apache Otava——面向持续性能工程（Continuous Performance Engineering）的开源性能回归检测 CLI，用统计方法从基准测试时间序列中自动检出性能变点（change point）并判定回归；覆盖孵化状态、项目定位与核心概念、PyPI 包名核实（关键坑）、Python 3.10 venv 安装、CLI 子命令清单与配置文件格式、50 点 CSV 注入 +30% 性能回归的检出实测、analyze 三种输出格式与常用参数、适用场景与常见问题。官方信息核实与全部命令均在 Ubuntu 22.04 环境于 2026-10-15 实测完成；Graphite/Grafana/PostgreSQL/BigQuery/Slack 等集成本文未实测，以官方文档为准。

⚠️ 提示：PyPI 包名是 apache-otava，不是 otava——实测 pip3 index versions otava 直接报 ERROR: No matching distribution found for otava，按直觉安装 otava 会失败。安装与搜索请认准 apache-otava（详见 4.1 节）。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Python：3.10.12 / pip 22.0.2（apt 安装 python3、python3-venv、python3-pip；Otava 支持 Python 3.10–3.14）
Otava：apache-otava 0.8.0（PyPI 最新版，2026-10-15 实测；可用版本 0.8.0、0.7.0、0.6.1、0.6.0）
venv 路径：/opt/otava-venv；实验目录：/opt/otava-demo（otava.yml 配置、exec_time.csv 数据）
信息核实方式：PyPI 与 GitHub 仓库 apache/otava 均于 2026-10-15 当日抓取
实测边界：CSV 数据源全流程实测（安装、配置、validate/list/analyze、变点检出与三种输出格式）；Graphite/Grafana/PostgreSQL/BigQuery/Slack 集成未实测

二、定位与孵化状态

2.1 项目定位（官方原文）

GitHub 仓库 apache/otava 的描述原文（2026-10-15 实测抓取）：

"Change Detection for Continuous Performance Engineering"

pip 安装后的包 Summary 原文（pip show apache-otava 实测）：

"Apache Otava (Incubating): Change Detection for Continuous Performance Engineering"

拆解这段定位：

性能回归检测 CLI：输入是基准测试产生的性能指标时间序列（数据点按时间/commit 排列）；
统计方法检出变点：不是简单阈值告警，而是用统计变点检测（E-Divisive 算法，统计核心为 scipy + numpy）找出序列发生显著变化的位置，并给出变化幅度与统计显著性；
面向持续性能工程：适合接在例行基准测试之后，自动回答"哪一次提交之后性能变了、变了多少"。

2.2 孵化状态

Otava 是 Apache 孵化期项目：官方 pip 包的 Summary 即自称 "Apache Otava (Incubating)"；官网域名 otava.apache.org。评估与使用时请将孵化状态、API 与行为可能变动纳入考量，以官方文档为准。

三、核心概念与工作方式

3.1 三个核心对象

概念	含义	实测示例
test	一次基准测试的定义：数据从哪来、按什么列排序、指标是什么；test 名支持带点的命名空间	`local.exec_time`
metric	test 下的性能指标；可配 `column`（数据列名）与 `direction`（1=越高越好，-1=越高越差）	`execution_time`（direction: -1）
change point（变点）	统计意义上序列显著变化的位置；输出 index、mean_before/mean_after、pvalue、magnitude 等	index 40（见 5.5 节）

3.2 工作流程

配置文件声明 test → Otava 从数据源读入时间序列 → 统计变点检测（E-Divisive）→ 输出变点列表与回归结论（结合 metric 的 direction 判定"回归/改善"）→ 可选把变更点回写为 Grafana/PostgreSQL/BigQuery 注解或发 Slack 通知（后两项本文未实测）。

3.3 数据源

默认安装即含 CLI + CSV/JSON/Graphite 数据源；BigQuery、PostgreSQL（连同 Slack 通知）经 extras 安装：apache-otava[bigquery]、apache-otava[postgres,slack]、apache-otava[all]。本文实测 CSV 数据源。

四、安装

4.1 关键坑：PyPI 包名是 apache-otava，不是 otava

pip3 index versions otava
pip3 index versions apache-otava

实测输出：

ERROR: No matching distribution found for otava
apache-otava (0.8.0)
Available versions: 0.8.0, 0.7.0, 0.6.1, 0.6.0

正确包名：apache-otava，最新版 0.8.0（截至 2026-10-15）；直接按 otava 安装/搜包会踩坑；
官方 README 指定的安装方式即 pip install apache-otava，无需从源码安装；
支持 Python 3.10–3.14（实测环境 3.10.12，兼容）。

4.2 venv 安装

python3 -m venv /opt/otava-venv
/opt/otava-venv/bin/pip install apache-otava

实测输出（节选）：

Successfully installed apache-otava-0.8.0 ... scipy-1.15.3 numpy-2.2.0 ruamel-yaml-0.18.16
  tabulate-0.10.0 configargparse-1.8.0 python-dateutil-2.9.0.post0 pg8000-1.31.5
  google-cloud-bigquery-3.46.1 slack-sdk-3.45.0 ...（共 50+ 依赖）

依赖要点：统计核心是 scipy（E-Divisive 变点检测）+ numpy；YAML 解析用 ruamel-yaml；CLI 参数解析用 configargparse（支持环境变量与配置文件覆盖）；bigquery/pg8000/slack-sdk 等为默认打进来的集成依赖。装包时会出现 Google api_core 对 Python 3.10 的 FutureWarning，不影响功能。

4.3 核实安装（注意：没有 --version）

/opt/otava-venv/bin/pip show apache-otava | head -4

Name: apache-otava
Version: 0.8.0
Summary: Apache Otava (Incubating): Change Detection for Continuous Performance Engineering
Home-page: https://otava.apache.org

注意：otava --version 不被支持（实测报 otava: error: unrecognized arguments: --version），查版本请用 pip show apache-otava。

五、上手实测

5.1 CLI 子命令清单

otava --help 完整实测原文：

usage: otava [-h] [--config-file CONFIG_FILE] [--graphite-url GRAPHITE_URL]
             [--grafana-url GRAFANA_URL] [--grafana-user GRAFANA_USER]
             [--grafana-password GRAFANA_PASSWORD] [--slack-token SLACK_TOKEN]
             [--postgres-hostname POSTGRES_HOSTNAME]
             [--postgres-port POSTGRES_PORT]
             [--postgres-username POSTGRES_USERNAME]
             [--postgres-password POSTGRES_PASSWORD]
             [--postgres-database POSTGRES_DATABASE]
             [--bigquery-project-id BIGQUERY_PROJECT_ID]
             [--bigquery-dataset BIGQUERY_DATASET]
             [--bigquery-credentials BIGQUERY_CREDENTIALS]
             {list-tests,list-metrics,list-groups,analyze,remove-annotations,validate}
             ...

Change Detection for Continuous Performance Engineering

positional arguments:
  {list-tests,list-metrics,list-groups,analyze,remove-annotations,validate}
    list-tests          list available tests
    list-metrics        list available metrics for a test
    list-groups         list available groups of tests
    analyze             analyze performance test results
    validate            validates the tests and metrics defined in the configuration
    (remove-annotations 也在子命令列表中，但 help 未给描述)

options:
  -h, --help
  --config-file CONFIG_FILE   Otava config file path [env var: OTAVA_CONFIG]

Graphite Options:  --graphite-url [env var: GRAPHITE_ADDRESS]
Grafana Options:   --grafana-url/--grafana-user/--grafana-password [env: GRAFANA_ADDRESS/USER/PASSWORD]
Slack Options:     --slack-token [env var: SLACK_BOT_TOKEN]
PostgreSQL Options: --postgres-hostname/port/username/password/database [env: POSTGRES_*]
BigQuery Options:  --bigquery-project-id/dataset/credentials [env: BIGQUERY_PROJECT_ID/BIGQUERY_DATASET/BIGQUERY_VAULT_SECRET]

Args that start with '--' can also be set in a config file (specified via --config-file).
In general, command-line values override environment variables which override config file values which override defaults.

子命令共 6 个：list-tests / list-metrics / list-groups / analyze / remove-annotations / validate。参数优先级：命令行 > 环境变量 > 配置文件 > 默认值。

5.2 配置文件

默认读取 ~/.otava/otava.yaml（注意是 otava.yaml，.yaml 后缀）；
可用环境变量 OTAVA_CONFIG 或 --config-file 指定任意路径；没有 -c 短参数。

本次实测配置 /opt/otava-demo/otava.yml（指标=执行时间，direction: -1 表示越高越差）：

tests:
  local.exec_time:
    type: csv
    file: /opt/otava-demo/exec_time.csv
    time_column: time
    attributes: [commit]
    metrics:
      execution_time:
        column: execution_time
        direction: -1
    csv_options:
      delimiter: ","
      quote_char: "'"

配置要点：

test 名支持带点的命名空间（如 local.exec_time）；
type: csv + file（路径相对配置文件工作目录或绝对路径）+ time_column（按该列排序）；
metrics 可为简单列表 metrics: [metric1]，也可为 dict 配置 column（CSV 列名）与 direction（1=越高越好，-1=越高越差）；
attributes 声明附带的元数据列（特殊属性 commit/version 可用于 --since-commit 等时间范围过滤）；
全局可配 csv: {delimiter, quote_char}，命令行 --csv-delimiter/--csv-quote-char，环境变量 CSV_DELIMITER/CSV_QUOTE_CHAR。

5.3 构造回归数据（50 点 CSV）

实测数据 /opt/otava-demo/exec_time.csv，共 50 行（表头 time,commit,execution_time），时间格式沿用官方样例 %Y.%m.%d %H:%M:%S +0000，每日一个点，commit 为 c000…c049：

前 40 点（c000–c039）：均值 100ms ± 2ms 噪声；
后 10 点（c040–c049）：均值 130ms ± 2ms（注入 +30% 性能回归）。

数据样例（节选）：

time,commit,execution_time
2026.09.01 03:00:00 +0000,c000,100.56
2026.09.02 03:00:00 +0000,c001,98.1
...
2026.10.10 03:00:00 +0000,c039,100.31   ← 变化点前最后一个
2026.10.11 03:00:00 +0000,c040,130.82   ← 变化点后第一个
...
2026.10.20 03:00:00 +0000,c049,129.46

5.4 配置与数据自检

otava validate
otava list-tests
otava list-metrics local.exec_time

实测输出：

INFO: Checking local.exec_time
INFO: Validation finished: VALID

local.exec_time

execution_time

5.5 变点检出：analyze 实测

otava analyze local.exec_time

文本表格输出（节选照录）：

time                       commit      execution_time
-------------------------  --------  ----------------
2026-09-01 03:00:00 +0000  c000                100.56
2026-09-02 03:00:00 +0000  c001                 98.1
...（c002–c038 全部在 98–102 区间，略）
2026-10-09 03:00:00 +0000  c038                101.45
2026-10-10 03:00:00 +0000  c039                100.31
                                     ················
                                               +29.3%
                                     ················
2026-10-11 03:00:00 +0000  c040                130.82
2026-10-12 03:00:00 +0000  c041                128.18
2026-10-13 03:00:00 +0000  c042                128.91
2026-10-14 03:00:00 +0000  c043                129.16

注意：文本表格只显示了 44 行数据（c000–c043），50 行 CSV 未全部展示，属输出展示截断；完整分析结论看 JSON 输出。

--output json（完整变更点报告）：

otava analyze local.exec_time --output json

{"local.exec_time": [{"time": 1791687600, "attributes": {"commit": "c040"}, "changes": [{"metric": "execution_time", "index": 40, "time": 1791687600, "forward_change_percent": "29", "magnitude": "0.293221", "mean_before": "99.957750", "stddev_before": "1.178424", "mean_after": "129.267500", "stddev_after": "0.965955", "pvalue": "0.000000"}]}]}

解读：变化点定位在 index 40 / commit c040 / 2026-10-11 03:00:00 +0000（time 1791687600），与注入位置完全一致（无误报多余变点）；mean_before 99.957750 → mean_after 129.267500（即 99.958 → 129.268），forward_change_percent 29（文本视图显示 +29.3%），magnitude 0.293221；pvalue 0.000000（统计显著性极强）；stddev_before 1.178424 / stddev_after 0.965955。

--output regressions_only（回归通知视图）：

otava analyze local.exec_time --output regressions_only

Regressions in local.exec_time:
2026-10-11 03:00:00 +0000
    execution_time  :       100.        -->     129.    ( +29.3%)

回归检出结论：Otava 0.8.0 成功检出注入的 +30% 性能回归；direction: -1 配置下 +29.3% 被正确归类为 Regressions（执行时间变长=回归）。

5.6 analyze 常用参数

来自 otava analyze --help（2026-10-15 实测捕获）的关键参数（positional 参数 tests 可传 test 或 group 名、可多个）：

参数	说明
`--output {log,json,regressions_only}`	输出格式：文本表格 / JSON 报告 / 仅回归
`-P, --p-value PVALUE`	变点最大可接受 P 值（假阳性概率）
`-M, --magnitude MAGNITUDE`	最小变化幅度 abs(new/old - 1.0)，过滤过小变化
`--window WINDOW`	一次分析的数据点窗口大小
`--since-commit/--since-version/--since`、`--until-commit/--until-version/--until`	时间范围过滤；日期支持 ISO 及 '10 weeks ago' 人类可读格式
`--last COUNT`	只取序列末尾 N 个点
`--metrics LIST`	逗号分隔的指标过滤
`--attrs LIST`	附到报告的属性列（commit/branch/version）
`--orig-edivisive N`	用原始 E-Divisive 算法（无窗口化）
`--update-grafana / --update-postgres / --update-bigquery`	把变更点回写为注解
`--notify-slack CHANNEL...`	Slack 通知

另：analyze 输出结果前会先打印 INFO: Computing change points for test … 到 stderr（正常使用时可见；CI 重定向时注意区分，别把 INFO 当成结果输出）。

六、适用场景与局限

适用场景：

CI/例行基准测试后的自动回归检测：跑完基准交给 Otava，自动回答"性能有没有变、从哪个数据点开始变、变了多少"；
长周期性能数据审阅：按 commit/时间排列的指标序列（执行时间、吞吐等）的变点定位；
告警闭环（未实测，方向参考）：变更点回写 Grafana/PostgreSQL/BigQuery 注解、Slack 通知。

局限与注意：

统计检出需要足够的数据点与变化幅度支撑（实测 50 点、+30% 幅度可稳定检出且无误报；灵敏度可用 -P/-M 参数调节，阈值按数据自行调优）；
文本表格输出有展示截断（44/50 行），结论以 --output json 为准；
otava --version 不被支持，查版本用 pip show apache-otava；PyPI 包名是 apache-otava（4.1 节）；
孵化期项目，API 与行为可能变动。

七、常见问题

Q1：pip install otava 找不到包？ 正确包名是 apache-otava，不是 otava（4.1 节实测：otava 报 No matching distribution）。搜索、安装、依赖声明统一用 apache-otava。

Q2：otava --version 报 unrecognized arguments？ 该 CLI 不支持 --version；用 pip show apache-otava 查版本（4.3 节）。

Q3：配置文件放哪、怎么指定？ 默认 ~/.otava/otava.yaml（注意 .yaml 后缀）；临时实验用 OTAVA_CONFIG 环境变量或 --config-file 指定路径更方便；没有 -c 短参数。

Q4：GitHub 仓库的 raw 链接 404？ apache/otava 的默认分支是 master（不是 main），raw 链接用 main 会 404。

Q5：文本表格行数比 CSV 数据少？ 输出展示截断（实测 50 行只显示 44 行，c000–c043）；完整分析结论看 --output json。

Q6：INFO 日志去哪了？ analyze 的 INFO（如 INFO: Computing change points for test …）走 stderr，不混在结果输出里；管道/重定向时注意。

参考链接

官网：https://otava.apache.org
GitHub 仓库：https://github.com/apache/otava
PyPI 包页：https://pypi.org/project/apache-otava/