同组织跨工作空间 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

配置项说明：

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

开关行为¶

开关关闭¶

SameOrgTraceQuerySet.enable=false 时：

• 获取同组织工作空间简化信息列表接口仍可正常使用。
• Trace 查询接口仅允许查询当前工作空间。
• 如果请求中的目标工作空间 UUID 列表包含非当前工作空间，OpenAPI 会返回 code=406、errorCode=ft.ParameterCheckFailed。该错误码也用于其它参数校验失败，不能仅凭错误码判定开关状态。

如只传当前工作空间 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

常用请求参数：

列表按工作空间 ID 倒序返回，不使用 pageIndex / page_index。分页字段对应关系如下：

例如，OpenAPI 首次请求体为：

{"pageSize": 20}

若响应中 hasMore=true 且 nextBeforeWorkspaceId=12345，下一次请求为：

{"pageSize": 20, "beforeWorkspaceId": 12345}

AIAPI 的对应请求为：

{"page_size": 20, "before_workspace_id": 12345}

分页时保持原有工作空间筛选条件不变；当 hasMore / has_more 为 false 时停止。工作空间 ID 只用于列表分页，后续 Trace 查询使用工作空间 UUID。

同组织 Trace 查询¶

OpenAPI：

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

AIAPI：

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

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

OpenAPI 不支持 selectClause 和 offset，分页请使用 cursorTime / cursorToken，具体流程见下文。

OpenAPI 请求示例¶

示例中的工作空间、链路 ID 和时间范围需替换为实际值；分页期间保持这些查询条件不变。

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
}

Trace 滚动分页¶

OpenAPI 的单次结果位于 content.data[0]；AIAPI 的对应位置为 data.data[0]。读取其中的 next_cursor_time 和 next_cursor_token。

1. 首次查询可省略游标，也可将 cursorTime / cursor_time 设为查询结束时间的 13 位毫秒时间戳。
2. 当 next_cursor_time < 0 时结束分页；不要把该负值再传回接口。
3. 需要下一页时，将 next_cursor_time 原样传回，并同时传回非空的 next_cursor_token。后续游标可能是 16 位微秒时间戳，不要转换成毫秒，否则可能漏掉同一时间戳附近的数据。
4. next_cursor_token 为空时可以省略或传空字符串。缺少有效的 next_cursor_time 时，不要自行构造游标或持续重复请求，应记录响应并排查。

假设上一页返回的 next_cursor_time 为 1772519729000123、next_cursor_token 为 cursor_example，OpenAPI 下一页请求体为：

{
  "traceId": "TRACE-XXXX",
  "workspaceUUIDs": ["wksp_xxx", "wksp_yyy"],
  "startTime": 1772516130000,
  "endTime": 1772519730000,
  "limit": 100,
  "cursorTime": 1772519729000123,
  "cursorToken": "cursor_example"
}

上面的游标仅为示意，实际请求必须使用上一页响应值。AIAPI 使用 cursor_time / cursor_token，其余字段使用前述下划线命名。startTime / endTime（或 start_time / end_time）仍保持原来的毫秒时间范围，不能随分页游标一起换算。若使用了 source 或过滤条件，翻页时也需保持不变。

常见问题¶

返回 ft.ParameterCheckFailed¶

关闭同组织跨工作空间 Trace 查询开关并请求其它工作空间时，OpenAPI 会返回该错误。目标工作空间不属于同组织、时间范围或其它参数不合法时也可能返回同一错误，需结合请求参数排查。

处理方式：

• 先核对时间范围、游标、工作空间归属及站点配置。
• 如果只需查当前工作空间，移除其它工作空间 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 小时的开始时间。