2. 环境搭建：Python虚拟环境创建、安装opentelemetry-sdk与otel-mock库、验证安装
本章是实战课程的起点。我们将从零搭建一个干净的 Python 隔离环境，安装核心依赖库，并通过一个最小化脚本验证链路追踪数据能否被 OTelMock 正确捕获。完成本章后，你将拥有一个可复用的本地实验沙箱。
2.1 环境准备清单
在开始之前，请确认你的开发机满足以下最低要求：
| 依赖项 | 推荐版本 | 验证命令 |
|---|---|---|
| Python | 3.10+ | python --version |
| pip | 24.0+ | pip --version |
| venv | 内置模块 | python -m venv --help |
| 操作系统 | macOS / Linux / Windows (WSL2) | — |
💡 提示： 如果你使用 Windows，强烈建议通过 WSL2 运行本课程的所有实验，以避免路径分隔符和信号处理差异带来的问题。
2.2 创建 Python 虚拟环境
虚拟环境可以隔离项目依赖，避免与系统级 Python 包冲突。执行以下命令创建并激活环境：
# 创建虚拟环境（在课程根目录下执行）
python -m venv .venv
# 激活环境（macOS / Linux）
source .venv/bin/activate
# 激活环境（Windows PowerShell）
.venv\Scripts\Activate.ps1
# 激活环境（Windows CMD）
.venv\Scripts\activate.bat激活后，终端提示符前会出现 (.venv) 前缀，表示当前处于隔离环境中。
2.3 安装核心依赖库
本课程需要两个核心包：opentelemetry-sdk 提供标准 OpenTelemetry 链路追踪能力，otel-mock 提供本地内存接收器，用于在不依赖远端 Collector 的情况下验证数据。
# 升级 pip 并安装依赖
pip install --upgrade pip
pip install opentelemetry-sdk opentelemetry-api otel-mock安装完成后，可以通过以下命令确认版本：
pip show opentelemetry-sdk otel-mock输出应包含类似如下的版本信息：
Name: opentelemetry-sdk
Version: 1.27.0
...
Name: otel-mock
Version: 0.8.0
...2.4 验证安装：最小化链路追踪脚本
我们编写一个极简脚本，创建一个 Span 并通过 OTelMock 的 InMemorySpanExporter 导出，验证整个链路是否正常工作。
# verify_setup.py
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from otel_mock import InMemorySpanExporter
# 1. 创建内存导出器
exporter = InMemorySpanExporter()
# 2. 配置 TracerProvider 并挂载导出器
provider = TracerProvider()
processor = SimpleSpanProcessor(exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
# 3. 获取 Tracer 并创建一个测试 Span
tracer = trace.get_tracer("setup-verification")
with tracer.start_as_current_span("hello-otel-mock") as span:
span.set_attribute("test.key", "setup-ok")
# 4. 从导出器获取已导出的 Span 列表
spans = exporter.get_finished_spans()
assert len(spans) == 1, f"期望 1 个 Span，实际得到 {len(spans)}"
assert spans[0].name == "hello-otel-mock"
assert spans[0].attributes.get("test.key") == "setup-ok"
print("✅ 环境验证通过！OTelMock 成功捕获并导出 Span。")
print(f" Span 名称: {spans[0].name}")
print(f" Span 属性: {spans[0].attributes}")运行脚本：
python verify_setup.py预期输出：
✅ 环境验证通过！OTelMock 成功捕获并导出 Span。
Span 名称: hello-otel-mock
Span 属性: {'test.key': 'setup-ok'}
🔍 关键点：
InMemorySpanExporter 将 Span 保存在内存列表中，不发送到任何网络端点。这使得我们可以在毫秒级完成链路数据的断言，非常适合单元测试和本地调试。
2.5 组件交互关系
下图展示了验证脚本中各组件之间的数据流关系：
2.6 常见问题与排查
- pip install 失败： 尝试使用国内镜像源，如
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple opentelemetry-sdk otel-mock。 - 找不到模块 otel_mock： 确认虚拟环境已激活，且
pip list中能看到otel-mock。注意包名是otel-mock，导入时使用下划线otel_mock。 - 断言失败： 检查
get_finished_spans()返回的列表长度。如果为 0，说明 Span 未被导出，请确认SimpleSpanProcessor已正确挂载到TracerProvider。 - Windows 路径问题： 如果使用原生 Windows CMD，激活脚本路径为
.venv\Scripts\activate.bat；PowerShell 用户请先执行Set-ExecutionPolicy Unrestricted -Scope Process以允许执行脚本。
⚠️ 注意： 本课程所有实验都基于
otel-mock 的内存导出模式。请勿在生产环境中使用 InMemorySpanExporter，它仅用于测试和本地验证。生产环境应使用 OTLPSpanExporter 将数据发送到 Collector。