feat: add async backtrace layer (#2765)

* feat: add async backtrace layer

Signed-off-by: dqhl76 <[email protected]>

* docs: add document for async backtrace layer

Signed-off-by: dqhl76 <[email protected]>

* fix: add cargo lock change

Signed-off-by: dqhl76 <[email protected]>

* fix: format layout

Co-authored-by: oowl <[email protected]>

---------

Signed-off-by: dqhl76 <[email protected]>
Co-authored-by: oowl <[email protected]>

core/Cargo.toml

@@ -77,6 +77,7 @@ layers-all = [
   "layers-minitrace",
   "layers-throttle",
   "layers-await-tree",
+  "layers-async-backtrace",
 ]
 # Enable layers chaos support
 layers-chaos = ["dep:rand"]
@@ -96,6 +97,8 @@ layers-otel-trace = ["dep:opentelemetry"]
 layers-throttle = ["dep:governor"]
 # Enable layers await-tree support.
 layers-await-tree = ["dep:await-tree"]
+# Enable layers async-backtrace support.
+layers-async-backtrace = ["dep:async-backtrace"]
 
 services-azblob = [
   "dep:sha2",
@@ -183,6 +186,7 @@ path = "tests/behavior/main.rs"
 
 [dependencies]
 anyhow = { version = "1.0.30", features = ["std"] }
+async-backtrace = { version = "0.2.6", optional = true }
 async-compat = "0.2"
 async-tls = { version = "0.11", optional = true }
 async-trait = "0.1.68"

core/src/layers/async_backtrace.rs

@@ -0,0 +1,137 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use crate::raw::*;
+use crate::*;
+
+use async_trait::async_trait;
+
+/// Add Efficient, logical 'stack' traces of async functions for the underlying services.
+///
+/// # Async Backtrace
+///
+/// async-backtrace allows developers to get a stack trace of the async functions.
+/// Read more about [async-backtrace](https://docs.rs/async-backtrace/latest/async_backtrace/)
+///
+/// # Examples
+///
+/// ```
+/// use anyhow::Result;
+/// use opendal::layers::AsyncBacktraceLayer;
+/// use opendal::services;
+/// use opendal::Operator;
+/// use opendal::Scheme;
+///
+/// let _ = Operator::new(services::Memory::default())
+///     .expect("must init")
+///     .layer(AsyncBacktraceLayer::new())
+///     .finish();
+/// ```
+
+#[derive(Clone, Default)]
+pub struct AsyncBacktraceLayer;
+
+impl<A: Accessor> Layer<A> for AsyncBacktraceLayer {
+    type LayeredAccessor = AsyncBacktraceAccessor<A>;
+
+    fn layer(&self, accessor: A) -> Self::LayeredAccessor {
+        AsyncBacktraceAccessor { inner: accessor }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct AsyncBacktraceAccessor<A: Accessor> {
+    inner: A,
+}
+
+#[async_trait]
+impl<A: Accessor> LayeredAccessor for AsyncBacktraceAccessor<A> {
+    type Inner = A;
+    type Reader = A::Reader;
+    type BlockingReader = A::BlockingReader;
+    type Writer = A::Writer;
+    type BlockingWriter = A::BlockingWriter;
+    type Appender = A::Appender;
+    type Pager = A::Pager;
+    type BlockingPager = A::BlockingPager;
+
+    fn inner(&self) -> &Self::Inner {
+        &self.inner
+    }
+
+    #[async_backtrace::framed]
+    async fn read(&self, path: &str, args: OpRead) -> Result<(RpRead, Self::Reader)> {
+        self.inner.read(path, args).await
+    }
+
+    #[async_backtrace::framed]
+    async fn write(&self, path: &str, args: OpWrite) -> Result<(RpWrite, Self::Writer)> {
+        self.inner.write(path, args).await
+    }
+
+    #[async_backtrace::framed]
+    async fn append(&self, path: &str, args: OpAppend) -> Result<(RpAppend, Self::Appender)> {
+        self.inner.append(path, args).await
+    }
+
+    #[async_backtrace::framed]
+    async fn copy(&self, from: &str, to: &str, args: OpCopy) -> Result<RpCopy> {
+        self.inner.copy(from, to, args).await
+    }
+
+    #[async_backtrace::framed]
+    async fn rename(&self, from: &str, to: &str, args: OpRename) -> Result<RpRename> {
+        self.inner.rename(from, to, args).await
+    }
+
+    #[async_backtrace::framed]
+    async fn stat(&self, path: &str, args: OpStat) -> Result<RpStat> {
+        self.inner.stat(path, args).await
+    }
+
+    #[async_backtrace::framed]
+    async fn delete(&self, path: &str, args: OpDelete) -> Result<RpDelete> {
+        self.inner.delete(path, args).await
+    }
+
+    #[async_backtrace::framed]
+    async fn list(&self, path: &str, args: OpList) -> Result<(RpList, Self::Pager)> {
+        self.inner.list(path, args).await
+    }
+
+    #[async_backtrace::framed]
+    async fn batch(&self, args: OpBatch) -> Result<RpBatch> {
+        self.inner.batch(args).await
+    }
+
+    #[async_backtrace::framed]
+    async fn presign(&self, path: &str, args: OpPresign) -> Result<RpPresign> {
+        self.inner.presign(path, args).await
+    }
+
+    fn blocking_read(&self, path: &str, args: OpRead) -> Result<(RpRead, Self::BlockingReader)> {
+        self.inner.blocking_read(path, args)
+    }
+
+    fn blocking_write(&self, path: &str, args: OpWrite) -> Result<(RpWrite, Self::BlockingWriter)> {
+        self.inner.blocking_write(path, args)
+    }
+
+    fn blocking_list(&self, path: &str, args: OpList) -> Result<(RpList, Self::BlockingPager)> {
+        self.inner.blocking_list(path, args)
+    }
+}

core/src/layers/mod.rs

@@ -84,7 +84,14 @@ mod throttle;
 pub use self::oteltrace::OtelTraceLayer;
 #[cfg(feature = "layers-throttle")]
 pub use self::throttle::ThrottleLayer;
+
 #[cfg(feature = "layers-await-tree")]
 mod await_tree;
 #[cfg(feature = "layers-await-tree")]
 pub use self::await_tree::AwaitTreeLayer;
+
+#[cfg(feature = "layers-async-backtrace")]
+mod async_backtrace;
+
+#[cfg(feature = "layers-async-backtrace")]
+pub use self::async_backtrace::AsyncBacktraceLayer;