Cross-Workspace Trace Query within the Same Organization Usage Guide¶

This document explains the switch configuration, interface usage, and common issues for the cross-workspace Trace query capability within the same organization in the Deployment Plan Studio.

This capability is used to query trace data from multiple workspaces under the same organization based on a specified trace_id. It is only intended for Trace query scenarios and does not alter the cross-space semantics of regular DQL query interfaces.

Prerequisites¶

The Studio backend version must include the SameOrgTraceQuerySet configuration and the dedicated cross-organization Trace query interface.
The target workspaces must belong to the same organization as the current workspace.
To query non-current workspaces, SameOrgTraceQuerySet.enable must be enabled.
No separate parameter adjustment is needed on the Kodo side. The Studio backend will carry the target workspace list in internal requests.

Configuration Switch¶

SameOrgTraceQuerySet is located in the Studio backend service configuration and is disabled by default.

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

Configuration item description:

Configuration Item	Default Value	Description
`enable`	`false`	Whether to allow cross-workspace Trace queries within the same organization. When disabled, only the current workspace can be queried.
`maxWorkspaceCount`	`20`	The maximum number of workspace UUIDs allowed to be passed in a single Trace query and workspace list filter.
`maxLimit`	`1000`	The maximum allowed value for the explicit `limit` parameter in a single Trace query.
`maxTimeRangeHours`	`24`	The maximum time window allowed for a single Trace query, in hours.
`workspaceListPageSizeMax`	`100`	The maximum allowed page size for the interface that retrieves the simplified information list of workspaces within the same organization.

After enabling the configuration, the relevant Studio backend services need to be restarted.

Switch Behavior¶

Switch Disabled¶

When SameOrgTraceQuerySet.enable=false:

The interface for retrieving the simplified information list of workspaces within the same organization remains functional.
The Trace query interface only allows querying the current workspace.
If the target workspace UUID list in the request contains non-current workspaces, the interface will return:

{
  "code": 406,
  "errorCode": "ft.SameOrgTraceQueryDisabled",
  "message": "Cross-workspace Trace query within the same organization is not enabled"
}

If only the current workspace UUID is passed, or if no workspace UUID list is passed, it is equivalent to querying trace data from the current workspace.

Switch Enabled¶

When SameOrgTraceQuerySet.enable=true, the Trace query interface allows passing multiple workspace UUIDs under the same organization. The server will validate the number of workspaces, the time window, and query parameters, and will carry the target workspace list during internal queries.

Retrieve Simplified Information List of Workspaces within the Same Organization¶

This interface is not controlled by SameOrgTraceQuerySet.enable and can be used to select target workspaces for Trace queries.

OpenAPI:

POST /api/v1/workspace/same_org/list

AIAPI:

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

Common request parameters:

Parameter	Description
`workspaceUUIDs`	OpenAPI parameter, optional, filters by workspace UUID list.
`workspace_uuids`	AIAPI parameter, optional, filters by workspace UUID list.
`pageIndex` / `page_index`	Page number, defaults to `1`.
`pageSize` / `page_size`	Number of items per page, defaults to `20`, maximum value is controlled by `workspaceListPageSizeMax`.

Cross-Organization Trace Query¶

OpenAPI:

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

AIAPI:

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

OpenAPI parameters use camelCase format, AIAPI parameters use underscore format.

OpenAPI Parameter	AIAPI Parameter	Description
`traceId`	`trace_id`	Required, Trace ID.
`workspaceUUIDs`	`workspace_uuids`	Optional, target workspace UUID list; queries the current workspace if not provided.
`whereClause`	`where_clause`	Optional, additional DQL filter conditions, should not include the `trace_id` condition.
`source`	`source`	Optional, Trace data source, queries all sources by default.
`startTime`	`start_time`	Optional, millisecond timestamp; defaults to the last 1 hour if not provided.
`endTime`	`end_time`	Optional, millisecond timestamp; if not provided, the internal DQL `time_range` will only have a start time.
`limit`	`limit`	Optional, maximum number of results to return; controlled by internal query defaults if not provided.
`cursorTime`	`cursor_time`	Optional, cursor time for pagination.
`searchAfter`	`search_after`	Optional, cursor for pagination.

OpenAPI does not support selectClause and offset. Use cursorTime / searchAfter for pagination.

OpenAPI Request Example¶

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 Request Example¶

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

Common Issues¶

Returns `ft.SameOrgTraceQueryDisabled`¶

Indicates that the cross-workspace Trace query switch within the same organization is not enabled for the current site, but the request contains UUIDs of non-current workspaces.

Resolution:

If you only need to query the current workspace, remove other workspace UUIDs.
If cross-workspace querying is indeed required, enable SameOrgTraceQuerySet.enable in the Studio backend configuration and restart the service.

Can the Original `query_data` Interface Still Accept Workspace Lists from the Same Organization?¶

No. The /api/v1/df/query_data, /api/v1/df/query_data_v1, /api/v1/df/asynchronous/query_data interfaces, and the regular DQL query interfaces of AIAPI no longer accept entry parameters for cross-workspace queries within the same organization. Please use the dedicated cross-organization Trace query interface instead.

How to Query Without Passing an End Time?¶

If endTime / end_time is not passed, the DQL time_range composed internally by the server will only have a start time. If the start time is also not passed, the server defaults to using the start time of the last 1 hour.