Logo
Project Icon

monocle

项目变更分析与可视化的开源协作平台

Monocle项目分析开发团队变更管理GitHubGithub开源项目

Monocle是一个开源的项目变更分析平台，为开发团队提供变更统计和可视化看板。支持GitHub、GitLab和Gerrit等代码托管服务，有助于团队优化工作流程，识别变更过程中的异常。Monocle支持Docker和Kubernetes部署，配置灵活，包括多工作区、身份管理和自定义搜索等功能。

访问官网访问官网GithubGithub
介绍相关项目

Monocle

Monocle 旨在为开发团队提供：

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

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

Monocle 支持 GitHub、GitLab 和 Gerrit。

如何开始使用 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。

该文件配置以下内容：

您可能想使用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由以下服务组成：

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

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":""}}'

监控

设置监控：

  1. 通过提供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
  1. 创建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
  1. 使用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
  1. 在http://localhost:19030/（使用'admin:secret'登录）上通过grafana仪表板检查指标

Monocle的用户

公司名称/项目名称主要用途（看板、指标、其他）公共实例（链接）/私有实例
changemetrics.io项目演示实例https://demo.changemetrics.io

如果您使用Monocle，请提交一个拉取请求以添加到此列表中。

相关项目
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手，通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能，支持100+编程语言，与主流编辑器无缝集成，显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台，能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐，Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案，通过智能技术简化视频制作流程。无论是企业宣传还是个人分享，有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持，能够阅读和理解用户上传的文件内容，解析网页信息，并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题，Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术，为商家提供一键生成商品图和营销文案的服务，显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台，让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型，免费访问各种图像生成与AI训练工具，从Stable Diffusion等基础模型开始，轻松实现创新图像生成。体验前沿的AI技术，推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器，它将改变您观看视频的方式！SubCat结合了先进的人工智能技术，为您提供即时视频字幕翻译，无论是本地视频还是网络流媒体，让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台，利用前沿AI技术，为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图，再到文案生成，美间让创意设计更简单、更高效。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具，简化了选题、文献检索至论文撰写的整个过程。通过简单设定，平台可快速生成高质量论文大纲和全文，配合图表、参考文献等一应俱全，同时提供开题报告和答辩PPT等增值服务，保障数据安全，有效提升写作效率和论文质量。

使用协议隐私政策广告服务
投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号