Skip to main content

opendal_layer_dtrace/
lib.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18#![cfg(target_os = "linux")]
19#![doc = include_str!("../README.md")]
20#![cfg_attr(docsrs, feature(doc_cfg))]
21#![cfg_attr(docsrs, doc(auto_cfg))]
22#![deny(missing_docs)]
23use std::ffi::CString;
24use std::sync::Arc;
25use std::task::Poll;
26
27use bytes::Buf;
28use futures::StreamExt;
29use futures::stream::poll_fn;
30use opendal_core::raw::*;
31use opendal_core::*;
32use probe::probe;
33use probe::probe_lazy;
34
35#[cfg(test)]
36mod tests;
37
38/// `DtraceLayer` supports User Statically-Defined Tracing (USDT) on Linux.
39///
40/// Enable this experimental layer with `features = ["layers-dtrace"]` in
41/// `Cargo.toml`.
42///
43/// For now we have following probes:
44///
45/// ### For Service
46///
47/// 1. ${operation}_start, arguments: path
48///     1. create_dir
49///     2. read
50///     3. write
51///     4. stat
52///     5. delete
53///     6. list
54///     7. presign
55///
56/// 2. ${operation}_end, arguments: path
57///     1. create_dir
58///     2. read
59///     3. write
60///     4. stat
61///     5. delete
62///     6. list
63///     7. presign
64///
65/// ### For Reader
66///
67/// 1. reader_read_start, arguments: path, range
68/// 2. reader_read_ok, arguments: path, range, length
69/// 3. reader_read_error, arguments: path, range
70///
71/// ### For Writer
72///
73/// 1. writer_write_start, arguments: path
74/// 2. writer_write_ok, arguments: path, length
75/// 3. writer_write_error, arguments: path
76/// 4. writer_abort_start, arguments: path
77/// 5. writer_abort_ok, arguments: path
78/// 6. writer_abort_error, arguments: path
79/// 7. writer_close_start, arguments: path
80/// 8. writer_close_ok, arguments: path
81/// 9. writer_close_error, arguments: path
82///
83/// ### For HTTP Transport
84///
85/// The `opendal` provider emits these probes for requests through the operator's
86/// [`OperationContext`].
87///
88/// - `http_request_start` fires before the transport fetches the request.
89/// - `http_request_ok` reports the HTTP status code when the transport returns
90///   a response, including responses with 4xx and 5xx status codes.
91/// - `http_request_error` fires when the transport returns an error.
92/// - `http_response_body_chunk` reports the byte length of each streamed chunk.
93/// - `http_response_body_end` fires when the underlying stream reports EOF.
94/// - `http_response_body_error` fires when the underlying stream returns an error.
95///
96/// Example:
97///
98/// ```no_run
99/// # use opendal_core::services;
100/// # use opendal_core::Operator;
101/// # use opendal_core::Result;
102/// # use opendal_layer_dtrace::DtraceLayer;
103/// #
104/// # #[tokio::main]
105/// # async fn main() -> Result<()> {
106/// // `Service` provides the low level APIs, we will use `Operator` normally.
107/// let op: Operator = Operator::new(services::Memory::default().root("/tmp"))?
108///     .layer(DtraceLayer::new());
109///
110/// let path = "/tmp/test.txt";
111/// for _ in 1..100000 {
112///     let bs = vec![0; 64 * 1024 * 1024];
113///     op.write(path, bs).await?;
114///     op.read(path).await?;
115/// }
116/// # Ok(())
117/// # }
118/// ```
119///
120/// Then you can use `readelf -n target/debug/examples/dtrace` to see the probes:
121///
122/// ```text
123/// Displaying notes found in: .note.stapsdt
124///   Owner                Data size        Description
125///   stapsdt              0x00000039       NT_STAPSDT (SystemTap probe descriptors)
126///     Provider: opendal
127///     Name: create_dir_start
128///     Location: 0x00000000000f8f05, Base: 0x0000000000000000, Semaphore: 0x00000000003649f8
129///     Arguments: -8@%rax
130///   stapsdt              0x00000037       NT_STAPSDT (SystemTap probe descriptors)
131///     Provider: opendal
132///     Name: create_dir_end
133///     Location: 0x00000000000f9284, Base: 0x0000000000000000, Semaphore: 0x00000000003649fa
134///     Arguments: -8@%rax
135///   stapsdt              0x0000003c       NT_STAPSDT (SystemTap probe descriptors)
136///     Provider: opendal
137///     Name: blocking_list_start
138///     Location: 0x00000000000f9487, Base: 0x0000000000000000, Semaphore: 0x0000000000364a28
139///     Arguments: -8@%rax
140///   stapsdt              0x0000003a       NT_STAPSDT (SystemTap probe descriptors)
141///     Provider: opendal
142///     Name: blocking_list_end
143///     Location: 0x00000000000f9546, Base: 0x0000000000000000, Semaphore: 0x0000000000364a2a
144///     Arguments: -8@%rax
145///   stapsdt              0x0000003c       NT_STAPSDT (SystemTap probe descriptors)
146/// ```
147#[derive(Clone, Debug, Default)]
148#[non_exhaustive]
149pub struct DtraceLayer {}
150
151impl DtraceLayer {
152    /// Create a new [`DtraceLayer`].
153    pub fn new() -> Self {
154        Self::default()
155    }
156}
157
158impl Layer for DtraceLayer {
159    fn apply_service(&self, inner: Servicer) -> Servicer {
160        Arc::new(self.layer(inner))
161    }
162
163    fn apply_context(&self, _service: Servicer, inner: OperationContext) -> OperationContext {
164        let transport = HttpTransporter::new(DtraceHttpTransport {
165            inner: inner.http_transport().clone(),
166        });
167        inner.with_http_transport(transport)
168    }
169}
170
171impl DtraceLayer {
172    fn layer(&self, inner: Servicer) -> DTraceService {
173        DTraceService { inner }
174    }
175}
176
177struct DtraceHttpTransport {
178    inner: HttpTransporter,
179}
180
181macro_rules! http_probe {
182    ($name:ident $(, $arg:expr)*) => {{
183        #[cfg(test)]
184        tests::record_http_probe(stringify!($name));
185        probe!(opendal, $name $(, $arg)*);
186    }};
187}
188
189impl HttpTransport for DtraceHttpTransport {
190    async fn fetch(&self, request: http::Request<Buffer>) -> Result<http::Response<HttpBody>> {
191        http_probe!(http_request_start);
192        let response = self.inner.fetch(request).await.inspect_err(|_| {
193            http_probe!(http_request_error);
194        })?;
195        http_probe!(http_request_ok, response.status().as_u16());
196
197        Ok(response.map(|body| {
198            body.map_inner(|mut stream| {
199                Box::new(poll_fn(move |cx| {
200                    let result = stream.poll_next_unpin(cx);
201                    match &result {
202                        Poll::Ready(Some(Ok(chunk))) => {
203                            http_probe!(http_response_body_chunk, chunk.len());
204                        }
205                        Poll::Ready(Some(Err(_))) => {
206                            http_probe!(http_response_body_error);
207                        }
208                        Poll::Ready(None) => {
209                            http_probe!(http_response_body_end);
210                        }
211                        Poll::Pending => {}
212                    }
213                    result
214                }))
215            })
216        }))
217    }
218}
219
220#[doc(hidden)]
221#[derive(Debug)]
222pub struct DTraceService {
223    inner: Servicer,
224}
225
226impl Service for DTraceService {
227    type Reader = DtraceLayerWrapper<oio::Reader>;
228    type Writer = DtraceLayerWrapper<oio::Writer>;
229    type Lister = oio::Lister;
230    type Deleter = oio::Deleter;
231    type Copier = oio::Copier;
232    type Composer = oio::Composer;
233
234    fn info(&self) -> ServiceInfo {
235        self.inner.info()
236    }
237
238    fn capability(&self) -> Capability {
239        self.inner.capability()
240    }
241
242    fn compose(&self, ctx: &OperationContext, to: &str, args: OpCompose) -> Result<Self::Composer> {
243        self.inner.compose(ctx, to, args)
244    }
245
246    async fn create_dir(
247        &self,
248        ctx: &OperationContext,
249        path: &str,
250        args: OpCreateDir,
251    ) -> Result<RpCreateDir> {
252        let c_path = CString::new(path).unwrap();
253        probe_lazy!(opendal, create_dir_start, c_path.as_ptr());
254        let result = self.inner.create_dir(ctx, path, args).await;
255        probe_lazy!(opendal, create_dir_end, c_path.as_ptr());
256        result
257    }
258
259    fn read(&self, ctx: &OperationContext, path: &str, args: OpRead) -> Result<Self::Reader> {
260        let c_path = CString::new(path).unwrap();
261        probe_lazy!(opendal, read_start, c_path.as_ptr());
262        let result = self
263            .inner
264            .read(ctx, path, args)
265            .map(|r| DtraceLayerWrapper::new(r, path));
266        probe_lazy!(opendal, read_end, c_path.as_ptr());
267        result
268    }
269
270    fn write(&self, ctx: &OperationContext, path: &str, args: OpWrite) -> Result<Self::Writer> {
271        let c_path = CString::new(path).unwrap();
272        probe_lazy!(opendal, write_start, c_path.as_ptr());
273        let result = self
274            .inner
275            .write(ctx, path, args)
276            .map(|r| DtraceLayerWrapper::new(r, path));
277
278        probe_lazy!(opendal, write_end, c_path.as_ptr());
279        result
280    }
281
282    fn copy(
283        &self,
284        ctx: &OperationContext,
285        from: &str,
286        to: &str,
287        args: OpCopy,
288    ) -> Result<Self::Copier> {
289        let c_from = CString::new(from).unwrap();
290        probe_lazy!(opendal, copy_start, c_from.as_ptr());
291        let result = self.inner.copy(ctx, from, to, args);
292        probe_lazy!(opendal, copy_end, c_from.as_ptr());
293        result
294    }
295
296    async fn rename(
297        &self,
298        ctx: &OperationContext,
299        from: &str,
300        to: &str,
301        args: OpRename,
302    ) -> Result<RpRename> {
303        self.inner.rename(ctx, from, to, args).await
304    }
305
306    async fn restore(
307        &self,
308        ctx: &OperationContext,
309        path: &str,
310        args: OpRestore,
311    ) -> Result<RpRestore> {
312        self.inner.restore(ctx, path, args).await
313    }
314
315    async fn stat(&self, ctx: &OperationContext, path: &str, args: OpStat) -> Result<RpStat> {
316        let c_path = CString::new(path).unwrap();
317        probe_lazy!(opendal, stat_start, c_path.as_ptr());
318        let result = self.inner.stat(ctx, path, args).await;
319        probe_lazy!(opendal, stat_end, c_path.as_ptr());
320        result
321    }
322
323    fn delete(&self, ctx: &OperationContext) -> Result<Self::Deleter> {
324        self.inner.delete(ctx)
325    }
326
327    fn list(&self, ctx: &OperationContext, path: &str, args: OpList) -> Result<Self::Lister> {
328        let c_path = CString::new(path).unwrap();
329        probe_lazy!(opendal, list_start, c_path.as_ptr());
330        let result = self.inner.list(ctx, path, args);
331        probe_lazy!(opendal, list_end, c_path.as_ptr());
332        result
333    }
334
335    async fn presign(
336        &self,
337        ctx: &OperationContext,
338        path: &str,
339        args: OpPresign,
340    ) -> Result<RpPresign> {
341        let c_path = CString::new(path).unwrap();
342        probe_lazy!(opendal, presign_start, c_path.as_ptr());
343        let result = self.inner.presign(ctx, path, args).await;
344        probe_lazy!(opendal, presign_end, c_path.as_ptr());
345        result
346    }
347}
348
349#[doc(hidden)]
350pub struct DtraceLayerWrapper<R> {
351    inner: R,
352    path: String,
353    range: Option<BytesRange>,
354}
355
356impl<R> DtraceLayerWrapper<R> {
357    fn new(inner: R, path: &str) -> Self {
358        Self::with_range(inner, path, None)
359    }
360
361    fn with_range(inner: R, path: &str, range: Option<BytesRange>) -> Self {
362        Self {
363            inner,
364            path: path.to_string(),
365            range,
366        }
367    }
368
369    fn range_label(&self) -> String {
370        self.range
371            .map(|range| range.to_string())
372            .unwrap_or_default()
373    }
374}
375
376impl<R: oio::ReadStream> oio::ReadStream for DtraceLayerWrapper<R> {
377    async fn read(&mut self) -> Result<Buffer> {
378        let c_path = CString::new(self.path.clone()).unwrap();
379        let c_range = CString::new(self.range_label()).unwrap();
380        probe_lazy!(
381            opendal,
382            reader_read_start,
383            c_path.as_ptr(),
384            c_range.as_ptr()
385        );
386        match self.inner.read().await {
387            Ok(bs) => {
388                probe_lazy!(
389                    opendal,
390                    reader_read_ok,
391                    c_path.as_ptr(),
392                    c_range.as_ptr(),
393                    bs.remaining()
394                );
395                Ok(bs)
396            }
397            Err(e) => {
398                probe_lazy!(
399                    opendal,
400                    reader_read_error,
401                    c_path.as_ptr(),
402                    c_range.as_ptr()
403                );
404                Err(e)
405            }
406        }
407    }
408}
409
410impl<R: oio::Read> oio::Read for DtraceLayerWrapper<R> {
411    async fn open(&self, range: BytesRange) -> Result<(RpRead, Box<dyn oio::ReadStreamDyn>)> {
412        let c_path = CString::new(self.path.clone()).unwrap();
413        let c_range = CString::new(range.to_string()).unwrap();
414        probe_lazy!(
415            opendal,
416            reader_read_start,
417            c_path.as_ptr(),
418            c_range.as_ptr()
419        );
420        match self.inner.open(range).await {
421            Ok((rp, stream)) => {
422                probe_lazy!(
423                    opendal,
424                    reader_read_ok,
425                    c_path.as_ptr(),
426                    c_range.as_ptr(),
427                    0
428                );
429                Ok((
430                    rp,
431                    Box::new(DtraceLayerWrapper::with_range(
432                        stream,
433                        &self.path,
434                        Some(range),
435                    )) as Box<dyn oio::ReadStreamDyn>,
436                ))
437            }
438            Err(e) => {
439                probe_lazy!(
440                    opendal,
441                    reader_read_error,
442                    c_path.as_ptr(),
443                    c_range.as_ptr()
444                );
445                Err(e)
446            }
447        }
448    }
449
450    async fn read(&self, range: BytesRange) -> Result<(RpRead, Buffer)> {
451        let c_path = CString::new(self.path.clone()).unwrap();
452        let c_range = CString::new(range.to_string()).unwrap();
453        probe_lazy!(
454            opendal,
455            reader_read_start,
456            c_path.as_ptr(),
457            c_range.as_ptr()
458        );
459        match self.inner.read(range).await {
460            Ok((rp, buffer)) => {
461                probe_lazy!(
462                    opendal,
463                    reader_read_ok,
464                    c_path.as_ptr(),
465                    c_range.as_ptr(),
466                    buffer.len()
467                );
468                Ok((rp, buffer))
469            }
470            Err(e) => {
471                probe_lazy!(
472                    opendal,
473                    reader_read_error,
474                    c_path.as_ptr(),
475                    c_range.as_ptr()
476                );
477                Err(e)
478            }
479        }
480    }
481}
482
483impl<R: oio::Write> oio::Write for DtraceLayerWrapper<R> {
484    async fn write(&mut self, bs: Buffer) -> Result<()> {
485        let c_path = CString::new(self.path.clone()).unwrap();
486        probe_lazy!(opendal, writer_write_start, c_path.as_ptr());
487        self.inner
488            .write(bs)
489            .await
490            .map(|_| {
491                probe_lazy!(opendal, writer_write_ok, c_path.as_ptr());
492            })
493            .inspect_err(|_| {
494                probe_lazy!(opendal, writer_write_error, c_path.as_ptr());
495            })
496    }
497
498    async fn copy_from(&mut self, path: &str, args: OpRead, range: BytesRange) -> Result<()> {
499        let c_path = CString::new(self.path.clone()).unwrap();
500        probe_lazy!(opendal, writer_write_start, c_path.as_ptr());
501        self.inner
502            .copy_from(path, args, range)
503            .await
504            .map(|_| {
505                probe_lazy!(opendal, writer_write_ok, c_path.as_ptr());
506            })
507            .inspect_err(|_| {
508                probe_lazy!(opendal, writer_write_error, c_path.as_ptr());
509            })
510    }
511
512    async fn abort(&mut self) -> Result<()> {
513        let c_path = CString::new(self.path.clone()).unwrap();
514        probe_lazy!(opendal, writer_poll_abort_start, c_path.as_ptr());
515        self.inner
516            .abort()
517            .await
518            .map(|_| {
519                probe_lazy!(opendal, writer_poll_abort_ok, c_path.as_ptr());
520            })
521            .inspect_err(|_| {
522                probe_lazy!(opendal, writer_poll_abort_error, c_path.as_ptr());
523            })
524    }
525
526    async fn close(&mut self) -> Result<Metadata> {
527        let c_path = CString::new(self.path.clone()).unwrap();
528        probe_lazy!(opendal, writer_close_start, c_path.as_ptr());
529        self.inner
530            .close()
531            .await
532            .inspect(|_| {
533                probe_lazy!(opendal, writer_close_ok, c_path.as_ptr());
534            })
535            .inspect_err(|_| {
536                probe_lazy!(opendal, writer_close_error, c_path.as_ptr());
537            })
538    }
539}