Skip to main content

grow_apache_skywalking/
logs.rs

1// Service code (Apache SkyWalking): native log exporter and the LogQueryClient.
2//! Logging for SkyWalking: the native log exporter (`POST /v3/logs`, carries the trace context)
3//! and the SPEC §4 `LogQueryClient` over GraphQL `queryLogs` with client-side text filtering
4//! (OAP on BanyanDB ignores content keywords).
5
6use std::collections::BTreeMap;
7use std::sync::atomic::{AtomicBool, Ordering};
8use std::sync::{Arc, LazyLock};
9use std::time::SystemTime;
10
11use async_trait::async_trait;
12use regex::Regex;
13use serde_json::{json, Value};
14
15use crate::api::Api;
16use crate::core::{Error, Result};
17use crate::duration::{epoch_ms, from_epoch_ms, Step, TimeRange, DEFAULT_RANGE};
18use crate::logging::{
19    poll_tail, AttrValue, Attributes, ExportOptions, ExportResult, LogExporter, LogQueryClient,
20    LogRecord, LogSearchResult, RecordCallback, SearchOptions, Severity, SortOrder, TailHandle,
21    TailOptions,
22};
23use crate::query::{LogOrder, NativeLog, Paging, QueryLogsOptions, SkyWalkingQueryClient};
24
25/// Service name used when a record has no `service.name` resource attribute.
26pub const DEFAULT_LOG_SERVICE_NAME: &str = "unknown_service";
27/// Raw page size used while filtering free text client side.
28pub const LOG_SCAN_PAGE_SIZE: usize = 1000;
29/// Default number of raw pages one `search` call may scan.
30pub const DEFAULT_MAX_SCAN_PAGES: usize = 10;
31
32fn is_lower_hex(s: &str, len: usize) -> bool {
33    s.len() == len && s.bytes().all(|b| matches!(b, b'0'..=b'9' | b'a'..=b'f'))
34}
35
36/// Converts an attribute value to SkyWalking's string tag form (JSON for arrays/objects).
37pub fn tag_text(value: &AttrValue) -> String {
38    match value {
39        AttrValue::String(s) => s.clone(),
40        other => other.to_string(),
41    }
42}
43
44/// Maps a SPEC [`LogRecord`] to native `LogData` JSON: `resource["service.name"]` →
45/// `service`, `service.instance.id` → `serviceInstance`, body → `body.text.text`,
46/// `severity_text` → tag `level`, attributes (stringified, nested values as JSON) → tags,
47/// `trace_id` → `traceContext.traceId` (enables `relatedTrace` queries), `span_id` → tag
48/// `span_id`.
49pub fn record_to_log_data(record: &LogRecord, default_service: &str) -> Value {
50    let level = if record.severity_text.is_empty() {
51        record.severity.text().to_owned()
52    } else {
53        record.severity_text.clone()
54    };
55    let mut tags = vec![json!({ "key": "level", "value": level })];
56    for (key, value) in &record.attributes {
57        if key != "level" {
58            tags.push(json!({ "key": key, "value": tag_text(value) }));
59        }
60    }
61    if let Some(span) = record.span_id.as_deref().filter(|s| !s.is_empty()) {
62        tags.push(json!({ "key": "span_id", "value": span }));
63    }
64    let mut out = json!({
65        "timestamp": epoch_ms(record.timestamp),
66        "service": record
67            .resource
68            .get("service.name")
69            .map(tag_text)
70            .unwrap_or_else(|| default_service.to_owned()),
71        "body": { "text": { "text": record.body } },
72        "tags": { "data": tags },
73        "layer": "GENERAL",
74    });
75    if let Some(instance) = record.resource.get("service.instance.id") {
76        out["serviceInstance"] = Value::String(tag_text(instance));
77    }
78    if let Some(trace) = record.trace_id.as_deref().filter(|s| !s.is_empty()) {
79        out["traceContext"] = json!({ "traceId": trace });
80    }
81    out
82}
83
84/// Maps a stored log back to a SPEC [`LogRecord`]: tag `level` → severity / severity text
85/// (default INFO), `span_id` → `span_id` (16 hex), a 32-hex trace id → `trace_id` (native trace
86/// ids go to attribute `sw.trace_id`), other tags → attributes (strings), service/instance →
87/// resource `service.name` / `service.instance.id`, endpoint → resource `sw.endpoint`.
88pub fn log_to_record(log: &NativeLog) -> LogRecord {
89    let mut attributes = Attributes::new();
90    let mut level: Option<String> = None;
91    let mut span_id: Option<String> = None;
92    for kv in &log.tags {
93        if kv.key == "level" {
94            level = Some(kv.value.clone());
95        } else if kv.key == "span_id" && is_lower_hex(&kv.value, 16) {
96            span_id = Some(kv.value.clone());
97        } else {
98            attributes.insert(kv.key.clone(), AttrValue::String(kv.value.clone()));
99        }
100    }
101    let mut resource = Attributes::new();
102    resource.insert(
103        "service.name".into(),
104        AttrValue::String(log.service_name.clone()),
105    );
106    if !log.service_instance_name.is_empty() {
107        resource.insert(
108            "service.instance.id".into(),
109            AttrValue::String(log.service_instance_name.clone()),
110        );
111    }
112    if !log.endpoint_name.is_empty() {
113        resource.insert(
114            "sw.endpoint".into(),
115            AttrValue::String(log.endpoint_name.clone()),
116        );
117    }
118    let severity = level
119        .as_deref()
120        .and_then(|l| l.parse::<Severity>().ok())
121        .unwrap_or(Severity::Info);
122    let trace = log.trace_id.to_ascii_lowercase();
123    let trace_id = if is_lower_hex(&trace, 32) {
124        Some(trace)
125    } else {
126        if !log.trace_id.is_empty() {
127            attributes.insert(
128                "sw.trace_id".into(),
129                AttrValue::String(log.trace_id.clone()),
130            );
131        }
132        None
133    };
134    LogRecord {
135        timestamp: from_epoch_ms(log.timestamp),
136        observed_timestamp: None,
137        severity,
138        severity_text: level.unwrap_or_else(|| "INFO".to_owned()),
139        body: log.content.clone(),
140        attributes,
141        resource,
142        trace_id,
143        span_id,
144        trace_flags: None,
145    }
146}
147
148/// [`LogExporter`] that posts batches to OAP's native log API (`POST /v3/logs`, JSON array,
149/// port 12800). Native logs carry the trace context, register the service and are queryable a
150/// few seconds later. The body is sent uncompressed (gzip is not verified on OAP's HTTP
151/// receiver), whatever `ExportOptions::gzip` says.
152#[derive(Debug)]
153pub struct SkyWalkingLogExporter {
154    api: Arc<Api>,
155    service_name: String,
156    owns_transport: bool,
157    shutdown: AtomicBool,
158}
159
160impl SkyWalkingLogExporter {
161    pub(crate) fn new(api: Arc<Api>, service_name: Option<String>, owns_transport: bool) -> Self {
162        SkyWalkingLogExporter {
163            api,
164            service_name: service_name.unwrap_or_else(|| DEFAULT_LOG_SERVICE_NAME.to_owned()),
165            owns_transport,
166            shutdown: AtomicBool::new(false),
167        }
168    }
169
170    /// Service name used for records without `service.name`.
171    pub fn service_name(&self) -> &str {
172        &self.service_name
173    }
174}
175
176#[async_trait]
177impl LogExporter for SkyWalkingLogExporter {
178    async fn export(&self, records: &[LogRecord], _opts: ExportOptions) -> Result<ExportResult> {
179        if records.is_empty() {
180            return Ok(ExportResult::accepted(0));
181        }
182        let body: Vec<Value> = records
183            .iter()
184            .map(|r| record_to_log_data(r, &self.service_name))
185            .collect();
186        self.api
187            .transport
188            .post("/v3/logs")
189            .operation("logging.export")
190            .json(&body)
191            .send()
192            .await?;
193        Ok(ExportResult::accepted(records.len()))
194    }
195
196    async fn shutdown(&self) -> Result<()> {
197        if !self.shutdown.swap(true, Ordering::SeqCst) && self.owns_transport {
198            self.api.transport.close();
199        }
200        Ok(())
201    }
202}
203
204/// Parsed form of a log search query (see [`parse_log_query`]).
205#[derive(Debug, Clone, Default, PartialEq, Eq)]
206pub struct ParsedLogQuery {
207    /// `service=`.
208    pub service: Option<String>,
209    /// `instance=`.
210    pub instance: Option<String>,
211    /// `endpoint=`.
212    pub endpoint: Option<String>,
213    /// `trace_id=` / `traceId=`.
214    pub trace_id: Option<String>,
215    /// Server-side tag filters (allow-listed keys only).
216    pub tags: BTreeMap<String, String>,
217    /// Free-text terms, matched client side.
218    pub text: Vec<String>,
219}
220
221static TOKEN: LazyLock<Regex> = LazyLock::new(|| {
222    Regex::new(r#"([A-Za-z_][\w.-]*)=(?:"([^"]*)"|(\S+))|"([^"]*)"|(\S+)"#).expect("valid regex")
223});
224
225/// Parses the log query syntax: space-separated `key=value` terms (`service=`, `instance=`,
226/// `endpoint=`, `trace_id=`/`traceId=` map to the GraphQL condition; any other key is a server
227/// tag filter and must be in `SW_SEARCHABLE_LOGS_TAG_KEYS`) plus free-text terms (`"quoted
228/// phrases"` allowed). Every free-text term must occur (case-insensitive) in the content or in
229/// a tag value.
230pub fn parse_log_query(query: &str) -> ParsedLogQuery {
231    let mut out = ParsedLogQuery::default();
232    for m in TOKEN.captures_iter(query) {
233        if let Some(key) = m.get(1) {
234            let value = m
235                .get(2)
236                .or_else(|| m.get(3))
237                .map(|v| v.as_str().to_owned())
238                .unwrap_or_default();
239            match key.as_str() {
240                "service" => out.service = Some(value),
241                "instance" => out.instance = Some(value),
242                "endpoint" => out.endpoint = Some(value),
243                "trace_id" | "traceId" => out.trace_id = Some(value),
244                other => {
245                    out.tags.insert(other.to_owned(), value);
246                }
247            }
248        } else {
249            let text = m
250                .get(4)
251                .or_else(|| m.get(5))
252                .map(|v| v.as_str())
253                .unwrap_or_default();
254            if !text.is_empty() {
255                out.text.push(text.to_owned());
256            }
257        }
258    }
259    out
260}
261
262/// True when every term occurs (case-insensitive) in the log content or one of its tag values.
263pub fn matches_text(log: &NativeLog, terms: &[String]) -> bool {
264    if terms.is_empty() {
265        return true;
266    }
267    let mut haystack = log.content.to_lowercase();
268    for t in &log.tags {
269        haystack.push('\n');
270        haystack.push_str(&t.value.to_lowercase());
271    }
272    terms.iter().all(|t| haystack.contains(&t.to_lowercase()))
273}
274
275fn decode_cursor(cursor: &str) -> Result<(usize, usize, usize)> {
276    let bad = || Error::validation("logging.search: invalid cursor");
277    let parts: Vec<&str> = cursor.split(':').collect();
278    if parts.len() != 3
279        || parts
280            .iter()
281            .any(|p| p.is_empty() || !p.bytes().all(|b| b.is_ascii_digit()))
282    {
283        return Err(bad());
284    }
285    let n = |s: &str| s.parse::<usize>().map_err(|_| bad());
286    let (page, offset, size) = (n(parts[0])?, n(parts[1])?, n(parts[2])?);
287    if page < 1 || !(1..=10_000).contains(&size) {
288        return Err(bad());
289    }
290    Ok((page, offset, size))
291}
292
293/// [`LogQueryClient`] for SkyWalking (GraphQL `queryLogs`). Free-text terms are filtered client
294/// side: `search` reads raw pages of 1000 logs (newest first by default) and keeps the matching
295/// ones until `limit` matches or `max_scan_pages` pages; `next_cursor` (`"page:offset:size"`)
296/// continues where it stopped. Without free text the page size is `limit` and nothing is
297/// filtered except the exact time window. Default window: the last hour. `tail` polls `search`.
298/// Obtain it from [`SkyWalkingClient::logs`](crate::SkyWalkingClient::logs). Cheap to clone.
299#[derive(Debug, Clone)]
300pub struct SkyWalkingLogQueryClient {
301    query: SkyWalkingQueryClient,
302    max_scan_pages: usize,
303}
304
305impl SkyWalkingLogQueryClient {
306    pub(crate) fn new(query: SkyWalkingQueryClient) -> Self {
307        SkyWalkingLogQueryClient {
308            query,
309            max_scan_pages: DEFAULT_MAX_SCAN_PAGES,
310        }
311    }
312
313    /// The same client with another raw-page budget per `search` call (default 10, ≥ 1).
314    pub fn with_max_scan_pages(&self, pages: usize) -> Result<Self> {
315        if pages < 1 {
316            return Err(Error::validation(
317                "logging: maxScanPages must be a positive integer",
318            ));
319        }
320        Ok(SkyWalkingLogQueryClient {
321            query: self.query.clone(),
322            max_scan_pages: pages,
323        })
324    }
325}
326
327#[async_trait]
328impl LogQueryClient for SkyWalkingLogQueryClient {
329    async fn search(&self, query: &str, opts: SearchOptions) -> Result<LogSearchResult> {
330        let operation = "logging.search";
331        let limit = opts.limit;
332        if !(1..=10_000).contains(&limit) {
333            return Err(Error::validation(format!(
334                "{operation}: limit must be 1..10000"
335            )));
336        }
337        let parsed = parse_log_query(query);
338        let end_ms = epoch_ms(opts.end.unwrap_or_else(SystemTime::now));
339        let start_ms = opts
340            .start
341            .map(epoch_ms)
342            .unwrap_or(end_ms - DEFAULT_RANGE.as_millis() as i64);
343        if start_ms > end_ms {
344            return Err(Error::validation(format!(
345                "{operation}: invalid time window"
346            )));
347        }
348        let (mut page, mut offset, size) = match &opts.cursor {
349            Some(c) => decode_cursor(c)?,
350            None => (
351                1,
352                0,
353                if parsed.text.is_empty() {
354                    limit
355                } else {
356                    LOG_SCAN_PAGE_SIZE
357                },
358            ),
359        };
360        let base = QueryLogsOptions {
361            service: parsed.service.clone(),
362            instance: parsed.instance.clone(),
363            endpoint: parsed.endpoint.clone(),
364            trace_id: parsed.trace_id.clone(),
365            tags: parsed.tags.clone(),
366            range: Some(TimeRange {
367                start: Some(from_epoch_ms(start_ms)),
368                end: Some(from_epoch_ms(end_ms)),
369                step: Some(Step::Minute),
370            }),
371            order: match opts.order {
372                SortOrder::Asc => LogOrder::Asc,
373                SortOrder::Desc => LogOrder::Des,
374            },
375            ..Default::default()
376        };
377        let mut records = Vec::new();
378        for _ in 0..self.max_scan_pages {
379            let mut q = base.clone();
380            q.paging = Paging::new(page, size);
381            let logs = self.query.query_logs(&q).await?.logs;
382            for (i, log) in logs.iter().enumerate().skip(offset) {
383                if log.timestamp < start_ms
384                    || log.timestamp > end_ms
385                    || !matches_text(log, &parsed.text)
386                {
387                    continue;
388                }
389                records.push(log_to_record(log));
390                if records.len() >= limit {
391                    let next_cursor = if i + 1 < logs.len() {
392                        Some(format!("{page}:{}:{size}", i + 1))
393                    } else if logs.len() >= size {
394                        Some(format!("{}:0:{size}", page + 1))
395                    } else {
396                        None
397                    };
398                    return Ok(LogSearchResult {
399                        records,
400                        next_cursor,
401                        total: None,
402                    });
403                }
404            }
405            if logs.len() < size {
406                return Ok(LogSearchResult {
407                    records,
408                    next_cursor: None,
409                    total: None,
410                });
411            }
412            page += 1;
413            offset = 0;
414        }
415        Ok(LogSearchResult {
416            records,
417            next_cursor: Some(format!("{page}:0:{size}")),
418            total: None,
419        })
420    }
421
422    /// Polls `search` oldest-first (see [`poll_tail`]); SkyWalking has no streaming API.
423    async fn tail(
424        &self,
425        query: &str,
426        on_record: RecordCallback,
427        opts: TailOptions,
428    ) -> Result<TailHandle> {
429        Ok(poll_tail(Arc::new(self.clone()), query, on_record, opts))
430    }
431
432    /// Service names known to OAP (SkyWalking has no streams; the service is the equivalent).
433    async fn list_streams(&self) -> Result<Vec<String>> {
434        let mut names: Vec<String> = self
435            .query
436            .list_services(None, None)
437            .await?
438            .into_iter()
439            .filter(|s| s.normal)
440            .map(|s| s.name)
441            .collect();
442        names.sort();
443        names.dedup();
444        Ok(names)
445    }
446
447    /// Log tag keys seen in the last hour (`queryLogTagAutocompleteKeys`).
448    async fn list_labels(&self) -> Result<Vec<String>> {
449        self.query.list_log_tag_keys(None).await
450    }
451}