KServe V1beta1LoggerSpec 完全指南:InferenceService 推理日志采集、CloudEvent 转发与对象存储落盘配置详解
KServe V1beta1LoggerSpec 完全指南:InferenceService 推理日志采集、CloudEvent 转发与对象存储落盘配置详解
在 KServe 中,LoggerSpec 是挂载于 InferenceService 各组件(predictor / transformer / explainer)之上的可选配置,用于对推理请求与响应做"旁路式"日志采集:它既可以借助内置 Agent 把请求/响应封装为 CloudEvent 转发到 HTTP 接收端(如 Knative Service、Knative Eventing Broker),也可以直接把日志批次写入 S3 / GCS / Azure Blob 等对象存储。本文以 python/kserve/docs/V1beta1LoggerSpec.md 为主体,结合 pkg/apis/serving/v1beta1/inference_service.go 中的结构体定义、pkg/logger 下的批处理与 marshaller 实现以及 docs/samples/logger 中的完整示例,系统讲解 LoggerSpec 全部 8 个字段的语义、默认值、校验规则与实际用法。读完本文,你将能够为任意 InferenceService 精确配置推理日志的采集范围(mode)、发送目标(url / storage)、批量策略(batchSize / batchInterval)、元数据透传(metadataHeaders / metadataAnnotations)以及自定义 marshaller 服务(marshallerUrl)。
一、LoggerSpec 是什么:字段总览与官方属性表
LoggerSpec specifies optional payload logging available for all components——它是 KServe 提供的、对所有组件通用的可选负载日志(payload logging)配置。官方 API 文档给出了如下 8 个属性:
| Name | Type | Description | Notes |
|---|---|---|---|
| batch_interval | str | Max duration to wait before flushing a partial batch (e.g. "5s", "100ms"). Only used when BatchSize > 1. Defaults to "0" (no time-based flushing). | [optional] |
| batch_size | int | Number of log records per batch for blob storage. Defaults to 1 (immediate). | [optional] |
| marshaller_url | str | URL of the log marshaller service that transforms log records before storage. Defaults to the embedded JSON marshaller at http://localhost:9083/marshal. | [optional] |
| metadata_annotations | list[str] | Matched inference service annotations for propagating to inference logger cloud events. | [optional] |
| metadata_headers | list[str] | Matched metadata HTTP headers for propagating to inference logger cloud events. | [optional] |
| mode | str | Specifies the scope of the loggers. Valid values are: "all" (default): log both request and response; "request": log only request; "response": log only response | [optional] |
| storage | V1beta1LoggerStorageSpec | 指定日志对象存储的落盘位置 | [optional] |
| url | str | URL to send logging events | [optional] |
这 8 个字段在 Go 侧的正式定义位于 pkg/apis/serving/v1beta1/inference_service.go#L98-L130,其 JSON 标签(mode、metadataHeaders、metadataAnnotations、storage、marshallerUrl、batchSize、batchInterval、url)与上面表格中 Python SDK 使用的 snake_case 命名一一对应。在 Python SDK 侧,同一模型的 OpenAPI 生成代码位于 python/kserve/kserve/models/v1beta1_logger_spec.py,其中的 openapi_types 与 attribute_map 明确列出了 batch_interval ↔ batchInterval、marshaller_url ↔ marshallerUrl 等映射关系,方便通过 KServeClient 以编程方式构造。
二、核心字段逐个拆解
2.1 mode:控制日志采集范围
mode 指定 logger 的作用域,合法值及语义如下:
all(默认值):同时记录请求与响应(request + response);request:仅记录请求;response:仅记录响应。
在源码层面,该字段对应 LoggerType 枚举与三个常量(见 pkg/apis/serving/v1beta1/inference_service.go#L84-L96):
// +kubebuilder:validation:Enum=all;request;response
type LoggerType string
const (
LogAll LoggerType = "all"
LogRequest LoggerType = "request"
LogResponse LoggerType = "response"
)
需要注意,mode 并非可以随意填写的自由字符串。在 pkg/apis/serving/v1beta1/component.go#L400-L413 的 validateLogger 中,控制器会严格校验 logger.Mode 必须等于 LogAll、LogRequest、LogResponse 三者之一,否则返回 invalid logger type 错误(常量定义见 pkg/apis/serving/v1beta1/component.go#L42)。对应的单元测试位于 pkg/apis/serving/v1beta1/component_test.go(覆盖合法/非法 mode 及非法 storage 配置的校验分支)。
2.2 url 与 storage:两条输出通道
url 与 storage 提供了两种互不冲突的日志出口(在合法的 YAML 中二者可以同时存在,但实践中通常二选一):
- url:日志事件(CloudEvent)的 HTTP 发送目标。不设置时,默认指向命名空间的 Knative broker,或控制器 ConfigMap 中
logger一节配置的DefaultUrl。 - storage:
V1beta1LoggerStorageSpec类型的对象存储配置,用于把日志批次直接写入 blob 存储(S3 / GCS / Azure),详见下文第三节。
2.3 batchSize 与 batchInterval:批量写盘策略
这两个字段只在 batchSize > 1 时生效,用于控制向对象存储(storage)写日志的批量节奏,从而降低存储请求次数:
- batch_size:每个批次包含的日志记录数,默认
1,即每条记录立即写出(immediate 模式); - batch_interval:等待刷新"未满批次"的最大时长(如
"5s"、"100ms")。默认"0",即不启用基于时间的刷新;只有在batchSize > 1时才使用。
这两个参数在 pkg/logger 中对应三种批量策略实现:
| 策略 | 实现文件 | 触发条件 |
|---|---|---|
| ImmediateBatch(单条立即写出) | pkg/logger/batch_immediate.go | batchSize == 1(默认) |
| SizeBatch(按条数凑批) | pkg/logger/batch_size.go | batchSize > 1 且 batchInterval == 0,缓冲区达到 size 即 flush |
| TimedBatch(条数 + 时间双触发) | pkg/logger/batch_timed.go | batchSize > 1 且 batchInterval > 0,条数攒满或定时器到期(二者先到先触发)即 flush |
例如设置 batchSize: 10、batchInterval: "5s",则日志 Agent 会每攒够 10 条记录、或每 5 秒(无论是否攒满)刷写一次部分批次。pkg/logger 中对应的 *_test.go(如 pkg/logger/batch_size_test.go、pkg/logger/batch_timed_test.go)覆盖了缓冲区 flush、通道关闭时残留记录刷写、上下文取消等边界场景。
2.4 marshallerUrl:日志格式转换服务
marshaller_url 指定"日志 marshaller 服务"的地址,该服务负责在日志写入存储之前对日志记录做格式转换。默认使用 KServe 内置的 JSON marshaller:http://localhost:9083/marshal(Agent 随推理 Pod 同生命周期运行)。从 pkg/logger/marshaller_http.go 的实现看,HTTPMarshaller 会把 []LogRequest 以 JSON 形式 POST 到该 URL,读取响应体作为写盘数据,并从响应头 X-Log-Marshal-Extension 读取文件扩展名(缺省为 json);非 2xx 状态码会作为错误向上抛出。
仓库还提供了多种内建 marshaller 实现,可理解为 marshallerUrl 未自定义时可能落到的转换能力:CSV(pkg/logger/marshaller_csv.go)、Parquet(pkg/logger/marshaller_parquet.go)、JSON(pkg/logger/marshaller_json.go),以及将 LogRequest 展平为表格记录的转换规则(pkg/logger/marshaller_record.go,其中字节内容以 base64 编码、元数据与注解以 JSON 字符串表达)。如果你需要自定义格式(例如专有的二进制协议或特定的文件组织),可以部署自己的 marshaller 服务,并通过 marshallerUrl 指向它。
2.5 metadataHeaders 与 metadataAnnotations:元数据透传
- metadata_headers:匹配的 HTTP 请求头列表,这些请求头的值会被传播到推理 logger 产生的 CloudEvent 中;
- metadata_annotations:匹配的 InferenceService 注解列表,同样会被传播到 CloudEvent。
二者的用途是把上下文信息(如租户 ID、请求追踪标识、业务标签等)随日志事件一起带出,便于下游做关联分析或过滤。在 CloudEvent 的输出中可以看到这些扩展字段与 inferenceservicename、namespace、endpoint、traceparent 等系统扩展并存(见 docs/samples/logger/basic/README.md 中的 message-dumper 输出示例)。
三、storage:V1beta1LoggerStorageSpec 对象存储配置
storage 字段的类型是 V1beta1LoggerStorageSpec,其官方定义见 python/kserve/docs/V1beta1LoggerStorageSpec.md,属性如下:
| Name | Type | Description | Notes |
|---|---|---|---|
| key | str | The Storage Key in the secret for this object. | [optional] |
| parameters | dict(str, str) | Parameters to override the default storage credentials and config. | [optional] |
| path | str | The path to the object in the storage. Note that this path is relative to the storage URI. | [optional] |
| service_account_name | str | 使用的服务账号名称 | [optional] |
在 Go 侧它由 StorageSpec 内联扩展而来(pkg/apis/serving/v1beta1/inference_service.go#L66-L82):
type StorageSpec struct {
Path *string `json:"path,omitempty"`
Parameters *map[string]string `json:"parameters,omitempty"`
StorageKey *string `json:"key,omitempty"`
}
type LoggerStorageSpec struct {
StorageSpec `json:",inline"`
ServiceAccountName *string `json:"serviceAccountName,omitempty"`
}
其中 path 是相对于存储 URI 的对象路径;key 是 secret 中存储该对象凭据的键名;parameters 用于覆盖默认的存储凭据与配置;service_account_name 指定写日志时使用的 Kubernetes 服务账号。
重要校验规则:一旦在 YAML 中声明了 storage,则 path、parameters、key 三个字段缺一不可。validateLogger 会检查 logger.Storage.Path == nil || logger.Storage.Parameters == nil || logger.Storage.StorageKey == nil 任一成立即返回 invalid logger storage configuration 错误(pkg/apis/serving/v1beta1/component.go#L405-L409)。这一点与 2.1 节提到的 mode 校验一同构成了 LoggerSpec 的准入控制约束。
从存储实现看,pkg/logger/store.go 根据 URL scheme 识别存储后端:s3/s3a 走 S3、gs 走 GCS、abfs 走 Azure、http/https 则按 HTTP 转发处理(GetStorageStrategy,见 pkg/logger/store.go#L46-L61)。BlobStore.Store 会先把日志批次交给 marshaller 转成字节流,再依据配置前缀、命名空间、InferenceService 名、组件名与 storePath 拼接对象键,最终通过存储 Provider 上传对象(pkg/logger/store.go#L125-L208)。
四、完整实操示例:从 CloudEvent 转发到对象存储落盘
4.1 场景一:最小配置,CloudEvent 转发到 Knative message-dumper
这是最经典的人门用法:创建 message-dumper 后,为 sklearn 预测器挂一个 logger。完整步骤见 docs/samples/logger/basic/README.md,核心 YAML 如下(对应 docs/samples/logger/basic/sklearn-logging.yaml):
apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
name: sklearn-iris
spec:
predictor:
logger:
mode: all
url: http://message-dumper.default/
sklearn:
storageUri: gs://kfserving-examples/models/sklearn/1.0/model
应用后发送推理请求:
MODEL_NAME=sklearn-iris
INPUT_PATH=@./iris-input.json
SERVICE_HOSTNAME=$(kubectl get inferenceservice sklearn-iris -o jsonpath='{.status.url}' | cut -d "/" -f 3)
curl -v -H "Host: ${SERVICE_HOSTNAME}" http://${INGRESS_HOST}:${INGRESS_PORT}/v1/models/$MODEL_NAME:predict -d $INPUT_PATH
随后在 message-dumper 的日志中即可看到两条 CloudEvent(请求与响应各一条),关键扩展字段与文档示例一致:
☁️ cloudevents.Event
Validation: valid
Context Attributes,
specversion: 1.0
type: org.kubeflow.serving.inference.request
source: http://localhost:9081/
id: 0009174a-24a8-4603-b098-09c8799950e9
Extensions,
inferenceservicename: sklearn-iris
namespace: default
traceparent: 00-90bdf848647d50283394155d2df58f19-84dacdfdf07cadfc-00
Data,
{ "instances": [ [6.8, 2.8, 4.8, 1.4], [6.0, 3.4, 4.5, 1.6] ] }
(第二个响应事件 type: org.kubeflow.serving.inference.response 结构类似。)其中 source: http://localhost:9081/ 正是 KServe 内置 Agent 的默认端口(InferenceServiceDefaultAgentPort,见 pkg/constants/constants.go#L405-L406)——日志采集由随 Pod 注入的 Agent 完成,因此对推理服务本身几乎零侵入。
4.2 场景二:对接 Knative Eventing Broker
如果要让日志事件进入 Knative Eventing 的事件总线,可以创建默认 broker,并把 url 指向 broker 的入口地址。完整过程(创建 broker、Trigger、InferenceService)见 docs/samples/logger/knative-eventing/README.md,核心配置:
apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
name: sklearn-iris
spec:
predictor:
minReplicas: 1
logger:
mode: all
url: http://broker-ingress.knative-eventing.svc.cluster.local/default/default
sklearn:
storageUri: gs://kfserving-examples/models/sklearn/1.0/model
该场景下 CloudEvent 会额外带上 knativearrivaltime、knativehistory 等 Knative 扩展字段(见 docs/samples/logger/knative-eventing/README.md 的日志输出),便于在事件链中追踪与重放。
4.3 场景三:对象存储落盘 + 批量写 + 元数据透传(综合配置)
结合前面各字段的语义,下面给出一个"高水位"的完整配置示例,同时用到了模式、批量、元数据与存储四条链路(字段值仅供演示,请按实际环境替换):
apiVersion: serving.kserve.io/v1beta1
kind: InferenceService
metadata:
name: sklearn-iris
annotations:
logging.kserve.io/tenant: "team-a" # 将被 metadataAnnotations 匹配并透传
spec:
predictor:
logger:
mode: all # 同时记录请求与响应
metadataHeaders: # 透传这些 HTTP 请求头到 CloudEvent
- "x-request-id"
- "x-user-id"
metadataAnnotations: # 透传这些服务注解到 CloudEvent
- "logging.kserve.io/tenant"
storage: # 写入对象存储
path: "sklearn-iris-logs" # 相对存储 URI 的对象路径
parameters:
bucket: "my-logs-bucket"
key: "storage-secret-key" # secret 中对应凭据的键名
serviceAccountName: "logger-sa"
batchSize: 10 # 每条 10 条日志凑一批
batchInterval: "5s" # 最多等待 5 秒刷写未满批次
marshallerUrl: "http://localhost:9083/marshal" # 默认内置 JSON marshaller
sklearn:
storageUri: gs://kfserving-examples/models/sklearn/1.0/model
需要再次强调的是:一旦声明 storage,path、parameters、key 三者必须全部给出,否则 InferenceService 会因 invalid logger storage configuration 校验失败而无法创建(可结合 pkg/apis/serving/v1beta1/component_test.go 中的用例验证该行为)。
五、Python SDK 编程式配置
如果你使用 KServe Python SDK 部署服务,可以直接用模型类构造 LoggerSpec。模型定义位于 python/kserve/kserve/models/v1beta1_logger_spec.py,用法示意:
from kserve import V1beta1LoggerSpec, V1beta1LoggerStorageSpec
logger = V1beta1LoggerSpec(
mode="all",
url="http://message-dumper.default/",
metadata_headers=["x-request-id"],
metadata_annotations=["logging.kserve.io/tenant"],
batch_size=10,
batch_interval="5s",
marshaller_url="http://localhost:9083/marshal",
storage=V1beta1LoggerStorageSpec(
path="sklearn-iris-logs",
parameters={"bucket": "my-logs-bucket"},
key="storage-secret-key",
service_account_name="logger-sa",
),
)
SDK 中的 openapi_types/attribute_map 与 CRD 的 JSON 字段完全对齐,因此构造出的对象序列化后即为上一节 YAML 中的 logger 段。
六、常见问题与排查建议
- mode 非法值:CRD 通过
+kubebuilder:validation:Enum=all;request;response约束枚举(pkg/apis/serving/v1beta1/inference_service.go#L85),Webhook 校验会拒绝其他取值,报错invalid logger type。 - storage 配置不完整:
path、parameters、key任一缺失即报invalid logger storage configuration。 - 批量不生效:
batchInterval只有在batchSize > 1时才起作用;若batchSize保持默认 1,则每条记录立即写出(ImmediateBatch 语义,见 pkg/logger/batch_immediate.go)。 - CloudEvent 里看不到自定义元数据:请确认请求头名称 / 注解键与
metadataHeaders/metadataAnnotations列表完全匹配(大小写敏感),并核对 CloudEvent 扩展字段输出(参考 docs/samples/logger/basic/README.md 中的示例事件结构)。 - 自定义 marshaller 异常:
HTTPMarshaller对非 2xx 响应会直接报错(pkg/logger/marshaller_http.go#L72-L76),排查时注意确认 marshaller 服务的可用性与返回的X-Log-Marshal-Extension响应头。
总结
V1beta1LoggerSpec 是 KServe 推理日志体系的总开关:mode 决定采集范围,url/storage 决定日志出口,batchSize/batchInterval 决定对象存储场景下的写盘节奏,metadataHeaders/metadataAnnotations 决定上下文透传,marshallerUrl 决定落盘前的格式转换。结合 pkg/logger 的批量策略、marshaller 与 BlobStore 实现,以及 docs/samples/logger 的两套端到端示例,你可以按需组合出"轻量调试"(message-dumper 查看事件)到"生产审计"(批量写入对象存储 + 元数据关联)的完整日志方案。