Fastrace Rust SDK¶

Fastrace 是 Beacon 中基于 fast/fastrace 的 Rust 链路追踪 SDK，通过 OTLP/gRPC 将 Trace 上报到 DataKit，再发送至观测云。

Fastrace 需要在应用中添加依赖、手动插桩并初始化上报器。请使用 Beacon Fastrace 项目提供的源码配置依赖，crates.io 上的同名 crate 属于上游发行包。

前置条件¶

安装项目支持的 Rust 工具链和 Cargo，并确保可访问 GitHub 及依赖源。运行环境要求见安装指南。
按公共配置开启 DataKit OpenTelemetry gRPC 接收端，以下示例使用 http://127.0.0.1:4317。

安装依赖¶

从 Fastrace 发布页面选择发行源码，按照对应的安装指南在应用的 Cargo.toml 中配置依赖。下方示例需要：

fastrace，开启 enable feature。
fastrace-opentelemetry，将 Fastrace Span 转交给 OpenTelemetry 导出器。
opentelemetry、opentelemetry_sdk，开启 trace feature。
opentelemetry-otlp，开启 trace 和 grpc-tonic feature。
tokio，开启 rt-multi-thread 和 macros feature。

应用必须开启 enable feature 才会采集 Span，库应由最终应用决定是否启用采集。所有 Fastrace crate（包括按需使用的 fastrace-futures）应使用同一 Git tag。提交生成的 Cargo.lock，后续使用 cargo build --locked 构建，并通过 cargo tree 检查是否混用了 Git 和 crates.io 的 Fastrace；不同来源的 Span 类型具有不同的 Cargo 身份。

插桩与上报¶

将以下代码保存为 src/main.rs。示例在 Tokio runtime 中创建导出器，设置服务名 fastrace-demo，并在退出前上报两个 Span：

use std::borrow::Cow;
use std::error::Error;
use std::time::Duration;

use fastrace::collector::Config;
use fastrace::prelude::*;
use opentelemetry_otlp::WithExportConfig;

#[tokio::main(flavor = "multi_thread")]
async fn main() -> Result<(), Box<dyn Error>> {
    let exporter = opentelemetry_otlp::SpanExporter::builder()
        .with_tonic()
        .with_endpoint("http://127.0.0.1:4317")
        .with_timeout(Duration::from_secs(5))
        .build()?;
    let reporter = fastrace_opentelemetry::OpenTelemetryReporter::new(
        exporter,
        Cow::Owned(
            opentelemetry_sdk::Resource::builder()
                .with_service_name("fastrace-demo")
                .build(),
        ),
        opentelemetry::InstrumentationScope::builder("fastrace-example").build(),
    );
    fastrace::set_reporter(reporter, Config::default());

    {
        let root = Span::root("request", SpanContext::random());
        let _guard = root.set_local_parent();
        handle_request();
    }

    fastrace::flush();
    Ok(())
}

#[fastrace::trace]
fn handle_request() {
    std::thread::sleep(Duration::from_millis(10));
}

运行 cargo run 后，在观测云「应用性能监测 > 链路」中按 service=fastrace-demo 筛选，确认存在 request 根 Span 和 handle_request 函数 Span。宏默认使用完整函数路径作为 Span 名称。

应先结束根 Span，再调用 fastrace::flush()，以便最后一条链路可被导出。进程正常退出不代表后端已经入库。本例在代码中显式配置接收地址和服务名，公共配置中的环境变量不能替代 SDK 初始化。容器中的 127.0.0.1 指向容器自身，应改为应用可访问的 DataKit 地址。

跨服务链路与验证¶

Trace ID 为 128 位（32 个十六进制字符），Span ID 为 64 位（16 个十六进制字符）。跨服务 HTTP 调用需使用 W3CTraceContext 显式注入和提取 traceparent、tracestate。SDK 不自动插桩 HTTP 边界，也不会通过内部 Span 保留任意 tracestate。

验收指南提供双进程 HTTP 示例和后端验证器。在发行源码目录执行：

python3 beacon/validation/otlp/run.py --output /tmp/fastrace-datakit-acceptance

该流程需要 Linux、验证工具支持的 Python 环境、上述 gRPC 接收端，以及 http://127.0.0.1:9529/v1/ping 状态接口。初始证据中的 backend_verified: false 表示尚未验证后端入库；继续按指南查询精确 Trace ID，核对五个 Span、服务名、父子关系、传播 Header 和退出前最后一条链路的交付。

发行与维护¶

从发布页面下载对应的源码归档、release-manifest.json 和 SHA256SUMS，保存到同一目录后，先执行 sha256sum --check SHA256SUMS 再解压。源码构建、升级和回滚见安装指南。

本指南的验证范围为 Linux 下经本机 DataKit OTLP/gRPC 上报 Trace，不包含 Metric、Log、其他接收端或协议组合，以及自动插桩。更多 API 说明见 SDK 文档。