Fastrace Rust SDK¶

Fastrace は fast/fastrace をベースとする Beacon の Rust トレーシング SDK です。OTLP/gRPC で DataKit に Trace を送信し、Guanceに転送します。

アプリケーションに依存関係を追加し、手動で計装してレポーターを初期化する必要があります。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 を有効にします。

Span の収集にはアプリケーション側で enable feature を有効にします。ライブラリは収集の有効化をアプリケーションに委ねてください。必要に応じて使う fastrace-futures を含め、すべての Fastrace crate に同じ Git tag を指定します。生成した Cargo.lock をコミットし、その後は cargo build --locked でビルドしてください。Git と crates.io の Fastrace を混在させると Span 型の Cargo 上の識別が異なるため、cargo tree で確認します。

計装と送信¶

次のコードを src/main.rs に保存します。Tokio runtime 内でエクスポーターを作成し、サービス名を fastrace-demo に設定して、終了前に 2 つの 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 を実行し、Guanceの「APM > トレース」で service=fastrace-demo を検索して、request のルート Span と handle_request 関数の Span を確認します。マクロの既定の Span 名は関数の完全なパスです。

最後のトレースを送信できるよう、ルート Span を終了してから fastrace::flush() を呼び出してください。プロセスの正常終了だけではバックエンドへの保存を確認できません。この例では受信先とサービス名をコード内で設定します。共通設定の環境変数は SDK 初期化の代わりにはなりません。コンテナの 127.0.0.1 はそのコンテナ自身を指すため、到達可能な DataKit アドレスに変更してください。

サービス間のコンテキストと検証¶

Trace ID は 128 ビット（16 進数 32 文字）、Span ID は 64 ビット（16 進数 16 文字）です。サービス間 HTTP 通信では W3CTraceContext で traceparent と tracestate を明示的に注入・抽出します。SDK は HTTP 境界を自動計装せず、内部 Span を介して任意の tracestate を保持することもありません。

検証ガイドには 2 プロセスの 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 を検索し、5 つの Span、サービス名、親子関係、伝播ヘッダー、終了前の最終トレースの送信を確認してください。

配布と保守¶

リリースページからソースアーカイブ、release-manifest.json、SHA256SUMS を同じディレクトリにダウンロードし、展開前に sha256sum --check SHA256SUMS を実行します。ソースビルド、更新、ロールバックはインストールガイドを参照してください。

このガイドの検証対象は Linux 上のローカル DataKit OTLP/gRPC 経由の Trace 送信です。Metric、Log、その他の受信先・プロトコルの組み合わせ、自動計装は対象外です。API の詳細は SDK ドキュメントを参照してください。