# trace

**Repository Path**: rippleos/trace

## Basic Information

- **Project Name**: trace
- **Description**: MOSS 分布式追踪模块
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mtrace - 分布式追踪模块

## 概述

mtrace 是 MOSS 中间件的分布式追踪模块，提供 OpenTelemetry 风格的追踪能力，支持跨服务调用链追踪、性能分析和 FoxGlove 可视化集成。

## 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│         (mcom RPC, msomeip, mdiag, etc.)                    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       mtrace                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Tracer     │  │    Span      │  │   Context    │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │  Processor   │  │   Exporter   │  │  Propagator  │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Export Destinations                       │
│     FoxGlove / OTLP / Console / Custom                      │
└─────────────────────────────────────────────────────────────┘
```

### 目录结构

```
moss/trace/
├── CMakeLists.txt
├── include/trace/
│   ├── mtrace.h            # 模块入口
│   ├── types.h             # 类型定义
│   ├── span.h              # Span 定义
│   ├── context.h           # 追踪上下文
│   ├── tracer.h            # Tracer 和 TracerProvider
│   ├── processor.h         # Span 处理器
│   ├── propagator.h        # 上下文传播器
│   ├── exporter.h          # 导出器接口
│   └── foxglove_exporter.h # FoxGlove 导出器
├── src/
│   ├── span.cpp
│   ├── tracer.cpp
│   ├── processor.cpp
│   ├── propagator.cpp
│   └── foxglove_exporter.cpp
└── test/
    └── test_*.cpp
```

## 核心概念

### Trace ID (128-bit)

唯一标识一次完整的追踪链路。

```cpp
struct TraceId {
    uint64_t high;
    uint64_t low;

    static TraceId generate();      // 随机生成
    static TraceId invalid();       // 无效 ID
    bool is_valid() const;
    std::string to_hex() const;     // 32 字符十六进制
    static TraceId from_hex(const std::string& hex);
};
```

### Span ID (64-bit)

标识追踪链路中的单个操作。

```cpp
struct SpanId {
    uint64_t value;

    static SpanId generate();
    static SpanId invalid();
    bool is_valid() const;
    std::string to_hex() const;     // 16 字符十六进制
    static SpanId from_hex(const std::string& hex);
};
```

### Span Kind

| 类型 | 值 | 描述 |
|------|-----|------|
| INTERNAL | 0 | 内部操作 |
| SERVER | 1 | 服务端处理请求 |
| CLIENT | 2 | 客户端发起请求 |
| PRODUCER | 3 | 消息生产者 |
| CONSUMER | 4 | 消息消费者 |

### Span Status

| 状态 | 值 | 描述 |
|------|-----|------|
| UNSET | 0 | 未设置 |
| OK | 1 | 成功 |
| ERROR | 2 | 错误 |

## 核心组件

### 1. Span - 追踪单元

```cpp
class Span : public std::enable_shared_from_this<Span> {
public:
    using Ptr = std::shared_ptr<Span>;

    // 生命周期
    void end();
    void end(uint64_t timestamp_ns);
    bool is_ended() const;

    // 属性
    void set_attribute(const std::string& key, const AttributeValue& value);
    void set_attributes(const std::map<std::string, AttributeValue>& attrs);

    // 状态
    void set_status(SpanStatus status);
    void set_status(SpanStatus status, const std::string& description);

    // 事件
    void add_event(const std::string& name);
    void add_event(const std::string& name,
                   const std::map<std::string, AttributeValue>& attrs);

    // 异常记录
    void record_exception(const std::exception& e);
    void record_exception(const std::string& type, const std::string& message);

    // 导出
    SpanData to_data() const;

    // 激活/停用
    void activate();
    void deactivate();
};
```

### 2. Tracer - 追踪器

```cpp
class Tracer {
public:
    // 创建 Span
    Span::Ptr start_span(const std::string& span_name);
    Span::Ptr start_span(const std::string& span_name, SpanKind kind);
    Span::Ptr start_span(const std::string& span_name, const TraceContext& parent_ctx);

    // 根 Span (无父级)
    Span::Ptr start_root_span(const std::string& span_name);

    // 激活 Span (自动设置当前上下文)
    Span::Ptr start_active_span(const std::string& span_name);

    // 当前上下文
    Span::Ptr current_span() const;
    TraceContext current_context() const;
};
```

### 3. TracerProvider - 追踪提供者

```cpp
struct TracerConfig {
    std::string service_name;
    std::string service_version{"1.0.0"};
    bool enable_console_exporter{true};
    bool enable_otlp_exporter{false};
    std::string otlp_endpoint{"http://localhost:4317"};
    uint32_t batch_export_timeout_ms{5000};
    uint32_t batch_export_max_spans{512};
    double sample_rate{1.0};
};

class TracerProvider {
public:
    explicit TracerProvider(const TracerConfig& config);

    Tracer* get_tracer(const std::string& name);

    bool force_flush(uint64_t timeout_ms);
    bool shutdown(uint64_t timeout_ms);

    void set_processor(std::shared_ptr<SpanProcessor> processor);
    void set_propagator(std::shared_ptr<Propagator> propagator);

    // 全局实例
    static TracerProvider* global_instance();
    static void set_global_instance(std::unique_ptr<TracerProvider> provider);
};
```

### 4. FoxGloveExporter - FoxGlove 导出器

```cpp
class FoxGloveExporter : public SpanExporter {
public:
    // 从 mvisual StudioBridge 构造 (推荐)
    explicit FoxGloveExporter(std::shared_ptr<mvisual::StudioBridge> bridge,
                              const std::string& topic = "/traces");

    // SpanExporter 接口
    bool export_spans(const std::vector<SpanData>& spans) override;
    bool force_flush(uint64_t timeout_ms) override;
    bool shutdown(uint64_t timeout_ms) override;
};
```

## 使用示例

### 初始化追踪

```cpp
#include <trace/mtrace.h>

using namespace moss::mtrace;

// 初始化全局 TracerProvider
TracerConfig config;
config.service_name = "perception-node";
config.service_version = "1.0.0";
config.enable_console_exporter = true;
config.sample_rate = 1.0;

init(config);
```

### 创建 Span

```cpp
// 方式 1: 使用全局函数
Span::Ptr span = start_span("process_frame");
// ... 执行操作 ...
span->end();

// 方式 2: 使用 Tracer
Tracer* tracer = get_tracer("perception");
Span::Ptr span = tracer->start_span("detect_objects", SpanKind::INTERNAL);

// 方式 3: 使用宏 (自动作用域)
{
    MTRACE_SPAN("process_frame");
    // span 在作用域结束时自动 end
}
```

### 设置属性和事件

```cpp
Span::Ptr span = start_span("detect_objects");

// 设置属性
span->set_attribute("frame_id", int64_t(12345));
span->set_attribute("camera_id", std::string("front_left"));
span->set_attribute("confidence", 0.95);

// 添加事件
span->add_event("model_inference_start");
// ... 推理 ...
span->add_event("model_inference_end");

// 设置状态
span->set_status(SpanStatus::OK);

span->end();
```

### 跨服务追踪

```cpp
// 服务端: 从请求提取上下文
Tracer* tracer = get_tracer("service");

// 从 HTTP/gRPC 头提取
TraceContext ctx = tracer->provider()->propagator()->extract(headers);

// 创建子 Span
Span::Ptr span = tracer->start_span("handle_request", SpanKind::SERVER, ctx);

// 客户端: 向请求注入上下文
Span::Ptr client_span = tracer->start_span("call_remote", SpanKind::CLIENT);
TraceContext ctx_to_inject = client_span->context();
tracer->provider()->propagator()->inject(ctx_to_inject, headers);
```

### FoxGlove 集成

```cpp
#include <trace/foxglove_exporter.h>
#include <visual/bridge.h>

// 创建 FoxGlove bridge
auto bridge = std::make_shared<mvisual::StudioBridge>();
bridge->start(8765);

// 创建 FoxGlove 导出器
auto exporter = std::make_shared<FoxGloveExporter>(bridge, "/traces");

// 配置 TracerProvider
TracerConfig config;
config.service_name = "moss-node";
config.enable_console_exporter = false;

auto provider = std::make_unique<TracerProvider>(config);
provider->set_processor(std::make_shared<BatchSpanProcessor>(exporter));
TracerProvider::set_global_instance(std::move(provider));

// 在 FoxGlove Studio 中查看:
// 1. 打开 https://app.foxglove.dev
// 2. 连接 ws://localhost:8765
// 3. 添加 "Raw Messages" 面板查看 /traces
```

### 异常记录

```cpp
Span::Ptr span = start_span("risky_operation");

try {
    // 可能抛出异常的操作
    risky_function();
    span->set_status(SpanStatus::OK);
} catch (const std::exception& e) {
    span->record_exception(e);
    span->set_status(SpanStatus::ERROR, e.what());
}

span->end();
```

## 上下文传播

### W3C Trace Context

支持 W3C Trace Context 标准格式：

```
traceparent: 00-{trace-id}-{parent-id}-{flags}
tracestate: vendor=value,vendor2=value2
```

示例：

```cpp
// 提取
std::map<std::string, std::string> headers = {
    {"traceparent", "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"}
};

TraceContext ctx;
ctx.trace_id = TraceId::from_hex("4bf92f3577b34da6a3ce929d0e0e4736");
ctx.span_id = SpanId::from_hex("00f067aa0ba902b7");
ctx.trace_flags = 0x01;

// 注入
std::map<std::string, std::string> outgoing_headers;
propagator->inject(ctx, outgoing_headers);
```

## 属性类型

```cpp
using AttributeValue = std::variant<
    bool,
    int64_t,
    uint64_t,
    double,
    std::string,
    std::vector<bool>,
    std::vector<int64_t>,
    std::vector<uint64_t>,
    std::vector<double>,
    std::vector<std::string>
>;
```

## 依赖关系

```yaml
mtrace:
  depends_on:
    - mruntime  # Clock, 工具类
    - mlog      # 日志
  optional:
    - mvisual   # FoxGlove 集成
```

## 测试覆盖

| 测试文件 | 覆盖范围 |
|----------|----------|
| test_types.cpp | TraceId/SpanId 生成和解析 |
| test_span.cpp | Span 生命周期和属性 |
| test_context.cpp | 上下文管理 |
| test_propagator.cpp | W3C 上下文传播 |
| test_tracer.cpp | Tracer 和 TracerProvider |
| foxglove_demo.cpp | FoxGlove 集成演示 |

## 里程碑

| 里程碑 | 内容 | 状态 |
|--------|------|------|
| mtrace-ms1 | 核心实现 | ✅ 完成 |
| mtrace-ms2 | FoxGlove 集成 | ✅ 完成 |

## 参考

- OpenTelemetry Specification: https://opentelemetry.io/docs/reference/specification/
- W3C Trace Context: https://www.w3.org/TR/trace-context/
- FoxGlove Studio: https://foxglove.dev/