{"id":13671970,"url":"https://github.com/apache/skywalking-rust","last_synced_at":"2025-04-02T13:02:37.896Z","repository":{"id":37984236,"uuid":"243689974","full_name":"apache/skywalking-rust","owner":"apache","description":"Apache SkyWalking Rust Agent","archived":false,"fork":false,"pushed_at":"2024-01-10T10:48:51.000Z","size":240,"stargazers_count":70,"open_issues_count":1,"forks_count":19,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-03-26T07:09:01.748Z","etag":null,"topics":["apm","dapper","distributed-tracing","logging","metrics","observability","rust","service-mesh","skywalking"],"latest_commit_sha":null,"homepage":"https://skywalking.apache.org/","language":"Rust","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-02-28T06:01:19.000Z","updated_at":"2025-03-07T18:58:39.000Z","dependencies_parsed_at":"2024-01-10T11:52:30.775Z","dependency_job_id":"5517272f-4051-4616-9912-7b47a14f8946","html_url":"https://github.com/apache/skywalking-rust","commit_stats":{"total_commits":72,"total_committers":8,"mean_commits":9.0,"dds":0.625,"last_synced_commit":"359ad93c4fe3a82cc417190c4030942ac8a74b00"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fskywalking-rust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fskywalking-rust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fskywalking-rust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fskywalking-rust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/skywalking-rust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246403897,"owners_count":20771526,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apm","dapper","distributed-tracing","logging","metrics","observability","rust","service-mesh","skywalking"],"created_at":"2024-08-02T09:01:23.238Z","updated_at":"2025-04-02T13:02:37.850Z","avatar_url":"https://github.com/apache.png","language":"Rust","readme":"Apache SkyWalking Rust Agent\n==========\n\n\u003cimg src=\"http://skywalking.apache.org/assets/logo.svg\" alt=\"Sky Walking logo\" height=\"90px\" align=\"right\" /\u003e\n\n[![Twitter Follow](https://img.shields.io/twitter/follow/asfskywalking.svg?style=for-the-badge\u0026label=Follow\u0026logo=twitter)](https://twitter.com/AsfSkyWalking)\n\n[![Crates](https://img.shields.io/badge/skywalking-crates.io-blue)](https://crates.io/crates/skywalking)\n![CI](https://github.com/apache/skywalking-rust/workflows/CI/badge.svg?branch=master)\n\n[**SkyWalking**](https://github.com/apache/skywalking) Rust Agent provides observability capability for Rust App and\nLibrary, including tracing, metrics, topology map for distributed system and alert. It uses SkyWalking native formats\nand core concepts to keep best compatibility and performance.\n\n# Concepts\n\nAll concepts are from the official SkyWalking definitions.\n\n## Tracing\n\n### Span\n\nSpan is an important and common concept in distributed tracing system. Learn Span from Google Dapper Paper. For better\nperformance, we extend the span into 3 kinds.\n\n1. EntrySpan EntrySpan represents a service provider, also the endpoint of server side. As an APM system, we are\n   targeting the application servers. So almost all the services and MQ-consumer are EntrySpan(s).\n2. LocalSpan LocalSpan represents a normal Java method, which does not relate to remote service, neither a MQ\n   producer/consumer nor a service(e.g. HTTP service) provider/consumer.\n3. ExitSpan ExitSpan represents a client of service or MQ-producer, as named as LeafSpan at early age of SkyWalking.\n   e.g. accessing DB by JDBC, reading Redis/Memcached are cataloged an ExitSpan.\n\nTag and Log are similar attributes of the span.\n\n- Tag is a key:value pair to indicate the attribute with a string value.\n- Log is heavier than tag, with one timestamp and multiple key:value pairs. Log represents an event, typically an error\n  happens.\n\n### TracingContext\n\nTracingContext is the context of the tracing process. Span should only be created through context, and be archived into\nthe context after the span finished.\n\n## Logging\n\n### LogRecord\n\nLogRecord is the simple builder for the LogData, which is the Log format of Skywalking.\n\n## Metrics\n\n### Meter\n\n- **Counter** API represents a single monotonically increasing counter which automatically collects data and reports to the backend.\n- **Gauge** API represents a single numerical value.\n- **Histogram** API represents a summary sample observations with customized buckets.\n\n## Management\n\nReporting the extra information of the instance.\n\n### Report instance properties\n\nThe method `insert_os_info` of `skywalking::management::instance::Properties` will insert the predefined os info.\nIn addition, you can use `insert`, `update`, and `remove` to customize your instance information.\n\nThe predefined os info:\n\n| Key                      | Value                          |\n| ------------------------ | ------------------------------ |\n| hostname                 | The hostname of os.            |\n| ipv4 (probably multiple) | The ipv4 addresses of network. |\n| language                 | rust                           |\n| OS Name                  | Linux / Windows / Mac OS X     |\n| Process No.              | The ID of Process.             |\n\n### Keep alive\n\nKeep the instance alive in the backend analysis.\nOnly recommend to do separate keepAlive report when no trace and metrics needs to be reported.\nOtherwise, it is duplicated.\n\n# Example\n\n```rust, no_run\nuse skywalking::{\n    logging::{logger::Logger, record::{LogRecord, RecordType}},\n    reporter::grpc::GrpcReporter,\n    trace::tracer::Tracer,\n    metrics::{meter::Counter, metricer::Metricer},\n};\nuse std::error::Error;\nuse tokio::signal;\n\nasync fn handle_request(tracer: Tracer, logger: Logger) {\n    let mut ctx = tracer.create_trace_context();\n\n    {\n        // Generate an Entry Span when a request is received.\n        // An Entry Span is generated only once per context.\n        // Assign a variable name to guard the span not to be dropped immediately.\n        let _span = ctx.create_entry_span(\"op1\");\n\n        // Something...\n\n        {\n            // Generates an Exit Span when executing an RPC.\n            let span2 = ctx.create_exit_span(\"op2\", \"remote_peer\");\n\n            // Something...\n\n            // Do logging.\n            logger.log(\n                LogRecord::new()\n                    .add_tag(\"level\", \"INFO\")\n                    .with_tracing_context(\u0026ctx)\n                    .with_span(\u0026span2)\n                    .record_type(RecordType::Text)\n                    .content(\"Something...\")\n            );\n\n            // Auto close span2 when dropped.\n        }\n\n        // Auto close span when dropped.\n    }\n\n    // Auto report ctx when dropped.\n}\n\nasync fn handle_metric(mut metricer: Metricer) {\n    let counter = metricer.register(\n        Counter::new(\"instance_trace_count\")\n            .add_label(\"region\", \"us-west\")\n            .add_label(\"az\", \"az-1\"),\n    );\n\n    metricer.boot().await;\n\n    counter.increment(10.);\n}\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn Error\u003e\u003e {\n    // Connect to skywalking oap server.\n    let reporter = GrpcReporter::connect(\"http://0.0.0.0:11800\").await?;\n    // Optional authentication, based on backend setting.\n    let reporter = reporter.with_authentication(\"\u003cTOKEN\u003e\");\n\n    // Spawn the reporting in background, with listening the graceful shutdown signal.\n    let handle = reporter\n        .reporting()\n        .await\n        .with_graceful_shutdown(async move {\n            signal::ctrl_c().await.expect(\"failed to listen for event\");\n        })\n        .spawn();\n\n    let tracer = Tracer::new(\"service\", \"instance\", reporter.clone());\n    let logger = Logger::new(\"service\", \"instance\", reporter.clone());\n    let metricer = Metricer::new(\"service\", \"instance\", reporter);\n\n    handle_metric(metricer).await;\n\n    handle_request(tracer, logger).await;\n\n    handle.await?;\n\n    Ok(())\n}\n```\n\n# Advanced APIs\n\n## Async Span APIs\n\n`Span::prepare_for_async` designed for async use cases.\nWhen tags, logs, and attributes (including end time) of the span need to be set in another\nthread or coroutine.\n\n`TracingContext::wait` wait for all `AsyncSpan` finished.\n\n```rust\nuse skywalking::{\n    trace::tracer::Tracer,\n    trace::span::HandleSpanObject,\n};\n\nasync fn handle(tracer: Tracer) {\n    let mut ctx = tracer.create_trace_context();\n\n    {\n        let span = ctx.create_entry_span(\"op1\");\n\n        // Create AsyncSpan and drop span.\n        // Internally, span will occupy the position of finalized span stack.\n        let mut async_span = span.prepare_for_async();\n\n        // Start async route, catch async_span with `move` keyword.\n        tokio::spawn(async move {\n\n            async_span.add_tag(\"foo\", \"bar\");\n\n            // Something...\n\n            // async_span will drop here, submit modifications to finalized spans stack.\n        });\n    }\n\n    // Wait for all `AsyncSpan` finished.\n    ctx.wait();\n}\n```\n\n# Advanced Reporter\n\nThe advanced report provides an alternative way to submit the agent collected data to the backend.\n\n## kafka reporter\n\nThe Kafka reporter plugin support report traces, metrics, logs, instance properties to Kafka cluster.\n\nMake sure the feature `kafka-reporter` is enabled.\n\n```rust\n#[cfg(feature = \"kafka-reporter\")]\nmod example {\n    use skywalking::reporter::Report;\n    use skywalking::reporter::kafka::{KafkaReportBuilder, KafkaReporter, RDKafkaClientConfig};\n\n    async fn do_something(reporter: \u0026impl Report) {\n        // ....\n    }\n\n    async fn foo() {\n        let mut client_config = RDKafkaClientConfig::new();\n        client_config\n            .set(\"bootstrap.servers\", \"broker:9092\")\n            .set(\"message.timeout.ms\", \"6000\");\n\n        let (reporter, reporting) = KafkaReportBuilder::new(client_config).build().await.unwrap();\n        let handle = reporting.spawn();\n\n        do_something(\u0026reporter);\n\n        handle.await.unwrap();\n    }\n}\n```\n\n# How to compile?\n\nIf you have `skywalking-(VERSION).crate`, you can unpack it with the way as follows:\n\n```shell\ntar -xvzf skywalking-(VERSION).crate\n```\n\nUsing `cargo build` generates a library. If you'd like to verify the behavior, we recommend to\nuse `cargo run --example simple_trace_report`\nwhich outputs executable, then run it.\n\n## NOTICE\n\nThis crate automatically generates protobuf related code, which requires `protoc` before compile.\n\nPlease choose one of the ways to install `protoc`.\n\n1. Using your OS package manager.\n\n   For Debian-base system:\n\n   ```shell\n   sudo apt install protobuf-compiler\n   ```\n\n   For MacOS:\n\n   ```shell\n   brew install protobuf\n   ```\n\n2. Auto compile `protoc` in the crate build script, just by adding the feature `vendored` in the `Cargo.toml`:\n\n   ```shell\n   cargo add skywalking --features vendored\n   ```\n\n3. Build from [source](https://github.com/protocolbuffers/protobuf). If `protc` isn't install inside $PATH, the env value `PROTOC` should be set.\n\n   ```shell\n   PROTOC=/the/path/of/protoc\n   ```\n\nFor details, please refer to [prost-build:sourcing-protoc](https://docs.rs/prost-build/latest/prost_build/index.html#sourcing-protoc).\n\n# Release\n\nThe SkyWalking committer(PMC included) could follow [this doc](https://github.com/apache/skywalking-rust/blob/master/Release-guide.md) to release an official version.\n\n# License\n\nApache 2.0\n","funding_links":[],"categories":["Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fskywalking-rust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fskywalking-rust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fskywalking-rust/lists"}