Skip to content

Fastrace Rust SDK

Fastrace is the Rust tracing SDK in Beacon, based on fast/fastrace. It sends traces to DataKit over OTLP/gRPC, then forwards them to Guance.

Applications must add dependencies, instrument code manually, and initialize a reporter. Configure dependencies using the source from the Beacon Fastrace project; crates with the same names on crates.io belong to the upstream distribution.

Requirements

  • Install a supported Rust toolchain and Cargo, with access to GitHub and dependency sources. See the installation guide for runtime requirements.
  • Enable the DataKit OpenTelemetry gRPC receiver using Common configuration. The following example uses http://127.0.0.1:4317.

Install dependencies

Select a source distribution from Fastrace Releases and configure dependencies in your application's Cargo.toml using the corresponding installation guide. The example below requires:

  • fastrace with the enable feature.
  • fastrace-opentelemetry to pass Fastrace spans to the OpenTelemetry exporter.
  • opentelemetry and opentelemetry_sdk with the trace feature.
  • opentelemetry-otlp with the trace and grpc-tonic features.
  • tokio with the rt-multi-thread and macros features.

Applications must enable the enable feature to collect spans; libraries should leave that decision to the application. Use the same Git tag for every Fastrace crate, including fastrace-futures if needed. Commit the generated Cargo.lock, use cargo build --locked for subsequent builds, and check cargo tree for mixed Git and crates.io Fastrace sources. Span types from different sources have different Cargo identities.

Instrument and report

Save the following code as src/main.rs. It creates an exporter inside the Tokio runtime, sets the service name to fastrace-demo, and reports two spans before exiting:

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));
}

Run cargo run, then open APM > Traces in Guance and filter by service=fastrace-demo. Confirm that the request root span and the handle_request function span are present. The macro uses the full function path as the default span name.

Close root spans before calling fastrace::flush() so the final trace is available for export. Normal process exit does not prove backend ingestion. This example sets the receiver and service name explicitly in code; the environment variables in Common configuration do not replace SDK initialization. In a container, 127.0.0.1 refers to the container itself. Use a DataKit address reachable from the application.

Cross-service context and verification

Trace IDs are 128-bit values (32 hexadecimal characters); span IDs are 64-bit values (16 hexadecimal characters). For cross-service HTTP calls, explicitly inject and extract traceparent and tracestate using W3CTraceContext. The SDK does not automatically instrument HTTP boundaries or retain arbitrary tracestate through internal spans.

The acceptance guide provides a two-process HTTP example and a backend verifier. Run from the release source directory:

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

This workflow requires Linux, a Python environment supported by the validation tools, the gRPC receiver above, and the status API at http://127.0.0.1:9529/v1/ping. The initial evidence contains backend_verified: false, meaning backend ingestion has not yet been verified. Follow the guide to query the exact Trace ID and check all five spans, service names, parent relationships, propagated headers, and final delivery before exit.

Distribution and maintenance

Download the source archive, release-manifest.json, and SHA256SUMS from the release page into the same directory. Run sha256sum --check SHA256SUMS before extraction. See the installation guide for source builds, upgrades, and rollback.

This guide validates trace reporting through local DataKit OTLP/gRPC on Linux. It does not cover metrics, logs, other receiver/protocol combinations, or automatic instrumentation. See the SDK documentation for more API details.

Feedback

Is this page helpful?