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로 지정한 뒤 종료 전에 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를 유지하지 않습니다.

검증 가이드는 두 프로세스의 HTTP 예제와 백엔드 검증 도구를 제공합니다. 릴리스 소스 디렉터리에서 실행합니다.

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

Linux, 검증 도구가 지원하는 Python 환경, 위 gRPC 수신기 및 http://127.0.0.1:9529/v1/ping 상태 API가 필요합니다. 초기 결과의 backend_verified: false는 백엔드 저장이 아직 검증되지 않았음을 뜻합니다. 가이드에 따라 정확한 Trace ID를 조회하고 Span 5개, 서비스 이름, 부모·자식 관계, 전파 헤더, 종료 전 마지막 트레이스 전달을 확인합니다.

배포 및 유지 관리¶

릴리스 페이지에서 소스 아카이브, release-manifest.json, SHA256SUMS를 같은 디렉터리에 다운로드합니다. sha256sum --check SHA256SUMS를 실행한 후 압축을 해제합니다. 소스 빌드, 업그레이드 및 롤백은 설치 가이드를 참조하세요.

이 가이드의 검증 범위는 Linux의 로컬 DataKit OTLP/gRPC를 통한 Trace 전송입니다. Metric, Log, 다른 수신기나 프로토콜 조합 및 자동 계측은 포함되지 않습니다. API에 관한 자세한 내용은 SDK 문서를 참조하세요.