使用 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，接口返回空系统日志列表。当前系统日志接口不支持按容器、工作负载名称、工作负载类型、关键词、分页或下载查询。

请求限制

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

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

开始使用

资源准备

开发与训练

模型与推理

运维与治理

最佳实践

开发者接入

常见问题

文档工具

使用 Python SDK 查询日志

查询用户日志

按 Pod 查询日志

按业务对象查询日志

按时间和关键词查询

下载用户日志

按业务对象下载

按 Pod 流式下载

查询系统日志

按 Pod 查询系统日志

按业务对象查询系统日志

请求限制

相关文档

​查询用户日志

​按 Pod 查询日志

​按业务对象查询日志

​按时间和关键词查询

​下载用户日志

​按业务对象下载

​按 Pod 流式下载

​查询系统日志

​按 Pod 查询系统日志

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

​请求限制

​相关文档

查询用户日志

按 Pod 查询日志

按业务对象查询日志

按时间和关键词查询

下载用户日志

按业务对象下载

按 Pod 流式下载

查询系统日志

按 Pod 查询系统日志

按业务对象查询系统日志

请求限制

相关文档