使用 Python SDK 查询日志和指标

Python SDK 提供统一的日志和指标查询能力，适用于自动化排查训练任务、通用服务和大模型推理服务的运行问题。使用本文示例前，请先完成 Python SDK 快速开始。

查询用户日志

用户日志来自容器标准输出和标准错误。SDK 提供两类接口：

client.logs.query()：直接按 Pod 名称查询，适合已知 Pod 名称的场景。
client.tasks.query_logs()、client.generalsvc.query_logs()、client.inference.query_logs()：按业务对象 ID 查询，SDK 自动关联 Pod。

按 Pod 查询日志

resp = client.logs.query(
    pods=["<POD_NAME>"],
    limit=100,
    offset=0,
    sort_order="asc",
)

print(f"total: {resp.total}")
for item in resp.logs:
    print(f"[{item.time}] [{item.pod_name}] {item.content}")

分页查询：

resp = client.logs.query(
    pods=["<POD_NAME>"],
    limit=100,
    offset=0,
    sort_order="asc",
)

next_page = client.logs.query(
    pods=["<POD_NAME>"],
    limit=100,
    offset=resp.latest_offset,
    sort_order="asc",
)

查询参数如下：

参数	说明
`pods`	Pod 名称列表。至少包含一个 Pod。
`container`	容器名称。仅查询单个 Pod 时可指定。
`start` / `end`	查询起止时间，使用 Unix 时间戳，单位为秒。
`limit`	每次返回最大条数，单次查询最大 `10000`。
`offset`	分页偏移量，`offset + limit` 最大 `100000`。
`sort_order`	排序方式，可选择 `asc` 或 `desc`。返回数据始终按时间正序排列。
`keyword`	全局关键词搜索，仅返回包含关键词的日志行。空字符串或纯空白等同不传；下载接口不支持关键词搜索。

响应字段如下：

字段	说明
`logs`	当前页日志列表。
`total`	匹配的日志总条数。
`latest_offset`	最新偏移量，可作为下一页的 `offset`。
`LogItem.time`	日志时间。
`LogItem.pod_name`	Pod 名称。
`LogItem.content`	日志正文。

如果 pods 为空，SDK 会抛出 ValueError。

按业务对象查询日志

按业务对象查询时，SDK 会自动关联该对象下的 Pod。

# 训练任务，传入任务 UUID。
task_logs = client.tasks.query_logs(
    "<TASK_UUID>",
    keyword="error",
    limit=100,
    sort_order="asc",
)

# 通用服务，传入通用服务 UUID。
general_service_logs = client.generalsvc.query_logs(
    "<GENERAL_SERVICE_UUID>",
    limit=100,
)

# 大模型推理服务，传入服务 ID。
llm_service_logs = client.inference.query_logs(
    123,
    limit=100,
)

高层日志接口参数如下：

参数	说明
`id`	业务对象 ID。训练任务和通用服务通常为 UUID 字符串，大模型推理服务为整数 ID。
`start` / `end`	查询起止时间，使用 Unix 时间戳，单位为秒。不传时，SDK 会根据业务对象和 Pod 信息推断查询范围。
`limit` / `offset`	分页参数。限制与底层日志查询一致。
`sort_order`	排序方式，可选择 `asc` 或 `desc`。
`keyword`	关键词搜索。

如果根据业务对象 ID 未关联到 Pod，查询接口返回空日志列表。

按时间和关键词查询

import time

now = int(time.time())
one_hour_ago = now - 3600

resp = client.tasks.query_logs(
    "<TASK_UUID>",
    keyword="error",
    start=one_hour_ago,
    end=now,
    limit=1000,
    offset=0,
    sort_order="asc",
)

for item in resp.logs:
    print(f"[{item.time}] {item.content}")

下载用户日志

需要保存排查记录时，可以将日志下载到文件。

按业务对象下载

file_path = client.tasks.download_logs(
    "<TASK_UUID>",
    file_path="./task.log",
    with_timestamp=True,
    with_pod_name=True,
)

print(file_path)

通用服务和大模型推理服务也支持同样的高层下载接口：

general_log = client.generalsvc.download_logs(
    "<GENERAL_SERVICE_UUID>",
    file_path="./general-service.log",
)

llm_log = client.inference.download_logs(
    123,
    file_path="./llm-service.log",
)

按 Pod 流式下载

lines = client.logs.download_stream(
    pods=["<POD_NAME>"],
    with_timestamp=True,
    with_pod_name=True,
)

for line in lines:
    print(line)

写入文件：

file_path = client.logs.download_stream_to_file(
    pods=["<POD_NAME>"],
    file_path="./pod.log",
)

print(file_path)

不传 file_path 时，SDK 会在当前目录自动生成日志文件名。file_path 不能是目录；如果目标文件已存在，应确保文件为空或改用新文件。下载参数如下：

参数	说明
`pods`	Pod 名称列表。使用底层接口时必填。
`id`	业务对象 ID。使用高层接口时传入。
`container`	容器名称。仅查询单个 Pod 时可指定。
`start` / `end`	下载起止时间，使用 Unix 时间戳，单位为秒。
`with_timestamp`	输出中是否包含时间戳。
`with_pod_name`	输出中是否包含 Pod 名称。
`file_path`	目标文件路径。不填时自动生成。

查询系统日志

系统日志来自工作负载 Pod 的 Kubernetes 事件，适合排查调度、拉取镜像、启动、驱逐、OOM 等平台侧问题。它与用户日志不同：用户日志是容器输出，系统日志是 Pod 生命周期事件。

按 Pod 查询系统日志

resp = client.logs.query_sys_logs(
    pods=["<POD_NAME>"],
)

print(f"total: {resp.total}")
for item in resp.sys_logs:
    print(f"[{item.time}] [{item.pod_name}] {item.type}/{item.name} {item.content}")

按时间范围查询：

import time

now = int(time.time())
one_hour_ago = now - 3600

resp = client.logs.query_sys_logs(
    pods=["<POD_NAME>"],
    start=one_hour_ago,
    end=now,
)

系统日志底层接口参数如下：

参数	说明
`pods`	Pod 名称列表。至少包含一个非空项。
`start` / `end`	查询起止时间，使用 Unix 时间戳，单位为秒。

系统日志响应字段如下：

字段	说明
`sys_logs`	系统日志列表。服务端无数据时为空列表。
`total`	匹配到的事件总数。
`SysLogItem.time`	事件首次发生时间。
`SysLogItem.pod_name`	关联的 Pod 名称。
`SysLogItem.type`	事件级别，例如 `Warning` 或 `Normal`。
`SysLogItem.name`	事件名称，例如 `Scheduled` 或 `Evict`。
`SysLogItem.content`	事件消息内容。

按业务对象查询系统日志

task_sys_logs = client.tasks.query_sys_logs("<TASK_UUID>")
general_sys_logs = client.generalsvc.query_sys_logs("<GENERAL_SERVICE_UUID>")
llm_sys_logs = client.inference.query_sys_logs(123)

系统日志高层接口也支持 start 和 end 参数。如果根据业务对象 ID 未关联到 Pod，接口返回空系统日志列表。当前系统日志接口不支持按容器、工作负载名称、工作负载类型、关键词、分页或下载查询。

查询训练任务指标

训练任务指标可用于在脚本中分析 GPU、CPU、内存、网络、存储或节点侧异常。

查询任务或 Pod 指标

查询一个任务的指标均值：

resp = client.tasks.metrics(task_name="<TASK_NAME>")

print(resp.meta.start_time, "->", resp.meta.end_time, resp.meta.step)
for metric in resp.metrics:
    print(metric.metric, metric.unit, metric.aggregation, len(metric.series))

查询一个 Pod 的指标：

resp = client.tasks.pod_metrics(
    pod_name="<POD_NAME>",
    metrics=["GpuCoreUsage", "GpuMemoryUsage"],
)

print(resp.meta.start_time, "->", resp.meta.end_time, resp.meta.step)
for metric in resp.metrics:
    print(metric.metric, metric.unit, len(metric.series))

查询同一任务下多个 Pod 的单项指标：

resp = client.tasks.all_pods_metric(
    task_name="<TASK_NAME>",
    metric="GpuCoreUsage",
    pods=["<POD_NAME_1>", "<POD_NAME_2>"],
)

if not resp.metrics:
    raise RuntimeError("当前查询范围没有返回指标")

for series in resp.metrics[0].series:
    if series.values:
        print(series.labels.pod, series.values[-1].value)

查询 Pod 所在节点的指标：

resp = client.tasks.node_metrics(
    pod_name="<POD_NAME>",
    metrics=["GpuTemp", "XidErrors", "CpuUsageOfNode"],
)

print(resp.node_name)

查询可用指标列表：

catalog = client.tasks.metrics_catalog(dimension="pod")
print(catalog)

识别掉队 Pod

resp = client.tasks.all_pods_metric(
    task_name="<TASK_NAME>",
    metric="GpuCoreUsage",
)

if not resp.metrics:
    raise RuntimeError("当前查询范围没有返回 GPU 利用率指标")

latest = {
    series.labels.pod: series.values[-1].value
    for series in resp.metrics[0].series
    if series.values
}
if not latest:
    raise RuntimeError("当前查询范围没有可用于比较的 Pod 指标数据")

avg = sum(latest.values()) / len(latest)

for pod, value in sorted(latest.items(), key=lambda item: item[1]):
    if value < avg * 0.5:
        print(f"slow pod: {pod} = {value}% (avg {avg:.1f}%)")

定位可疑 GPU

resp = client.tasks.node_metrics(
    pod_name="<SUSPECT_POD_NAME>",
    metrics=["GpuTemp", "XidErrors"],
)

print(f"node: {resp.node_name}")
for metric in resp.metrics:
    for series in metric.series:
        if not series.values:
            continue
        peak = max(point.value for point in series.values)
        if metric.metric == "GpuTemp" and peak > 85:
            print(f"high temperature: GPU {series.labels.gpu}, peak {peak}")
        if metric.metric == "XidErrors" and peak > 0:
            print(f"xid error: GPU {series.labels.gpu}, code {series.labels.extra}")

判断节点侧资源压力

可先查询 Pod 自身使用量，再查询 Pod 所在节点整体使用量，对比是否可能受到节点侧资源竞争影响。

mine = client.tasks.pod_metrics(
    pod_name="<POD_NAME>",
    metrics=["CpuUsageOfNode"],
)
whole = client.tasks.node_metrics(
    pod_name="<POD_NAME>",
    metrics=["CpuUsageOfNode"],
)

def latest_value(response):
    if not response.metrics:
        raise RuntimeError("当前查询范围没有返回指标")
    for series in response.metrics[0].series:
        if series.values:
            return series.values[-1].value
    raise RuntimeError("当前查询范围没有返回指标数据点")


pod_usage = latest_value(mine)
node_usage = latest_value(whole)
print(f"pod {pod_usage}% / node {node_usage}% / other {node_usage - pod_usage:.1f}%")

常用训练任务指标

任务级和 Pod 级均可查询 53 个指标，节点级可查询 51 个指标，全部 Pod 维度可查询 47 个指标。完整指标以 client.tasks.metrics_catalog() 返回为准。

指标	常见用途
`GpuCoreUsage`	查看 GPU 计算利用率，定位 GPU 是否空转或掉队。
`GpuMemoryUsage` / `GpuMemoryUsed`	查看显存使用比例和使用量，定位显存不足或显存利用异常。
`SmActive` / `TensorActive`	查看 GPU 计算引擎活跃度，辅助判断矩阵计算是否充分利用硬件。
`GpuTemp` / `PowerUsage`	查看 GPU 温度和功耗，辅助判断硬件运行状态。
`XidErrors` / `EccSbe` / `EccDbe`	查看 GPU 错误计数，辅助定位硬件或驱动异常。
`RdmaHealth` / `RdmaTxBytes` / `RdmaRxBytes`	查看 RDMA 健康状态和吞吐，辅助定位分布式训练通信问题。
`CpuUsageOfRequest` / `MemUsageOfRequest`	查看 CPU 和内存使用量相对申请资源的占比。
`CpuUsageOfNode` / `MemUsageOfNode`	查看 Pod 所在节点整体 CPU 和内存压力。
`NetworkTxBytes` / `NetworkRxBytes`	查看网络发送和接收速率。
`GpfsReadBytes` / `GpfsWriteBytes` / `GpfsOperations`	查看 GPFS 读写吞吐和操作速率，辅助定位存储瓶颈。
`DiskReadBytes` / `DiskWriteBytes` / `DiskIoUtil`	查看本地磁盘读写和 IO 利用率。

查询通用指标

除训练任务封装接口外，也可以通过 client.metrics 按资源类型查询指标。查询较长时间范围时，建议先获取推荐步长。

start, end = "2026-07-31 05:44:27", "2026-08-04 07:19:18"

step = client.metrics.recommend_time_step(start, end)

resp = client.metrics.query(
    start_time=start,
    end_time=end,
    time_step=step,
    resource_type="Pod",
    metric_type="GpuCoreUsage",
    pod="<POD_NAME>",
)

print(resp)

也可以导入模块级函数获取推荐步长：

from siflow.resources.metrics import recommend_time_step

step = recommend_time_step("2026-01-01 00:00:00", "2026-12-31 23:59:59")
print(step)

查询时需要同时指定 resource_type 和 metric_type。当 resource_type="Pod" 时，传入 pod；当 resource_type="Node" 时，传入 node。

请求限制

日志查询与下载接口存在并发和请求次数限制。自动化脚本应控制轮询频率；如果返回请求过多或服务繁忙，请按响应中的重试建议退避后再请求。

限制	触发情况	建议处理
并发限制	同一类接口同时处理中的请求数超过服务端上限，错误信息包含 `Concurrent request limit exceeded`。	降低并发，短暂退避后重试。
请求次数限制	单位时间窗口内请求次数超限，状态码为 `429 Too Many Requests`，错误信息包含 `Rate limit exceeded`。	按响应中的 `Retry-After` 或 `retryAfter` 等待后重试。

开始使用

资源准备

开发与训练

模型与推理

运维与治理

开发者接入

使用 Python SDK 查询日志和指标

查询用户日志

按 Pod 查询日志

按业务对象查询日志

按时间和关键词查询

下载用户日志

按业务对象下载

按 Pod 流式下载

查询系统日志

按 Pod 查询系统日志

按业务对象查询系统日志

查询训练任务指标

查询任务或 Pod 指标

识别掉队 Pod

定位可疑 GPU

判断节点侧资源压力

常用训练任务指标

查询通用指标

请求限制

相关文档

​查询用户日志

​按 Pod 查询日志

​按业务对象查询日志

​按时间和关键词查询

​下载用户日志

​按业务对象下载

​按 Pod 流式下载

​查询系统日志

​按 Pod 查询系统日志

​按业务对象查询系统日志

​查询训练任务指标

​查询任务或 Pod 指标

​识别掉队 Pod

​定位可疑 GPU

​判断节点侧资源压力

​常用训练任务指标

​查询通用指标

​请求限制

​相关文档

查询用户日志

按 Pod 查询日志

按业务对象查询日志

按时间和关键词查询

下载用户日志

按业务对象下载

按 Pod 流式下载

查询系统日志

按 Pod 查询系统日志

按业务对象查询系统日志

查询训练任务指标

查询任务或 Pod 指标

识别掉队 Pod

定位可疑 GPU

判断节点侧资源压力

常用训练任务指标

查询通用指标

请求限制

相关文档