本页演示如何配置终结点遥测,以便将 OpenTelemetry 日志、跟踪和指标从 自定义模型服务终结点 保存到 Unity 目录表。 使用持久化遥测数据执行根本原因分析、监视终结点运行状况,以及满足标准 SQL 查询的符合性要求。
要求
你的工作区必须启用 Unity Catalog。 默认存储不被支持。
必须对存储日志的目标 Unity Catalog 目录和架构分别具有
USE CATALOG、USE SCHEMA、CREATE TABLE和MODIFY权限。工作区必须位于受支持的区域中:
canadacentralwestuswestus2southcentraluseastuseastus2centralusnorthcentralusswedencentralwesteuropenortheuropeuksouthaustraliaeastsoutheastasia
步骤 1:设置模型代码
将监控功能添加到您的模型代码中,以收集遥测数据。
将应用程序日志记录添加到模型。 终结点遥测会自动捕获标准 Python
logging输出。 基本日志记录无需使用 OpenTelemetry SDK 进行instrumentation。import logging class MyCustomModel(mlflow.pyfunc.PythonModel): def predict(self, context, model_input): # This log will be persisted to the <prefix>_otel_logs table logging.warning("Received inference request") try: # Your model logic here result = model_input * 2 return result except Exception as e: # Error logs are also captured with severity 'ERROR' logging.error(f"Inference failed: {e}") raise e根日志记录级别设置为
WARNING。 请参阅 “故障排除 ”以更改日志记录级别。(可选)使用 OpenTelemetry 来仪表化自定义指标和追踪。 若要在基本日志记录之外捕获自定义指标和跟踪,请将 OpenTelemetry SDK 工具添加到您的模型中。 展开以下部分,获取演示如何创建计数器、记录范围和附加自定义属性的完整示例。
示例:使用 OpenTelemetry 进行自定义指标、跨度和模型日志记录
注释
由于模型序列化的限制,为避免错误,您必须在记录日志前将模型写入单独的文件,如下所示使用
%%writefile return_input_model.py。%%writefile return_input_model.py import os import mlflow from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter from opentelemetry.metrics import get_meter, set_meter_provider from opentelemetry.sdk.metrics import MeterProvider from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.trace import get_tracer, set_tracer_provider # highlight-start # ---- OTel initialization (per-worker) ---- resource = Resource.create({ "worker.pid": str(os.getpid()), }) otlp_trace_exporter = OTLPSpanExporter() tracer_provider = TracerProvider(resource=resource) tracer_provider.add_span_processor(BatchSpanProcessor(otlp_trace_exporter)) set_tracer_provider(tracer_provider) otlp_metric_exporter = OTLPMetricExporter() metric_reader = PeriodicExportingMetricReader(otlp_metric_exporter) meter_provider = MeterProvider(metric_readers=[metric_reader], resource=resource) set_meter_provider(meter_provider) _tracer = get_tracer(__name__) _meter = get_meter(__name__) _prediction_counter = _meter.create_counter( name="prediction_count", description="Number of predictions made", unit="1" ) # highlight-end class ReturnInputModel(mlflow.pyfunc.PythonModel): def load_context(self, context): # highlight-start self.tracer = _tracer self.prediction_counter = _prediction_counter # highlight-end def predict(self, context, model_input): # highlight-next-line with self.tracer.start_as_current_span("ReturnInputModel.predict") as span: # highlight-next-line span.set_attribute("input_shape", str(model_input.shape)) # highlight-next-line span.set_attribute("input_columns", str(list(model_input.columns))) # highlight-next-line self.prediction_counter.add(1) return model_input mlflow.models.set_model(ReturnInputModel())(可选)记录每个请求的自定义数据。 为了持久化每个请求的数据,比如中间分数,每个请求都发送一条OpenTelemetry日志记录。 记录作为表中的
<prefix>_otel_logs一行存储。OpenTelemetry 导出器通过 HTTP 将每条记录发送到端点 pod 中的遥测采集器,收集器再将其传递到 Unity Catalog,超出你的模型进程。 端点为你的模型容器设置
OTEL_EXPORTER_OTLP_ENDPOINT和OTEL_EXPORTER_OTLP_PROTOCOL(http/protobuf),所以导出器不需要配置。 用HTTP导出器,不要用gRPC导出器。import json from opentelemetry._logs import LogRecord from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter from opentelemetry.sdk._logs import LoggerProvider from opentelemetry.sdk._logs.export import BatchLogRecordProcessor logger_provider = LoggerProvider() logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter())) _record_logger = logger_provider.get_logger(__name__) class MyCustomModel(mlflow.pyfunc.PythonModel): def predict(self, context, model_input): scores = {"model_score": 0.82, "lookup_hits": 3} # A JSON string body is much cheaper to encode than a nested dict _record_logger.emit( LogRecord( event_name="prediction_details", body=json.dumps(scores), attributes={"model_version": "1"}, ) ) return model_input要读取记录,请按
event_name筛选:SELECT timestamp, body, attributes FROM <catalog>.<schema>.<prefix>_otel_logs WHERE event_name = 'prediction_details';对于每个请求的数据,不要从模型代码中调用像 Zerobus Ingest SDK 这样的摄取 SDK。 如果服务缓慢或不可用,这些调用可能会阻塞模型运行。 而 OpenTelemetry 则是你的模型只把记录交给本地采集器,所以缓慢或不可用的接收服务会延迟送达,但不会阻塞请求。 此外,对于在每个请求上发出的记录,请避免使用 Python
logging。记录并注册模型。
import pandas as pd import mlflow from mlflow.models import infer_signature # Prepare tabular input/output for signature (pyfunc expects DataFrame) input_df = pd.DataFrame({"inputs": ["hello world"]}) output_df = input_df.copy() # model returns input unchanged # Log the model with OpenTelemetry dependencies (using code-based logging to avoid serialization issues) with mlflow.start_run(): signature = infer_signature(input_df, output_df) model_info = mlflow.pyfunc.log_model( name="model", python_model="return_input_model.py", signature=signature, input_example=input_df, pip_requirements=[ "mlflow==3.1", # highlight-next-line "opentelemetry-sdk>=1.37.0", # highlight-next-line "opentelemetry-exporter-otlp-proto-http>=1.37.0", ], )# Use Unity Catalog name: catalog.schema.model_name registered = mlflow.register_model( model_info.model_uri, MODEL_NAME, )
步骤 2:准备 Unity Catalog 目标
在创建终结点之前,请确保已准备好一个目录和架构来接收遥测数据。 Azure Databricks 会自动在此架构中创建必要的表(如果它们尚不存在)。
在目录资源管理器中,导航到要使用的目录和架构(例如)。
my_catalog.observability如果你还没有目标模式或目录, 可以创建一个模式 或 目录来存放遥测表。 例如:
CREATE CATALOG IF NOT EXISTS my_catalog; CREATE SCHEMA IF NOT EXISTS my_catalog.observability;确保启用遥测功能的身份对目标目录和架构拥有
USE CATALOG、USE SCHEMA、CREATE TABLE和MODIFY权限。 这些权限是必要的,以便 Azure Databricks 能够自动创建并写入遥测表。 你也可以 授予这些特权,例如:GRANT USE CATALOG ON CATALOG my_catalog TO `<principal>`; GRANT USE SCHEMA, CREATE TABLE, MODIFY ON SCHEMA my_catalog.observability TO `<principal>`;
步骤 3:启用终结点遥测
创建新终结点或将其添加到现有终结点时,可以启用遥测。
新终结点
若要在 UI 中启用遥测数据,请执行以下操作:
- 导航到左侧栏中的服务。
- 单击“创建服务终结点”。
- 展开 “高级”选项,转到 “AI 网关 ”部分,然后选择“ 启用推理表和遥测”。
- Unity 目录位置:选择步骤2中准备的目标 目录 和 模式 。
- (可选) 表前缀:输入生成的表的前缀。 如果留空,则没有前缀。 表的名称
<prefix>_otel_logs<prefix>_otel_spans和<prefix>_otel_metrics。 - 完成终结点配置的其余部分(模型选择、计算设置),然后单击“ 创建”。
若要使用 API 执行此操作,请执行以下操作:
使用 API 启用遥测
curl -X POST -H "Authorization: Bearer <your-token>" \
https://<workspace-url>/api/2.0/serving-endpoints \
-d '{
"name": "my-custom-logging-endpoint",
"config": {
"served_entities": [
{
"name": "my-model",
"entity_name": "my-model",
"entity_version": "1",
"workload_size": "Small",
"scale_to_zero_enabled": true
}
]
},
"telemetry_config": {
"table_names": {
"logs_table": "my_catalog.observability.custom_endpoint_logs",
"metrics_table": "my_catalog.observability.custom_endpoint_metrics",
"traces_table": "my_catalog.observability.custom_endpoint_spans"
},
"inference_table_config": {
"sampling_fraction": 0.1
}
}
}'
inference_table_config.sampling_fraction 是可选的,控制记录在推理表中的请求比例(值介于0和1之间;默认值为1,记录所有请求)。 仅在同一个 table_names 中将其与 telemetry_config 一起设置。 该 sampling_fraction 参数调整所选 table_names 的推理表,并对其本身没有影响。 有关采样行为的详细信息,请参阅 负载采样。
现有端点
注释
更新会触发新的部署。 部署完成后,更改将生效。
若要在 UI 中启用遥测数据,请执行以下操作:
- 在“终结点视图”页的 “AI 网关 ”部分中,单击“ 编辑 AI 网关”,然后选择“ 启用推理表和遥测”。
- Unity Catalog 位置:选择步骤 2 中准备的目标 目录 和 模式。
- (可选) 表前缀:输入生成的表的前缀。 如果留空,则没有前缀。 表的名称
<prefix>_otel_logs<prefix>_otel_spans和<prefix>_otel_metrics。 - 单击“ 更新”。
步骤 4:验证和查询遥测数据
终结点收到流量后,遥测数据会被传输到配置好的 Unity Catalog 表中。
转到 目录资源管理器 或 SQL 编辑器。
找到在配置的架构中命名
<prefix>_otel_logs的表。运行查询以验证数据是否流动:
SELECT * FROM <catalog>.<schema>.<prefix>_otel_logs LIMIT 10;
查询遥测数据
以下示例显示了常见查询。
若要查看任何遥测表的完整架构,请运行:
DESCRIBE TABLE <catalog>.<schema>.<prefix>_otel_logs;
使用这些列筛选和关联遥测数据:
timestampseverity_textbodytrace_idspan_id-
attributes—— 一个包含特定事件元数据的映射。
检查过去一小时内的错误
SELECT
timestamp,
severity_text,
body,
attributes
FROM <catalog>.<schema>.<prefix>_otel_logs
WHERE
severity_text = 'ERROR'
AND timestamp > current_timestamp() - INTERVAL 1 HOUR
ORDER BY timestamp DESC;
故障排除
日志未显示在表中:根日志记录级别默认为 WARNING,以降低开销。 若要捕获低严重性日志,请更改模型代码中的级别:
class MyModel(mlflow.pyfunc.PythonModel):
def load_context(self, context):
root = logging.getLogger()
root.setLevel(logging.DEBUG)
for handler in root.handlers:
handler.setLevel(logging.DEBUG)
局限性
以下限制适用于终结点遥测:
不支持目标表的模式演进。
仅支持托管 Delta 表。 不支持外部存储和默认存储。
表位置必须与工作区位于同一区域。
仅支持包含 ASCII 字母、数字和下划线的表名。
不支持重新创建目标表。
仅支持单可用区(single-az)持久性。
数据投递采用“至少一次”模式。 服务器的确认意味着记录是持久记录,并且位于 Delta 表中。
每个记录必须小于 10 MB。
每个请求必须小于 30 MB。
日志行必须小于 1 MB。
遥测延迟恶化至超过 2500 QPS。
发出日志数秒后,日志会显示在 Unity 目录表中。