OpenSandbox SDK Telemetry 详解沙箱创建耗时指标的上报链路、服务端落地与禁用方式【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxOpenSandbox 的各语言 SDK 会尽力而为地将沙箱创建耗时sandbox creation latency上报到生命周期服务端用于构建端到端的创建延迟直方图。本文基于官方指南 SDK Telemetry完整梳理其上报机制、版本要求、载荷结构、服务端 OTEL 落地细节与禁用方式并结合仓库源码说明 fire-and-forget 实现原理帮助你在生产环境正确启用、观测或关闭这套遥测能力。设计定位best-effort 且不携带用户内容SDK 遥测只有一个核心指标sandbox.create事件的创建耗时。其设计原则在官方文档中表述得非常明确上报是 best-effort 的任何上报失败网络错误、TLS 失败、超时、服务端 404都不会影响Sandbox.create的行为也不会向用户抛出可见错误载荷不含用户内容上报体只有沙箱 ID、镜像、耗时与成败标志不包含命令、文件等任何用户数据。这一fire-and-forget发射后不管语义是贯穿全部 SDK 的一致性约定也是 SDK 与服务端可以独立升级版本 skew的前提。版本要求与版本漂移Version skewPOST /v1/metrics/events端点与各 SDK 上报器要求如下最低版本。低于这些版本的 SDK 直接不发送事件旧服务端则会以404拒绝未知路由SDK 会静默吞掉该响应组件最低版本Serveropensandbox-server0.2.2Python SDKopensandbox0.1.15JavaScript / TypeScript SDKalibaba-group/opensandbox0.1.11Go SDKgithub.com/alibaba/OpenSandbox/sdks/sandbox/go1.0.5C# SDKAlibaba.OpenSandbox0.1.5Kotlin / Java SDKcom.alibaba.opensandbox:sandbox1.0.17由于每个 SDK 中的上报都是后台任务/线程中的 fire-and-forget任何异常或非 2xx 响应都会被捕获并仅在 debug 级别记录日志因此可以独立升级 SDK 与服务端新 SDK 旧服务端 0.2.2服务端对/v1/metrics/events返回404SDK 忽略该响应Sandbox.create行为不变唯一副作用是每次 create 多一条 debug 日志旧 SDK 新服务端SDK 不发送事件服务端直方图对该客户端不记录任何样本网络错误、TLS 失败、超时行为与 404 一致——被吞掉Sandbox.create不受影响。上报载荷POST /v1/metrics/eventscreate 成功或失败后SDK 会以后台方式向POST /v1/metrics/events发送如下 JSON{ eventType: sandbox.create, sandboxId: sbx_..., image: python:3.12, createDurationMs: 1842, success: true }结合服务端请求模型 MetricsEvent各字段的约束可以进一步确认字段类型/约束说明eventType必填固定字面量sandbox.create当前阶段唯一的指标事件类型schema 注释标注为 Phase 1sandboxId可选字符串创建失败在早期阶段时可能缺省image可选字符串容器镜像 URI或快照启动的来源标签createDurationMs必填整数且 0从 create 开始到就绪或失败的墙钟耗时毫秒success必填布尔create readiness 是否全部成功完成另外两点容易忽略的细节SDK 语言与版本不放在 body 里而是来自 HTTPUser-Agent头例如OpenSandbox-Python-SDK/0.1.15。服务端在 metrics.py 中用正则OpenSandbox-([A-Za-z0-9])-SDK/([^\s])解析出(language, version)解析失败则回退为unknown/unknownsandboxId/image在创建早期失败时可能整体缺省因此 schema 中两者均为Optional。服务端接受事件后返回204 No Content当服务端的[otel]配置启用时会额外记录一条 OTEL 直方图样本见下一节。服务端落地从 HTTP 事件到 OTEL 直方图服务端的处理链路非常短全部实现在 server/opensandbox_server/api/metrics.py端点 report_metrics_event 校验MetricsEvent载荷从User-Agent头解析 SDK 语言与版本当事件类型为sandbox.create时调用 record_sandbox_create_duration 记录样本以 debug 级别记录一行sandbox_id / image / duration_ms / sdk / success摘要日志返回204。直方图指标本身定义在 server/opensandbox_server/integrations/otel/metrics.py关键参数为指标名opensandbox.sandbox.create.duration单位ms显式桶边界ExplicitBucketHistogramAggregation100, 250, 500, 1000, 2500, 5000, 10000, 30000, 60000毫秒即从百毫秒级到分钟级覆盖典型沙箱创建延迟区间属性标签sdk.language、sdk.version、success可用于按 SDK 语言/版本切分延迟分布导出[otel] enabledtrue时通过 OTLP HTTP 导出器 PeriodicExportingMetricReader周期导出见 server 配置文档enabledfalse时 histogram 为Nonerecord_sandbox_create_duration直接 no-op 返回——事件端点本身仍正常接受并返回204。从源码结构看服务端还有一个值得注意的健壮性细节即使全局MeterProvider已存在例如宿主进程自带 OTel 初始化服务端也会把 instrument 绑定到自建 provider 以保证走自己的 OTLP reader且record_sandbox_create_duration内部对hist.record的异常做了兜底捕获Never raises。触发时机各 SDK 分别在何时上报官方文档给出了每个 SDK 的触发点这里完整继承SDK触发时机Pythonasync syncSandbox.create/ 同步 create 完成或抛出异常后JavaScript / TypeScriptSandbox.create完成或失败后GoCreateSandbox完成或失败后C#Sandbox.CreateAsync完成或失败后Kotlin独立Sandbox.builder()...build()或池 direct-create 兜底路径完成或失败后Kotlin 分阶段staged池预热是有意例外Kotlin staged warmup 刻意不发送sandbox.create事件。原因是其 create 阶段在就绪轮询、可选准备、post-prepare 校验、续期与 idle commit 之前就已返回若把这个不完整阶段当作端到端创建延迟上报会让该指标的含义与独立 create 的直方图不一致。该排除仅针对 staged warmup 路径——独立 create 与池 direct-create 兜底仍正常上报要观测完整的 staged-warmup 生命周期应使用池的结构化 summary 日志和可选的 warmup tracing见 SDK Tracing 指南。源码纵深fire-and-forget 是如何保证绝不影响 create的以 Python SDK 的上报器 lifecycle_metrics.py 为例可以看到 best-effort 语义的具体实现手法其余 SDKGo lifecycle_metrics.go、C# LifecycleMetricsReporter.cs、Kotlin LifecycleMetricsReporter.kt、JS/TS lifecycleMetrics.ts结构同构双层开关判断_metrics_disabled(config)同时检查连接配置的disable_metrics字段与环境变量OPENSANDBOX_DISABLE_METRICS值为1时生效任一命中即直接返回顶层 try/except 包住整个函数体文档注释明确解释了这样做的动机——该函数同样被Sandbox.create的失败路径调用如果上报器自身抛异常哪怕只是构造 payload 失败遥测异常会替换掉原始的 create 失败。因此 payload 构造与任务/线程调度全部纳入顶层保护事件循环内用asyncio.Task线程上下文用守护线程report_sandbox_create_metric通过asyncio.get_running_loop()判断运行环境——在事件循环中创建后台 task否则启动threading.Thread(daemonTrue)同步 POST两种路径都只记录 debug 日志强引用防止任务被 GC模块级_pending: set[asyncio.Task]保存所有在飞任务task 完成时通过add_done_callback自动摘除避免 fire-and-forget 任务在中途被垃圾回收不复用 SDK 共享 transport同步路径故意新建独立的httpx.Client注释说明复用共享 transport 会在关闭 client 时连带关闭其他 adapter 的连接鉴权头透传请求头包含Content-Type: application/json透传配置中的自定义 headers并自动附带OPEN-SANDBOX-API-KEY与User-Agent后者正是服务端解析 SDK 语言/版本的依据。超时则直接复用连接配置的request_timeout。整体效果是遥测路径上的任何故障DNS、TLS、超时、4xx/5xx都止步于一条 debug 日志。如何禁用遥测遥测默认开启可通过两种方式退出opt out方式一环境变量所有 SDK 通用export OPENSANDBOX_DISABLE_METRICS1方式二连接配置字段按语言设置Pythonfrom opensandbox import ConnectionConfig, Sandbox config ConnectionConfig(disable_metricsTrue) sandbox await Sandbox.create(python:3.12, connection_configconfig)JavaScript / TypeScriptimport { ConnectionConfig, Sandbox } from alibaba-group/opensandbox; const connectionConfig new ConnectionConfig({ disableMetrics: true }); const sandbox await Sandbox.create({ image: python:3.12, connectionConfig, });Gocfg : opensandbox.ConnectionConfig{DisableMetrics: true} sandbox, err : opensandbox.CreateSandbox(ctx, cfg, opensandbox.SandboxCreateOptions{ Image: python:3.12, })C#using OpenSandbox; using OpenSandbox.Config; var connectionConfig new ConnectionConfig(new ConnectionConfigOptions { DisableMetrics true, }); var sandbox await Sandbox.CreateAsync(new SandboxCreateOptions { Image python:3.12, ConnectionConfig connectionConfig, });Kotlinimport com.alibaba.opensandbox.sandbox.Sandbox import com.alibaba.opensandbox.sandbox.config.ConnectionConfig val connectionConfig ConnectionConfig.builder() .disableMetrics(true) .build() val sandbox Sandbox.builder() .image(python:3.12) .connectionConfig(connectionConfig) .build()适用场景在气隙/本地部署air-gapped / on-prem环境中不希望 SDK 发出任何额外 HTTP 流量或企业出口流量审计egress logging中不希望出现遥测请求时应使用上述 opt-out 配置。测试与验证入口仓库内为这套链路提供了多层测试便于在升级或改造时回归验证服务端端点单测test_metrics_api.py覆盖sandbox.create事件处理、User-Agent 解析与 204 响应各 SDK 上报器单测Python test_lifecycle_metrics.py、Go lifecycle_metrics_test.go、C# LifecycleMetricsReporterTests.cs、Kotlin LifecycleMetricsReporterTest.kt端到端测试Python test_lifecycle_metrics_e2e.py、Go lifecycle_metrics_e2e_test.go、JavaScript test_lifecycle_metrics_e2e.test.ts分别覆盖正常上报与OPENSANDBOX_DISABLE_METRICS1下不上报的行为。小结OpenSandbox 的 SDK 遥测是一条极简而严谨的链路SDK 在 create 完成/失败后以 fire-and-forget 方式 POST 一个不含用户内容的 JSON 事件到/v1/metrics/events服务端以204应答并按[otel]配置将样本落入opensandbox.sandbox.create.duration直方图按 SDK 语言、版本与成败打标签。全链路以绝不影响沙箱创建为硬约束版本漂移安全且可用环境变量或连接配置一键关闭。理解其触发时机尤其是 Kotlin staged warmup 的有意排除与直方图桶边界你就能正确解读这份创建延迟指标并在自建监控中做对应聚合。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考