@temporalio/core-bridge 1.8.5 → 1.9.0-rc.0

package/sdk-core/core-api/src/telemetry/metrics.rs

@@ -0,0 +1,334 @@
+use std::{
+    any::Any,
+    borrow::Cow,
+    fmt::Debug,
+    sync::{Arc, OnceLock},
+};
+
+/// Implementors of this trait are expected to be defined in each language's bridge.
+/// The implementor is responsible for the allocation/instantiation of new metric meters which
+/// Core has requested.
+pub trait CoreMeter: Send + Sync + Debug {
+    /// Given some k/v pairs, create a return a new instantiated instance of metric attributes.
+    /// Only [MetricAttributes] created by this meter can be used when calling record on instruments
+    /// created by this meter.
+    fn new_attributes(&self, attribs: NewAttributes) -> MetricAttributes;
+    /// Extend some existing attributes with new values. Implementations should create new instances
+    /// when doing so, rather than mutating whatever is backing the passed in `existing` attributes.
+    /// Ideally that new instance retains a ref to the extended old attribute, promoting re-use.
+    fn extend_attributes(
+        &self,
+        existing: MetricAttributes,
+        attribs: NewAttributes,
+    ) -> MetricAttributes;
+    fn counter(&self, params: MetricParameters) -> Arc<dyn Counter>;
+    fn histogram(&self, params: MetricParameters) -> Arc<dyn Histogram>;
+    fn gauge(&self, params: MetricParameters) -> Arc<dyn Gauge>;
+}
+
+#[derive(Debug, Clone, derive_builder::Builder)]
+pub struct MetricParameters {
+    /// The name for the new metric/instrument
+    #[builder(setter(into))]
+    pub name: Cow<'static, str>,
+    /// A description that will appear in metadata if the backend supports it
+    #[builder(setter(into), default = "\"\".into()")]
+    pub description: Cow<'static, str>,
+    /// Unit information that will appear in metadata if the backend supports it
+    #[builder(setter(into), default = "\"\".into()")]
+    pub unit: Cow<'static, str>,
+}
+impl From<&'static str> for MetricParameters {
+    fn from(value: &'static str) -> Self {
+        Self {
+            name: value.into(),
+            description: Default::default(),
+            unit: Default::default(),
+        }
+    }
+}
+
+/// Wraps a [CoreMeter] to enable the attaching of default labels to metrics. Cloning is cheap.
+#[derive(derive_more::Constructor, Clone, Debug)]
+pub struct TemporalMeter {
+    pub inner: Arc<dyn CoreMeter>,
+    pub default_attribs: NewAttributes,
+}
+
+impl CoreMeter for Arc<dyn CoreMeter> {
+    fn new_attributes(&self, attribs: NewAttributes) -> MetricAttributes {
+        self.as_ref().new_attributes(attribs)
+    }
+
+    fn extend_attributes(
+        &self,
+        existing: MetricAttributes,
+        attribs: NewAttributes,
+    ) -> MetricAttributes {
+        self.as_ref().extend_attributes(existing, attribs)
+    }
+
+    fn counter(&self, params: MetricParameters) -> Arc<dyn Counter> {
+        self.as_ref().counter(params)
+    }
+    fn histogram(&self, params: MetricParameters) -> Arc<dyn Histogram> {
+        self.as_ref().histogram(params)
+    }
+    fn gauge(&self, params: MetricParameters) -> Arc<dyn Gauge> {
+        self.as_ref().gauge(params)
+    }
+}
+
+/// Attributes which are provided every time a call to record a specific metric is made.
+/// Implementors must be very cheap to clone, as these attributes will be re-used frequently.
+#[derive(Clone, Debug)]
+#[non_exhaustive]
+pub enum MetricAttributes {
+    #[cfg(feature = "otel_impls")]
+    OTel {
+        kvs: Arc<Vec<opentelemetry::KeyValue>>,
+    },
+    Buffer(BufferAttributes),
+    Dynamic(Arc<dyn CustomMetricAttributes>),
+}
+
+/// A reference to some attributes created lang side.
+pub trait CustomMetricAttributes: Debug + Send + Sync {
+    /// Must be implemented to work around existing type system restrictions, see
+    /// [here](https://internals.rust-lang.org/t/downcast-not-from-any-but-from-any-trait/16736/12)
+    fn as_any(self: Arc<Self>) -> Arc<dyn Any + Send + Sync>;
+}
+
+/// Options that are attached to metrics on a per-call basis
+#[derive(Clone, Debug, Default, derive_more::Constructor)]
+pub struct NewAttributes {
+    pub attributes: Vec<MetricKeyValue>,
+}
+impl NewAttributes {
+    pub fn extend(&mut self, new_kvs: impl IntoIterator<Item = MetricKeyValue>) {
+        self.attributes.extend(new_kvs)
+    }
+}
+impl<I> From<I> for NewAttributes
+where
+    I: IntoIterator<Item = MetricKeyValue>,
+{
+    fn from(value: I) -> Self {
+        Self {
+            attributes: value.into_iter().collect(),
+        }
+    }
+}
+
+/// A K/V pair that can be used to label a specific recording of a metric
+#[derive(Clone, Debug)]
+pub struct MetricKeyValue {
+    pub key: String,
+    pub value: MetricValue,
+}
+impl MetricKeyValue {
+    pub fn new(key: impl Into<String>, value: impl Into<MetricValue>) -> Self {
+        Self {
+            key: key.into(),
+            value: value.into(),
+        }
+    }
+}
+
+/// Values metric labels may assume
+#[derive(Clone, Debug, derive_more::From)]
+pub enum MetricValue {
+    String(String),
+    Int(i64),
+    Float(f64),
+    Bool(bool),
+    // can add array if needed
+}
+impl From<&'static str> for MetricValue {
+    fn from(value: &'static str) -> Self {
+        MetricValue::String(value.to_string())
+    }
+}
+
+pub trait Counter: Send + Sync {
+    fn add(&self, value: u64, attributes: &MetricAttributes);
+}
+
+pub trait Histogram: Send + Sync {
+    // When referring to durations, this value is in millis
+    fn record(&self, value: u64, attributes: &MetricAttributes);
+}
+
+pub trait Gauge: Send + Sync {
+    // When referring to durations, this value is in millis
+    fn record(&self, value: u64, attributes: &MetricAttributes);
+}
+
+#[derive(Debug, Clone)]
+pub enum MetricEvent<I: BufferInstrumentRef> {
+    Create {
+        params: MetricParameters,
+        /// One you receive this event, call `set` on this with the initialized instrument reference
+        populate_into: LazyBufferInstrument<I>,
+        kind: MetricKind,
+    },
+    CreateAttributes {
+        /// One you receive this event, call `set` on this with the initialized attributes
+        populate_into: BufferAttributes,
+        /// If not `None`, use these already-initialized attributes as the base (extended with
+        /// `attributes`) for the ones you are about to initialize.
+        append_from: Option<BufferAttributes>,
+        attributes: Vec<MetricKeyValue>,
+    },
+    Update {
+        instrument: LazyBufferInstrument<I>,
+        attributes: BufferAttributes,
+        update: MetricUpdateVal,
+    },
+}
+#[derive(Debug, Clone, Copy)]
+pub enum MetricKind {
+    Counter,
+    Gauge,
+    Histogram,
+}
+#[derive(Debug, Clone, Copy)]
+pub enum MetricUpdateVal {
+    // Currently all deltas are natural numbers
+    Delta(u64),
+    // Currently all values are natural numbers
+    Value(u64),
+}
+
+pub trait MetricCallBufferer<I: BufferInstrumentRef>: Send + Sync {
+    fn retrieve(&self) -> Vec<MetricEvent<I>>;
+}
+
+/// A lazy reference to some metrics buffer attributes
+pub type BufferAttributes = LazyRef<Arc<dyn CustomMetricAttributes + 'static>>;
+
+/// Types lang uses to contain references to its lang-side defined instrument references must
+/// implement this marker trait
+pub trait BufferInstrumentRef {}
+/// A lazy reference to a metrics buffer instrument
+pub type LazyBufferInstrument<T> = LazyRef<Arc<T>>;
+
+#[derive(Debug, Clone)]
+pub struct LazyRef<T> {
+    to_be_initted: Arc<OnceLock<T>>,
+}
+impl<T> LazyRef<T> {
+    pub fn hole() -> Self {
+        Self {
+            to_be_initted: Arc::new(OnceLock::new()),
+        }
+    }
+
+    /// Get the reference you previously initialized
+    ///
+    /// # Panics
+    /// If `set` has not already been called. You must set the reference before using it.
+    pub fn get(&self) -> &T {
+        self.to_be_initted
+            .get()
+            .expect("You must initialize the reference before using it")
+    }
+
+    /// Assigns a value to fill this reference.
+    /// Returns according to semantics of [OnceLock].
+    pub fn set(&self, val: T) -> Result<(), T> {
+        self.to_be_initted.set(val)
+    }
+}
+
+#[derive(Debug)]
+pub struct NoOpCoreMeter;
+impl CoreMeter for NoOpCoreMeter {
+    fn new_attributes(&self, _: NewAttributes) -> MetricAttributes {
+        MetricAttributes::Dynamic(Arc::new(NoOpAttributes))
+    }
+
+    fn extend_attributes(&self, existing: MetricAttributes, _: NewAttributes) -> MetricAttributes {
+        existing
+    }
+
+    fn counter(&self, _: MetricParameters) -> Arc<dyn Counter> {
+        Arc::new(NoOpInstrument)
+    }
+
+    fn histogram(&self, _: MetricParameters) -> Arc<dyn Histogram> {
+        Arc::new(NoOpInstrument)
+    }
+
+    fn gauge(&self, _: MetricParameters) -> Arc<dyn Gauge> {
+        Arc::new(NoOpInstrument)
+    }
+}
+
+pub struct NoOpInstrument;
+impl Counter for NoOpInstrument {
+    fn add(&self, _: u64, _: &MetricAttributes) {}
+}
+impl Histogram for NoOpInstrument {
+    fn record(&self, _: u64, _: &MetricAttributes) {}
+}
+impl Gauge for NoOpInstrument {
+    fn record(&self, _: u64, _: &MetricAttributes) {}
+}
+
+#[derive(Debug, Clone)]
+pub struct NoOpAttributes;
+impl CustomMetricAttributes for NoOpAttributes {
+    fn as_any(self: Arc<Self>) -> Arc<dyn Any + Send + Sync> {
+        self as Arc<dyn Any + Send + Sync>
+    }
+}
+
+#[cfg(feature = "otel_impls")]
+mod otel_impls {
+    use super::*;
+    use opentelemetry::{metrics, KeyValue};
+
+    impl From<MetricKeyValue> for KeyValue {
+        fn from(kv: MetricKeyValue) -> Self {
+            KeyValue::new(kv.key, kv.value)
+        }
+    }
+
+    impl From<MetricValue> for opentelemetry::Value {
+        fn from(mv: MetricValue) -> Self {
+            match mv {
+                MetricValue::String(s) => opentelemetry::Value::String(s.into()),
+                MetricValue::Int(i) => opentelemetry::Value::I64(i),
+                MetricValue::Float(f) => opentelemetry::Value::F64(f),
+                MetricValue::Bool(b) => opentelemetry::Value::Bool(b),
+            }
+        }
+    }
+
+    impl Counter for metrics::Counter<u64> {
+        fn add(&self, value: u64, attributes: &MetricAttributes) {
+            if let MetricAttributes::OTel { kvs } = attributes {
+                self.add(value, kvs);
+            } else {
+                debug_assert!(
+                    false,
+                    "Must use OTel attributes with an OTel metric implementation"
+                );
+            }
+        }
+    }
+
+    impl Histogram for metrics::Histogram<u64> {
+        fn record(&self, value: u64, attributes: &MetricAttributes) {
+            if let MetricAttributes::OTel { kvs } = attributes {
+                self.record(value, kvs);
+            } else {
+                debug_assert!(
+                    false,
+                    "Must use OTel attributes with an OTel metric implementation"
+                );
+            }
+        }
+    }
+}

package/sdk-core/core-api/src/telemetry.rs

@@ -1,11 +1,18 @@
+pub mod metrics;
+
+use crate::telemetry::metrics::CoreMeter;
 use std::{
     collections::HashMap,
+    fmt::Debug,
     net::SocketAddr,
+    sync::Arc,
     time::{Duration, SystemTime, UNIX_EPOCH},
 };
 use tracing_core::Level;
 use url::Url;
 
+pub static METRIC_PREFIX: &str = "temporal_";
+
 /// Each core runtime instance has a telemetry subsystem associated with it, this trait defines the
 /// operations that lang might want to perform on that telemetry after it's initialized.
 pub trait CoreTelemetry {
@@ -23,32 +30,25 @@ pub trait CoreTelemetry {
 #[derive(Debug, Clone, derive_builder::Builder)]
 #[non_exhaustive]
 pub struct TelemetryOptions {
-    /// Optional trace exporter - set as None to disable.
-    #[builder(setter(into, strip_option), default)]
-    pub tracing: Option<TraceExportConfig>,
     /// Optional logger - set as None to disable.
     #[builder(setter(into, strip_option), default)]
     pub logging: Option<Logger>,
     /// Optional metrics exporter - set as None to disable.
     #[builder(setter(into, strip_option), default)]
-    pub metrics: Option<MetricsExporter>,
-
-    /// If set true, do not prefix metrics with `temporal_`. Will be removed eventually as
-    /// the prefix is consistent with other SDKs.
-    #[builder(default)]
-    pub no_temporal_prefix_for_metrics: bool,
-
-    /// Specifies the aggregation temporality for metric export. Defaults to cumulative.
-    #[builder(default = "MetricTemporality::Cumulative")]
-    pub metric_temporality: MetricTemporality,
-
-    // A map of tags to be applied to all metrics
-    #[builder(default)]
-    pub global_tags: HashMap<String, String>,
+    pub metrics: Option<Arc<dyn CoreMeter>>,
+    /// If set true (the default) explicitly attach a `service_name` label to all metrics. Turn this
+    /// off if your collection system supports the `target_info` metric from the OpenMetrics spec.
+    /// For more, see
+    /// [here](https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#supporting-target-metadata-in-both-push-based-and-pull-based-systems)
+    #[builder(default = "true")]
+    pub attach_service_name: bool,
+    /// A prefix to be applied to all core-created metrics. Defaults to "temporal_".
+    #[builder(default = "METRIC_PREFIX.to_string()")]
+    pub metric_prefix: String,
 }
 
 /// Options for exporting to an OpenTelemetry Collector
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, derive_builder::Builder)]
 pub struct OtelCollectorOptions {
     /// The url of the OTel collector to export telemetry and metrics to. Lang SDK should also
     /// export to this same collector.
@@ -56,32 +56,30 @@ pub struct OtelCollectorOptions {
     /// Optional set of HTTP headers to send to the Collector, e.g for authentication.
     pub headers: HashMap<String, String>,
     /// Optionally specify how frequently metrics should be exported. Defaults to 1 second.
-    pub metric_periodicity: Option<Duration>,
-}
-
-/// Configuration for the external export of traces
-#[derive(Debug, Clone)]
-pub struct TraceExportConfig {
-    /// An [EnvFilter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/struct.EnvFilter.html) filter string.
-    pub filter: String,
-    /// Where they should go
-    pub exporter: TraceExporter,
-}
-
-/// Control where traces are exported.
-#[derive(Debug, Clone)]
-pub enum TraceExporter {
-    /// Export traces to an OpenTelemetry Collector <https://opentelemetry.io/docs/collector/>.
-    Otel(OtelCollectorOptions),
+    #[builder(default = "Duration::from_secs(1)")]
+    pub metric_periodicity: Duration,
+    /// Specifies the aggregation temporality for metric export. Defaults to cumulative.
+    #[builder(default = "MetricTemporality::Cumulative")]
+    pub metric_temporality: MetricTemporality,
+    // A map of tags to be applied to all metrics
+    #[builder(default)]
+    pub global_tags: HashMap<String, String>,
 }
 
-/// Control where metrics are exported
-#[derive(Debug, Clone)]
-pub enum MetricsExporter {
-    /// Export metrics to an OpenTelemetry Collector <https://opentelemetry.io/docs/collector/>.
-    Otel(OtelCollectorOptions),
-    /// Expose metrics directly via an embedded http server bound to the provided address.
-    Prometheus(SocketAddr),
+/// Options for exporting metrics to Prometheus
+#[derive(Debug, Clone, derive_builder::Builder)]
+pub struct PrometheusExporterOptions {
+    pub socket_addr: SocketAddr,
+    // A map of tags to be applied to all metrics
+    #[builder(default)]
+    pub global_tags: HashMap<String, String>,
+    /// If set true, all counters will include a "_total" suffix
+    #[builder(default = "false")]
+    pub counters_total_suffix: bool,
+    /// If set true, all histograms will include the unit in their name as a suffix.
+    /// Ex: "_milliseconds".
+    #[builder(default = "false")]
+    pub unit_suffix: bool,
 }
 
 /// Control where logs go
@@ -97,6 +95,13 @@ pub enum Logger {
         /// An [EnvFilter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/struct.EnvFilter.html) filter string.
         filter: String,
     },
+    // Push logs to Lang. Can used with temporal_sdk_core::telemetry::CoreLogBufferedConsumer to buffer.
+    Push {
+        /// An [EnvFilter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/struct.EnvFilter.html) filter string.
+        filter: String,
+        /// Trait invoked on each log.
+        consumer: Arc<dyn CoreLogConsumer>,
+    },
 }
 
 /// Types of aggregation temporality for metric export.
@@ -143,3 +148,9 @@ impl CoreLog {
             .as_millis()
     }
 }
+
+/// Consumer trait for use with push logger.
+pub trait CoreLogConsumer: Send + Sync + Debug {
+    /// Invoked synchronously for every single log.
+    fn on_log(&self, log: CoreLog);
+}

package/sdk-core/core-api/src/worker.rs

@@ -115,6 +115,7 @@ pub struct WorkerConfig {
     #[builder(default = "5")]
     pub fetching_concurrency: usize,
 
+    // TODO: Move this out - dependency on tokio should not exist just for this
     /// If set, and the `save_wf_inputs` feature is enabled in core, will be sent a serialized
     /// instance of every input to workflow state in order. This is for testing purposes, SDK
     /// implementations never need to care about it.
@@ -126,6 +127,12 @@ pub struct WorkerConfig {
     /// initiated and this amount of time has elapsed.
     #[builder(default)]
     pub graceful_shutdown_period: Option<Duration>,
+
+    /// The amount of time core will wait before timing out activities using its own local timers
+    /// after one of them elapses. This is to avoid racing with server's own tracking of the
+    /// timeout.
+    #[builder(default = "Duration::from_secs(5)")]
+    pub local_timeout_buffer_for_activities: Duration,
 }
 
 impl WorkerConfig {

package/sdk-core/{.buildkite/docker → docker}/docker-compose.yaml

@@ -9,7 +9,7 @@ services:
   #      - '9042:9042'
 
   temporal:
-    image: temporalio/auto-setup:1.20.0
+    image: temporalio/auto-setup:1.22.0
     ports:
       - "7233:7233"
       - "7234:7234"

package/sdk-core/etc/dynamic-config.yaml

@@ -1,2 +1,12 @@
 system.enableActivityLocalDispatch:
-  - value: true
+  - value: true
+system.enableEagerWorkflowStart:
+  - value: true
+frontend.workerVersioningWorkflowAPIs:
+  - value: true
+frontend.workerVersioningDataAPIs:
+  - value: true
+frontend.enableUpdateWorkflowExecution:
+  - value: true
+frontend.enableUpdateWorkflowExecutionAsyncAccepted:
+  - value: true

package/sdk-core/fsm/rustfsm_procmacro/Cargo.toml

@@ -16,7 +16,7 @@ path = "tests/progress.rs"
 [dependencies]
 derive_more = "0.99"
 proc-macro2 = "1.0"
-syn = { version = "1.0", features = ["default", "extra-traits"] }
+syn = { version = "2.0", features = ["default", "extra-traits"] }
 quote = "1.0"
 rustfsm_trait = { version = "0.1", path = "../rustfsm_trait" }
 

package/sdk-core/fsm/rustfsm_procmacro/src/lib.rs

@@ -5,7 +5,6 @@ use syn::{
     parenthesized,
     parse::{Parse, ParseStream, Result},
     parse_macro_input,
-    punctuated::Punctuated,
     spanned::Spanned,
     Error, Fields, Ident, Token, Type, Variant, Visibility,
 };
@@ -212,8 +211,7 @@ impl Parse for StateMachineDefinition {
             })?;
         // Then the state machine definition is simply a sequence of transitions separated by
         // semicolons
-        let transitions: Punctuated<Transition, Token![;]> =
-            input.parse_terminated(Transition::parse)?;
+        let transitions = input.parse_terminated(Transition::parse, Token![;])?;
         let transitions: Vec<_> = transitions.into_iter().collect();
         // Check for and whine about any identical transitions. We do this here because preserving
         // the order transitions were defined in is important, so simply collecting to a set is

package/sdk-core/fsm/rustfsm_procmacro/tests/trybuild/no_handle_conversions_require_into_fail.stderr

@@ -1,8 +1,8 @@
 error[E0277]: the trait bound `One: From<Two>` is not satisfied
-  --> tests/trybuild/no_handle_conversions_require_into_fail.rs:11:18
+  --> tests/trybuild/no_handle_conversions_require_into_fail.rs:11:5
    |
 11 |     Two --(B)--> One;
-   |                  ^^^ the trait `From<Two>` is not implemented for `One`
+   |     ^^^ the trait `From<Two>` is not implemented for `One`
    |
    = note: required for `Two` to implement `Into<One>`
 note: required by a bound in `TransitionResult::<Sm, Ds>::from`

package/sdk-core/sdk/Cargo.toml

@@ -28,7 +28,7 @@ serde = "1.0"
 tokio = { version = "1.26", features = ["rt", "rt-multi-thread", "parking_lot", "time", "fs"] }
 tokio-util = { version = "0.7" }
 tokio-stream = "0.1"
-tonic = "0.8"
+tonic = { workspace = true }
 tracing = "0.1"
 
 [dependencies.temporal-sdk-core]