Usage Ping Guide

原文：https://docs.gitlab.com/ee/development/telemetry/usage_ping.html

• What is Usage Ping?
  • Why should we enable Usage Ping?
  • Limitations
• Usage Ping payload
• Disable Usage Ping
• Usage Ping request flow
• How Usage Ping works
• Implementing Usage Ping
  • Why batch counting
  • Ordinary Batch Counters
  • Distinct Batch Counters
  • Redis Counters
  • Alternative Counters
  • Prometheus Queries
• Developing and testing Usage Ping
  • 1. Use your Rails console to manually test counters
  • 2. Generate the SQL query
  • 3. Optimize queries with #database-lab
  • 4. Add the metric definition
  • 5. Add new metric to Versions Application
  • 6. Add the feature label
  • 7. Add a changelog file
  • 8. Ask for a Telemetry Review
  • Optional: Test Prometheus based Usage Ping
    • Test with an Omnibus container
    • Test with GitLab development toolkits
• Usage Statistics definitions
• Example Usage Ping payload

Usage Ping Guide

版本历史

• 在 GitLab 企业版 8.10 中引入.
• 在 GitLab 企业版 8.12 中添加了更多统计信息.
• 在 9.1 中移至 GitLab Core.
• 在 GitLab Ultimate 11.2 中添加了更多统计信息.

本指南介绍了用法 Ping 的用途及其实现方式.

有关遥测的更多信息，请参见：

• Telemetry Guide
• Snowplow Guide

更有用的链接：

• Telemetry Direction
• Data Analysis Process
• Data for Product Managers
• Data Infrastructure

What is Usage Ping?

• GitLab 每周将包含使用情况数据的有效负载发送到 GitLabInc.用法 Ping 提供高级数据来帮助我们的产品，支持和销售团队. 它不发送任何项目名称，用户名或任何其他特定数据. 使用 ping 中的信息不是匿名的，它链接到实例的主机名. 发送使用情况 ping 是可选的，任何实例都可以禁用分析.
• 使用情况数据主要由实例数据库中不同表的行计数组成. 通过逐月比较这些计数（或逐周比较），我们可以大致了解实例如何使用产品中的不同功能. 除计数外，还收集了其他有助于我们分类和了解 GitLab 安装的事实.
• 使用 ping 对 GitLab 很重要，因为我们使用它来计算阶段每月活跃用户（SMAU），这有助于我们衡量阶段和功能的成功程度.
• 启用使用情况 ping 后，GitLab 将从其他实例收集数据，并能够向用户显示您实例的使用情况统计信息.

Why should we enable Usage Ping?

• 使用 Ping 的主要目的是构建更好的 GitLab. 收集有关如何使用 GitLab 的数据，以更好地了解功能/阶段的采用和使用情况，这有助于我们了解 GitLab 如何增加价值，并帮助我们的团队更好地了解人们使用 GitLab 的原因，并且借助这些知识，我们可以做得更好产品决策.
• 作为激活使用 ping 的一项好处，GitLab 可让您分析 GitLab 安装过程中用户的活动.
• 作为激活使用 ping 的一项好处，GitLab 为您提供了 DevOps 得分，它为您提供了从计划到监视整个实例对并发 DevOps 的采用情况的概述.
• 您将获得更好，更主动的支持. （假设我们的 TAM 和支持组织使用这些数据来提供更多价值）
• 您将获得有关如何从 GitLab 的投资中获得最大价值的见识和建议. 您是否不想知道组织中未采用许多功能或价值？
• 您将获得一份报告，说明如何与其他类似组织（匿名）进行比较，并提供有关如何改进 DevOps 流程的具体建议和建议.
• 默认情况下启用用法 Ping. 要禁用它，请参阅禁用用法 Ping .

Limitations

• Usage Ping does not track frontend events things like page views, link clicks, or user sessions, and only focuses on aggregated backend events.
• 由于这些限制，我们建议使用 Snowplow 来对您的产品进行检测，以在 GitLab.com 上进行更详细的分析，并使用 Usage Ping 跟踪自我管理中的汇总后端事件.

Usage Ping payload

您可以在管理面板中查看发送到 GitLab Inc.的确切 JSON 有效负载. 要查看有效负载：

1. 导航到” 管理区域”>”设置”>”度量标准和性能分析” .
2. 展开使用情况统计信息部分.
3. 单击预览有效负载按钮.

有关有效负载的示例，请参阅示例用法 Ping 有效负载 .

Disable Usage Ping

要在 GitLab UI 中禁用”使用情况 Ping”，请转到管理面板的“设置”页面，然后取消选中” 使用情况 Ping”复选框.

要禁用用法 Ping 并防止日后通过管理面板对其进行配置，Omnibus 安装可以在gitlab.rb设置以下gitlab.rb ：

gitlab_rails['usage_ping_enabled'] = false

源代码安装可以在gitlab.yml设置以下gitlab.yml ：

production: &base
  # ...
  gitlab:
    # ...
    usage_ping_enabled: false

Usage Ping request flow

The following example shows a basic request/response flow between a GitLab instance, the Versions Application, the License Application, Salesforce, GitLab’s S3 Bucket, GitLab’s Snowflake Data Warehouse, and Sisense:

sequenceDiagram 参与者 GitLab 实例参与者版本应用程序参与者许可证应用程序参与者 Salesforce 参与者 S3 存储桶参与者 Snowflake DW 参与者 Sisense 仪表板 GitLab 实例->>版本应用程序：发送使用情况 ping 循环流程使用情况数据版本应用程序->>版本应用程序：解析使用情况数据版本应用程序- >>版本应用程序：写入数据库版本应用程序->>版本应用程序：更新许可证 ping 超时循环 Salesforce 版本的过程数据 Application-xLicenses 应用程序：请求 Zuora 订阅 ID 许可证 Application-xVersions 应用程序：Zuora 订阅 ID 版本 Application-xSalesforce：通过 Zuora 订阅 ID 请求 Zuora 帐户 ID Salesforce-xVersions 应用程序：Zuora 帐户 ID 版本 Application-xSalesforce：Zuora 帐户最终版本的使用数据 Application->> S3 存储桶：导出版本数据库 S3 存储桶->>雪花 DW：导入数据 Snowflake DW->>雪花 DW：Trans 使用 dbt Snowflake DW->> Sisense 仪表板的表单数据：可用于查询版本 Application->> GitLab 实例的数据：DevOps 得分（会话开发索引）

How Usage Ping works

1. 在 Sidekiq 中将 Usage Ping cron 作业设置为每周运行.
2. 当 cron 作业运行时，它将调用GitLab::UsageData.to_json .
3. GitLab::UsageData.to_json 级联到GitLab::UsageData.to_json +其他计数器方法调用.
4. 所有方法调用的响应都在GitLab::UsageData.to_json中合并为一个 JSON 负载.
5. 然后将 JSON 有效负载发布到 Versions 应用程序 .

Implementing Usage Ping

Usage Ping consists of two kinds of data, counters and observations. Counters track how often a certain event happened over time, such as how many CI pipelines have run. They are monotonic and always trend up. Observations are facts collected from one or more GitLab instances and can carry arbitrary data. There are no general guidelines around how to collect those, due to the individual nature of that data.

在usage_data.rb中可以找到四种类型的计数器：

• 普通批处理计数器：给定 ActiveRecord_Relation 的简单计数
• 不同的批次计数器：给定列上给定 ActiveRecord_Relation 的不同计数
• 备用计数器：用于设置和配置
• Redis 计数器：用于内存中计数. 由于数据不正确，此方法已被弃用，并将由持久性方法代替.

注意：仅使用提供的计数器方法. 每个计数器方法都包含一个内置的故障保险柜，用于隔离每个计数器，以避免破坏整个使用情况 Ping.

Why batch counting

对于大型表，由于 MVCC （多版本并发控制） ，PostgreSQL 可能需要很长时间才能对行进行计数. 批计数是一种将单个大型查询分解为多个较小查询的计数方法. 例如，您可以执行 100 个每个 10,000 条记录的查询，而不是一个查询 1,000,000 条记录并进行批处理的查询. 批计数对于避免数据库超时很有用，因为每个批查询都比一个长期运行的查询短得多.

对于 GitLab.com，有非常大的表具有 15 秒的查询超时，因此我们使用批计数来避免遇到超时. 以下是一些 GitLab.com 表的大小：

提供了两种批处理计数方法：” Ordinary Batch Counters和” Distinct Batch Counters . 批计数需要列上的索引来计算最大值，最小值和范围查询. 在某些情况下，可能需要在计数器涉及的列上添加专门的索引.

Ordinary Batch Counters

Handles ActiveRecord::StatementInvalid error

给定 ActiveRecord_Relation 的简单计数

Method: count(relation, column = nil, batch: true, start: nil, finish: nil)

Arguments:

• relation ActiveRecord_Relation 以执行计数
• column要执行计数的列，默认情况下是主键
• batch ：默认为true以便使用批次计数
• start ：批处理计数的自定义开始，以避免复杂的最小值计算
• end ：批处理计数的自定义结束，以避免复杂的最小值计算

Examples:

count(User.active)
count(::Clusters::Cluster.aws_installed.enabled, :cluster_id)
count(::Clusters::Cluster.aws_installed.enabled, :cluster_id, start: ::Clusters::Cluster.minimum(:id), finish: ::Clusters::Cluster.maximum(:id))

Distinct Batch Counters

Handles ActiveRecord::StatementInvalid error

给定列上给定 ActiveRecord_Relation 的不重复计数

Method: distinct_count(relation, column = nil, batch: true, start: nil, finish: nil)

Arguments:

• relation ActiveRecord_Relation 以执行计数
• column该列执行非重复计数，默认情况下是主键
• batch ：默认为true以便使用批次计数
• start ：批处理计数的自定义开始，以避免复杂的最小值计算
• end ：批处理计数的自定义结束，以避免复杂的最小值计算

Examples:

distinct_count(::Project, :creator_id)
distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::User.minimum(:id), finish: ::User.maximum(:id))
distinct_count(::Clusters::Applications::CertManager.where(time_period).available.joins(:cluster), 'clusters.user_id')

Redis Counters

当发送一个块时，句柄::Redis::CommandError和Gitlab::UsageDataCounters::BaseCounter::UnknownEvent返回-1，或者在向counter(Gitlab::UsageDataCounters)发送不同行为时由于所有 2 个不同而返回具有所有值-1 的哈希 Redis 计数器的实现

Method: redis_usage_data(counter, &block)

Arguments:

• counter ：来自Gitlab::UsageDataCounters的计数器，该计数器已实现fallback_totals方法
• 或block ：被评估

用法示例：

redis_usage_data(Gitlab::UsageDataCounters::WikiPageCounter)
redis_usage_data { ::Gitlab::UsageCounters::PodLogs.usage_totals[:total] }

请注意，Redis 计数器正在被弃用 ，您应该改为尝试使用 Snowplow 事件. 我们正在构建自我管理的事件跟踪 ，一旦可用，我们会将所有 Redis 计数器转换为 Snowplow 事件.

Alternative Counters

以这种方式处理StandardError并将后备值处理为-1，如果遇到一个异常，并非所有度量都会失败. 主要用于设置和配置.

Method: alt_usage_data(value = nil, fallback: -1, &block)

Arguments:

• value ：一个简单的静态值，在这种情况下，仅返回该值.
• 或block ：被评估
• fallback: -1 ：用于失败的任何度量的通用值.

用法示例：

alt_usage_data { Gitlab::VERSION }
alt_usage_data { Gitlab::CurrentSettings.uuid }
alt_usage_data(999)

Prometheus Queries

在那些操作指标应成为 Usage Ping 一部分的情况下，数据库或 Redis 查询不太可能提供有用的数据. 取而代之的是，Prometheus 可能更合适，因为大多数 GitLab 的体系结构组件都会向其发布指标，这些指标可以查询，汇总并作为使用数据包含在内.

注意： Prometheus 作为 Usage Ping 的数据源目前仅适用于运行捆绑的 Prometheus实例的单节点 Omnibus 安装.

为了查询 Prometheus 的度量标准，可以使用一个助手方法，该方法将yield一个完整配置的PrometheusClient ，前提是可以按照上述说明使用它：

with_prometheus_client do |client|
  response = client.query('<your query>')
  ...
end

请参阅PrometheusClient定义，以了解如何使用其 API 查询数据.

Developing and testing Usage Ping

1. Use your Rails console to manually test counters

# count
Gitlab::UsageData.count(User.active)
Gitlab::UsageData.count(::Clusters::Cluster.aws_installed.enabled, :cluster_id)
# count distinct
Gitlab::UsageData.distinct_count(::Project, :creator_id)
Gitlab::UsageData.distinct_count(::Note.with_suggestions.where(time_period), :author_id, start: ::User.minimum(:id), finish: ::User.maximum(:id))

2. Generate the SQL query

您的 Rails 控制台将返回生成的 SQL 查询.

Example:

pry(main)> Gitlab::UsageData.count(User.active)
   (2.6ms)  SELECT "features"."key" FROM "features"
   (15.3ms)  SELECT MIN("users"."id") FROM "users" WHERE ("users"."state" IN ('active')) AND ("users"."user_type" IS NULL OR "users"."user_type" IN (6, 4))
   (2.4ms)  SELECT MAX("users"."id") FROM "users" WHERE ("users"."state" IN ('active')) AND ("users"."user_type" IS NULL OR "users"."user_type" IN (6, 4))
   (1.9ms)  SELECT COUNT("users"."id") FROM "users" WHERE ("users"."state" IN ('active')) AND ("users"."user_type" IS NULL OR "users"."user_type" IN (6, 4)) AND "users"."id" BETWEEN 1 AND 100000

3. Optimize queries with #database-lab

将 SQL 查询粘贴到#database-lab以查看查询的大规模执行情况.

• #database-lab is a Slack channel which uses a production-sized environment to test your queries.
• GitLab.com 的生产数据库有 15 秒的超时.
• 任何单个查询的冷缓存都必须保持在 1 秒以下的执行时间.
• 在涉及的列上添加专门的索引，以减少执行时间.

为了了解查询的执行情况，我们在 MR 描述中添加了以下信息：

• 对于具有time_period测试的计数器，我们添加了两种情况的信息：
  • 所有时间段的time_period = {}
  • time_period = { created_at: 28.days.ago..Time.current }最近 28 天的时间段
• 优化前后的执行计划和查询时间
• 查询生成的索引和时间
• 上下执行的迁移输出

我们还使用#database-lab和explain.depesz.com . 有关更多详细信息，请参见数据库查看指南 .

查询优化工作的示例：

• Example 1
• Example 2

4. Add the metric definition

添加，更改或更新指标时，请更新使用情况统计信息定义表 .

5. Add new metric to Versions Application

检查是否需要将新指标添加到”版本应用程序”. 请参见usage_data 模式和已接受的用法数据参数 . 在counts键下添加的所有度量标准都保存在counts列中.

有关更多详细信息，请参见将其他工具添加到”用法” Ping 的过程 .

6. Add the feature label

将feature标签添加到”合并请求”以获取新的”用法 Ping”度量. 这些是面向用户的更改，并且是扩展”用法” Ping 功能的一部分.

7. Add a changelog file

确保您遵守Changelog 条目指南 .

8. Ask for a Telemetry Review

在 GitLab.com 上，我们具有 DangerBot 设置来监视遥测相关文件，并且 DangerBot 将建议进行遥测. 在您的 MR 中提及@gitlab-org/growth/telemetry/engineers以进行审核.

Optional: Test Prometheus based Usage Ping

如果提交的数据包含您要检查和验证的从 Prometheus 查询的指标，则需要确保 Prometheus 服务器在本地运行，并且相应的 GitLab 组件正在向其导出指标. 如果您不需要测试来自 Prometheus 的数据，则无需采取任何进一步的措施，因为在没有运行 Prometheus 服务器的情况下，Using Ping 应该会正常降低性能.

当前，存在三种可以将数据导出到 Prometheus 的组件，这些组件包括在 Useing Ping 中：

• node_exporter从主机导出节点指标
• gitlab-exporter从各种 GitLab 组件导出过程指标
• 各种 GitLab 服务（例如 Sidekiq 和 Rails 服务器）可导出自己的指标

Test with an Omnibus container

这是测试基于 Prometheus 的用法 Ping 的推荐方法.

验证更改的最简单方法是通过 CI 从代码分支构建新的 Omnibus 映像，然后下载该映像并运行本地容器实例：

1. 在合并请求中，单击qa阶段，然后触发package-and-qa作业. 这项工作将触发omnibus-gitlab-mirror项目的下游管道中的 Omnibus 构建.
2. 在下游管道中，等待gitlab-docker作业完成.
3. 打开作业日志，然后找到完整的容器名称（包括版本）. 它将采用以下形式： registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION> .
4. 在本地计算机上，确保您已登录到 GitLab Docker 注册表. 您可以在向 GitLab 容器注册表进行身份验证中找到有关此操作的说明.
5. 登录后，通过docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>下载新映像docker pull registry.gitlab.com/gitlab-org/build/omnibus-gitlab-mirror/gitlab-ee:<VERSION>
6. 有关在 Docker 中使用和运行 Omnibus GitLab 容器的更多信息，请参阅 Omnibus 文档中的GitLab Docker 映像 .

Test with GitLab development toolkits

这是不建议使用的方法，因为在模拟实际的 GitLab 部署时会遇到很多困难.

当前未将GDK设置为与其他 GitLab 组件一起运行 Prometheus 服务器或node_exporter . 如果您愿意，可以使用 Prometheus 监控 GDK .

GCK对测试基于 Prometheus 的 Useing Ping 的支持有限. 默认情况下，它已经带有完整配置的 Prometheus 服务，该服务设置为可刮除许多组件，但具有以下限制：

• 它当前未运行gitlab-exporter实例，因此可能缺少诸如 Gitaly 之类的服务中的多个process_*指标.
• 当它运行node_exporter ， node_exporter docker-compose服务会模拟主机，这意味着它通常会报告自身不与正在运行的任何其他服务关联. 这不是在生产设置中报告节点度量的方式，在生产设置中， node_exporter始终作为进程与任何给定节点上的其他 GitLab 组件一起运行. 从用法 Ping 的角度来看，没有节点数据因此似乎与任何正在运行的服务相关联，因为它们似乎都在不同的主机上运行. 为了缓解此问题， node_exporter GCK 中的node_exporter任意”分配”给了web服务，这意味着仅针对该服务的node_*指标将出现在”用法” Ping 中.

Usage Statistics definitions

Example Usage Ping payload

以下是用法 Ping 有效内容的示例内容.

{  "uuid":  "0000000-0000-0000-0000-000000000000",  "hostname":  "example.com",  "version":  "12.10.0-pre",  "installation_type":  "omnibus-gitlab",  "active_user_count":  999,  "recorded_at":  "2020-04-17T07:43:54.162+00:00",  "edition":  "EEU",  "license_md5":  "00000000000000000000000000000000",  "license_id":  null,  "historical_max_users":  999,  "licensee":  {  "Name":  "ABC, Inc.",  "Email":  "email@example.com",  "Company":  "ABC, Inc."  },  "license_user_count":  999,  "license_starts_at":  "2020-01-01",  "license_expires_at":  "2021-01-01",  "license_plan":  "ultimate",  "license_add_ons":  {  },  "license_trial":  false,  "counts":  {  "assignee_lists":  999,  "boards":  999,  "ci_builds":  999,  ...  },  "container_registry_enabled":  true,  "dependency_proxy_enabled":  false,  "gitlab_shared_runners_enabled":  true,  "gravatar_enabled":  true,  "influxdb_metrics_enabled":  true,  "ldap_enabled":  false,  "mattermost_enabled":  false,  "omniauth_enabled":  true,  "prometheus_enabled":  false,  "prometheus_metrics_enabled":  false,  "reply_by_email_enabled":  "incoming+%{key}@incoming.gitlab.com",  "signup_enabled":  true,  "web_ide_clientside_preview_enabled":  true,  "ingress_modsecurity_enabled":  true,  "projects_with_expiration_policy_disabled":  999,  "projects_with_expiration_policy_enabled":  999,  ...  "elasticsearch_enabled":  true,  "license_trial_ends_on":  null,  "geo_enabled":  false,  "git":  {  "version":  {  "major":  2,  "minor":  26,  "patch":  1  }  },  "gitaly":  {  "version":  "12.10.0-rc1-93-g40980d40",  "servers":  56,  "clusters":  14,  "filesystems":  [  "EXT_2_3_4"  ]  },  "gitlab_pages":  {  "enabled":  true,  "version":  "1.17.0"  },  "database":  {  "adapter":  "postgresql",  "version":  "9.6.15"  },  "app_server":  {  "type":  "console"  },  "avg_cycle_analytics":  {  "issue":  {  "average":  999,  "sd":  999,  "missing":  999  },  "plan":  {  "average":  null,  "sd":  999,  "missing":  999  },  "code":  {  "average":  null,  "sd":  999,  "missing":  999  },  "test":  {  "average":  null,  "sd":  999,  "missing":  999  },  "review":  {  "average":  null,  "sd":  999,  "missing":  999  },  "staging":  {  "average":  null,  "sd":  999,  "missing":  999  },  "production":  {  "average":  null,  "sd":  999,  "missing":  999  },  "total":  999  },  "analytics_unique_visits":  {  "g_analytics_contribution":  999,  ...  },  "usage_activity_by_stage":  {  "configure":  {  "project_clusters_enabled":  999,  ...  },  "create":  {  "merge_requests":  999,  ...  },  "manage":  {  "events":  999,  ...  },  "monitor":  {  "clusters":  999,  ...  },  "package":  {  "projects_with_packages":  999  },  "plan":  {  "issues":  999,  ...  },  "release":  {  "deployments":  999,  ...  },  "secure":  {  "user_container_scanning_jobs":  999,  ...  },  "verify":  {  "ci_builds":  999,  ...  }  },  "usage_activity_by_stage_monthly":  {  "configure":  {  "project_clusters_enabled":  999,  ...  },  "create":  {  "merge_requests":  999,  ...  },  "manage":  {  "events":  999,  ...  },  "monitor":  {  "clusters":  999,  ...  },  "package":  {  "projects_with_packages":  999  },  "plan":  {  "issues":  999,  ...  },  "release":  {  "deployments":  999,  ...  },  "secure":  {  "user_container_scanning_jobs":  999,  ...  },  "verify":  {  "ci_builds":  999,  ...  }  },  "topology":  {  "duration_s":  0.013836685999194742,  "application_requests_per_hour":  4224,  "failures":  [],  "nodes":  [  {  "node_memory_total_bytes":  33269903360,  "node_cpus":  16,  "node_uname_info":  {  "machine":  "x86_64",  "sysname":  "Linux",  "release":  "4.19.76-linuxkit"  },  "node_services":  [  {  "name":  "web",  "process_count":  16,  "process_memory_pss":  233349888,  "process_memory_rss":  788220927,  "process_memory_uss":  195295487,  "server":  "puma"  },  {  "name":  "sidekiq",  "process_count":  1,  "process_memory_pss":  734080000,  "process_memory_rss":  750051328,  "process_memory_uss":  731533312  },  ...  ],  ...  },  ...  ]  }  }