同组织跨工作空间 Trace 查询使用说明¶

本文说明部署版 Studio 中同组织跨工作空间 Trace 查询能力的开关配置、接口使用方式和常见问题。

该能力用于在同一组织下，按指定 trace_id 查询多个工作空间中的链路数据。它只面向 Trace 查询场景，不改变常规 DQL 查询接口的跨空间语义。

使用前提¶

Studio 后端版本需要包含 SameOrgTraceQuerySet 配置和同组织 Trace 查询独立接口。
目标工作空间必须与当前工作空间属于同一组织。
如需查询非当前工作空间，必须开启 SameOrgTraceQuerySet.enable。
Kodo 侧参数无需单独调整，Studio 后端会在内部请求中携带目标工作空间列表。

配置开关¶

SameOrgTraceQuerySet 位于 Studio 后端服务配置中，默认关闭。

SameOrgTraceQuerySet:
  enable: false
  maxWorkspaceCount: 20
  maxLimit: 1000
  maxTimeRangeHours: 24
  workspaceListPageSizeMax: 100

配置项说明：

配置项	默认值	说明
`enable`	`false`	是否允许同组织跨工作空间 Trace 查询。关闭时只能查询当前工作空间。
`maxWorkspaceCount`	`20`	单次 Trace 查询和工作空间列表筛选允许传入的最大工作空间 UUID 数量。
`maxLimit`	`1000`	单次 Trace 查询显式传入 `limit` 时允许的最大值。
`maxTimeRangeHours`	`24`	单次 Trace 查询允许的最大时间窗口，单位小时。
`workspaceListPageSizeMax`	`100`	获取同组织工作空间简化信息列表接口允许的最大分页大小。

开启配置后，需要重启 Studio 后端相关服务。

开关行为¶

开关关闭¶

SameOrgTraceQuerySet.enable=false 时：

获取同组织工作空间简化信息列表接口仍可正常使用。
Trace 查询接口仅允许查询当前工作空间。
如果请求中的目标工作空间 UUID 列表包含非当前工作空间，接口会返回：

{
  "code": 406,
  "errorCode": "ft.SameOrgTraceQueryDisabled",
  "message": "同组织跨工作空间 Trace 查询开关未开启"
}

如只传当前工作空间 UUID，或不传工作空间 UUID 列表，则等价于查询当前工作空间的链路数据。

开关开启¶

SameOrgTraceQuerySet.enable=true 时，Trace 查询接口允许传入同组织下的多个工作空间 UUID。服务端会校验工作空间数量、时间窗口和查询参数，并在内部查询时携带目标工作空间列表。

相关接口¶

获取同组织工作空间简化信息列表¶

该接口不受 SameOrgTraceQuerySet.enable 控制，可用于选择 Trace 查询的目标工作空间。

OpenAPI：

POST /api/v1/workspace/same_org/list

AIAPI：

POST /api/v1/account/workspace/same_org/list

常用请求参数：

参数	说明
`workspaceUUIDs`	OpenAPI 参数，可选，按工作空间 UUID 列表过滤。
`workspace_uuids`	AIAPI 参数，可选，按工作空间 UUID 列表过滤。
`pageIndex` / `page_index`	页码，默认 `1`。
`pageSize` / `page_size`	每页数量，默认 `20`，最大值受 `workspaceListPageSizeMax` 控制。

同组织 Trace 查询¶

OpenAPI：

POST /api/v1/df/same_org/trace/query

AIAPI：

POST /api/v1/data/same_org/trace/query

OpenAPI 参数使用小驼峰格式，AIAPI 参数使用下划线格式。

OpenAPI 参数	AIAPI 参数	说明
`traceId`	`trace_id`	必填，链路 ID。
`workspaceUUIDs`	`workspace_uuids`	可选，目标工作空间 UUID 列表；不传时查询当前工作空间。
`whereClause`	`where_clause`	可选，追加 DQL 过滤条件，不需要包含 `trace_id` 条件。
`source`	`source`	可选，Trace 数据源，默认查询全部来源。
`startTime`	`start_time`	可选，毫秒时间戳；不传时默认最近 1 小时。
`endTime`	`end_time`	可选，毫秒时间戳；不传时内部 DQL `time_range` 只有开始时间。
`limit`	`limit`	可选，返回数量上限；不传时由内部查询默认控制。
`cursorTime`	`cursor_time`	可选，滚动分页游标时间。
`searchAfter`	`search_after`	可选，滚动分页游标。

OpenAPI 不支持 selectClause 和 offset，分页请使用 cursorTime / searchAfter。

OpenAPI 请求示例¶

curl --location 'https://<studio-backend-host>/api/v1/df/same_org/trace/query' \
  --header 'Content-Type: application/json' \
  --header 'DF-API-KEY: <your-openapi-key>' \
  --data '{
    "traceId": "TRACE-XXXX",
    "workspaceUUIDs": ["wksp_xxx", "wksp_yyy"],
    "startTime": 1772516130000,
    "endTime": 1772519730000,
    "limit": 100
  }'

AIAPI 请求示例¶

{
  "trace_id": "TRACE-XXXX",
  "workspace_uuids": ["wksp_xxx", "wksp_yyy"],
  "where_clause": "`service` = 'api'",
  "start_time": 1772516130000,
  "limit": 100
}

常见问题¶

返回 `ft.SameOrgTraceQueryDisabled`¶

表示当前站点未开启同组织跨工作空间 Trace 查询开关，但请求里包含了非当前工作空间 UUID。

处理方式：

如果只需查当前工作空间，移除其它工作空间 UUID。
如果确实需要跨工作空间查询，在 Studio 后端配置中开启 SameOrgTraceQuerySet.enable 并重启服务。

原 `query_data` 接口还能传同组织工作空间列表吗¶

不支持。/api/v1/df/query_data、/api/v1/df/query_data_v1、/api/v1/df/asynchronous/query_data 以及 AIAPI 的常规 DQL 查询接口不再接收同组织跨工作空间入口参数。请改用同组织 Trace 查询独立接口。

不传结束时间时如何查询¶

如果未传 endTime / end_time，服务端内部组成的 DQL time_range 只有开始时间。若开始时间也未传，服务端默认使用最近 1 小时的开始时间。