grow-apache-skywalking 0.2.0

Rust SDK for Apache SkyWalking by Grow Codes
Documentation
// Generated by sdk-kit 0.3.0 — do not edit; change sdk-kit and run "sdk-kit sync"
//! Trace query interface (SPEC §5 `TraceQueryClient`) and `wait_for_trace`.

use std::time::{Duration, SystemTime};

use async_trait::async_trait;

use super::{normalize_trace_id, DependencyLink, Trace, TraceSearchQuery, TraceSummary};
use crate::core::{poll_until, Error, PollOptions, Result};

/// Time range for [`TraceQueryClient::get_dependencies`].
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DependencyOptions {
    /// Range start.
    pub start: Option<SystemTime>,
    /// Range end.
    pub end: Option<SystemTime>,
}

/// Options for [`wait_for_trace`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct WaitForTraceOptions {
    /// Give up after this long (default 30 s) with `TIMEOUT`.
    pub timeout: Duration,
    /// Delay between lookups (default 1 s).
    pub interval: Duration,
    /// Wait until the trace has at least this many spans (default 1).
    pub min_spans: usize,
}

impl Default for WaitForTraceOptions {
    fn default() -> Self {
        WaitForTraceOptions {
            timeout: Duration::from_secs(30),
            interval: Duration::from_secs(1),
            min_spans: 1,
        }
    }
}

impl WaitForTraceOptions {
    /// Sets the timeout.
    pub fn timeout(mut self, d: Duration) -> Self {
        self.timeout = d;
        self
    }
    /// Sets the interval.
    pub fn interval(mut self, d: Duration) -> Self {
        self.interval = d;
        self
    }
    /// Sets the minimum span count.
    pub fn min_spans(mut self, n: usize) -> Self {
        self.min_spans = n;
        self
    }
}

/// Queries a tracing backend (SPEC §5). Methods a service cannot serve return `UNSUPPORTED`.
#[async_trait]
pub trait TraceQueryClient: Send + Sync {
    /// One trace by id; `None` when unknown.
    async fn get_trace(&self, trace_id: &str) -> Result<Option<Trace>>;
    /// Trace summaries matching the query.
    async fn search_traces(&self, query: &TraceSearchQuery) -> Result<Vec<TraceSummary>>;
    /// Services that reported spans.
    async fn list_services(&self) -> Result<Vec<String>>;
    /// Operations (span names) of a service.
    async fn list_operations(&self, service: &str) -> Result<Vec<String>>;
    /// Service dependency graph.
    async fn get_dependencies(&self, opts: DependencyOptions) -> Result<Vec<DependencyLink>> {
        let _ = opts;
        Err(Error::unsupported(
            "traces.getDependencies: not supported by this service",
        ))
    }
    /// Polls [`get_trace`](Self::get_trace) until the trace has `min_spans` spans.
    async fn wait_for_trace(&self, trace_id: &str, opts: WaitForTraceOptions) -> Result<Trace> {
        wait_for_trace(self, trace_id, opts).await
    }
}

/// Polls `client.get_trace` until the trace exists with at least `opts.min_spans` spans;
/// `TIMEOUT` otherwise. The id is normalized first (`VALIDATION` when malformed).
pub async fn wait_for_trace<C>(
    client: &C,
    trace_id: &str,
    opts: WaitForTraceOptions,
) -> Result<Trace>
where
    C: TraceQueryClient + ?Sized,
{
    wait_for_trace_with(client, trace_id, opts, normalize_trace_id).await
}

/// Like [`wait_for_trace`] with a custom id normalizer, e.g.
/// [`normalize_trace_id_or_native`](super::normalize_trace_id_or_native) for backends with
/// native ids, or `|id| Ok(id.to_owned())` to pass the id through unchanged.
pub async fn wait_for_trace_with<C, N>(
    client: &C,
    trace_id: &str,
    opts: WaitForTraceOptions,
    normalize: N,
) -> Result<Trace>
where
    C: TraceQueryClient + ?Sized,
    N: Fn(&str) -> Result<String>,
{
    let id = normalize(trace_id)?;
    let poll = PollOptions {
        timeout: opts.timeout,
        interval: opts.interval,
    };
    poll_until("traces.waitForTrace", poll, || async {
        Ok(client
            .get_trace(&id)
            .await?
            .filter(|t| t.spans.len() >= opts.min_spans))
    })
    .await
}