技能介绍

要解决什么问题

自建应用、脚本或边缘组件产生的日志往往不在 Azure 默认采集范围内。若要把结构化自定义日志稳定写入 Log Analytics 并在 KQL 里与平台日志一起分析，需要走 Logs Ingestion API，并正确配置 DCE、DCR 与目标自定义表（通常以 _CL 结尾）。本技能围绕 Azure Monitor Ingestion Python SDK，说明如何用 Python 完成上传与错误处理，而不是只贴 API 文档链接。

技能如何工作

SDK 通过 LogsIngestionClient（同步）或 LogsIngestionClient（aio 异步）向 DCE 提交数据；Stream 名称需与 DCR 中定义一致（自定义表常用 Custom-<表名>_CL 形式）。文档强调两条贯穿示例的约定：

鉴权：优先 DefaultAzureCredential，本地可用 Azure CLI / VS Code 等，云上可用托管标识；生产环境可用 AZURE_TOKEN_CREDENTIALS 收窄凭据链，避免长期连接串或 API 密钥。
生命周期：客户端与异步凭据应放在 with / async with 中，确保 HTTP 连接与令牌缓存被释放。

上传侧 SDK 会自动把 payload 拆成 ≤1MB 块、gzip 压缩并并行上传，大批量 JSON 不必手写批处理逻辑。日志需包含 TimeGenerated，字段布局须与 DCR schema 一致；部分失败可通过 on_error 回调处理，也可选择忽略非致命错误。高吞吐场景文档建议统一走异步客户端，并可在 Log Analytics 中核对摄取结果。

适用边界与注意点

前置资源缺一不可：Log Analytics 工作区、DCE、DCR 及目标表（经 DCR 或手动创建）。
同一调用链不要混用 azure.xxx 同步包与 azure.xxx.aio 异步包，模块内选一种模式并保持一致。
主权云、从 JSON 文件批量导入、非核心场景与生产检查项见技能内 references/capabilities.md、references/non-hero-scenarios.md 等参考文件。

截图预览

使用场景

Azure 上的 Python 服务需把业务事件写入已通过 DCR 映射的 Log Analytics 自定义 `_CL` 表，便于 KQL 与平台日志一起查。
要把磁盘上的历史 JSON 日志文件按 DCR 列定义批量上传到指定 DCE 与 Stream，无需自己实现 1MB 分块。
单批日志体积大、并发高时，用异步客户端依赖 SDK 的 gzip 分块与并行上传，避免阻塞主业务线程。
生产摄取管线里部分记录校验失败时，用 `on_error` 回调记录失败条目并决定是否继续提交其余日志。

适合人员

负责 Azure 可观测性与 Log Analytics 工作区、DCE/DCR 配置的平台/SRE 工程师，要为自建应用接自定义摄取流。
在 Azure 上用托管标识或工作负载标识部署 Python 服务的后端开发，需要按规范用 DefaultAzureCredential 与上下文管理器上传日志。
需把脚本、边缘节点或第三方 JSON 日志集中入库的安全/运维工程师，要在 Log Analytics 里用 KQL 做关联与审计查询。
正在把同步 REST 调用改为高吞吐摄取的实现者，需要在同一模块内选定同步或异步 SDK 并匹配 DCR schema 与 TimeGenerated 字段。