Monocle

Monocle 旨在为开发团队提供：

项目变更分析
根据标准展示变更的看板

它帮助团队和个人更好地组织日常工作，并检测变更生产和审查方式中的异常。

Monocle 支持 GitHub、GitLab 和 Gerrit。

如何开始使用 Monocle：

探索网站和博客：changemetrics.io
在演示实例上试用：demo.changemetrics.io
在项目 Matrix 聊天室与我们交流：#monocle:matrix.org
在讨论页面提问和讨论 Monocle
运行你自己的实例：阅读安装指南
参与开发：阅读贡献指南
查看谁在使用 Monocle

来自演示实例的 Monocle 截图

活动视图：

开发者看板：

同行实力视图：

安装

以下过程描述了如何从 GitHub 仓库索引变更，然后如何启动 Web UI 来浏览指标。

部署基于 Docker，通过 docker-compose 定义。

此外，还支持以下部署方法：

检出代码

git clone https://github.com/change-metrics/monocle.git
cd monocle
# 用默认的 API 密钥初始化 .secrets 文件，用于爬虫进程
echo CRAWLERS_API_KEY=$(uuidgen) > .secrets

创建 config.yaml 文件

crawler 和 api 服务使用 config.yaml 文件。

要爬取 GitHub 公共仓库，你必须在 https://github.com/settings/tokens 生成一个个人访问令牌（无需任何特定权限）。

然后创建配置文件 etc/config.yaml。这里有一个你可以开始使用的示例。确保在 .secrets 文件中写入 GITHUB_TOKEN=<github_token>：

---
workspaces:
  - name: monocle
    crawlers:
      - name: github-tektoncd
        provider:
          github_organization: tektoncd
          github_repositories:
            - operator
            - pipeline
        update_since: '2021-01-01'

要爬取整个 tektoncd GitHub 组织，请从文件中删除 github_repositories 条目。查看工作区部分，了解完整的配置说明。

启动 docker-compose

docker-compose 文件设置为使用 Monocle 最新稳定版本（1.11.1）的容器镜像。建议使用最新的稳定版 Monocle。然而，由于我们的 CI 发布最新（开发）容器镜像，因此可以运行最新版本。要做到这一点，请在 .env 文件中将 COMPOSE_MONOCLE_VERSION 设置为 latest。

请参阅环境变量部分。

启动 Monocle：

docker-compose up -d

确保服务正在运行且健康：

docker-compose ps

检查服务日志：

docker-compose logs -f

你应该能够在 http://localhost:8080 访问 Web UI。

如有需要，请参阅故障排除部分。

配置

Monocle 配置分为配置文件和各种环境变量。

环境变量配置系统设置和密钥。任何更改都需要重启 Monocle API。

配置文件包含非敏感数据，可以暴露在 Git 仓库中。可以在 Git 仓库之上启用 CI/CD 流程，允许 Monocle 用户提出配置更改。Monocle API 会在配置更改时自动重新加载。

环境变量

对于本地部署，默认设置就可以了。

以下设置可在 .env 文件中使用（参见 .env.sample 示例文件）：

COMPOSE_ES_XMS和COMPOSE_ES_XMX用于更改ElasticSearch JVM堆大小。默认为512m。
COMPOSE_MONOCLE_VERSION用于指定特定版本。默认使用最新稳定版本。
COMPOSE_MONOCLE_API_ADDR用于设置容器暴露Monocle API的绑定地址。
COMPOSE_MONOCLE_API_PORT用于设置容器暴露Monocle API的绑定端口。
COMPOSE_MONOCLE_PUBLIC_URL用于配置访问UI和API的公共URL。认证过程中进行用户重定向时需要此URL。默认为http://localhost:8080
COMPOSE_MONOCLE_WEBAPP_TITLE用于更改Web应用程序的标题。默认为Monocle。

.secrets文件中可用以下设置：

MONOCLE_JWK_GEN_KEY用于设置本地JWT发行者密钥。密钥长度必须至少为64个字符。默认情况下会自动生成密钥。
MONOCLE_OIDC_<PROVIDER_NAME>_CLIENT_SECRET用于设置Monocle请求ID令牌时使用的密钥（默认未设置）。
MONOCLE_ADMIN_TOKEN用于设置访问管理端点的令牌。默认未设置且端点停用。

配置文件

Monocle配置文件由API和爬虫进程使用。文件格式为YAML。

该文件配置以下内容：

Monocle工作区
关于 WEB应用程序端点
认证系统

您可能想使用Dhall来管理它或更好地理解其架构（dhall-monocle）。

工作区

工作区使用专用的ElasticSearch索引。工作区定义了：

爬虫 - 详情
项目 - 详情
身份 - 详情
群组 - 详情
搜索别名 - 详情

爬虫

Monocle提供两种爬虫：

Change：用于获取提交到仓库的变更的爬虫。Monocle支持Gerrit（Reviews）、GitHub（Pull-Requests）、GitLab（Merge-Requests）。
TaskData：用于获取与仓库相关的任务数据的爬虫。Monocle支持GitHub（issues）和BugZilla（Bugs）。

.secrets文件用于存储爬虫向提供商进行身份验证时使用的凭据和API密钥。

crawlers值是爬虫列表。每个爬虫由以下部分组成：

name：用于标识爬虫的任意名称。
update_since：爬虫将获取自该日期以来创建/更新的变更。
provider：提供商设置

workspaces:
  - name: demo
    crawlers:
      - name: spinnaker
        update_since: "2020-01-01"
        provider: {}

Change

GitHub提供商设置

  provider:
    github_organization: spinnaker
    # 可选设置
    github_repositories:
      - pipeline
    github_url: https://github.com/api/graphql
    github_token: GITHUB_TOKEN

github_organization是唯一必需的键。如果未指定github_repositories，则爬虫将爬取整个组织的仓库。如果指定了，则只会爬取列出的仓库。要爬取个人GitHub帐户的仓库，您需要将 github_organization设置为您的帐户名，并在github_repositories键下列出仓库。

如果使用替代URL，可以指定github_url。默认为"https://github.com/api/graphql"。

可以指定github_token以使用替代环境变量名来查找令牌值。默认为"GITHUB_TOKEN"

关于GitHub令牌（经典）：

要爬取公共仓库，不需要特定的作用域（不选中任何复选框）。
要爬取私有仓库，必须设置"repo"作用域。

关于GitHub细粒度令牌（新）：

要爬取公共仓库，保持选中"Public Repositories (read-only)"复选框。不需要其他设置。
要爬取私有仓库，选择"All repositories"或"Only select repositories"，然后在"Repository permissions" 中选择"Pull Requests"、"Contents"为"Read-only"。

GitHub提供商还可以配置为爬取特定GitHub用户创建的Pull-Requests。例如，以下爬虫的提供商将获取john和jane用户的Pull-Requests和相关事件：

  provider:
    github_users:
      - john
      - jane
    # 可选设置
    github_url: https://github.com/api/graphql
    github_token: GITHUB_TOKEN

Gerrit提供商设置

  provider:
    gerrit_url: https://review.opendev.org
    gerrit_repositories:
      - openstack/nova
      - openstack/neutron
    # 可选设置
    gerrit_login: monocle
    gerrit_password: GERRIT_PASSWORD
    gerrit_prefix: opendev/

gerrit_url是必需的，必须是Gerrit提供商的URL。 gerrit_repositories是必需的，是爬虫将从中获取Reviews的仓库列表。

可以指定gerrit_login以在提供商API上进行身份验证。可以指定gerrit_password以使用替代环境变量名来查找密码。默认为"GERRIT_PASSWORD"

可以设置gerrit_prefix以配置爬虫在仓库名称前添加前缀。

GitLab提供商设置

  provider:
    gitlab_organization: redhat/centos-stream/ci-cd/zuul
    # 可选设置
    gitlab_repositories:
      - jobs-config
    gitlab_url: https://gitlab.com/api/graphql
    gitlab_token: GITLAB_TOKEN

gitlab_organization 是唯一必填的键。如果未指定 gitlab_repositories，爬虫将爬取整个组织的仓库。如果指定了，则只会爬取列出的仓库。

如果使用其他URL，可以指定 gitlab_url。默认值为 "https://gitlab.com/api/graphql"。

可以指定 gitlab_token 来使用其他环境变量名查找令牌值。默认为 "GITLAB_TOKEN"。

要爬取私有仓库，你必须生成一个具有 "read_api" 权限的个人访问令牌。

任务数据

Monocle 提供额外的爬虫，通过匹配 change_url 将任务/问题/RFE 附加到变更上。然后，变更会被增强，包含相关任务的信息，如 priority 或 score。

对于 GitHub：

GitHub 任务数据爬虫会在 GitHub 变更爬虫定义中指定仓库时自动运行。

使用"精细"令牌访问私有仓库时，请确保选择"Issues"权限。

对于 Bugzilla：

Bugzilla 提供者设置

  provider:
    bugzilla_url: https://redhat.bugzilla.com
    bugzilla_products:
      - Awesome product
    # 可选设置
    bugzilla_token: BUGZILLA_TOKEN

必须指定 bugzilla_product。爬虫将爬取列出的产品中包含外部错误引用 ext_bz_bug_id 的 bug。爬虫假定外部引用用于链接到变更（拉取请求/审查）。

可以指定 bugzilla_token 来使用其他环境变量名查找令牌值。默认为 "BUGZILLA_TOKEN"。

注意，此爬虫由 crawler 容器管理。

项目定义

可以在工作区配置中定义项目。项目由名称标识，并允许设置以下筛选属性：

repository_regex
branch_regex
file_regex

以下是配置示例。

workspaces:
  - name: example
    crawlers:
      - name: openstack
        provider:
          gerrit_url: https://review.opendev.org
          gerrit_repositories:
            - ^openstack/.*
        update_since: "2021-01-01"
    projects:
      - name: compute
        repository_regex: ".*nova.*"
      - name: compute-tests
        file_regex: "test[s]/.*"
        repository_regex: ".*nova.*"
      - name: deployment
        repository_regex: ".*tripleo.*|.*puppet.*|.*ansible.*"
        branch_regex: "master"

可以查询 Monocle API 端点 api/1/get_projects 以获取给定工作区的已定义项目列表。参见 Monocle OpenAPI。

Monocle 查询端点处理查询参数：project。

身份管理

Monocle 能够从多个代码审查系统索引变更。一个贡献者可能在不同的代码审查系统中有不同的身份。因此，Monocle 提供了一个配置部分来为贡献者定义别名。

假设 Monocle 工作区配置为从 github.com 和 review.opendev.org（Gerrit）获取变更，我们希望 John 的指标在 John Doe 身份下合并。

workspaces:
  - name: example
    idents:
      - ident: John Doe
        aliases:
          - github.com/john-doe
          - review.opendev.org/John Doe/12345
          - AuthProviderUID:jdoe
    crawlers:
      - name: github-containers
        provider:
          github_organization: containers
          github_token: <github_token>
        update_since: '2000-01-01'

      - name: gerrit-opendev
        provider:
          gerrit_url: https://review.opendev.org
          gerrit_repositories:
            - ^openstack/.*
        update_since: '2000-01-01'

github.com 或 GitHub 企业实例上的贡献者 ID 格式为 <域名>/<登录名>。

Gerrit 实例上的贡献者 ID 格式为 <域名>/<全名>/<gerrit-用户-id>。

应用身份配置

必须更新数据库对象以反映配置。更新 config.yaml 后，运行以下命令：

docker-compose run --rm --no-deps api monocle janitor update-idents --elastic elastic:9200 --config /etc/monocle/config.yaml

群组定义

Monocle 中的群组允许将变更作者分组，并从 Web 界面对其进行筛选。

群组成员资格通过配置的 idents 部分定义。

以下是一个示例：

workspaces:
  - name: example
    idents:
      - ident: John Doe
        aliases:
          - github.com/john-doe
          - review.opendev.org/John Doe/12345
        groups:
          - devs
      - ident: Jane Doe
        aliases:
          - github.com/jane-doe
        groups:
          - devs
          - ptl

搜索别名定义

Monocle 配置文件提供了一种方法来定义可在搜索查询中使用的别名。一个用例可能是将 bot 作者分组，以便轻松地从搜索结果中排除它们。

以下是一个示例：

workspaces:
  - name: example
    search_aliases:
      - name: bots
        alias: '(author:"github-actions" or author:"bedevere-bot")'

然后查询可以是："from:now-3weeks and not bot"。

关于

本节配置WEB应用程序在"关于"模态框中显示的信息。

以下是一个示例:

about:
  links:
    - category: 社区
      name: Monocle配置
      url: https://github.com/change-metrics/demo-node-config

爬虫

本节配置全局爬虫设置。

注意，crawlers是配置文件根级别的参数。

以下是一个示例:

crawlers:
  # 每次迭代间隔一小时
  loop_delay_sec: 3600

身份验证

Monocle支持通过OIDC(OpenID Connect)提供程序进行用户身份验证。

一旦通过身份验证，Monocle能够显示个性化内容，如解析查询中的self值，例如查询:author: self。

Monocle一次只支持一个提供程序。

请注意，默认情况下，如果未配置或配置错误身份验证系统，Monocle提供一个未认证登录机制，允许用户输入其作者名称。

OIDC提供程序

以下是配置示例:

auth:
  auth_provider:
    oidc_client_id: my_client_id
    oidc_issuer_url: https://accounts.google.com
    oidc_provider_name: my provider
    oidc_user_claim: email
  enforce_auth: false

oidc_client_id: 是由OIDC提供程序提供的客户端ID。
oidc_issuer_url: 是用于发现OIDC提供程序配置的URL(通过*.well-known/openid-configuration*端点)。
oidc_provider_name: 是在WEB应用程序的身份验证模态框中显示的名称。
oidc_user_claim: (可选)是用作/(或用于发现匹配的)Monocle用户ID的JWT声明。(默认:sub)
enforce_auth: (可选)如果设置为True，则Monocle要求有效的JWT才能访问任何API端点，并且WEB应用程序要求用户登录才能导航。(默认:False)

需要在OIDC提供程序上配置的重定向URI是:<MONOCLE_PUBLIC_URL>/api/2/auth/cb。

此外，还需要两个额外的设置(环境变量)来启用身份验证提供程序:

MONOCLE_PUBLIC_URL: 用于将OIDC提供程序重定向到回调端点，并在成功身份验证后将用户重定向到Monocle WEB应用程序。
MONOCLE_OIDC_<PROVIDER_NAME>_CLIENT_SECRET: Monocle查找此变量以发现由OIDC提供程序提供的客户端密钥。

当身份验证提供程序正确设置时，Monocle API会生成以下日志行:

2022-10-11 10:39:11 INFO    Monocle.Main:149: AuthSystemReady {"provider":"my provider"}

Monocle向WEB应用程序用户发放自己的JWT。OIDC提供程序发放的JWT用于获取已认证用户的信息，如通过oidc_user_claim获取其唯一uid。Monocle使用(来自OIDC提供程序的)UID通过idents设置发现匹配的Monocle Ident。匹配的ident定义了一个别名，格式为AuthProviderUID:<user_unique_id>。如果没有匹配的ident，则使用用户声明值。

Monocle JWT的有效期为24小时，过期后用户必须再次登录OIDC提供程序。

服务令牌

Monocle可以发放服务令牌，供使用Monocle API的应用程序使用。要请求令牌，您需要执行以下调用:

curl -XPOST -d '{"token": "<admin_token>"}' -H "Content-type: application/json" <monocle_public_url>/auth/get
{"jwt":"eyJhbGciOiJIUzUxMiJ9.eyJkYXQiOnsiYURlZmF1bHRNdWlkIjoiYm90IiwiYU11aWRNYXAiOnt9fX0.bmj5vcxXxz2LmkrVKxX8jd-aYzHeTng_QBzR_9YZwCb9ToKA59TVlN1wZf6hhPlUX1VU82Y94gVCREDifintZg"}

然后设置Authorization头以访问Monocle API:

curl -XPOST -d '{"void": ""}' -H "Content-type: application/json" -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJkYXQiOnsiYURlZmF1bHRNdWlkIjoiYm90IiwiYU11aWRNYXAiOnt9fX0.bmj5vcxXxz2LmkrVKxX8jd-aYzHeTng_QBzR_9YZwCb9ToKA59TVlN1wZf6hhPlUX1VU82Y94gVCREDifintZg' <monocle_public_url>/auth/whoami

必须设置MONOCLE_ADMIN_TOKEN才能启用此端点。

完整配置文件示例

以下是需要添加到.secrets文件中的预期环境变量:

CRAWLERS_API_KEY: 爬虫用于索引数据的任意API密钥。
GITHUB_TOKEN: GitHub爬虫的API密钥。
GITLAB_TOKEN: GitLab爬虫的API密钥。

打开示例config.yaml。

故障排除

ElasticSearch可能需要一些功能才能在容器模式下运行。查看日志以确认它是否正确启动:

$ docker-compose logs elastic

例如，您可能需要增加此系统参数:

$ sudo sysctl -w vm.max_map_count=262144

或使数据目录对其他用户可写:

$ chmod o+w data

要删除一个工作区（工作区是一个elasticsearch索引）：

# 使用以下命令列出索引：
docker-compose run --rm --no-deps api curl http://elastic:9200/_aliases?pretty=true
# 使用以下命令删除索引：
docker-compose run --rm --no-deps api curl -XDELETE http://elastic:9200/<索引名称>

ElasticSearch 为新索引设置默认设置。基于正则表达式的查询的默认设置值可能不适合您的使用，特别是当您的项目定义使用超过该限制的正则表达式时。但是，可以使用以下命令增加限制：

docker-compose run --rm --no-deps api curl \
-XPUT http://localhost:9200/monocle.changes.1.<索引名称>/_settings \
-H "Content-Type: application/json" -d '{"index": {"max_regex_length": 50000}}'

爬虫默认的加密套件可能较为严格，无法与某些远程服务器负载均衡器公布的不受支持的加密套件配合使用。如果您在爬虫容器中遇到"wrong signature type"错误，应考虑在docker-compose配置文件中使用TLS_CIPHER环境变量更改加密套件。您可以在Fedora更新日志中找到额外信息。

要禁用TLS验证，请将TLS_NO_VERIFY环境变量设置为1。

如果您远程访问Web服务，请确保在.env文件中将MONOCLE_PUBLIC_URL设置为正确的URL，因为这将用于重定向来自UI的请求。否则，您会看到UI因"Network error"消息而失败。

从数据库中清除爬虫数据

要清除与工作区爬虫相关的任何数据：

docker-compose stop crawler
docker-compose run --rm --no-deps api monocle janitor wipe-crawler-data --elastic elastic:9200 --config /etc/monocle/config.yaml --workspace <工作区> --crawler-name <爬虫名称>
docker-compose start crawler

重置爬虫提交日期

Monocle爬虫会跟踪上次成功获取文档的日期（提交日期）。以下命令可用于强制爬虫从另一个日期开始（重新）获取文档。

docker-compose run --rm --no-deps api monocle janitor set-crawler-commit-date --elastic elastic:9200 --config /etc/monocle/config.yaml --workspace <工作区> --crawler-name <爬虫名称> --commit-date 2023-01-01

组件

Monocle由以下服务组成：

Elasticsearch数据存储。
API服务，用于服务Web应用和API请求。
爬虫服务，用于从提供者获取变更。

API使用protobuf定义，并通过Monocle OpenAPI以HTTP方式提供服务。

通过API消费指标

大多数指标通过api/2/metric/get端点公开。api/2/metric/list列出可用的指标。Monocle Web UI通过Catalog页面利用这些指标。

查询和响应格式的详细信息在Monocle OpenAPI文档中描述。

请注意，目前正在进行一项工作，以确保Monocle Web UI显示的所有指标都使用api/2/metric端点。

列出可用的指标：

curl 'https://demo.changemetrics.io/api/2/metric/list' \
  -H 'Content-Type: application/json' \
  --data '{"void":""}'

获取Changes created指标作为具有自动间隔的trend：

curl 'https://demo.changemetrics.io/api/2/metric/get' \
  -H 'Content-Type: application/json' \
  --data '{"index":"python","username":"","query":"from:now-3weeks","metric":"changes_created","trend":{"interval":""}}'

监控

设置监控：

通过提供API和CRAWLER位置创建prometheus服务

export API_TARGET=localhost:8080
export CRAWLER_TARGET=localhost:9001
mkdir -p /srv/prometheus
podman create --network host -v /srv/prometheus:/var/lib/prometheus:Z -e API_TARGET=${API_TARGET} -e CRAWLER_TARGET=${CRAWLER_TARGET} --name monocle-prometheus quay.io/change-metrics/monocle-prometheus:latest

创建grafana服务（在prometheus主机上）

mkdir -p /srv/grafana
podman create --network host -v /srv/grafana:/var/lib/grafana:Z -e GRAFANA_PASS=secret --name monocle-grafana quay.io/change-metrics/monocle-grafana:latest

使用systemd启动服务

mkdir -p ~/.config/systemd/user/
for service in prometheus grafana; do podman generate systemd -n monocle-$service > ~/.config/systemd/user/monocle-$service.service; done
systemctl --user daemon-reload
for service in prometheus grafana; do systemctl --user start monocle-$service; done