SkyWalking Rust Agent provides observability capability for Rust App and Library, including tracing, metrics, topology map for distributed system and alert. It uses SkyWalking native formats and core concepts to keep best compatibility and performance.
All concepts are from the official SkyWalking definitions.
Span is an important and common concept in distributed tracing system. Learn Span from Google Dapper Paper. For better performance, we extend the span into 3 kinds.
Tag and Log are similar attributes of the span.
TracingContext is the context of the tracing process. Span should only be created through context, and be archived into the context after the span finished.
LogRecord is the simple builder for the LogData, which is the Log format of Skywalking.
Reporting the extra information of the instance.
The method insert_os_info
of skywalking::management::instance::Properties
will insert the predefined os info. In addition, you can use insert
, update
, and remove
to customize your instance information.
The predefined os info:
Key | Value |
---|---|
hostname | The hostname of os. |
ipv4 (probably multiple) | The ipv4 addresses of network. |
language | rust |
OS Name | Linux / Windows / Mac OS X |
Process No. | The ID of Process. |
Keep the instance alive in the backend analysis. Only recommend to do separate keepAlive report when no trace and metrics needs to be reported. Otherwise, it is duplicated.
use skywalking::{ logging::{logger::Logger, record::{LogRecord, RecordType}}, reporter::grpc::GrpcReporter, trace::tracer::Tracer, metrics::{meter::Counter, metricer::Metricer}, }; use std::error::Error; use tokio::signal; async fn handle_request(tracer: Tracer, logger: Logger) { let mut ctx = tracer.create_trace_context(); { // Generate an Entry Span when a request is received. // An Entry Span is generated only once per context. // Assign a variable name to guard the span not to be dropped immediately. let _span = ctx.create_entry_span("op1"); // Something... { // Generates an Exit Span when executing an RPC. let span2 = ctx.create_exit_span("op2", "remote_peer"); // Something... // Do logging. logger.log( LogRecord::new() .add_tag("level", "INFO") .with_tracing_context(&ctx) .with_span(&span2) .record_type(RecordType::Text) .content("Something...") ); // Auto close span2 when dropped. } // Auto close span when dropped. } // Auto report ctx when dropped. } async fn handle_metric(mut metricer: Metricer) { let counter = metricer.register( Counter::new("instance_trace_count") .add_label("region", "us-west") .add_label("az", "az-1"), ); metricer.boot().await; counter.increment(10.); } #[tokio::main] async fn main() -> Result<(), Box<dyn Error>> { // Connect to skywalking oap server. let reporter = GrpcReporter::connect("http://0.0.0.0:11800").await?; // Optional authentication, based on backend setting. let reporter = reporter.with_authentication("<TOKEN>"); // Spawn the reporting in background, with listening the graceful shutdown signal. let handle = reporter .reporting() .await .with_graceful_shutdown(async move { signal::ctrl_c().await.expect("failed to listen for event"); }) .spawn(); let tracer = Tracer::new("service", "instance", reporter.clone()); let logger = Logger::new("service", "instance", reporter.clone()); let metricer = Metricer::new("service", "instance", reporter); handle_metric(metricer).await; handle_request(tracer, logger).await; handle.await?; Ok(()) }
Span::prepare_for_async
designed for async use cases. When tags, logs, and attributes (including end time) of the span need to be set in another thread or coroutine.
TracingContext::wait
wait for all AsyncSpan
finished.
use skywalking::{ trace::tracer::Tracer, trace::span::HandleSpanObject, }; async fn handle(tracer: Tracer) { let mut ctx = tracer.create_trace_context(); { let span = ctx.create_entry_span("op1"); // Create AsyncSpan and drop span. // Internally, span will occupy the position of finalized span stack. let mut async_span = span.prepare_for_async(); // Start async route, catch async_span with `move` keyword. tokio::spawn(async move { async_span.add_tag("foo", "bar"); // Something... // async_span will drop here, submit modifications to finalized spans stack. }); } // Wait for all `AsyncSpan` finished. ctx.wait(); }
The advanced report provides an alternative way to submit the agent collected data to the backend.
The Kafka reporter plugin support report traces, metrics, logs, instance properties to Kafka cluster.
Make sure the feature kafka-reporter
is enabled.
#[cfg(feature = "kafka-reporter")] mod example { use skywalking::reporter::Report; use skywalking::reporter::kafka::{KafkaReportBuilder, KafkaReporter, RDKafkaClientConfig}; async fn do_something(reporter: &impl Report) { // .... } async fn foo() { let mut client_config = RDKafkaClientConfig::new(); client_config .set("bootstrap.servers", "broker:9092") .set("message.timeout.ms", "6000"); let (reporter, reporting) = KafkaReportBuilder::new(client_config).build().await.unwrap(); let handle = reporting.spawn(); do_something(&reporter); handle.await.unwrap(); } }
If you have skywalking-(VERSION).crate
, you can unpack it with the way as follows:
tar -xvzf skywalking-(VERSION).crate
Using cargo build
generates a library. If you'd like to verify the behavior, we recommend to use cargo run --example simple_trace_report
which outputs executable, then run it.
This crate automatically generates protobuf related code, which requires protoc
before compile.
Please choose one of the ways to install protoc
.
Using your OS package manager.
For Debian-base system:
sudo apt install protobuf-compiler
For MacOS:
brew install protobuf
Auto compile protoc
in the crate build script, just by adding the feature vendored
in the Cargo.toml
:
cargo add skywalking --features vendored
Build from source. If protc
isn't install inside $PATH, the env value PROTOC
should be set.
PROTOC=/the/path/of/protoc
For details, please refer to prost-build:sourcing-protoc.
The SkyWalking committer(PMC included) could follow this doc to release an official version.
Apache 2.0