云原生运维【免费下载链接】deschedulerDescheduler for Kubernetes项目地址https://gitcode.com/gh_mirrors/de/descheduler点击查看免费下载导读go.opentelemetry.io/otel/semconv/v1.37.0是 OpenTelemetry 官方发布的 v1.37.0 语义约定Semantic ConventionsGo 实现包它把 OpenTelemetry 社区约定的标准属性名如service.name、error.type、http.response.status_code编译为类型安全的 Go 常量与构造函数帮助开发者写出命名一致、可被后端与查询工具稳定检索的链路追踪与指标数据。本文以该包在 descheduler 仓库中的 vendor 副本为素材系统讲解包的组成、核心 API 用法、常见命名空间速览以及从 v1.36.0 升级到 v1.37.0 时的破坏性变更清单与迁移步骤并给出它在 Go 项目中实际的调用证据。一、什么是 semconv以及本仓库中的这份副本OpenTelemetry Semantic Conventions语义约定是一套经过各方协商一致的标准命名模式用于统一描述 Span、日志、指标和 Resource 中出现的属性名与取值。官方 Go SDK 用独立的semconv子包来承载这套约定每个版本一个目录。在 descheduler 仓库中该包位于vendor/go.opentelemetry.io/otel/semconv/v1.37.0/包含以下文件文件职责README.md包入口说明标注版本为 v1.37.0doc.go包级文档声明本包实现 v1.37.0 版本语义约定schema.go声明本包对应的 Schema URLattribute_group.go全部属性 Key 常量与类型安全构造函数约 1.5 万行由规范自动生成error_type.go根据 error 类型推导error.type属性的辅助函数exception.go异常 Span 事件名称常量MIGRATION.md从 v1.36.0 升级到 v1.37.0 的迁移说明其中attribute_group.go文件头明确标注 Code generated from semantic convention specification. DO NOT EDIT.说明所有属性定义均由 OpenTelemetry 官方语义约定规范自动生成升级版本时只需重新生成不需要也不应该手改。二、Schema URL版本一致性的锚点schema.go 定义了本包对应的 Schema URL// SchemaURL is the schema URL that matches the version of the semantic conventions // that this package defines. Semconv packages starting from v1.4.0 must declare // non-empty schema URL in the form https://opentelemetry.io/schemas/version const SchemaURL https://opentelemetry.io/schemas/1.37.0两点关键信息规范约束从 v1.4.0 起semconv 包必须声明形如https://opentelemetry.io/schemas/version的非空 Schema URL。SchemaURL常量就是为此而设。落地用法在创建 Resource资源描述服务自身身份的一组属性时通常将SchemaURL传给sdkresource.WithSchemaURL()。descheduler 的 pkg/tracing/tracing.go 中就有同款用法其使用 v1.41.0 版本func defaultResourceOpts(name string) []sdkresource.Option { return []sdkresource.Option{ sdkresource.WithAttributes(semconv.ServiceNameKey.String(name)), sdkresource.WithSchemaURL(semconv.SchemaURL), sdkresource.WithProcess(), } }Schema URL 的价值在于当同一份遥测数据被采集端/后端处理时后端可根据 Schema URL 判断该数据遵循哪一版约定从而正确执行属性改名等迁移逻辑。三、包的核心 APIKey 常量 构造函数3.1 两种基础形态attribute_group.go为每个属性提供两种 APIKey 常量类型为attribute.Key直接给出属性名。例如 attribute_group.goServiceNameKey attribute.Key(service.name)构造函数返回attribute.KeyValue把属性名与值打包。例如 attribute_group.gofunc ServiceName(val string) attribute.KeyValue { return ServiceNameKey.String(val) }构造函数会自动选择与属性类型匹配的编码方法字符串用.String()、整型用.Int()、浮点用.Float64()、数组用.StringSlice()/.IntSlice()等。以 GenAI 请求参数为例attribute_group.gofunc GenAIRequestChoiceCount(val int) attribute.KeyValue { return GenAIRequestChoiceCountKey.Int(val) } func GenAIRequestTemperature(val float64) attribute.KeyValue { return GenAIRequestTemperatureKey.Float64(val) } func GenAIRequestEncodingFormats(val ...string) attribute.KeyValue { return GenAIRequestEncodingFormatsKey.StringSlice(val) }这种常量 构造函数双形态设计让使用者既可以直接引用属性 Key 做动态取值也可以一行代码生成标准化的attribute.KeyValue从而杜绝手写字符串拼错属性名的风险。3.2 典型落地示例以服务与网络属性为例一个 Web 服务的 Span 可以这样打点span.SetAttributes( semconv.ServiceName(shoppingcart), // service.name semconv.ServerAddress(api.example.com), // server.address semconv.ServerPort(443), // server.port semconv.HTTPRequestMethodGet, // http.request.method GET semconv.HTTPResponseStatusCode(200), // http.response.status_code semconv.URLFull(https://api.example.com/v1/orders), )HTTPRequestMethodGet是枚举型常量attribute_group.go定义为HTTPRequestMethodKey.String(GET)。这类枚举值常量在包中大量存在例如GenAIOperationNameChat、GenAIOperationNameTextCompletion、GenAIOperationNameEmbeddings等它们保证了同一枚举语义在不同服务间写出完全一致的值。四、特殊辅助函数ErrorType 与异常事件除了成体系的 Key/构造函数本包还提供两个能力型辅助文件。4.1 error_type.go自动推导error.typeerror_type.go 中的ErrorType(err error) attribute.KeyValue是一个值得单独介绍的工具函数其推导规则按优先级排列err为nil时返回枚举兜底值ErrorTypeOther即error.type _OTHER定义见 attribute_group.go若错误类型实现了ErrorType() string方法优先使用该方法返回值否则通过反射取reflect.TypeOf(err)的包路径 类型名如net.OpError对无包路径/无类型名的内置类型退化为t.String()。对应的属性语义attribute_group.go要求error.type可预测、低基数优先使用领域专属状态码如 HTTP 500、gRPC 状态码且操作成功时不应设置该属性。这解释了为什么规范要求用类型/类别而不是具体消息来描述错误——error.message虽然存在ErrorMessageKey但因其无界基数unbounded cardinality与 Span Status 重叠不建议用于 metrics 或 spans。4.2 exception.go异常事件名exception.go 只定义一个常量const ExceptionEventName exception配合ExceptionTypeKeyexception.type、ExceptionMessageKeyexception.message、ExceptionStacktraceKeyexception.stacktrace三个属性见 attribute_group.go即可在 Span 上记录标准化的异常事件。本包在 descheduler 仓库中的真实使用点恰好就在这里vendor/go.opentelemetry.io/auto/sdk/span.goauto-instrumentation SDK导入go.opentelemetry.io/otel/semconv/v1.37.0并在 span.go 中通过异常事件上报错误semconv.ExceptionType(typeStr(err)), semconv.ExceptionMessage(err.Error()), attrs append(attrs, semconv.ExceptionStacktrace(string(buf[0:n]))) ... s.addEvent(semconv.ExceptionEventName, cfg.Timestamp(), attrs)也就是说v1.37.0 在本仓库中的直接消费者是go.opentelemetry.io/auto/sdkgo.mod中声明为go.opentelemetry.io/auto/sdk v1.2.1 // indirect见 go.mod它负责在自动插桩场景下把异常转换为符合语义约定的 Span 事件。而 descheduler 自身的显式追踪代码 pkg/tracing/tracing.go 则使用更新的v1.41.0版本——这正体现了语义约定包按版本演进、各依赖方按需锁定的生态特点。五、主要命名空间速览v1.37.0attribute_group.go按命名空间Namespace组织全部属性各段以// Namespace: xxx注释分隔。以下是本文从源码中确认的部分命名空间与代表性属性命名空间代表性属性 Key说明serviceservice.name、service.namespace、service.version、service.instance.id服务标识Resource 核心属性Stable 级errorerror.type、error.message错误分类error.type为 Stable 级exceptionexception.type、exception.message、exception.stacktrace异常 Span 事件属性httphttp.request.method、http.response.status_codeHTTP 客户端/服务端遥测networknetwork.protocol.name网络协议信息serverserver.address、server.port服务器地址与端口urlurl.full完整 URLk8sk8s.cluster.name、k8s.namespace.name、k8s.node.name、k8s.pod.nameKubernetes 资源标识gen_aigen_ai.operation.name、gen_ai.request.model、gen_ai.request.temperature、gen_ai.request.max_tokens、gen_ai.response.id、gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、gen_ai.agent.id、gen_ai.system_instructionsGenAI/LLM 遥测androidandroid.app.state、android.os.api_levelAndroid 应用遥测artifactartifact.filename、artifact.hash、artifact.purl、artifact.version制品Artifact供应链遥测aws.*aws.bedrock.guardrail.id、aws.dynamodb.*系列AWS 服务相关遥测faasfaas.coldstart、faas.cronServerless/FaaS 遥测deploymentdeployment.environment.name部署环境标识每个属性在源码中都带有一组标准注释标注Type属性类型、RequirementLevelRecommended / Required 等、StabilityStable / Development与Examples相当于把规范文档直接内嵌到了 Go 代码里IDE 悬停即可查阅。例如 attribute_group.go 对service.instance.id的注释详细说明了 UUID 生成建议、跨实例唯一性要求以及 Collector 侧设置时的注意事项。特别值得留意的是GenAI 属性在 v1.37.0 中大幅演进本版本拥有完整的gen_ai.agent.*、gen_ai.data_source.id、gen_ai.input.messages、gen_ai.request.*、gen_ai.response.*、gen_ai.usage.*属性族覆盖 Agent、RAG 数据源、工具调用等场景其中gen_ai.input.messages的注释明确警告该属性很可能包含用户/PII 敏感信息要求插桩方提供过滤/截断机制见 attribute_group.go。六、从 v1.36.0 迁移到 v1.37.0破坏性变更与处理MIGRATION.md 是本包最重要的使用前提文档。官方声明Thego.opentelemetry.io/otel/semconv/v1.37.0package should be a drop-in replacement forgo.opentelemetry.io/otel/semconv/v1.36.0with the following exceptions.即整体上是即插即用替换drop-in replacement唯一例外是以下声明的移除。6.1 已移除声明清单按文档列出原文顺序ContainerRuntimeContainerRuntimeKeyGenAIOpenAIRequestServiceTierAutoGenAIOpenAIRequestServiceTierDefaultGenAIOpenAIRequestServiceTierKeyGenAIOpenAIResponseServiceTierGenAIOpenAIResponseServiceTierKeyGenAIOpenAIResponseSystemFingerprintGenAIOpenAIResponseSystemFingerprintKeyGenAISystemAWSBedrockGenAISystemAnthropicGenAISystemAzureAIInferenceGenAISystemAzureAIOpenAIGenAISystemCohereGenAISystemDeepseekGenAISystemGCPGeminiGenAISystemGCPGenAIGenAISystemGCPVertexAIGenAISystemGroqGenAISystemIBMWatsonxAIGenAISystemKeyGenAISystemMistralAIGenAISystemOpenAIGenAISystemPerplexityGenAISystemXai6.2 变更原因与处理建议文档给出了明确的处置原则若该声明在语义约定文档中被标记为 deprecated请按官方文档中的弃用说明迁移通常是对应新属性或改用法。若未被标记为 deprecated说明它在 v1.37.0 中因缺乏适用性或使用量而被移除。如果你在应用中确实使用到这些非弃用声明官方建议提交 issue 描述你的使用场景以便维护者评估是否恢复或提供替代方案。6.3 迁移时的核查要点升级到 v1.37.0 后请重点排查以下两类代码GenAISystem*系列gen_ai.system.name相关声明整体被移除。当前 v1.37.0 源码中已不存在GenAISystemKey取而代之的仍是GenAISystemInstructionsKeygen_ai.system_instructionsattribute_group.go。若旧代码依赖系统名如GenAISystemOpenAI来标记模型供应商需要改用其他属性表达该信息。ContainerRuntime/ContainerRuntimeKey容器运行时相关简写声明被移除。注意不要与仍存在的ContainerRuntimeNameKeycontainer.runtime.nameattribute_group.go混淆——后者是标准属性前者是 v1.36.0 中额外导出的声明。标准做法是先静态搜索整个代码库中上述符号的引用逐个迁移再重新运行构建与单元测试。本仓库的验证脚本链如hack/verify-gofmt.sh、hack/verify-govet.sh、hack/verify-vendor.sh同样适用于升级后的检查其中verify-vendor.sh会校验 vendor 目录与go.mod/go.sum的一致性是升级 semconv 后必跑的脚本。七、在 Go 项目中引入与使用本包的注意事项7.1 引入方式在项目中引入该包的标准方式go get go.opentelemetry.io/otel/semconv/v1.37.0由于本仓库将依赖以 vendor 模式管理实际生效的源码即vendor/go.opentelemetry.io/otel/semconv/v1.37.0/目录升级 semconv 版本后需同步运行hack/update-vendor.sh或go mod vendor刷新 vendor 目录保持与go.mod/go.sum一致。7.2 使用建议统一用构造函数而不是手写字面量例如写semconv.ServiceName(descheduler)而非attribute.String(service.name, descheduler)既省去记忆属性名也让代码在版本升级时能通过编译期检查暴露失效的属性。注意版本一致性同一仓库的不同组件可能依赖不同 semconv 版本descheduler 自身用 v1.41.0auto SDK 用 v1.37.0见 pkg/tracing/tracing.go 与 span.go。只要每个 Span/Resource 声明了对应的SchemaURL后端就能正确解释数据但跨组件混用不同版本时仍应以最新的SchemaURL作为最终对齐基准。善用代码内注释属性定义自带Type、RequirementLevel、Stability、Examples注释编写打点代码前先在 IDE 里悬停查看这些元信息可避免误用已标记为 Development尚不稳定的属性于生产环境。结语go.opentelemetry.io/otel/semconv/v1.37.0是一个小而全的类型安全约定包schema.go锚定 Schema URLattribute_group.go承载全量属性常量与构造函数error_type.go与exception.go提供错误分类与异常事件的基础设施MIGRATION.md则划清了与上一版本的破坏性边界。无论你是为 Kubernetes 控制器如本仓库的 descheduler接入 OTLP 追踪还是构建 GenAI 应用的遥测打点先吃透所用 semconv 版本的常量体系与迁移清单都是让遥测数据从能看变成可分析的第一步。赞分享云原生运维【免费下载链接】deschedulerDescheduler for Kubernetes项目地址https://gitcode.com/gh_mirrors/de/descheduler点击查看免费下载相关推荐OpenTelemetry Go semconv v1.37.0 迁移指南GenAI 与容器运行时语义属性移除详解sliver 仓库依赖视角OpenTelemetry Go semconv v1.37.0 迁移指南GenAI 与容器运行时语义属性移除详解sliver 仓库依赖视角 本文聚焦于网络安全OpenTelemetry SemConv v1.37.0 迁移指南解读 v1.36.0→v1.37.0 的被移除声明与升级路径linuxkit 仓库实践OpenTelemetry SemConv v1.37.0 迁移指南解读 v1.36.0→v1.37.0 的被移除声明与升级路径linuxkit 仓库实践操作系统云原生容器运行时OpenTelemetry Go Semconv v1.39.0 迁移指南RPC 语义约定重构与 60 个废弃声明移除OpenTelemetry Go Semconv v1.39.0 迁移指南RPC 语义约定重构与 60 个废弃声明移除 本指南以仓库内 vendor/go.o网络安全创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考