OpenTelemetry Demo 实战:用官方微服务演示应用学 OTel

用官方 Astronomy Shop 启动 OpenTelemetry Demo 3.1.0,对比正常结账与支付故障的链路,查看 Collector 管道,并把 trace 另送至观测云 DataKit。

最佳实践
OpenTelemetry Demo 实战:用官方微服务演示应用学 OTel封面

OpenTelemetry Demo 是官方维护的虚构电商应用「Astronomy Shop」。Go、Java、Python、Node.js、.NET 等语言写成的服务自带 OTel 埋点,可以在动手给自己的应用埋点前,先看一次请求怎么经过结算、支付和异步消息处理。不同服务提供的信号不同。

核心要点速览

  • Demo 包含前端、购物车、支付、广告、推荐等服务,覆盖多种语言。
  • Compose 的基础配置启动核心应用和 Collector,叠加完整模式和可观测层后才有 Kafka、Jaeger、Prometheus、Grafana 和 OpenSearch。
  • 可以用同一笔测试订单观察上下文传播、采样和 Collector 管道,再把链路另送一份到观测云。

Demo 里有什么?

Astronomy Shop 模拟电商场景:前端展示商品,调用推荐、广告、购物车、结算、支付和物流等服务。完整模式还会启动 Kafka 及其消费者,包括会计和欺诈检测。特性开关可以人为注入故障。

预置埋点包含 HTTP、gRPC 或消息队列调用的 Span、指标及日志,具体信号和属性随服务而异。日志是否能按 trace ID 关联,也取决于该服务的日志记录方式。可先查官方的服务遥测清单。Demo 架构 · 遥测覆盖范围

本地启动步骤

以下以 Demo 3.1.0 为例。用 Docker 和 Compose v2 在独立测试环境运行。上游 Compose 会挂载主机目录和 Docker socket,并发布多个端口,练习时请使用演示数据。

git clone --branch 3.1.0 --depth 1 https://github.com/open-telemetry/opentelemetry-demo.git
cd opentelemetry-demo
export DEMO_VERSION=3.1.0
docker compose --env-file .env --env-file .env.override \
  -f compose.yaml -f compose.full.yaml \
  -f compose.observability.yaml -f compose.extras.yaml up -d

直接执行 docker compose up 只会读入基础配置。上面的命令按顺序加载基础、完整模式、可观测层和最后的自定义层。等服务就绪后,从默认的 http://localhost:8080/ 入口访问 Web 商店。Jaeger 在 /jaeger/ui/,Grafana 在 /grafana/,负载发生器在 /loadgen/,特性开关界面在 /feature/,服务遥测清单在 /telemetry/。官方 Docker 部署指南 · 3.1.0 发布记录

本文核对了固定版本的 Compose 配置、代理路由和支付行为,未实跑整套容器或接入外部 DataKit。

用 Demo 学什么?

  1. 上下文传播:观察 Kafka 异步消息中的 trace 上下文,留意 Span 是父子关系,还是通过 Span Link 关联。 上下文传播
  2. Collector 管道:Demo 展示了 OTLP 接收与多路导出。可观测层把链路发往 Jaeger、指标发往 Prometheus、日志发往 OpenSearch,span_metrics 还会从 Span 生成指标。 固定版本可观测层配置
  3. 语义约定:对照 Span 属性理解约定在不同服务中的用法。 语义约定
  4. 采样:调整链路采样策略,观察哪些 trace 被保留。要减少整个 Demo 的合成流量,从负载发生器调整。

先将 paymentFailure 设为 off,用示例付款信息完成一笔测试订单。在 Jaeger 按时间和 checkout 服务找到 trace,顺着它进入 payment 服务,查看 charge Span。接着在 flagd 界面把 paymentFailure 的默认变体改为 100% 并保存,再下单一次。该版本的支付处理函数会抛出合成错误,并给 charge Span 标记错误状态。对比两条链路看故障出在哪一步,练习后将开关恢复为 off。官方故障开关说明 · 3.1.0 支付处理函数

如果 Collector 容器能通过私有网络访问 DataKit,可以为 Demo 的 Collector 增加一个链路导出目标。在 src/otel-collector/otelcol-config-extras.yml 添加以下配置,将示例地址换成容器实际可达的 OTLP/HTTP Protobuf 接收端。DataKit 默认 HTTP 端口为 9529,链路路径为 /otel/v1/traces。TLS 和认证按实际部署配置。DataKit 接入文档

exporters:
  otlp_http/datakit:
    traces_endpoint: https://datakit.example.com/otel/v1/traces
service:
  pipelines:
    traces:
      exporters: [debug, otlp_grpc/jaeger, span_metrics, otlp_http/datakit]

Collector 合并配置时会替换数组,因此要在链路导出列表中保留原有的 Jaeger、debug 和 span_metrics。修改后用相同的 Compose 层重启 Collector。接通后重新完成两次测试订单,在观测云核对服务和 Span 层级。若还要发送指标、日志,应分别配置对应的 OTLP/HTTP 路径和管道。

常见问题(FAQ)

Q:Demo 对机器配置要求高吗? 官方 Docker 指南列出完整模式需 6 GB 应用内存和 14 GB 磁盘空间。官方精简模式保留可观测组件,省略 Kafka 和依赖它的服务,应用内存约 3 GB。

Q:Demo 的埋点代码值得抄吗? 可以参考,但生产埋点还需按实际环境配置资源标识、采样、脱敏和资源限制。实操时请使用示例数据,保持原始敏感数据输出开关关闭。 敏感数据脱敏

Q:可以在 K8s 里跑 Demo 吗? 官方提供 Helm Chart,可按文档的 values、资源需求和端口转发说明部署到测试集群。 官方 Kubernetes 部署指南

Q:Demo 数据量会不会很大? 负载发生器默认持续产生合成流量,导入观测云练习时可以先调低流量。链路采样不会统一降低指标和日志流量。

系列阅读

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台