temporalio 0.0.1 → 0.1.0

data/bridge/sdk-core/core-api/Cargo.toml

@@ -13,14 +13,16 @@ categories = ["development-tools"]
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-anyhow = "1.0"
 async-trait = "0.1"
-derive_builder = "0.11"
-log = "0.4"
-opentelemetry = "0.18"
+derive_builder = "0.12"
 prost-types = "0.11"
+serde = { version = "1.0", default_features = false, features = ["derive"] }
+serde_json = "1.0"
 thiserror = "1.0"
+tokio = "1.24"
 tonic = "0.8"
+tracing-core = "0.1"
+url = "2.3"
 
 [dependencies.temporal-sdk-core-protos]
 path = "../sdk-core-protos"

data/bridge/sdk-core/core-api/src/errors.rs

@@ -1,10 +1,6 @@
 //! Error types exposed by public APIs
 
-use prost_types::TimestampError;
-use temporal_sdk_core_protos::coresdk::{
-    activity_result::ActivityExecutionResult,
-    workflow_activation::remove_from_cache::EvictionReason,
-};
+use temporal_sdk_core_protos::coresdk::activity_result::ActivityExecutionResult;
 
 /// Errors thrown by [crate::Worker::poll_workflow_activation]
 #[derive(thiserror::Error, Debug)]
@@ -64,32 +60,3 @@ pub enum CompleteActivityError {
         completion: Option<ActivityExecutionResult>,
     },
 }
-
-/// Errors thrown inside of workflow machines
-#[derive(thiserror::Error, Debug)]
-pub enum WFMachinesError {
-    #[error("Nondeterminism error: {0}")]
-    Nondeterminism(String),
-    #[error("Fatal error in workflow machines: {0}")]
-    Fatal(String),
-
-    #[error("Unrecoverable network error while fetching history: {0}")]
-    HistoryFetchingError(tonic::Status),
-}
-
-impl WFMachinesError {
-    pub fn evict_reason(&self) -> EvictionReason {
-        match self {
-            WFMachinesError::Nondeterminism(_) => EvictionReason::Nondeterminism,
-            WFMachinesError::Fatal(_) | WFMachinesError::HistoryFetchingError(_) => {
-                EvictionReason::Fatal
-            }
-        }
-    }
-}
-
-impl From<TimestampError> for WFMachinesError {
-    fn from(_: TimestampError) -> Self {
-        Self::Fatal("Could not decode timestamp".to_string())
-    }
-}

data/bridge/sdk-core/core-api/src/lib.rs

@@ -1,13 +1,11 @@
 pub mod errors;
+pub mod telemetry;
 pub mod worker;
 
 use crate::{
     errors::{CompleteActivityError, CompleteWfError, PollActivityError, PollWfError},
     worker::WorkerConfig,
 };
-use log::Level;
-use opentelemetry::metrics::Meter;
-use std::time::{Duration, SystemTime, UNIX_EPOCH};
 use temporal_sdk_core_protos::coresdk::{
     activity_task::ActivityTask, workflow_activation::WorkflowActivation,
     workflow_completion::WorkflowActivationCompletion, ActivityHeartbeat, ActivityTaskCompletion,
@@ -47,13 +45,17 @@ pub trait Worker: Send + Sync {
     /// concurrently internally.
     async fn poll_activity_task(&self) -> Result<ActivityTask, PollActivityError>;
 
-    /// Tell the worker that a workflow activation has completed. May be freely called concurrently.
+    /// Tell the worker that a workflow activation has completed. May (and should) be freely called
+    /// concurrently. The future may take some time to resolve, as fetching more events might be
+    /// necessary for completion to... complete - thus SDK implementers should make sure they do
+    /// not serialize completions.
     async fn complete_workflow_activation(
         &self,
         completion: WorkflowActivationCompletion,
     ) -> Result<(), CompleteWfError>;
 
-    /// Tell the worker that an activity has finished executing. May be freely called concurrently.
+    /// Tell the worker that an activity has finished executing. May (and should) be freely called
+    /// concurrently.
     async fn complete_activity_task(
         &self,
         completion: ActivityTaskCompletion,
@@ -109,43 +111,3 @@ pub trait Worker: Send + Sync {
     /// This should be called only after [Worker::shutdown] has resolved.
     async fn finalize_shutdown(self);
 }
-
-/// Should be backed by a process-wide singleton who is responsible for telemetry and logging
-/// management.
-pub trait CoreTelemetry {
-    /// Core buffers logs that should be shuttled over to lang so that they may be rendered with
-    /// the user's desired logging library. Use this function to grab the most recent buffered logs
-    /// since the last time it was called. A fixed number of such logs are retained at maximum, with
-    /// the oldest being dropped when full.
-    ///
-    /// Returns the list of logs from oldest to newest. Returns an empty vec if the feature is not
-    /// configured.
-    fn fetch_buffered_logs(&self) -> Vec<CoreLog>;
-
-    /// If metrics gathering is enabled, returns the OTel meter for core telemetry, which can be
-    /// used to create metrics instruments, or passed to things that create/record metrics (ex:
-    /// clients).
-    fn get_metric_meter(&self) -> Option<&Meter>;
-}
-
-/// A log line (which ultimately came from a tracing event) exported from Core->Lang
-#[derive(Debug)]
-pub struct CoreLog {
-    /// Log message
-    pub message: String,
-    /// Time log was generated (not when it was exported to lang)
-    pub timestamp: SystemTime,
-    /// Message level
-    pub level: Level,
-    // KV pairs aren't meaningfully exposed yet to the log interface by tracing
-}
-
-impl CoreLog {
-    /// Return timestamp as ms since epoch
-    pub fn millis_since_epoch(&self) -> u128 {
-        self.timestamp
-            .duration_since(UNIX_EPOCH)
-            .unwrap_or(Duration::ZERO)
-            .as_millis()
-    }
-}

data/bridge/sdk-core/core-api/src/telemetry.rs

@@ -0,0 +1,141 @@
+use std::{
+    collections::HashMap,
+    net::SocketAddr,
+    time::{Duration, SystemTime, UNIX_EPOCH},
+};
+use tracing_core::Level;
+use url::Url;
+
+/// 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 {
+    /// Each worker buffers logs that should be shuttled over to lang so that they may be rendered
+    /// with the user's desired logging library. Use this function to grab the most recent buffered
+    /// logs since the last time it was called. A fixed number of such logs are retained at maximum,
+    /// with the oldest being dropped when full.
+    ///
+    /// Returns the list of logs from oldest to newest. Returns an empty vec if the feature is not
+    /// configured.
+    fn fetch_buffered_logs(&self) -> Vec<CoreLog>;
+}
+
+/// Telemetry configuration options. Construct with [TelemetryOptionsBuilder]
+#[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,
+}
+
+/// Options for exporting to an OpenTelemetry Collector
+#[derive(Debug, Clone)]
+pub struct OtelCollectorOptions {
+    /// The url of the OTel collector to export telemetry and metrics to. Lang SDK should also
+    /// export to this same collector.
+    pub url: Url,
+    /// 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),
+}
+
+/// 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),
+}
+
+/// Control where logs go
+#[derive(Debug, Clone)]
+pub enum Logger {
+    /// Log directly to console.
+    Console {
+        /// An [EnvFilter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/struct.EnvFilter.html) filter string.
+        filter: String,
+    },
+    /// Forward logs to Lang - collectable with `fetch_global_buffered_logs`.
+    Forward {
+        /// An [EnvFilter](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/struct.EnvFilter.html) filter string.
+        filter: String,
+    },
+}
+
+/// Types of aggregation temporality for metric export.
+/// See: <https://github.com/open-telemetry/opentelemetry-specification/blob/ce50e4634efcba8da445cc23523243cb893905cb/specification/metrics/datamodel.md#temporality>
+#[derive(Debug, Clone, Copy)]
+pub enum MetricTemporality {
+    /// Successive data points repeat the starting timestamp
+    Cumulative,
+    /// Successive data points advance the starting timestamp
+    Delta,
+}
+
+impl Default for TelemetryOptions {
+    fn default() -> Self {
+        TelemetryOptionsBuilder::default().build().unwrap()
+    }
+}
+
+/// A log line (which ultimately came from a tracing event) exported from Core->Lang
+#[derive(Debug)]
+pub struct CoreLog {
+    /// The module within core this message originated from
+    pub target: String,
+    /// Log message
+    pub message: String,
+    /// Time log was generated (not when it was exported to lang)
+    pub timestamp: SystemTime,
+    /// Message level
+    pub level: Level,
+    /// Arbitrary k/v pairs (span k/vs are collapsed with event k/vs here). We could change this
+    /// to include them in `span_contexts` instead, but there's probably not much value for log
+    /// forwarding.
+    pub fields: HashMap<String, serde_json::Value>,
+    /// A list of the outermost to the innermost span names
+    pub span_contexts: Vec<String>,
+}
+
+impl CoreLog {
+    /// Return timestamp as ms since epoch
+    pub fn millis_since_epoch(&self) -> u128 {
+        self.timestamp
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or(Duration::ZERO)
+            .as_millis()
+    }
+}

data/bridge/sdk-core/core-api/src/worker.rs

@@ -1,7 +1,8 @@
 use std::time::Duration;
+use tokio::sync::mpsc::UnboundedSender;
 
 /// Defines per-worker configuration options
-#[derive(Debug, Clone, derive_builder::Builder)]
+#[derive(Debug, Clone, derive_builder::Builder, serde::Serialize, serde::Deserialize)]
 #[builder(setter(into), build_fn(validate = "Self::validate"))]
 #[non_exhaustive]
 pub struct WorkerConfig {
@@ -95,6 +96,28 @@ pub struct WorkerConfig {
     /// todo: link to feature docs
     #[builder(default = "false")]
     pub use_worker_versioning: bool,
+
+    /// If set false (default), shutdown will not finish until all pending evictions have been
+    /// issued and replied to. If set true shutdown will be considered complete when the only
+    /// remaining work is pending evictions.
+    ///
+    /// This flag is useful during tests to avoid needing to deal with lots of uninteresting
+    /// evictions during shutdown. Alternatively, if a lang implementation finds it easy to clean
+    /// up during shutdown, setting this true saves some back-and-forth.
+    #[builder(default = "false")]
+    pub ignore_evicts_on_shutdown: bool,
+
+    /// Maximum number of next page (or initial) history event listing requests we'll make
+    /// concurrently. I don't this it's worth exposing this to users until we encounter a reason.
+    #[builder(default = "5")]
+    pub fetching_concurrency: usize,
+
+    /// 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.
+    #[builder(default)]
+    #[serde(skip)]
+    pub wf_state_inputs: Option<UnboundedSender<Vec<u8>>>,
 }
 
 impl WorkerConfig {
@@ -114,6 +137,9 @@ impl WorkerConfigBuilder {
         if self.max_concurrent_wft_polls == Some(0) {
             return Err("`max_concurrent_wft_polls` must be at least 1".to_owned());
         }
+        if self.max_concurrent_at_polls == Some(0) {
+            return Err("`max_concurrent_at_polls` must be at least 1".to_owned());
+        }
         if self.max_cached_workflows > Some(0)
             && self.max_outstanding_workflow_tasks > self.max_cached_workflows
         {