📚 课程目录第4章环境搭建

4. 环境搭建：安装 OTel SDK、配置导出器与 Hello World Trace

本章是动手实践的第一站。我们将以 Python 语言为例，完成 OpenTelemetry SDK 的安装、导出器配置，并运行第一条 Hello World Trace。Python 的 OTel SDK 生态成熟、API 简洁，适合快速建立对 Trace 生命周期的直观理解。

语言选择说明：本课程以 Python 为主线演示，但所有概念（Span、TracerProvider、Exporter）在 Java/Go SDK 中完全对应。你可以在课后对照官方文档完成其他语言的等价实现。

4.1 环境准备与 SDK 安装

确保你的开发环境满足以下条件：

依赖项	最低版本	验证命令
Python	3.8+	`python --version`
pip	21.0+	`pip --version`
虚拟环境（推荐）	—	`python -m venv .venv`

激活虚拟环境后，安装核心 SDK 包：

pip install opentelemetry-api \
            opentelemetry-sdk \
            opentelemetry-exporter-otlp-proto-grpc \
            opentelemetry-exporter-console

  包说明：
  opentelemetry-api — 提供 Tracer、Span 等接口定义
opentelemetry-sdk — 提供默认实现（TracerProvider、SpanProcessor 等）
opentelemetry-exporter-otlp-proto-grpc — OTLP gRPC 导出器，用于将数据发送到 Collector
opentelemetry-exporter-console — 控制台导出器，用于调试输出

4.2 导出器配置：Console 与 OTLP

导出器（Exporter）负责将 Span 数据序列化并发送到指定后端。本课程配置两种导出器：

ConsoleSpanExporter：将 Span 以 JSON 格式打印到标准输出，适合开发调试。
OTLPSpanExporter：通过 OTLP 协议（gRPC）将 Span 发送到 OpenTelemetry Collector 或兼容后端。

以下代码展示如何同时配置两种导出器，并通过 BatchSpanProcessor 提升吞吐：

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import ConsoleSpanExporter

# 1. 创建 TracerProvider
provider = TracerProvider()

# 2. 配置 Console 导出器（调试用）
console_exporter = ConsoleSpanExporter()
provider.add_span_processor(BatchSpanProcessor(console_exporter))

# 3. 配置 OTLP 导出器（生产用）
otlp_exporter = OTLPSpanExporter(
    endpoint="http://localhost:4317",  # Collector gRPC 端点
    insecure=True                     # 开发环境允许非 TLS
)
provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

# 4. 设置为全局 TracerProvider
trace.set_tracer_provider(provider)

# 5. 获取 Tracer 实例
tracer = trace.get_tracer(__name__)

注意：BatchSpanProcessor 会缓存 Span 并在达到阈值（默认 512 条或 5 秒）后批量导出。如果希望每条 Span 立即导出，可使用 SimpleSpanProcessor，但生产环境不推荐。

4.3 Hello World Trace 实现

现在编写第一个 Trace，它包含一个根 Span 和一个子 Span，模拟“处理请求”的简单流程：

with tracer.start_as_current_span("hello-world-root") as root_span:
    root_span.set_attribute("service.name", "otel-demo")
    root_span.set_attribute("version", "1.0.0")

    # 模拟业务逻辑：创建子 Span
    with tracer.start_as_current_span("process-data") as child_span:
        child_span.set_attribute("data.size", 1024)
        child_span.add_event("data.loaded", {"source": "memory"})

        # 模拟耗时操作
        import time
        time.sleep(0.1)

    root_span.set_attribute("result", "success")

运行脚本后，控制台将输出类似以下的 JSON 结构（已简化）：

{
    "name": "hello-world-root",
    "context": {"trace_id": "0x...", "span_id": "0x..."},
    "parent_span_id": null,
    "attributes": {
        "service.name": "otel-demo",
        "version": "1.0.0",
        "result": "success"
    },
    "events": [],
    "status": {"status_code": "UNSET"}
}
{
    "name": "process-data",
    "context": {"trace_id": "0x...", "span_id": "0x..."},
    "parent_span_id": "0x...",
    "attributes": {"data.size": 1024},
    "events": [
        {"name": "data.loaded", "attributes": {"source": "memory"}, "timestamp": ...}
    ],
    "status": {"status_code": "UNSET"}
}

4.4 Trace 数据流架构

下图展示了从 SDK 埋点到导出器输出的完整数据流：

4.5 验证与常见问题

验证步骤	预期结果	失败排查
运行脚本后控制台输出	两条 JSON 格式的 Span 记录	检查 `ConsoleSpanExporter` 是否已添加到 Processor
OTLP 导出器连接 Collector	Collector 日志显示接收 Trace 数据	确认 endpoint 地址正确，Collector 已启动且端口开放
Span 层级关系	子 Span 的 `parent_span_id` 指向根 Span	检查 `start_as_current_span` 上下文传播是否正确

快速验证命令：启动一个简单的 OTel Collector 接收端：
docker run -p 4317:4317 otel/opentelemetry-collector:latest
然后运行你的 Python 脚本，Collector 日志会显示 TracesExporter 接收到的 Span 数量。

至此，你已经完成了 OTel SDK 的安装、双导出器配置，并成功运行了第一条 Hello World Trace。这是后续所有埋点实践的基础——无论是手动埋点、自动插装还是自定义扩展，都建立在这个核心数据流之上。