第十章：Dashboards 与 Discover 数据分析

# src/sentry/snuba/discover.py:52-62
__all__ = (
    "PaginationResult",
    "InvalidSearchQuery",
    "query",              # 主事件查询
    "timeseries_query",   # 时序查询
    "top_events_timeseries",  # Top-N 时序查询
    "get_facets",         # 维度分布查询
    "zerofill",           # 时间桶填充工具
    "histogram_query",    # 直方图查询
    "check_multihistogram_fields",
)

# src/sentry/snuba/dataset.py:5-55
class Dataset(Enum):
    Events = "events"              # 所有摄入的错误事件
    Transactions = "transactions"  # 所有摄入的事务（性能）事件
    Discover = "discover"          # Events + Transactions 的联合视图
    Outcomes = "outcomes"          # 使用量统计
    Replays = "replays"            # 会话重放
    Profiles = "profiles"          # 性能剖析
    IssuePlatform = "search_issues"# 通用 Issue 平台
    Functions = "functions"        # 函数级剖析
    SpansIndexed = "spans"         # 索引 Span 数据
    PerformanceMetrics = "generic_metrics"  # 通用指标平台
    EventsAnalyticsPlatform = "events_analytics_platform"  # EAP

# src/sentry/snuba/discover.py:162-264
def query(
    selected_columns: list[str],     # 选择的字段和聚合函数
    query: str,                      # 过滤条件查询字符串
    snuba_params: SnubaParams,       # 时间范围、项目、环境等参数
    equations: list[str] | None = None,  # 算术表达式
    orderby: list[str] | None = None,    # 排序字段
    offset: int | None = None,           # 分页偏移
    limit: int = 50,                     # 返回行数
    auto_fields: bool = False,           # 自动添加 project + eventid
    auto_aggregations: bool = False,     # 自动为条件中的聚合函数添加字段
    include_equation_fields: bool = False,
    allow_metric_aggregates: bool = False,
    use_aggregate_conditions: bool = False,
    conditions: list[Condition] | None = None,  # 直接透传给 Snuba 的条件
    functions_acl: list[str] | None = None,     # 函数白名单
    transform_alias_to_input_format: bool = False,
    sample: float | None = None,      # 采样率
    has_metrics: bool = False,        # 是否使用指标增强
    skip_tag_resolution: bool = False,
    extra_columns: list[Column] | None = None,
    on_demand_metrics_enabled: bool = False,
    on_demand_metrics_type: MetricSpecType | None = None,
    dataset: Dataset = Dataset.Discover,  # 数据集选择
    fallback_to_transactions: bool = False,
    query_source: QuerySource | None = None,
    *,
    referrer: str,                    # 调用来源标识（必填,用于追踪）
) -> EventsResponse:

# src/sentry/snuba/discover.py:231-253
builder = DiscoverQueryBuilder(
    dataset,
    params={},
    snuba_params=snuba_params,
    query=query,
    selected_columns=selected_columns,
    equations=equations,
    orderby=orderby,
    limit=limit,
    offset=offset,
    sample_rate=sample,
    config=QueryBuilderConfig(
        auto_fields=auto_fields,
        auto_aggregations=auto_aggregations,
        use_aggregate_conditions=use_aggregate_conditions,
        functions_acl=functions_acl,
        equation_config={"auto_add": include_equation_fields},
        has_metrics=has_metrics,
        transform_alias_to_input_format=transform_alias_to_input_format,
        skip_tag_resolution=skip_tag_resolution,
    ),
)

# src/sentry/snuba/discover.py:335-353
if comparison_delta:
    if len(base_builder.aggregates) != 1:
        raise InvalidSearchQuery("Only one column can be selected for comparison queries")
    comp_query_params = snuba_params.copy()
    comp_query_params.start -= comparison_delta
    comp_query_params.end -= comparison_delta
    comparison_builder = TimeseriesQueryBuilder(...)
    query_list.append(comparison_builder)

# src/sentry/snuba/discover.py:383-385
for row, compared_row in zip(results[0]["data"], results[1]["data"]):
    compared_value = compared_row.get(col_name, 0)
    row["comparisonCount"] = compared_value

# src/sentry/snuba/discover.py:75
resolve_discover_column = resolve_column(Dataset.Discover)

# 直接透传给 Snuba 的条件（跳过解析层）
conditions: list[Condition] | None = None

# src/sentry/search/events/datasets/discover.py:356-366
"p95": SnQLFunction(
    "p95",
    required_args=[NumberRange(1, 1, NumberTypes.DURATION)],
    snql_aggregate=lambda args, alias: ...
    result_type_fn=...,
    default_result_type="duration",
),

# src/sentry/search/events/datasets/function_aliases.py:337-376
def resolve_eps(args, alias):
    # EPS = count() / (end - start).seconds
    ...

def resolve_epm(args, alias):
    # EPM = count() * 60 / (end - start).seconds
    ...

# src/sentry/search/events/fields.py:1756
"failure_rate", transform="failure_rate()", default_result_type="percentage"

# src/sentry/discover/arithmetic.py:15-17
EQUATION_PREFIX = "equation|"
EQUATION_ALIAS_REGEX = re.compile(r"^equation\[\d*\]$")
SUPPORTED_OPERATORS = {"plus", "minus", "multiply", "divide"}

# src/sentry/discover/arithmetic.py:95-100
arithmetic_grammar = Grammar(
    r"""
term                 = maybe_factor remaining_adds
remaining_adds       = add_sub*
add_sub              = add_sub_operator maybe_factor
maybe_factor         = spaces (factor / primary) spaces
...

# src/sentry/discover/arithmetic.py:62-72
def to_snuba_json(self, alias: str | None = None) -> JsonQueryType:
    lhs = self.lhs.to_snuba_json() if isinstance(self.lhs, Operation) else self.lhs
    if isinstance(lhs, str):
        lhs = ["toFloat64", [lhs]]
    rhs = self.rhs.to_snuba_json() if isinstance(self.rhs, Operation) else self.rhs
    result: JsonQueryType = [self.operator, [lhs, rhs]]
    if alias:
        result.append(alias)
    return result

# 按错误数量降序排序,每页 50 条
query(
    selected_columns=["count()", "message"],
    query="",
    orderby=["-count()"],
    limit=50,
    offset=0,
    ...
)

# src/sentry/snuba/discover.py:70
PaginationResult = namedtuple("PaginationResult", ["next", "previous", "oldest", "latest"])

# src/sentry/discover/dataset_split.py:51-80
TRANSACTION_ONLY_AGGREGATES = [
    "failure_rate", "failure_count", "apdex", "count_miserable",
    "user_misery", "count_web_vitals", "percentile",
    "p50", "p75", "p90", "p95", "p99", "p100",
]

TRANSACTION_ONLY_FIELDS = [
    "duration", "transaction_op", "transaction_status",
    "measurements[lcp]", "measurements[cls]", "measurements[fcp]",
    "measurements[fid]", "measurements[inp]", "measurements[ttfb]",
    "measurements[app_start_cold]", "measurements[app_start_warm]",
    "measurements[frames_total]", "measurements[frames_slow]",
    ...
]

# src/sentry/discover/models.py:81-127
class DiscoverSavedQuery(Model):
    projects = models.ManyToManyField("sentry.Project", through=DiscoverSavedQueryProject)
    organization = FlexibleForeignKey("sentry.Organization")
    created_by_id = HybridCloudForeignKey("sentry.User", null=True, on_delete="SET_NULL")
    name = models.CharField(max_length=255)
    query = models.JSONField()          # 查询配置的 JSON 结构
    version = models.IntegerField(null=True)
    date_created = models.DateTimeField(auto_now_add=True)
    date_updated = models.DateTimeField(auto_now=True)
    visits = BoundedBigIntegerField(null=True, default=1)
    last_visited = models.DateTimeField(null=True, default=timezone.now)
    is_homepage = models.BooleanField(null=True, blank=True)
    dataset = BoundedPositiveIntegerField(       # 数据集类型
        choices=DiscoverSavedQueryTypes.as_choices(),
        default=DiscoverSavedQueryTypes.DISCOVER,
    )
    dataset_source = BoundedPositiveIntegerField(  # 数据集的确定来源
        choices=DatasetSourcesTypes.as_choices(),
        default=DatasetSourcesTypes.UNKNOWN.value,
    )

# src/sentry/discover/models.py:24-40
class DiscoverSavedQueryTypes(TypesClass):
    DISCOVER = 0        # 原始联合查询
    ERROR_EVENTS = 1    # 错误事件查询
    TRANSACTION_LIKE = 2 # 事务类查询

# src/sentry/discover/models.py:43-61
class DatasetSourcesTypes(Enum):
    UNKNOWN = 0    # 未分类（待处理）
    INFERRED = 1   # 通过运行查询或启发式推断
    USER = 2       # 用户显式指定
    FORCED = 3     # 模糊查询被强制分割（系统选择默认值）

# src/sentry/discover/models.py:120-126
class Meta:
    constraints = [
        UniqueConstraint(
            fields=["organization", "created_by_id", "is_homepage"],
            condition=Q(is_homepage=True),
            name="unique_user_homepage_query",
        )
    ]

query(
    selected_columns=["count()", "error.type", "error.value"],
    query="has:error.type",
    orderby=["-count()"],
    limit=20,
    ...
)

timeseries_query(
    selected_columns=["count()"],
    query="has:error.type",
    rollup=3600,  # 每小时一个数据点
    ...
)

query(
    selected_columns=["environment", "count()", "count_unique(user)"],
    query="",
    orderby=["-count()"],
    ...
)

query(
    selected_columns=["transaction", "count()", "p95(transaction.duration)"],
    query="",
    orderby=["-p95(transaction.duration)"],
    limit=20,
    ...
)

query(
    selected_columns=["transaction", "failure_rate()", "count()"],
    query="",
    orderby=["-failure_rate()"],
    ...
)

query(
    selected_columns=[
        "transaction",
        "p75(measurements.lcp)",
        "p75(measurements.fcp)",
        "p75(measurements.cls)",
    ],
    query="transaction.op:pageload",
    orderby=["-p75(measurements.lcp)"],
    ...
)

timeseries_query(
    selected_columns=["epm()"],
    query="transaction:/api/*",
    rollup=60,
    ...
)

query(
    selected_columns=["error.type", "count()", "count_unique(user)"],
    query="",
    orderby=["-count_unique(user)"],
    limit=20,
    ...
)

query(
    selected_columns=["transaction", "user_misery(300)", "count_unique(user)"],
    query="",
    orderby=["-user_misery(300)"],
    limit=10,
    ...
)

query(
    selected_columns=["project", "environment", "transaction", "p95(transaction.duration)", "count()"],
    query="transaction.op:http.server",
    orderby=["-count()"],
    limit=50,
    ...
)

query(
    selected_columns=["count()", "count_if(transaction.status,ok)"],
    equations=["equation|(count_if(transaction.status,ok))/count()"],
    query="",
    orderby=["-equation[0]"],
    include_equation_fields=True,
    ...
)

# src/sentry/models/dashboard.py:336-353
class Dashboard(Model):
    title = models.CharField(max_length=255)
    created_by_id = HybridCloudForeignKey("sentry.User", null=True, on_delete="CASCADE")
    organization = FlexibleForeignKey("sentry.Organization")
    date_added = models.DateTimeField(default=timezone.now)
    visits = BoundedBigIntegerField(null=True, default=1)
    last_visited = models.DateTimeField(null=True, default=timezone.now)
    projects = models.ManyToManyField("sentry.Project", through=DashboardProject)
    filters = JSONField(null=True)
    prebuilt_id = BoundedPositiveIntegerField(null=True, db_default=None)

    MAX_WIDGETS = 30

# src/sentry/models/dashboard.py:358-375
class Meta:
    constraints = [
        UniqueConstraint(
            fields=["organization", "title"],
            condition=Q(prebuilt_id__isnull=True),
            name="sentry_dashboard_organization_title_uniq",
        ),
        UniqueConstraint(
            fields=["organization", "prebuilt_id"],
            condition=Q(prebuilt_id__isnull=False),
            name="sentry_dashboard_organization_prebuilt_id_uniq",
        ),
        CheckConstraint(
            condition=Q(prebuilt_id__isnull=True) | Q(created_by_id__isnull=True),
            name="sentry_dashboard_prebuilt_null_created_by",
        ),
    ]

# src/sentry/dashboards/endpoints/organization_dashboards.py:65-237
class PrebuiltDashboardId(IntEnum):
    FRONTEND_SESSION_HEALTH = 1
    BACKEND_QUERIES = 2
    BACKEND_QUERIES_SUMMARY = 3
    HTTP = 4
    HTTP_DOMAIN_SUMMARY = 5
    WEB_VITALS = 6
    WEB_VITALS_SUMMARY = 7
    MOBILE_VITALS = 8
    MOBILE_VITALS_APP_STARTS = 9
    MOBILE_VITALS_SCREEN_LOADS = 10
    MOBILE_VITALS_SCREEN_RENDERING = 11
    BACKEND_OVERVIEW = 12
    MOBILE_SESSION_HEALTH = 13
    FRONTEND_OVERVIEW = 14
    NEXTJS_FRONTEND_OVERVIEW = 15
    AI_AGENTS_OVERVIEW = 16
    AI_AGENTS_MODELS = 17
    AI_AGENTS_TOOLS = 18
    MCP_OVERVIEW = 19
    MCP_TOOLS = 20
    MCP_RESOURCES = 21
    MCP_PROMPTS = 22
    LARAVEL_OVERVIEW = 23
    FRONTEND_ASSETS = 24
    FRONTEND_ASSETS_SUMMARY = 25
    BACKEND_QUEUES = 26
    BACKEND_QUEUE_SUMMARY = 27
    BACKEND_CACHES = 28
    NODE_RUNTIME_METRICS = 29

PREBUILT_DASHBOARDS: list[PrebuiltDashboard] = [
    {
        "prebuilt_id": PrebuiltDashboardId.WEB_VITALS,
        "title": "Web Vitals",
        "pre_favorited": True,  # 对新用户自动收藏
    },
    {
        "prebuilt_id": PrebuiltDashboardId.BACKEND_QUERIES_SUMMARY,
        "title": "Query Details",
        "hidden": True,  # 不在常规列表中展示
    },
    ...
]

# src/sentry/dashboards/endpoints/organization_dashboards.py:264-309
def sync_prebuilt_dashboards(organization: Organization) -> None:
    enabled_prebuilt_dashboards = get_enabled_prebuilt_dashboards(organization)
    saved_prebuilt_dashboards = Dashboard.objects.filter(
        organization=organization,
        prebuilt_id__isnull=False,
    )
    # 为不存在的预置仪表盘创建记录,更新已存在的标题
    ...
    # 删除不再需要的预置仪表盘
    ...

# src/sentry/models/dashboard.py:429-452
@classmethod
def incremental_title(cls, organization, name):
    base_name = re.sub(r" ?copy ?(\d+)?$", "", name)
    matching_dashboards = cls.objects.filter(
        organization=organization, title__regex=rf"^{re.escape(base_name)} ?(copy)? ?(\d+)?$"
    ).values("title")
    if not matching_dashboards:
        return name
    next_copy_number = 0
    for dashboard in matching_dashboards:
        match = re.search(r" copy ?(\d+)?", dashboard["title"])
        if match:
            copy_number = int(match.group(1) or 0)
            next_copy_number = max(next_copy_number, copy_number + 1)
    if next_copy_number == 0:
        return f"{base_name} copy"
    return f"{base_name} copy {next_copy_number}"

# src/sentry/models/dashboard.py:474-498
class DashboardRevision(DefaultFieldsModel):
    SNAPSHOT_SCHEMA_VERSION = 1
    RETENTION_LIMIT = 10

    created_by_id = HybridCloudForeignKey("sentry.User", ...)
    title = models.CharField(max_length=255)
    source = models.CharField(max_length=32, default="edit")
    snapshot = JSONField(default=dict)
    snapshot_schema_version = models.IntegerField()
    dashboard = FlexibleForeignKey("sentry.Dashboard", on_delete=models.CASCADE)

# src/sentry/models/dashboard_widget.py:346-386
class DashboardWidget(Model):
    dashboard = FlexibleForeignKey("sentry.Dashboard")
    order = BoundedPositiveIntegerField(null=True)    # 排列顺序
    title = models.CharField(max_length=255)
    description = models.TextField(null=True, blank=True)
    thresholds = JSONField(null=True)                 # 阈值配置
    interval = models.CharField(max_length=10, null=True)
    display_type = BoundedPositiveIntegerField(       # 显示类型
        choices=DashboardWidgetDisplayTypes.as_choices()
    )
    date_added = models.DateTimeField(default=timezone.now)
    widget_type = BoundedPositiveIntegerField(        # 数据源类型
        choices=DashboardWidgetTypes.as_choices(), null=True
    )
    limit = models.IntegerField(null=True)            # 返回数据行数限制
    detail = JSONField(null=True)                     # 展示细节配置
    discover_widget_split = BoundedPositiveIntegerField(
        choices=DashboardWidgetTypes.as_choices(), null=True
    )
    dataset_source = BoundedPositiveIntegerField(     # 数据集选取来源
        choices=DatasetSourcesTypes.as_choices(),
        default=DatasetSourcesTypes.UNKNOWN.value,
    )
    widget_snapshot = models.JSONField(null=True)     # 迁移前快照
    changed_reason = models.JSONField(null=True)      # 迁移字段丢弃原因

# src/sentry/models/dashboard_widget.py:221-258
class DashboardWidgetQuery(Model):
    widget = FlexibleForeignKey("sentry.DashboardWidget")
    name = models.CharField(max_length=255)        # 查询名称（在图例中显示）
    fields = ArrayField(models.TextField(), default=list)       # 字段列表
    conditions = models.TextField()                # 过滤条件
    aggregates = ArrayField(models.TextField(), null=True)      # 聚合函数
    columns = ArrayField(models.TextField(), null=True)         # 非聚合列
    field_aliases = ArrayField(models.TextField(), null=True)   # 字段别名
    orderby = models.TextField(default="")         # 排序条件
    order = BoundedPositiveIntegerField()          # 查询在 Widget 中的顺序
    is_hidden = models.BooleanField(default=False) # 是否隐藏（用于指标部件后台查询）
    selected_aggregate = models.IntegerField(null=True)  # Big Number 选中的聚合索引

# src/sentry/models/dashboard_widget.py:177-205
class DashboardWidgetDisplayTypes(TypesClass):
    LINE_CHART = 0           # 折线图
    AREA_CHART = 1           # 面积图
    BAR_CHART = 3            # 柱状图
    TABLE = 4                # 表格
    BIG_NUMBER = 6           # 大数字
    DETAILS = 8              # 详情列表
    CATEGORICAL_BAR_CHART = 9  # 分类柱状图
    WHEEL = 10               # 圆环/饼图（wheel）
    RAGE_AND_DEAD_CLICKS = 11  # 愤怒点击与死点击
    SERVER_TREE = 12         # 服务调用树
    TEXT = 13                # 文本部件
    AGENTS_TRACES_TABLE = 14 # AI Agent Trace 表格
    HEATMAP = 15             # 热力图

# src/sentry/models/dashboard_widget.py:210-213
MAX_WIDGET_LIMIT_BY_DISPLAY_TYPE: dict[int, int] = {
    DashboardWidgetDisplayTypes.CATEGORICAL_BAR_CHART: 25,
    DashboardWidgetDisplayTypes.TABLE: 20,
}

# src/sentry/models/dashboard_widget.py:50-93
class DashboardWidgetTypes(TypesClass):
    DISCOVER = 0        # @deprecated 旧版联合查询
    ISSUE = 1           # Issue 查询
    RELEASE_HEALTH = 2  # 发布健康
    METRICS = 3         # 指标查询
    ERROR_EVENTS = 100  # 拆分后的错误事件
    TRANSACTION_LIKE = 101  # 拆分后的事务类数据
    SPANS = 102         # Span 数据
    LOGS = 103          # 日志
    TRACEMETRICS = 104  # Trace 指标
    PREPROD_APP_SIZE = 105  # 预发布应用尺寸

# src/sentry/models/dashboard_widget.py:277-343
class DashboardWidgetQueryOnDemand(Model):
    dashboard_widget_query = FlexibleForeignKey("sentry.DashboardWidgetQuery")
    spec_hashes = ArrayField(models.TextField(), default=list)
    spec_version = models.IntegerField(null=True)
    extraction_state = models.CharField(
        max_length=30,
        choices=OnDemandExtractionState.choices  # 多个启用/禁用状态
    )

def can_extraction_be_auto_overridden(self):
    if self.extraction_state in [
        self.OnDemandExtractionState.DISABLED_MANUAL,
        self.OnDemandExtractionState.DISABLED_HIGH_CARDINALITY,
        self.OnDemandExtractionState.DISABLED_SPEC_LIMIT,
    ]:
        return False
    return True

# src/sentry/models/dashboard_permissions.py:23-53
class DashboardPermissions(Model):
    is_editable_by_everyone = models.BooleanField(default=True, db_default=True)
    teams_with_edit_access = models.ManyToManyField(
        "sentry.Team", through=DashboardPermissionsTeam, blank=True
    )
    dashboard = models.OneToOneField(
        "sentry.Dashboard", on_delete=models.CASCADE, related_name="permissions"
    )

    def has_edit_permissions(self, user_id):
        if self.is_editable_by_everyone:
            return True
        if user_id == self.dashboard.created_by_id:
            return True  # 创建者永远有编辑权限
        return self.teams_with_edit_access.filter(
            organizationmemberteam__organizationmember__user_id=user_id
        ).exists()

# src/sentry/models/dashboard.py:286-294
class DashboardFavoriteUser(DefaultFieldsModel):
    user_id = HybridCloudForeignKey("sentry.User", on_delete="CASCADE")
    organization = FlexibleForeignKey("sentry.Organization")
    dashboard = FlexibleForeignKey("sentry.Dashboard", on_delete=models.CASCADE)
    position = models.PositiveSmallIntegerField(null=True)
    favorited = models.BooleanField(db_default=True)

self.filter(
    organization=organization,
    user_id=user_id,
    favorited=True,
    position__gt=deleted_position,
).update(position=models.F("position") - 1)

# src/sentry/dashboards/endpoints/organization_dashboards.py:448-452
if features.has("organizations:dashboards-prebuilt-insights-dashboards", organization):
    # 同步预置仪表盘到数据库
    ...
    sync_prebuilt_dashboards(organization)

# src/sentry/snuba/discover.py:113-151
def zerofill(
    data: SnubaData,
    start_param: datetime,
    end_param: datetime,
    rollup: int,
    orderby: list[str],
    time_col_name: str | None = None,
) -> SnubaData:
    return_value: SnubaData = []
    start = int(to_naive_timestamp(naiveify_datetime(start_param)) / rollup) * rollup
    end = (int(to_naive_timestamp(naiveify_datetime(end_param)) / rollup) * rollup) + rollup
    data_by_time: dict[int, SnubaData] = {}
    ...
    for key in range(start, end, rollup):
        if key in data_by_time and len(data_by_time[key]) > 0:
            return_value.extend(data_by_time[key])
        else:
            return_value.append({"time": key})  # 空桶：只包含 timestamp,聚合字段为 0
    ...

# src/sentry/snuba/discover.py:354-356
query_results = bulk_snuba_queries(
    [query.get_snql_query() for query in query_list], referrer, query_source=query_source
)