引言“可观测性不是工具是能力。要学会用 Traces/Metrics/Logs 诊断分布式系统光读文档不够得有一个真实的系统可以折腾。”这是第 195 篇。今天的项目是OpenTelemetry DemoAstronomy Shop—— OpenTelemetry 官方出品的分布式电商演示系统核心定位是一个可以主动制造故障、然后用可观测性数据找出根因的实战学习环境。不是 Hello World不是玩具项目。17 个微服务12 种编程语言Kafka 消息队列PostgreSQL 数据库gRPC HTTP 混合通信加上 Grafana Jaeger Prometheus 全套可视化。3,300 Stars7,000 Forks。Apache-2.0 许可。Datadog、AWS、Google Cloud、New Relic、Dynatrace 等超过 50 家云厂商 Fork 它用来做自己的集成演示。你会学到什么OpenTelemetry Demo 的三大用途和定位17 个服务的架构全景和技术选型逻辑Traces/Metrics/Logs 三大信号在不同语言里的实现方式13 个故障开关如何主动制造问题来练习根因分析完整可视化栈Grafana Jaeger Prometheus 的数据流为什么 50 家厂商选它作为集成演示基础前提知识了解微服务架构的基本概念知道 Traces链路追踪、Metrics指标、Logs日志是什么Docker 基础操作背景可观测性学习的困境学习可观测性有一个根本问题没有真实系统就没有真实数据没有真实数据就学不了真实的诊断方法。拿单服务应用练习链路追踪学到的是如何给一个 HTTP 处理器打 span。但实际生产环境的问题是请求从前端出发经过 API 网关调用三个微服务其中一个调用了 Kafka异步消费者在 30 秒后处理触发了数据库写入失败——你在哪里看到错误错误是哪个服务的责任根因在第几跳这类问题必须在真正的分布式系统里才能理解。OpenTelemetry Demo 的解法是造一个足够真实的系统然后给它配上 13 个可控的故障开关让你按需制造问题再用可观测性数据找出来。项目的三大定位OpenTelemetry Demo 同时服务于三类人这一点从它的架构设计上就能看出来。1. 学习者可观测性实战教材对于想学 OpenTelemetry 的工程师项目提供了一个现成的分布式系统涵盖12 种语言的真实 SDK 用法自动插桩 vs 手动插桩的差异gRPC 和 HTTP 两种协议的 span 传播跨服务的上下文传播context propagationKafka 消息队列的异步 trace 关联打开 Jaeger能看到一条请求从浏览器出发流过 Frontend → Checkout → Payment → Email 的完整链路。每一跳用了多少时间哪里出了错一目了然。2. 厂商和工具开发者集成演示基础Datadog、Elastic、AWS OpenSearch、Grafana Labs、New Relic、Dynatrace、Splunk、Google Cloud……超过 50 家公司 Fork 了这个仓库接上自己的后端用来演示OTel 数据导入我们平台的效果。这意味着你在这个项目里学会的 OTel 知识在这 50 家厂商的产品里都可以直接用。OTel 的可观测性信号是中立标准不锁定在任何一家厂商。3. OTel 贡献者API/SDK 测试床新版本的 OTel SDK 发布前需要在真实的多语言环境里验证兼容性和性能。这个项目同时运行 12 种语言的 SDK是天然的集成测试环境。架构全景17 个服务12 种语言服务列表服务语言主要职责FrontendTypeScriptWeb UI调用多个后端服务Frontend ProxyC (Envoy)请求路由、故障注入AdJava广告推荐触发 gRPC 调用Cart.NET购物车连接 Valkey 缓存CheckoutGo结账流程协调多服务CurrencyC汇率转换高 QPS 服务EmailRuby发送确认邮件Fraud DetectionKotlin欺诈检测Kafka 消费者PaymentJavaScript支付处理Product CatalogGo商品列表gRPC 接口QuotePHP运费报价HTTP 接口RecommendationPython商品推荐调用 Product CatalogShippingRust配送处理调用 QuoteAccounting.NET订单记账Kafka 消费者Load GeneratorPython/Locust模拟真实用户流量FlagdGoFeature Flag 服务Flagd UIElixirFeature Flag 管理界面基础设施组件缓存: ValkeyRedis 兼容数据库: PostgreSQL消息队列: KafkaJavaOTel Collector: 统一收集所有遥测数据通信协议服务间主要用 gRPC少数用 HTTP遥测数据OTLP/gRPC端口 4317和 OTLP/HTTP端口 4318异步Kafka TCP 连接技术选型的逻辑语言选择不是随机的每种语言对应 OTel SDK 的一个实现C (Currency)高 QPS 场景验证 C SDK 性能开销Rust (Shipping)新兴后端语言演示 Rust SDK 用法PHP (Quote)传统 Web 技术演示 PHP SDK 集成Elixir (Flagd UI)函数式语言演示 BEAM 平台的 OTel 支持遥测数据流从服务到 Grafana所有服务的遥测数据汇入同一个 OTel Collector再分发到各可视化后端各服务12种语言 ↓ OTLP/gRPC 或 OTLP/HTTP OTel Collector ├──→ Prometheus指标存储 → localhost:9090 ├──→ Jaeger链路追踪存储 → localhost:16686 └──→ OpenSearch日志存储 → localhost:9200 ↑ ↑ ↑ Grafana统一可视化 → localhost:3000Collector 还通过 OpAMP 扩展把自身的健康状态、版本、有效配置上报给 OpAMP 服务器这是 OTel 的远程配置管理能力演示。13 个故障开关主动制造问题这是 OpenTelemetry Demo 区别于普通演示项目最关键的设计。所有故障开关由FlagdOpenFeature 标准的 Feature Flag 服务管理在http://localhost:8080/feature界面开关不需要重启服务。故障开关完整列表开关名称影响服务制造的问题adServiceFailureAd1/10 概率 GetAds 请求报错adServiceManualGcAd手动触发垃圾回收adServiceHighCpuAd模拟高 CPU 负载cartServiceFailureCartEmptyCart 调用报错emailMemoryLeakEmail内存泄漏productCatalogFailureProduct Catalog特定商品 ID 请求失败recommendationServiceCacheFailureRecommendation缓存指数增长内存泄漏每次 1.4 倍50% 请求触发paymentServiceFailurePaymentcharge 调用报错paymentServiceUnreachableCheckout支付服务不可达loadgeneratorFloodHomepageLoad Generator主页请求洪泛kafkaQueueProblemsKafka队列过载 消费延迟触发堆积峰值imageSlowLoadFrontendEnvoy 故障注入延迟图片加载failedReadinessProbeCart就绪探针失败仅 Kubernetes 场景故障练习路径练习 1内存泄漏诊断开启recommendationServiceCacheFailure在 Grafana 看到 Recommendation 服务内存指标呈指数增长在 Jaeger 看到部分推荐请求的 span 标注缓存操作异常练习从指标异常 → 定位服务 → 追溯 trace → 确认根因练习 2支付链路级联故障开启paymentServiceUnreachableCheckout 服务开始收到支付失败错误在 Jaeger 里看到 Checkout trace 中 Payment 服务的子 span 显示超时练习从用户报告无法付款 → Checkout trace → Payment span → 定位服务不可达练习 3Kafka 堆积分析开启kafkaQueueProblemsKafka 消费者Accounting、Fraud Detection开始积压Prometheus 里 Kafka 消费延迟指标持续上升练习从订单处理延迟 → Kafka 指标 → 消费者 lag → 定位队列问题练习 4前端延迟分析开启imageSlowLoadEnvoy 故障注入Frontend 的图片加载时间突然延长在 Jaeger 的 Frontend trace 里看到图片请求的 span 耗时异常练习浏览器 Web Vitals 劣化 → Frontend trace → 定位具体请求快速上手Docker Compose 部署# 克隆仓库gitclone https://github.com/open-telemetry/opentelemetry-demo.gitcdopentelemetry-demo# 启动全部服务首次拉取镜像需要几分钟dockercompose up --no-build# 等待服务就绪有些服务启动较慢等 1-2 分钟dockercomposeps服务就绪后的访问地址地址服务http://localhost:8080Astronomy Shop电商前端http://localhost:8080/featureFeature Flag 管理界面http://localhost:3000Grafana统一可视化http://localhost:16686Jaeger链路追踪http://localhost:9090Prometheus指标Kubernetes / Helm 部署# 添加 OTel Demo Helm 仓库helm repoaddopen-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts helm repo update# 安装到 otel-demo 命名空间helminstallmy-otel-demo open-telemetry/opentelemetry-demo\--namespaceotel-demo\--create-namespaceHelm Chart 已上架 Artifact Hub可以按需覆盖各服务的配置。插桩方式对比自动 vs 手动OTel 提供两种插桩路径项目里同时有示例自动插桩Zero-code代码零修改通过 agent/SDK 初始化自动捕获框架层的遥测数据Java (Ad Service)JVM Agent启动参数加-javaagent:opentelemetry-javaagent.jarPython (Recommendation)opentelemetry-instrument python app.py.NET (Cart, Accounting)OTEL_DOTNET_AUTO_*环境变量适合需要快速上线可观测性、不想修改已有代码。手动插桩在业务代码里直接用 SDK 创建 span、添加属性、记录事件// Go 手动插桩示例Checkout Servicetracer:otel.Tracer(checkout)ctx,span:tracer.Start(ctx,placeOrder)deferspan.End()span.SetAttributes(attribute.String(order.id,orderID),attribute.Int(order.items,len(items)),)// 处理业务逻辑...iferr!nil{span.RecordError(err)span.SetStatus(codes.Error,err.Error())}// Rust 手动插桩示例Shipping Servicelettracerglobal::tracer(shipping);letmutspantracer.start(shipOrder);span.set_attribute(KeyValue::new(shipping.method,method));适合需要对业务逻辑有精细控制需要自定义属性和事件。为什么 50 家厂商选它选一个统一的演示基础而不是自己造轮子有几个实际好处受众熟悉工程师在学习 OTel 时可能已经看过这个项目再看厂商演示时有共同背景公正对比所有厂商基于同一数据源客户可以用同样的工作负载比较不同平台的效果维护成本官方团队维护基础服务架构厂商只需维护OTel Collector → 自家后端的对接部分跟上版本随着 OTel 新版本发布官方项目同步更新厂商 Fork 可以 rebase项目地址与资源GitHub: open-telemetry/opentelemetry-demo官方文档: opentelemetry.io/docs/demoHelm Chart: Artifact Hub - opentelemetry-demoOTel 官网: opentelemetry.io总结OpenTelemetry Demo 解决了可观测性学习里最核心的障碍缺少一个可以安全折腾的真实系统。12 种语言的服务让你看到 OTel SDK 在不同技术栈里的实际用法不用猜文档里的抽象描述对应到代码是什么样子。13 个故障开关让你在受控环境里练习根因分析从指标异常到链路追踪到日志走完完整的诊断流程。更大的价值是它建立了一个行业共识Datadog 的 Traces 界面展示的是它Grafana Cloud 演示的是它AWS X-Ray 集成演示的是它。当你在这个项目里学会如何从 Kafka 延迟指标追溯到消费者堆积这套思路在任何一家厂商的平台上都适用——OTel 的信号格式是中立的不锁定。3,300 Stars 加上 7,000 Forks 是一个反常的比例Fork 数是 Star 数的两倍。背后的原因是那 50 家厂商——每家都 Fork 了一份自己维护说明这个项目对行业来说是基础设施级别的参考不只是学习材料。探索 PrimeSkills —— 精选 AI Agent 与技能的市场每一个都经过真实企业工作流验证去掉浮夸留下真正有用的。欢迎访问我的个人主页发现更多有价值的见解和有趣的产品。 
长河君 · 2026/8/24 21:20:06 · 阅读 1.2k 开源项目第195期：OpenTelemetry Demo（Astronomy Shop）— 官方出品的分布式系统可观测性实战教材
引言“可观测性不是工具是能力。要学会用 Traces/Metrics/Logs 诊断分布式系统光读文档不够得有一个真实的系统可以折腾。”这是第 195 篇。今天的项目是OpenTelemetry DemoAstronomy Shop—— OpenTelemetry 官方出品的分布式电商演示系统核心定位是一个可以主动制造故障、然后用可观测性数据找出根因的实战学习环境。不是 Hello World不是玩具项目。17 个微服务12 种编程语言Kafka 消息队列PostgreSQL 数据库gRPC HTTP 混合通信加上 Grafana Jaeger Prometheus 全套可视化。3,300 Stars7,000 Forks。Apache-2.0 许可。Datadog、AWS、Google Cloud、New Relic、Dynatrace 等超过 50 家云厂商 Fork 它用来做自己的集成演示。你会学到什么OpenTelemetry Demo 的三大用途和定位17 个服务的架构全景和技术选型逻辑Traces/Metrics/Logs 三大信号在不同语言里的实现方式13 个故障开关如何主动制造问题来练习根因分析完整可视化栈Grafana Jaeger Prometheus 的数据流为什么 50 家厂商选它作为集成演示基础前提知识了解微服务架构的基本概念知道 Traces链路追踪、Metrics指标、Logs日志是什么Docker 基础操作背景可观测性学习的困境学习可观测性有一个根本问题没有真实系统就没有真实数据没有真实数据就学不了真实的诊断方法。拿单服务应用练习链路追踪学到的是如何给一个 HTTP 处理器打 span。但实际生产环境的问题是请求从前端出发经过 API 网关调用三个微服务其中一个调用了 Kafka异步消费者在 30 秒后处理触发了数据库写入失败——你在哪里看到错误错误是哪个服务的责任根因在第几跳这类问题必须在真正的分布式系统里才能理解。OpenTelemetry Demo 的解法是造一个足够真实的系统然后给它配上 13 个可控的故障开关让你按需制造问题再用可观测性数据找出来。项目的三大定位OpenTelemetry Demo 同时服务于三类人这一点从它的架构设计上就能看出来。1. 学习者可观测性实战教材对于想学 OpenTelemetry 的工程师项目提供了一个现成的分布式系统涵盖12 种语言的真实 SDK 用法自动插桩 vs 手动插桩的差异gRPC 和 HTTP 两种协议的 span 传播跨服务的上下文传播context propagationKafka 消息队列的异步 trace 关联打开 Jaeger能看到一条请求从浏览器出发流过 Frontend → Checkout → Payment → Email 的完整链路。每一跳用了多少时间哪里出了错一目了然。2. 厂商和工具开发者集成演示基础Datadog、Elastic、AWS OpenSearch、Grafana Labs、New Relic、Dynatrace、Splunk、Google Cloud……超过 50 家公司 Fork 了这个仓库接上自己的后端用来演示OTel 数据导入我们平台的效果。这意味着你在这个项目里学会的 OTel 知识在这 50 家厂商的产品里都可以直接用。OTel 的可观测性信号是中立标准不锁定在任何一家厂商。3. OTel 贡献者API/SDK 测试床新版本的 OTel SDK 发布前需要在真实的多语言环境里验证兼容性和性能。这个项目同时运行 12 种语言的 SDK是天然的集成测试环境。架构全景17 个服务12 种语言服务列表服务语言主要职责FrontendTypeScriptWeb UI调用多个后端服务Frontend ProxyC (Envoy)请求路由、故障注入AdJava广告推荐触发 gRPC 调用Cart.NET购物车连接 Valkey 缓存CheckoutGo结账流程协调多服务CurrencyC汇率转换高 QPS 服务EmailRuby发送确认邮件Fraud DetectionKotlin欺诈检测Kafka 消费者PaymentJavaScript支付处理Product CatalogGo商品列表gRPC 接口QuotePHP运费报价HTTP 接口RecommendationPython商品推荐调用 Product CatalogShippingRust配送处理调用 QuoteAccounting.NET订单记账Kafka 消费者Load GeneratorPython/Locust模拟真实用户流量FlagdGoFeature Flag 服务Flagd UIElixirFeature Flag 管理界面基础设施组件缓存: ValkeyRedis 兼容数据库: PostgreSQL消息队列: KafkaJavaOTel Collector: 统一收集所有遥测数据通信协议服务间主要用 gRPC少数用 HTTP遥测数据OTLP/gRPC端口 4317和 OTLP/HTTP端口 4318异步Kafka TCP 连接技术选型的逻辑语言选择不是随机的每种语言对应 OTel SDK 的一个实现C (Currency)高 QPS 场景验证 C SDK 性能开销Rust (Shipping)新兴后端语言演示 Rust SDK 用法PHP (Quote)传统 Web 技术演示 PHP SDK 集成Elixir (Flagd UI)函数式语言演示 BEAM 平台的 OTel 支持遥测数据流从服务到 Grafana所有服务的遥测数据汇入同一个 OTel Collector再分发到各可视化后端各服务12种语言 ↓ OTLP/gRPC 或 OTLP/HTTP OTel Collector ├──→ Prometheus指标存储 → localhost:9090 ├──→ Jaeger链路追踪存储 → localhost:16686 └──→ OpenSearch日志存储 → localhost:9200 ↑ ↑ ↑ Grafana统一可视化 → localhost:3000Collector 还通过 OpAMP 扩展把自身的健康状态、版本、有效配置上报给 OpAMP 服务器这是 OTel 的远程配置管理能力演示。13 个故障开关主动制造问题这是 OpenTelemetry Demo 区别于普通演示项目最关键的设计。所有故障开关由FlagdOpenFeature 标准的 Feature Flag 服务管理在http://localhost:8080/feature界面开关不需要重启服务。故障开关完整列表开关名称影响服务制造的问题adServiceFailureAd1/10 概率 GetAds 请求报错adServiceManualGcAd手动触发垃圾回收adServiceHighCpuAd模拟高 CPU 负载cartServiceFailureCartEmptyCart 调用报错emailMemoryLeakEmail内存泄漏productCatalogFailureProduct Catalog特定商品 ID 请求失败recommendationServiceCacheFailureRecommendation缓存指数增长内存泄漏每次 1.4 倍50% 请求触发paymentServiceFailurePaymentcharge 调用报错paymentServiceUnreachableCheckout支付服务不可达loadgeneratorFloodHomepageLoad Generator主页请求洪泛kafkaQueueProblemsKafka队列过载 消费延迟触发堆积峰值imageSlowLoadFrontendEnvoy 故障注入延迟图片加载failedReadinessProbeCart就绪探针失败仅 Kubernetes 场景故障练习路径练习 1内存泄漏诊断开启recommendationServiceCacheFailure在 Grafana 看到 Recommendation 服务内存指标呈指数增长在 Jaeger 看到部分推荐请求的 span 标注缓存操作异常练习从指标异常 → 定位服务 → 追溯 trace → 确认根因练习 2支付链路级联故障开启paymentServiceUnreachableCheckout 服务开始收到支付失败错误在 Jaeger 里看到 Checkout trace 中 Payment 服务的子 span 显示超时练习从用户报告无法付款 → Checkout trace → Payment span → 定位服务不可达练习 3Kafka 堆积分析开启kafkaQueueProblemsKafka 消费者Accounting、Fraud Detection开始积压Prometheus 里 Kafka 消费延迟指标持续上升练习从订单处理延迟 → Kafka 指标 → 消费者 lag → 定位队列问题练习 4前端延迟分析开启imageSlowLoadEnvoy 故障注入Frontend 的图片加载时间突然延长在 Jaeger 的 Frontend trace 里看到图片请求的 span 耗时异常练习浏览器 Web Vitals 劣化 → Frontend trace → 定位具体请求快速上手Docker Compose 部署# 克隆仓库gitclone https://github.com/open-telemetry/opentelemetry-demo.gitcdopentelemetry-demo# 启动全部服务首次拉取镜像需要几分钟dockercompose up --no-build# 等待服务就绪有些服务启动较慢等 1-2 分钟dockercomposeps服务就绪后的访问地址地址服务http://localhost:8080Astronomy Shop电商前端http://localhost:8080/featureFeature Flag 管理界面http://localhost:3000Grafana统一可视化http://localhost:16686Jaeger链路追踪http://localhost:9090Prometheus指标Kubernetes / Helm 部署# 添加 OTel Demo Helm 仓库helm repoaddopen-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts helm repo update# 安装到 otel-demo 命名空间helminstallmy-otel-demo open-telemetry/opentelemetry-demo\--namespaceotel-demo\--create-namespaceHelm Chart 已上架 Artifact Hub可以按需覆盖各服务的配置。插桩方式对比自动 vs 手动OTel 提供两种插桩路径项目里同时有示例自动插桩Zero-code代码零修改通过 agent/SDK 初始化自动捕获框架层的遥测数据Java (Ad Service)JVM Agent启动参数加-javaagent:opentelemetry-javaagent.jarPython (Recommendation)opentelemetry-instrument python app.py.NET (Cart, Accounting)OTEL_DOTNET_AUTO_*环境变量适合需要快速上线可观测性、不想修改已有代码。手动插桩在业务代码里直接用 SDK 创建 span、添加属性、记录事件// Go 手动插桩示例Checkout Servicetracer:otel.Tracer(checkout)ctx,span:tracer.Start(ctx,placeOrder)deferspan.End()span.SetAttributes(attribute.String(order.id,orderID),attribute.Int(order.items,len(items)),)// 处理业务逻辑...iferr!nil{span.RecordError(err)span.SetStatus(codes.Error,err.Error())}// Rust 手动插桩示例Shipping Servicelettracerglobal::tracer(shipping);letmutspantracer.start(shipOrder);span.set_attribute(KeyValue::new(shipping.method,method));适合需要对业务逻辑有精细控制需要自定义属性和事件。为什么 50 家厂商选它选一个统一的演示基础而不是自己造轮子有几个实际好处受众熟悉工程师在学习 OTel 时可能已经看过这个项目再看厂商演示时有共同背景公正对比所有厂商基于同一数据源客户可以用同样的工作负载比较不同平台的效果维护成本官方团队维护基础服务架构厂商只需维护OTel Collector → 自家后端的对接部分跟上版本随着 OTel 新版本发布官方项目同步更新厂商 Fork 可以 rebase项目地址与资源GitHub: open-telemetry/opentelemetry-demo官方文档: opentelemetry.io/docs/demoHelm Chart: Artifact Hub - opentelemetry-demoOTel 官网: opentelemetry.io总结OpenTelemetry Demo 解决了可观测性学习里最核心的障碍缺少一个可以安全折腾的真实系统。12 种语言的服务让你看到 OTel SDK 在不同技术栈里的实际用法不用猜文档里的抽象描述对应到代码是什么样子。13 个故障开关让你在受控环境里练习根因分析从指标异常到链路追踪到日志走完完整的诊断流程。更大的价值是它建立了一个行业共识Datadog 的 Traces 界面展示的是它Grafana Cloud 演示的是它AWS X-Ray 集成演示的是它。当你在这个项目里学会如何从 Kafka 延迟指标追溯到消费者堆积这套思路在任何一家厂商的平台上都适用——OTel 的信号格式是中立的不锁定。3,300 Stars 加上 7,000 Forks 是一个反常的比例Fork 数是 Star 数的两倍。背后的原因是那 50 家厂商——每家都 Fork 了一份自己维护说明这个项目对行业来说是基础设施级别的参考不只是学习材料。探索 PrimeSkills —— 精选 AI Agent 与技能的市场每一个都经过真实企业工作流验证去掉浮夸留下真正有用的。欢迎访问我的个人主页发现更多有价值的见解和有趣的产品。