Help us learn about your current experience with the documentation. Take the survey.

内部分析

内部分析系统能够跟踪用户行为和系统状态，为 GitLab 实例提供数据支持，从而助力客户成功服务和产品进一步发展。

这些文档页面提供了指南和信息，说明在开发新功能或对现有功能进行埋点时，如何利用 GitLab 的内部分析功能。

基本概念

观看关于 事件和指标概念的 视频

事件和指标是内部分析系统的基础。 理解这两个概念之间的差异对于使用该系统至关重要。

事件

事件是对 GitLab 实例内发生的某个动作的记录。 例如，用户交互动作包括访问问题页面或将鼠标悬停在顶部导航搜索框上。 其他动作可能来自后台系统处理，如计划流水线成功执行或接收来自第三方系统的 API 调用。 并非所有动作都会被跟踪并自动记录为事件。 相反，如果一个动作有助于提取产品洞察并帮助做出更明智的业务决策，我们可以在该动作发生时跟踪事件。 生成的事件记录至少包含动作发生的信息，但也可以包含伴随该动作的上下文详细信息。 上下文示例包括执行操作的人员信息或操作发生时的系统状态。

指标

单个事件记录信息量不足，可能只是偶然发生。 我们需要寻找具有共同特征的事件集合作为分析基础。 这就是指标发挥作用的地方。指标是对信息进行的计算。 例如，单个记录付费用户在新功能发布后访问功能页面的事件，并不能告诉我们这个新功能的成功与否。 然而，如果我们统计新功能发布前一周的页面浏览事件数量，然后与功能发布后一周的事件数量进行比较， 我们可以得出关于新功能发布后兴趣增长的洞察。

这个过程就形成了我们所说的指标。基于事件的指标统计事件总体或指定时间段内发生的次数。 相同的事件可用于不同的指标，一个指标可以统计一个或多个事件。 计数可以基于唯一性标准（如只统计执行过事件的独立用户），但并非必须如此。

指标不一定基于事件。指标也可以是对 GitLab 实例本身状态的观察， 例如某个设置的值或数据库表中的行数。

埋点

数据发现

事件和指标数据最终存储在我们的 Snowflake 数据仓库中。 可以通过 Snowflake 中的 SQL 直接访问进行临时分析， 或在我们的数据可视化工具 Tableau 中可视化，该工具可访问 Snowflake。 两个平台都需要访问请求（Snowflake、Tableau）。

要在浏览器中跟踪用户交互，需要禁用"请勿跟踪"（DNT）。大多数浏览器默认已禁用 DNT。

Tableau

Tableau 是一个数据可视化平台，允许构建仪表板和基于 GUI 的事件与指标探索。 这种探索方式最适合熟悉商业智能工具、基本验证以及创建持久化可共享仪表板和可视化的用户。 访问 Tableau 需要访问请求。

检查事件

访问 Snowplow 事件探索仪表板。 此仪表板向您显示事件计数以及最常触发的事件。 您可以向下滚动到"生产环境中过去 30 天触发的结构化事件"图表，并筛选您的特定事件操作。筛选器仅适用于精确名称。

检查指标

您可以访问指标探索仪表板。 侧边栏有指标路径筛选器（即您指标的 key_path）和安装 ID 筛选器，包括如何筛选 GitLab.com 的指导。

自定义图表和仪表板

在 Tableau 中，还可以完成更高级的图表，如漏斗分析。 可以通过在他们的项目中创建问题向产品数据洞察团队请求自定义图表和仪表板。

Snowflake

Snowflake 允许在其 UI 中使用 Snowflake SQL 方言直接查询仓库中的相关表。 这种探索方式最适合熟悉 SQL 的用户，以及快速灵活地检查数据是否正确传播。 访问 Snowflake 需要访问请求。

查询事件

以下示例查询返回 feature_used 事件的每日发生次数。

SELECT
  behavior_date,
  COUNT(*) as event_occurences
FROM prod.common_mart.mart_behavior_structured_event
WHERE event_action = 'feature_used'
AND behavior_date > '2023-08-01' --为性能限制最小日期
AND app_id='gitlab' --生产环境事件使用 gitlab，staging 环境事件使用 gitlab-staging
GROUP BY 1 ORDER BY 1 desc

有关其他指标表的列表，请参阅数据模型速查表。

查询指标

以下示例查询返回过去六个月内 count_distinct_user_id_from_feature_used_7d 的所有报告值及相应的 instance_id：

SELECT
  date_trunc('week', ping_created_at),
  dim_instance_id,
  metric_value
FROM prod.common.fct_ping_instance_metric_rolling_6_months --为性能限制模型为最近 6 个月
WHERE metrics_path = 'counts.users_visiting_dashboard_weekly' --设置为感兴趣的指标
ORDER BY ping_created_at DESC

有关其他指标表的列表，请参阅数据模型速查表。

产品分析

内部分析正在使用 GitLab 产品分析 功能，该功能也允许您可视化事件。 分析仪表板文档 解释了如何构建自定义可视化和仪表板。 可在GitLab 项目内访问的自定义仪表板在单独的仓库中定义。 可以构建基于通过内部事件系统埋点的事件的仪表板。只有 .com 实例发出的事件才会在这些可视化中被计数。

产品分析组的仪表板可以作为如何基于单个事件构建图表的灵感来源。

数据可用性

对于 GitLab，GitLab.com 与 GitLab 自托管或 GitLab 专用实例之间的分析设置存在重要差异。

自托管和专用版

对于自托管和专用实例，只有预计算指标可用。这些指标每周在随机选择的一天计算一次，并通过称为 Service Ping 的过程转发到我们的版本应用。 只有在实例运行的版本中已埋点的指标才可用。例如，如果在版本 16.9 开发期间埋点了一个指标，它将在运行等于或大于 16.9 版本的实例上可用，但在运行 16.8 等先前版本的实例上不可用。 接收到的有效载荷每天导入一次到我们的数据仓库。

GitLab.com

在我们的 GitLab.com 实例上，单个事件和预计算指标都可用于分析。此外，页面浏览会自动埋点。

单个事件和页面浏览

单个事件和页面浏览直接转发到我们的收集基础设施，然后进入我们的数据仓库。 然而，此时数据处于难以查询的原始格式。因此，数据会被清理并在仓库中传播，直到在数据发现部分指出的表格和图表中可用。

传播过程需要数小时才能完成。下图说明了事件的可用性：

GitLab.com 上事件收集和传播的时间线

来源

预计算指标

指标每周计算一次，与自托管版本类似，唯一区别是大部分计算在仓库内而非实例内进行。 对于 GitLab.com，此过程在周一上午启动，计算从上周日 23:59 UTC 到本周日 23:59 UTC 时间段的指标。

下图说明了该过程：

GitLab.com 上 Service Ping 计算的时间线

来源

数据流

在 SaaS 版本中，事件记录直接发送到名为 Snowplow 的收集系统，并导入到我们的数据仓库。 GitLab 自托管和 GitLab 专用实例在本地记录事件计数。每周，一个称为 Service Ping 的过程将所有预定义和活跃指标的当前值发送到我们的数据仓库。对于 GitLab.com，指标直接在数据仓库中计算。

下图旨在说明此数据流：

flowchart LR;
    feature-->track
    track-->|发送事件记录 - 仅限 gitlab.com|snowplow
    track-->|增加指标计数|redis
    database-->service_ping
    redis-->service_ping
    service_ping-->|包含指标值的 json - 每周导出|snowflake
    snowplow-->|事件记录 - 持续导入|snowflake
    snowflake-->vis

    subgraph glb[Gitlab 应用]
        feature[功能代码]
        subgraph events[内部分析代码]
            track[track_event / trackEvent]
            redis[(Redis)]
            database[(数据库)]
            service_ping[\Service Ping 进程\]
        end
    end
    snowplow[\Snowplow 管道\]
    snowflake[(Snowflake 数据仓库)]
    vis[Tableau 中的仪表板]

数据隐私

GitLab 仅从 GitLab 自托管实例接收事件计数或类似的聚合信息。GitLab SaaS 版本中单个事件的用户标识符被匿名化。 关于通过内部分析系统收集何种数据的详细说明，请参阅我们的手册。

贡献指南