1. 接口描述
接口请求域名： dbbrain.tencentcloudapi.com 。
查询指定实例在时间窗口内的阻塞日志扁平明细列表，不建阻塞树。每一条Item对应一次blocked_process_report（一条blocker→blocked边）在某一次monitorLoop内被lock monitor捕获的瞬时数据。支持按ReportTime / DurationMs / BlockedWaitTimeMs / BlockingWaitTimeMs升降序排序，并支持根因、数据库名、头SQL / 被阻塞SQL MD5、会话ID、登录名、客户端主机 / 应用、被阻塞锁模式、等待时长范围过滤与分页。适合普通表格展示与二次过滤；若需查看某个采集点的完整链路拓扑，请透传返回的MonitorLoop调用DescribeBlockingLockTree。注意：同一blocker→blocked会话对跨monitorLoop连续采集场景下会产生多条明细行，若需统计发生多少次阻塞请按(BlockingSessionId, BlockedSessionId, BlockedWaitResource)自行去重。时间字段按服务端时区UTC+8解析，建议单次查询跨度≤7天。
默认接口请求频率限制：20次/秒。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：DescribeBlockingLogs。 |
| Version | 是 | String | 公共参数，本接口取值：2021-05-27。 |
| Region | 是 | String | 公共参数，详见产品支持的 地域列表。 |
| InstanceId | 是 | String | 实例ID。 示例值：mssql-15rso1sb |
| Product | 是 | String | 服务产品类型，固定为sqlserver。 示例值：sqlserver |
| StartTime | 是 | String | 查询起始时间（服务端时区 UTC+8），格式：yyyy-MM-dd HH:mm:ss。必须在最近 30 天内，否则返回 InvalidParameterValue。 示例值：2026-10-15 21:00:00 |
| EndTime | 是 | String | 查询结束时间（服务端时区 UTC+8），格式：yyyy-MM-dd HH:mm:ss，需大于 StartTime。单次查询跨度必须 ≤ 1 天（24 小时），否则返回 InvalidParameterValue。大跨度趋势场景请改用 DescribeBlockingTrend。 示例值：2026-10-15 21:15:00 |
| RootCause | 否 | String | 根因过滤（可选），支持：C1_LONG_QUERY=长事务查询持锁；C2_SLEEP_UNCOMMITTED=sleeping会话持未提交事务；C3_LOCK_ESCALATION=锁升级；C4_HIGH_CONCURRENCY=高并发争用；C5_INDEX_MISS=索引缺失导致大范围锁；C6_ORPHAN_TRAN=孤儿事务。 示例值：C2_SLEEPING_UNCOMMITTED |
| BlockingSqlMd5 | 否 | String | 头SQL（blocker）MD5过滤（可选）。 示例值：5de54dd3b0ebe66a69262a59721986e3 |
| BlockedSqlMd5 | 否 | String | 被阻塞SQL（blocked）MD5过滤（可选）。 示例值：6f89b5ae86f5ccba7252cf7a70697776 |
| DatabaseNames.N | 否 | Array of String | 数据库名列表过滤（可选），按阻塞事件所在数据库名过滤；列表内任意匹配即命中，最多50项。多库实例场景下推荐用本字段定位阻塞所在库。 示例值：["test_lock"] |
| BlockingSessionIds.N | 否 | Array of Integer | 头阻塞会话 ID（SPID）列表过滤（可选），列表内任意匹配即命中，最多50项。 示例值：[170] |
| BlockedSessionIds.N | 否 | Array of Integer | 被阻塞会话 ID（SPID）列表过滤（可选），列表内任意匹配即命中，最多50项。 示例值：[72] |
| BlockingLoginNames.N | 否 | Array of String | 头阻塞登录名列表过滤（可选），列表内任意匹配即命中，最多50项。 示例值：["NT SERVICE\SQLAgent$S24"] |
| BlockedLoginNames.N | 否 | Array of String | 被阻塞登录名列表过滤（可选），列表内任意匹配即命中，最多50项。 示例值：["report_svc"] |
| BlockingHostNames.N | 否 | Array of String | 头阻塞客户端主机列表过滤（可选），列表内任意匹配即命中，最多50项。 示例值：["TEN-4DUQ5CVE6R"] |
| BlockedHostNames.N | 否 | Array of String | 被阻塞客户端主机列表过滤（可选），列表内任意匹配即命中，最多50项。 示例值：["TEN-4DUQ5CVE6R"] |
| BlockingClientApps.N | 否 | Array of String | 头阻塞客户端应用列表过滤（可选），列表内任意匹配即命中，最多50项。 示例值：["python-pymssql"] |
| BlockedClientApps.N | 否 | Array of String | 被阻塞客户端应用列表过滤（可选），列表内任意匹配即命中，最多50项。 示例值：["python-pymssql"] |
| BlockedLockModes.N | 否 | Array of String | 被阻塞方等待锁模式列表过滤（可选），SQL Server原生lock_mode枚举，常见取值（非穷尽）：S、U、X、IS、IU、IX、SIU、SIX、UIX、Sch-S、Sch-M；serializable隔离级别下还可能出现RangeS-S / RangeS-U / RangeX-X / RangeI-N系列。列表内任意匹配即命中，最多50项。 示例值：["X"] |
| DurationMsMin | 否 | Integer | 被阻塞方等待时长下限（毫秒，含），用于筛选慢阻塞（可选）。 示例值：13356 |
| DurationMsMax | 否 | Integer | 被阻塞方等待时长上限（毫秒，含），用于筛选阻塞时长不超过某值的记录（可选）。 示例值：13356 |
| OrderBy | 否 | String | 排序字段（可选），支持reportTime（按明细行上报时间，默认）/ durationMs（按链路阻塞时长）/ blockedWaitTimeMs（按被阻塞方等待时长）/ blockingWaitTimeMs（按头阻塞自身等待时长）。 示例值：DurationMs |
| OrderDirection | 否 | String | 排序方向（可选），支持desc（默认，倒序）/ asc（正序）。 示例值：desc |
| Limit | 否 | Integer | 返回条数上限，默认20，最大100。 示例值：100000 |
| Offset | 否 | Integer | 偏移量，默认 0。 示例值：18 |
| WithXml | 否 | Boolean | 是否返回原始 blocked_process_report XML（可选，默认 false 不返回）。该字段体积较大（KB 级起步，含完整执行计划/等待链/死锁明细等原始上下文），常规列表展示不需要，仅在需要查看完整 XML 现场（如线下诊断、离线分析）时将本参数置为 true 按需拉取。 示例值：true |
3. 输出参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| TotalCount | Integer | 满足条件的阻塞明细总条数。 示例值：63 |
| Items | Array of BlockingLogItem | 阻塞明细行列表（按OrderBy / OrderDirection排序）。 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 查询阻塞日志详情
查询阻塞日志详情
输入示例
POST / HTTP/1.1
Host: dbbrain.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeBlockingLogs
<公共请求参数>
{
"InstanceId": "mssql-15rso1sb",
"Product": "sqlserver",
"StartTime": "2026-10-15 21:00:00",
"EndTime": "2026-10-15 21:15:00",
"WithXml": true
}输出示例
{
"Response": {
"Items": [
{
"BlockedClientApp": "SQLAgent - TSQL JobStep (Job 0x18EF8CB8CF2AFD4FB112247D30FE8605 : Step 1)",
"BlockedHostName": "TEN-4DUQ5CVE6R",
"BlockedInputBuffer": "EXEC DBO.JOB_MONITOR_FILTER",
"BlockedIsolationLevel": "read committed (2)",
"BlockedLastTranStarted": "2026-10-15T13:12:26.417",
"BlockedLockMode": "Sch-S",
"BlockedLoginName": "app_user",
"BlockedProcessXml": "<blocked-process-report monitorLoop=\"2123355\">\r\n <blocked-process>\r\n <process id=\"process08cce44605\" taskpriority=\"0\" logused=\"0\" waitresource=\"KEY: 7:115467663 (a0982edbe93f50f5) \" waittime=\"42607\" ownerId=\"749987700\" transactionname=\"INSERT\" lasttranstarted=\"2026-10-15T13:12:26.417\" XDES=\"0x0xa570b5da6773d\" lockMode=\"Sch-S\" schedulerid=\"8\" kpid=\"78426\" status=\"suspended\" spid=\"116\" sbid=\"0\" ecid=\"0\" priority=\"0\" trancount=\"2\" lastbatchstarted=\"2026-10-15T13:12:26.850\" lastbatchcompleted=\"2026-10-15T13:12:26.850\" lastattention=\"1900-01-01T00:00:00.327\" clientapp=\"SQLAgent - TSQL JobStep (Job 0x18EF8CB8CF2AFD4FB112247D30FE8605 : Step 1)\" hostname=\"TEN-4DUQ5CVE6R\" hostpid=\"50025\" loginname=\"app_user\" isolationlevel=\"read committed (2)\" xactid=\"749987700\" currentdb=\"7\" currentdbname=\"reportdb\" lockTimeout=\"4294967295\" clientoption1=\"673185824\" clientoption2=\"128056\">\r\n <executionStack>\r\n <frame line=\"11\" stmtstart=\"57916\" stmtend=\"27743\" sqlhandle=\"0x030005002b567886d367cec25c516e540c4f7a1ee4f05a8f87252afc8e4abe27dc9cc72a43cf68c30000000000000000000000000000000000000000\"/>\r\n <frame line=\"1\" stmtend=\"52\" sqlhandle=\"0x030005007a75416b29235ec6317951ec353e9af1a86d81d7941b638d7f4e6a883bcfd5798a26a8870000000000000000000000000000000000000000\"/>\r\n </executionStack>\r\n <inputbuf>\r\nEXEC DBO.JOB_MONITOR_FILTER </inputbuf>\r\n </process>\r\n </blocked-process>\r\n <blocking-process>\r\n <process status=\"suspended\" spid=\"120\" sbid=\"0\" ecid=\"0\" priority=\"0\" trancount=\"2\" lastbatchstarted=\"2026-10-15T13:12:26.820\" lastbatchcompleted=\"2026-10-15T13:12:26.820\" lastattention=\"1900-01-01T00:00:00.664\" clientapp=\"SQLAgent - TSQL JobStep (Job 0x8FA6C0ECC85510429881508623587978 : Step 1)\" hostname=\"TEN-4DUQ5CVE6R\" hostpid=\"50025\" loginname=\"sa\" isolationlevel=\"read committed (2)\" xactid=\"749941246\" currentdb=\"7\" currentdbname=\"reportdb\" lockTimeout=\"4294967295\" clientoption1=\"673185824\" clientoption2=\"128056\">\r\n <executionStack>\r\n <frame line=\"278\" stmtstart=\"19639\" stmtend=\"20836\" sqlhandle=\"0x0300050010cf5e13b947f01843d20fc9f62fe896ba621d42291aa485b93d5188c21b7d4e86817a7b0000000000000000000000000000000000000000\"/>\r\n <frame line=\"5\" stmtstart=\"94\" stmtend=\"170\" sqlhandle=\"0x0300050070304dc2f0940d07fe829a9ce01dd7ee9159e405acb43e0ad8984b85b61c56e716e64ac00000000000000000000000000000000000000000\"/>\r\n </executionStack>\r\n <inputbuf>\r\nSELECT COUNT(*) FROM DBO.LARGE_TABLE WITH (TABLOCKX) </inputbuf>\r\n </process>\r\n </blocking-process>\r\n</blocked-process-report>\r\n",
"BlockedSessionId": 116,
"BlockedSqlMd5": "05c5e788a3fe2ace9f63efd9bee972c8",
"BlockedSqlTemplate": "EXEC DBO.JOB_MONITOR_FILTER",
"BlockedStatus": "suspended",
"BlockedTranCount": 2,
"BlockedTransactionId": 749987700,
"BlockedTransactionName": "INSERT",
"BlockedWaitResource": "KEY: 7:115467663 (a0982edbe93f50f5) ",
"BlockedWaitTimeMs": 42607,
"BlockingClientApp": "SQLAgent - TSQL JobStep (Job 0x8FA6C0ECC85510429881508623587978 : Step 1)",
"BlockingHostName": "TEN-4DUQ5CVE6R",
"BlockingInputBuffer": "SELECT COUNT(*) FROM DBO.LARGE_TABLE WITH (TABLOCKX)",
"BlockingIsolationLevel": "read committed (2)",
"BlockingLastTranStarted": "",
"BlockingLockMode": "",
"BlockingLoginName": "sa",
"BlockingSessionId": 120,
"BlockingSqlMd5": "2a1826132ed238dfb711c241f09b42a9",
"BlockingSqlTemplate": "SELECT COUNT(*) FROM DBO.LARGE_TABLE WITH (TABLOCKX)",
"BlockingStatus": "suspended",
"BlockingTranCount": 2,
"BlockingTransactionName": "",
"BlockingWaitTimeMs": 0,
"DatabaseName": "reportdb",
"DurationMs": 42607,
"MonitorLoop": "2123355",
"ReportTime": "2026-10-15 21:12:26",
"RootCause": "C1_LONG_QUERY",
"RootCauseDesc": "长事务查询持锁"
}
],
"TotalCount": 63,
"RequestId": "88eb3bd5-21aa-402b-99e3-1fa51fdc3640"
}
}5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况，并自动生成各语言版本的 API 代码，也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Java: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for PHP: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Go: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Node.js: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for .NET: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for C++: CNB, GitHub, Gitee
- Tencent Cloud SDK 3.0 for Ruby: CNB, GitHub, Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。
| 错误码 | 描述 |
|---|---|
| AuthFailure | CAM签名/鉴权错误。 |
| DryRunOperation | DryRun 操作，代表请求将会是成功的，只是多传了 DryRun 参数。 |
| FailedOperation | 操作失败。 |
| FailedOperation.AuditNotOpened | 实例审计未开启 |
| FailedOperation.PaasAuditNotOpened | paas 侧商业审计状态未开启 |
| FailedOperation.SegmentLoading | 数据加载中 |
| InternalError | 内部错误。 |
| InternalError.DbOperationFailed | 数据库操作失败 |
| InternalError.InternalError | InternalError.InternalError |
| InvalidFilter | 无效的过滤器 |
| InvalidParameter | 参数错误。 |
| InvalidParameter.InvalidParameter | InvalidParameter.InvalidParameter |
| InvalidParameterCombination | 无效参数组合 |
| InvalidParameterValue | 参数取值错误。 |
| InvalidParameterValue.InvalidParameterValue | InvalidParameterValue.InvalidParameterValue |
| LimitExceeded | 超过配额限制。 |
| MissingParameter | 缺少参数错误。 |
| MissingParameter.MissingParameter | MissingParameter.MissingParameter |
| OperationDenied | 操作被拒绝。 |
| OperationDenied.UserHasNoStrategy | CAM鉴权错误。 |
| RegionError | 地域错误 |
| RequestLimitExceeded | 请求的次数超过了频率限制。 |
| ResourceInUse | 资源被占用。 |
| ResourceInsufficient | 资源不足。 |
| ResourceNotFound | 资源不存在。 |
| ResourceUnavailable | 资源不可用。 |
| ResourcesSoldOut | 资源售罄。 |
| UnauthorizedOperation | 未授权操作。 |
| UnauthorizedOperation.UnauthorizedOperation | UnauthorizedOperation.UnauthorizedOperation |
| UnknownParameter | 未知参数错误。 |
| UnsupportedOperation | 操作不支持。 |
| UnsupportedOperation.HasDuplicatedTask | 该时间范围内的审计日志已下载 |
