span查询

最近更新时间: 2026-10-11 00:12:03

1. 接口描述

接口请求域名： tsf.api3.fincloud.tencent.com。

span查询

默认接口请求频率限制：20次/秒。

接口更新时间：2026-02-04 20:25:42。

接口只验签名不鉴权。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见公共请求参数。

参数名称	必选	允许NULL	类型	描述
Action	是	否	String	公共参数，本接口取值：SearchSpan
Version	是	否	String	公共参数，本接口取值：2018-03-26
Region	是	否	String	公共参数，地域信息可通过DescribeRegions接口查看产品支持的地域列表
MinDuration	否	否	Uint64	最小耗时示例值：
Tags	否	否	String	用户自定义标签示例值：
StartTime	是	否	String	搜索开始时间示例值：
CallerServiceName	否	否	String	调用方服务名示例值：
CallerInterfaceName	否	否	String	调用方接口名示例值：
CalleeIp	否	否	String	被调方IP 示例值：
OrderBy	否	否	String	排序方式，支持"timestamp"和"duration" 示例值：
OrderType	否	否	String	排序方向，支持"asc"和"desc" 示例值：
Offset	否	否	Uint64	查询trace偏移量示例值：
TraceId	否	否	String	调用链traceid 示例值：
CalleeInterfaceName	否	否	String	被调方接口名示例值：
Limit	否	否	Uint64	返回span数目，取值范围[0, 100]，默认值20 示例值：
ErrorTrace	否	否	Bool	是否仅展示错误调用链示例值：
MaxDuration	否	否	Uint64	最长耗时示例值：
NamespaceId	否	否	String	TSF命名空间ID 示例值：
SpanId	否	否	String	调用链spanid 示例值：
EndTime	是	否	String	搜索结束时间示例值：
CalleeServiceName	否	否	String	被调方服务名示例值：
ResultStatus	否	否	String	错误码示例值：
CallerIp	否	否	String	调用方IP 示例值：

3. 输出参数

参数名称	类型	描述
Result	TsfPageTraceSpanInfo	span信息示例值：查看
RequestId	String	唯一请求 ID，每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见公共错误码。

错误码	描述
FailedOperation.TsfApmCtsdbClientRequestError	TSF应用性能管理CTSDB客户端调用失败。
InternalError.UnhandledException	[%s]模块未处理异常。。
InvalidParameter.TsfApmTraceSearchRequestParamError	TSF应用性能管理调用链搜索请求参数错误。
ResourceNotFound.MicroserviceOffline	目标微服务已离线[%s]。。
ResourceNotFound.TsfApmNamespaceUnavailable	TSF应用性能管理子账户没有可用的命名空间。
InvalidParameterValue.ServiceNotExistsOrPermissionDenied	服务不存在或权限不足。

5. 示例

示例1 demo

输入示例

POST / HTTP/1.1
Host: tsf.api3.fincloud.tencent.com
Content-Type: application/json
X-TC-Action: SearchSpan
<Common Parameters>

{
    "OrderBy": "", 
    "CalleeInterfaceName": "", 
    "CalleeServiceName": "", 
    "ErrorTrace": true, 
    "Tags": "", 
    "OrderType": "", 
    "CallerServiceName": "", 
    "Offset": 1, 
    "CalleeIp": "", 
    "NamespaceId": "", 
    "CallerIp": "", 
    "TraceId": "", 
    "Limit": 1, 
    "ResultStatus": "", 
    "StartTime": "", 
    "MinDuration": 1, 
    "EndTime": "", 
    "CallerInterfaceName": "", 
    "SpanId": "", 
    "MaxDuration": 1
}

输出示例

{
    "Response": {
        "Result": {
            "Content": [
                {
                    "Kind": "", 
                    "TraceId": "", 
                    "Name": "", 
                    "RemoteEndpoint": {
                        "Ipv4": "", 
                        "ServiceName": "", 
                        "Port": 0, 
                        "Ipv6": ""
                    }, 
                    "Timestamp": 1, 
                    "LocalEndpoint": {
                        "Ipv4": "", 
                        "ServiceName": "", 
                        "Port": 0, 
                        "Ipv6": ""
                    }, 
                    "ClusterType": "", 
                    "NamespaceId": "", 
                    "NamespaceName": "", 
                    "GroupName": "", 
                    "ServiceName": "", 
                    "ResultStatus": "", 
                    "ServiceId": "", 
                    "Duration": 0.0, 
                    "SpanId": "", 
                    "ResultCode": "", 
                    "LocalComponent": "", 
                    "GroupId": "", 
                    "ParentId": "", 
                    "TagList": [
                        {
                            "Value": "", 
                            "Key": ""
                        }
                    ]
                }
            ], 
            "TotalCount": 1
        }, 
        "RequestId": ""
    }
}