From 5f4d6e6008488c4ce0eb138b2b445a99044b092e Mon Sep 17 00:00:00 2001 From: Tim Kuehn Date: Wed, 14 Apr 2021 15:53:36 -0700 Subject: [PATCH] Prepare release of v0.26.0 --- README.md | 13 ++++--- RELEASES.md | 77 +++++++++++++++++++++++++++++++++++++- example-service/Cargo.toml | 4 +- plugins/Cargo.toml | 2 +- tarpc/Cargo.toml | 4 +- tarpc/src/lib.rs | 12 +++++- 6 files changed, 98 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ebf9223..b9d8591 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,7 @@ process, and no context switching between different languages. Some other features of tarpc: - Pluggable transport: any type impling `Stream + Sink` can be used as a transport to connect the client and server. +- `Send + 'static` optional: if the transport doesn't require it, neither does tarpc! - Cascading cancellation: dropping a request will send a cancellation message to the server. The server will cease any unfinished work on the request, subsequently cancelling any of its own requests, repeating for the entire chain of transitive dependencies. @@ -50,9 +51,9 @@ Some other features of tarpc: requests sent by the server that use the request context will propagate the request deadline. For example, if a server is handling a request with a 10s deadline, does 2s of work, then sends a request to another server, that server will see an 8s deadline. -- Distributed tracing: tarpc is instrumented with [tracing](https://github.com/tokio-rs/tracing) - primitives extended with [OpenTelemetry](https://opentelemetry.io/) traces. Using a compatible - tracing subscriber like +- Distributed tracing: tarpc is instrumented with + [tracing](https://github.com/tokio-rs/tracing) primitives extended with + [OpenTelemetry](https://opentelemetry.io/) traces. Using a compatible tracing subscriber like [Jaeger](https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry-jaeger), each RPC can be traced through the client, server, amd other dependencies downstream of the server. Even for applications not connected to a distributed tracing collector, the @@ -66,7 +67,7 @@ Some other features of tarpc: Add to your `Cargo.toml` dependencies: ```toml -tarpc = "0.25" +tarpc = "0.26" ``` The `tarpc::service` attribute expands to a collection of items that form an rpc service. @@ -80,7 +81,7 @@ your `Cargo.toml`: ```toml futures = "1.0" -tarpc = { version = "0.25", features = ["tokio1"] } +tarpc = { version = "0.26", features = ["tokio1"] } tokio = { version = "1.0", features = ["macros"] } ``` @@ -147,7 +148,7 @@ async fn main() -> io::Result<()> { // WorldClient is generated by the #[tarpc::service] attribute. It has a constructor `new` // that takes a config and any Transport as input. - let mut client = WorldClient::new(client::Config::default(), client_transport).spawn()?; + let mut client = WorldClient::new(client::Config::default(), client_transport).spawn(); // The client has an RPC method for each RPC defined in the annotated trait. It takes the same // args as defined, with the addition of a Context, which is always the first arg. The Context diff --git a/RELEASES.md b/RELEASES.md index 714cb64..11c2106 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -1,3 +1,78 @@ +## 0.26.0 (2021-04-14) + +### New Features + +#### Tracing + +tarpc is now instrumented with tracing primitives extended with +OpenTelemetry traces. Using a compatible tracing-opentelemetry +subscriber like Jaeger, each RPC can be traced through the client, +server, amd other dependencies downstream of the server. Even for +applications not connected to a distributed tracing collector, the +instrumentation can also be ingested by regular loggers like env_logger. + +### Breaking Changes + +#### Logging + +Logged events are now structured using tracing. For applications using a +logger and not a tracing subscriber, these logs may look different or +contain information in a less consumable manner. The easiest solution is +to add a tracing subscriber that logs to stdout, such as +tracing_subscriber::fmt. + +#### Context + +- Context no longer has parent_span, which was actually never needed, + because the context sent in an RPC is inherently the parent context. + For purposes of distributed tracing, the client side of the RPC has all + necessary information to link the span to its parent; the server side + need do nothing more than export the (trace ID, span ID) tuple. +- Context has a new field, SamplingDecision, which has two variants, + Sampled and Unsampled. This field can be used by downstream systems to + determine whether a trace needs to be exported. If the parent span is + sampled, the expectation is that all child spans be exported, as well; + to do otherwise could result in lossy traces being exported. Note that + if an Openetelemetry tracing subscriber is not installed, the fallback + context will still be used, but the Context's sampling decision will + always be inherited by the parent Context's sampling decision. +- Context::scope has been removed. Context propagation is now done via + tracing's task-local spans. Spans can be propagated across tasks via + Span::in_scope. When a service receives a request, it attaches an + Opentelemetry context to the local Span created before request handling, + and this context contains the request deadline. This span-local deadline + is retrieved by Context::current, but it cannot be modified so that + future Context::current calls contain a different deadline. However, the + deadline in the context passed into an RPC call will override it, so + users can retrieve the current context and then modify the deadline + field, as has been historically possible. +- Context propgation precedence changes: when an RPC is initiated, the + current Span's Opentelemetry context takes precedence over the trace + context passed into the RPC method. If there is no current Span, then + the trace context argument is used as it has been historically. Note + that Opentelemetry context propagation requires an Opentelemetry + tracing subscriber to be installed. + +#### Server + +- The server::Channel trait now has an additional required associated + type and method which returns the underlying transport. This makes it + more ergonomic for users to retrieve transport-specific information, + like IP Address. BaseChannel implements Channel::transport by returning + the underlying transport, and channel decorators like Throttler just + delegate to the Channel::transport method of the wrapped channel. + +#### Client + +- NewClient::spawn no longer returns a result, as spawn can't fail. + +### References + +[1] https://github.com/tokio-rs/tracing +[2] https://opentelemetry.io +[3] https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry-jaeger +[4] https://github.com/env-logger-rs/env_logger + ## 0.25.0 (2021-03-10) ### Breaking Changes @@ -170,7 +245,7 @@ nameable futures and will just be boxing the return type anyway. This macro does ### Breaking Changes -- Enums had _non_exhaustive fields replaced with the #[non_exhaustive] attribute. +- Enums had `_non_exhaustive` fields replaced with the #[non_exhaustive] attribute. ### Bug Fixes diff --git a/example-service/Cargo.toml b/example-service/Cargo.toml index 7db8a38..9de7c8c 100644 --- a/example-service/Cargo.toml +++ b/example-service/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "tarpc-example-service" -version = "0.9.0" +version = "0.10.0" authors = ["Tim Kuehn "] edition = "2018" license = "MIT" @@ -21,7 +21,7 @@ opentelemetry = { version = "0.13", features = ["rt-tokio"] } opentelemetry-jaeger = { version = "0.12", features = ["tokio"] } rand = "0.8" serde = { version = "1.0" } -tarpc = { path = "../tarpc", features = ["full"] } +tarpc = { version = "0.26", path = "../tarpc", features = ["full"] } tokio = { version = "1", features = ["macros", "net", "rt-multi-thread"] } tokio-serde = { version = "0.8", features = ["json"] } tracing = { version = "0.1" } diff --git a/plugins/Cargo.toml b/plugins/Cargo.toml index 314eae5..754172f 100644 --- a/plugins/Cargo.toml +++ b/plugins/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "tarpc-plugins" -version = "0.10.0" +version = "0.11.0" authors = ["Adam Wright ", "Tim Kuehn "] edition = "2018" license = "MIT" diff --git a/tarpc/Cargo.toml b/tarpc/Cargo.toml index 1e16b4e..2555352 100644 --- a/tarpc/Cargo.toml +++ b/tarpc/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "tarpc" -version = "0.25.1" +version = "0.26.0" authors = ["Adam Wright ", "Tim Kuehn "] edition = "2018" license = "MIT" @@ -34,7 +34,7 @@ pin-project = "1.0" rand = "0.8" serde = { optional = true, version = "1.0", features = ["derive"] } static_assertions = "1.1.0" -tarpc-plugins = { path = "../plugins", version = "0.10" } +tarpc-plugins = { path = "../plugins", version = "0.11" } thiserror = "1.0" tokio = { version = "1", features = ["time"] } tokio-util = { version = "0.6.3", features = ["time"] } diff --git a/tarpc/src/lib.rs b/tarpc/src/lib.rs index 2649100..2bced52 100644 --- a/tarpc/src/lib.rs +++ b/tarpc/src/lib.rs @@ -38,6 +38,14 @@ //! requests sent by the server that use the request context will propagate the request deadline. //! For example, if a server is handling a request with a 10s deadline, does 2s of work, then //! sends a request to another server, that server will see an 8s deadline. +//! - Distributed tracing: tarpc is instrumented with +//! [tracing](https://github.com/tokio-rs/tracing) primitives extended with +//! [OpenTelemetry](https://opentelemetry.io/) traces. Using a compatible tracing subscriber like +//! [Jaeger](https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry-jaeger), +//! each RPC can be traced through the client, server, amd other dependencies downstream of the +//! server. Even for applications not connected to a distributed tracing collector, the +//! instrumentation can also be ingested by regular loggers like +//! [env_logger](https://github.com/env-logger-rs/env_logger/). //! - Serde serialization: enabling the `serde1` Cargo feature will make service requests and //! responses `Serialize + Deserialize`. It's entirely optional, though: in-memory transports can //! be used, as well, so the price of serialization doesn't have to be paid when it's not needed. @@ -46,7 +54,7 @@ //! Add to your `Cargo.toml` dependencies: //! //! ```toml -//! tarpc = "0.25" +//! tarpc = "0.26" //! ``` //! //! The `tarpc::service` attribute expands to a collection of items that form an rpc service. @@ -60,7 +68,7 @@ //! //! ```toml //! futures = "1.0" -//! tarpc = { version = "0.25", features = ["tokio1"] } +//! tarpc = { version = "0.26", features = ["tokio1"] } //! tokio = { version = "1.0", features = ["macros"] } //! ``` //!