Skip to main content

archivist_lib/logs/
container.rs

1// Copyright 2020 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use crate::identity::ComponentIdentity;
6use crate::logs::shared_buffer::ContainerBuffer;
7use crate::logs::stats::LogStreamStats;
8use crate::logs::stored_message::StoredMessage;
9use derivative::Derivative;
10use fidl::endpoints::RequestStream;
11use fidl_fuchsia_diagnostics::LogInterestSelector;
12use fidl_fuchsia_diagnostics_types::{Interest as FidlInterest, Severity as FidlSeverity};
13use fidl_fuchsia_logger::{LogSinkOnInitRequest, LogSinkRequest, LogSinkRequestStream};
14use fuchsia_async as fasync;
15use fuchsia_async::condition::Condition;
16use futures::future::{Fuse, FusedFuture};
17use futures::prelude::*;
18use futures::select;
19use futures::stream::StreamExt;
20use log::{debug, error};
21use selectors::SelectorExt;
22use std::cmp::Ordering;
23use std::collections::BTreeMap;
24use std::pin::pin;
25use std::sync::Arc;
26use std::task::Poll;
27
28pub type OnInactive = Box<dyn Fn(&LogsArtifactsContainer) + Send + Sync>;
29
30#[derive(Derivative)]
31#[derivative(Debug)]
32pub struct LogsArtifactsContainer {
33    /// The source of logs in this container.
34    pub identity: Arc<ComponentIdentity>,
35
36    /// Inspect instrumentation.
37    pub stats: Arc<LogStreamStats>,
38
39    /// Buffer for all log messages.
40    #[derivative(Debug = "ignore")]
41    buffer: ContainerBuffer,
42
43    /// Mutable state for the container.
44    #[derivative(Debug = "ignore")]
45    state: Arc<Condition<ContainerState>>,
46
47    /// A callback which is called when the container is inactive i.e. has no channels, sockets or
48    /// stored logs.
49    #[derivative(Debug = "ignore")]
50    on_inactive: Option<OnInactive>,
51}
52
53#[derive(Debug)]
54struct ContainerState {
55    /// Number of LogSink channels currently being listened to for this component.
56    num_active_channels: u64,
57
58    /// Current interest for this component.
59    interests: BTreeMap<Interest, usize>,
60
61    is_initializing: bool,
62}
63
64impl LogsArtifactsContainer {
65    pub fn new<'a>(
66        identity: Arc<ComponentIdentity>,
67        interest_selectors: impl Iterator<Item = &'a LogInterestSelector>,
68        initial_interest: Option<FidlSeverity>,
69        stats: Arc<LogStreamStats>,
70        buffer: ContainerBuffer,
71        on_inactive: Option<OnInactive>,
72    ) -> Self {
73        let mut interests = BTreeMap::new();
74        if let Some(severity) = initial_interest {
75            interests.insert(Interest::from(severity), 1);
76        }
77        let new = Self {
78            identity,
79            buffer,
80            state: Arc::new(Condition::new(ContainerState {
81                num_active_channels: 0,
82                interests,
83                is_initializing: true,
84            })),
85            stats,
86            on_inactive,
87        };
88
89        // there are no control handles so this won't notify anyone
90        new.update_interest(interest_selectors, &[]);
91
92        new
93    }
94
95    /// Handle `LogSink` protocol on `stream`. Each socket received from the `LogSink` client is
96    /// drained by a `Task` which is sent on `sender`. The `Task`s do not complete until their
97    /// sockets have been closed.
98    pub fn handle_log_sink(
99        self: &Arc<Self>,
100        stream: LogSinkRequestStream,
101        scope: fasync::ScopeHandle,
102    ) {
103        if stream
104            .control_handle()
105            .send_on_init(LogSinkOnInitRequest {
106                buffer: Some(self.buffer.iob()),
107                interest: Some(self.state.lock().min_interest()),
108                ..Default::default()
109            })
110            .is_err()
111        {
112            return;
113        }
114
115        {
116            let mut guard = self.state.lock();
117            guard.num_active_channels += 1;
118            guard.is_initializing = false;
119        }
120        scope.spawn(Arc::clone(self).actually_handle_log_sink(stream));
121    }
122
123    /// This function does not return until the channel is closed.
124    async fn actually_handle_log_sink(self: Arc<Self>, mut stream: LogSinkRequestStream) {
125        let mut previous_interest_sent = None;
126        debug!(identity:% = self.identity; "Draining LogSink channel.");
127
128        let mut hanging_gets = Vec::new();
129        let mut interest_changed = pin!(Fuse::terminated());
130
131        loop {
132            select! {
133                next = stream.next() => {
134                    let Some(next) = next else { break };
135                    match next {
136                        Ok(LogSinkRequest::WaitForInterestChange { responder }) => {
137                            // If the interest has changed since we last reported it, we'll report
138                            // it below.
139                            hanging_gets.push(responder);
140                        }
141                        Err(e) => error!(identity:% = self.identity, e:%; "error handling log sink"),
142                        Ok(LogSinkRequest::_UnknownMethod { .. }) => {}
143                    }
144                }
145                _ = interest_changed => {}
146            }
147
148            if !hanging_gets.is_empty() {
149                let min_interest = self.state.lock().min_interest();
150                if Some(&min_interest) != previous_interest_sent.as_ref() {
151                    // Send updates to all outstanding hanging gets.
152                    for responder in hanging_gets.drain(..) {
153                        let _ = responder.send(Ok(&min_interest));
154                    }
155                    interest_changed.set(Fuse::terminated());
156                    previous_interest_sent = Some(min_interest);
157                } else if interest_changed.is_terminated() {
158                    // Set ourselves up to be woken when the interest changes.
159                    let previous_interest_sent = previous_interest_sent.clone();
160                    interest_changed.set(
161                        self.state
162                            .when(move |state| {
163                                if previous_interest_sent != Some(state.min_interest()) {
164                                    Poll::Ready(())
165                                } else {
166                                    Poll::Pending
167                                }
168                            })
169                            .fuse(),
170                    );
171                }
172            }
173        }
174
175        debug!(identity:% = self.identity; "LogSink channel closed.");
176        self.state.lock().num_active_channels -= 1;
177        self.check_inactive();
178    }
179
180    /// Updates log stats in inspect and push the message onto the container's buffer.
181    pub fn ingest_message(&self, message: StoredMessage) {
182        self.buffer.push_back(message.bytes());
183    }
184
185    /// Set the `Interest` for this component, notifying all active `LogSink/WaitForInterestChange`
186    /// hanging gets with the new interset if it is a change from the previous interest.
187    /// For any match that is also contained in `previous_selectors`, the previous values will be
188    /// removed from the set of interests.
189    pub fn update_interest<'a>(
190        &self,
191        interest_selectors: impl Iterator<Item = &'a LogInterestSelector>,
192        previous_selectors: &[LogInterestSelector],
193    ) {
194        let mut new_interest = FidlInterest::default();
195        let mut remove_interest = FidlInterest::default();
196        for selector in interest_selectors {
197            if self
198                .identity
199                .moniker
200                .matches_component_selector(&selector.selector)
201                .unwrap_or_default()
202            {
203                new_interest = selector.interest.clone();
204                // If there are more matches, ignore them, we'll pick the first match.
205                break;
206            }
207        }
208
209        if let Some(previous_selector) = previous_selectors.iter().find(|s| {
210            self.identity.moniker.matches_component_selector(&s.selector).unwrap_or_default()
211        }) {
212            remove_interest = previous_selector.interest.clone();
213        }
214
215        let mut state = self.state.lock();
216        // Unfortunately we cannot use a match statement since `FidlInterest` doesn't derive Eq.
217        // It does derive PartialEq though. All these branches will send an interest update if the
218        // minimum interest changes after performing the required actions.
219        if new_interest == FidlInterest::default() && remove_interest != FidlInterest::default() {
220            state.erase(&remove_interest);
221        } else if new_interest != FidlInterest::default()
222            && remove_interest == FidlInterest::default()
223        {
224            state.push_interest(new_interest);
225        } else if new_interest != FidlInterest::default()
226            && remove_interest != FidlInterest::default()
227        {
228            state.erase(&remove_interest);
229            state.push_interest(new_interest);
230        } else {
231            return;
232        }
233
234        for waker in state.drain_wakers() {
235            waker.wake();
236        }
237    }
238
239    /// Resets the `Interest` for this component, notifying all active
240    /// `LogSink/WaitForInterestChange` hanging gets with the lowest interest found in the set of
241    /// requested interests for all control handles.
242    pub fn reset_interest(&self, interest_selectors: &[LogInterestSelector]) {
243        for selector in interest_selectors {
244            if self
245                .identity
246                .moniker
247                .matches_component_selector(&selector.selector)
248                .unwrap_or_default()
249            {
250                let mut state = self.state.lock();
251                state.erase(&selector.interest);
252                for waker in state.drain_wakers() {
253                    waker.wake();
254                }
255                return;
256            }
257        }
258    }
259
260    /// Returns `true` if this container corresponds to a running component, or still has pending
261    /// objects to drain.
262    pub fn is_active(&self) -> bool {
263        let state = self.state.lock();
264        state.is_initializing || state.num_active_channels > 0 || self.buffer.is_active()
265    }
266
267    /// Called whenever there's a transition that means the component might no longer be active.
268    fn check_inactive(&self) {
269        if !self.is_active()
270            && let Some(on_inactive) = &self.on_inactive
271        {
272            on_inactive(self);
273        }
274    }
275
276    /// Stop accepting new messages, ensuring that pending Cursors return Poll::Ready(None) after
277    /// consuming any messages received before this call.
278    pub fn terminate(&self) {
279        self.buffer.terminate();
280    }
281
282    #[cfg(test)]
283    pub fn mark_stopped(&self) {
284        self.state.lock().is_initializing = false;
285        self.check_inactive();
286    }
287
288    pub fn buffer(&self) -> &ContainerBuffer {
289        &self.buffer
290    }
291}
292
293impl ContainerState {
294    /// Pushes the given `interest` to the set.
295    fn push_interest(&mut self, interest: FidlInterest) {
296        if interest != FidlInterest::default() {
297            let count = self.interests.entry(interest.into()).or_insert(0);
298            *count += 1;
299        }
300    }
301
302    /// Removes the given `interest` from the set
303    fn erase(&mut self, interest: &FidlInterest) {
304        let interest = interest.clone().into();
305        if let Some(count) = self.interests.get_mut(&interest) {
306            if *count <= 1 {
307                self.interests.remove(&interest);
308            } else {
309                *count -= 1;
310            }
311        }
312    }
313
314    /// Returns a copy of the lowest interest in the set. If the set is empty, an EMPTY interest is
315    /// returned.
316    fn min_interest(&self) -> FidlInterest {
317        // btreemap: keys are sorted and ascending.
318        self.interests.keys().next().map(|i| i.0.clone()).unwrap_or_default()
319    }
320}
321
322#[derive(Debug, PartialEq)]
323struct Interest(FidlInterest);
324
325impl From<FidlInterest> for Interest {
326    fn from(interest: FidlInterest) -> Interest {
327        Interest(interest)
328    }
329}
330
331impl From<FidlSeverity> for Interest {
332    fn from(severity: FidlSeverity) -> Interest {
333        Interest(FidlInterest { min_severity: Some(severity), ..Default::default() })
334    }
335}
336
337impl std::ops::Deref for Interest {
338    type Target = FidlInterest;
339    fn deref(&self) -> &Self::Target {
340        &self.0
341    }
342}
343
344impl Eq for Interest {}
345
346impl Ord for Interest {
347    fn cmp(&self, other: &Self) -> Ordering {
348        self.min_severity.cmp(&other.min_severity)
349    }
350}
351
352impl PartialOrd for Interest {
353    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
354        Some(self.cmp(other))
355    }
356}
357
358#[cfg(test)]
359mod tests {
360    use super::*;
361    use crate::logs::shared_buffer::{SharedBuffer, create_ring_buffer};
362    use fidl_fuchsia_diagnostics::{ComponentSelector, StringSelector};
363    use fidl_fuchsia_diagnostics_types::Severity;
364    use fidl_fuchsia_logger::{LogSinkMarker, LogSinkProxy};
365    use fuchsia_async::{Task, TestExecutor};
366    use fuchsia_inspect as inspect;
367    use moniker::ExtendedMoniker;
368
369    fn initialize_container(
370        severity: Option<Severity>,
371        scope: fasync::ScopeHandle,
372    ) -> (Arc<LogsArtifactsContainer>, LogSinkProxy) {
373        let identity = Arc::new(ComponentIdentity::new(
374            ExtendedMoniker::parse_str("/foo/bar").unwrap(),
375            "fuchsia-pkg://test",
376        ));
377        let stats =
378            Arc::new(LogStreamStats::new(inspect::component::inspector().root(), &identity));
379        let buffer = SharedBuffer::new(
380            create_ring_buffer(1024 * 1024),
381            Box::new(|_| {}),
382            Default::default(),
383            inspect::component::inspector().root(),
384        );
385        let buffer = buffer.new_container_buffer(Arc::new(vec!["a"].into()), Arc::clone(&stats));
386        let container = Arc::new(LogsArtifactsContainer::new(
387            identity,
388            std::iter::empty(),
389            severity,
390            Arc::clone(&stats),
391            buffer,
392            None,
393        ));
394        // Connect out LogSink under test and take its events channel.
395        let (proxy, stream) = fidl::endpoints::create_proxy_and_stream::<LogSinkMarker>();
396        container.handle_log_sink(stream, scope);
397        (container, proxy)
398    }
399
400    #[fuchsia::test(allow_stalls = false)]
401    async fn update_interest() {
402        // Sync path test (initial interest)
403        let scope = fasync::Scope::new();
404        let (container, log_sink) = initialize_container(None, scope.to_handle());
405
406        // Get initial interest
407        let initial_interest = log_sink.wait_for_interest_change().await.unwrap().unwrap();
408
409        // Async (blocking) path test.
410        assert_eq!(initial_interest.min_severity, None);
411        let log_sink_clone = log_sink.clone();
412        let mut interest_future =
413            Task::spawn(async move { log_sink_clone.wait_for_interest_change().await });
414
415        // The call should be blocked.
416        assert!(TestExecutor::poll_until_stalled(&mut interest_future).await.is_pending());
417
418        // We should see this interest update. This should unblock the hanging get.
419        container.update_interest([interest(&["foo", "bar"], Some(Severity::Info))].iter(), &[]);
420
421        // Verify we see the last interest we set.
422        assert_eq!(interest_future.await.unwrap().unwrap().min_severity, Some(Severity::Info));
423    }
424
425    #[fuchsia::test]
426    async fn initial_interest() {
427        let scope = fasync::Scope::new();
428        let (_container, log_sink) = initialize_container(Some(Severity::Info), scope.to_handle());
429        let initial_interest = log_sink.wait_for_interest_change().await.unwrap().unwrap();
430        assert_eq!(initial_interest.min_severity, Some(Severity::Info));
431    }
432
433    #[fuchsia::test]
434    async fn interest_serverity_semantics() {
435        let scope = fasync::Scope::new();
436        let (container, log_sink) = initialize_container(None, scope.to_handle());
437        let initial_interest = log_sink.wait_for_interest_change().await.unwrap().unwrap();
438        assert_eq!(initial_interest.min_severity, None);
439        // Set some interest.
440        container.update_interest([interest(&["foo", "bar"], Some(Severity::Info))].iter(), &[]);
441        assert_severity(&log_sink, Severity::Info).await;
442        assert_interests(&container, [(Severity::Info, 1)]);
443
444        // Sending a higher interest (WARN > INFO) has no visible effect, even if the new interest
445        // (WARN) will be tracked internally until reset.
446        container.update_interest([interest(&["foo", "bar"], Some(Severity::Warn))].iter(), &[]);
447        assert_interests(&container, [(Severity::Info, 1), (Severity::Warn, 1)]);
448
449        // Sending a lower interest (DEBUG < INFO) updates the previous one.
450        container.update_interest([interest(&["foo", "bar"], Some(Severity::Debug))].iter(), &[]);
451        assert_severity(&log_sink, Severity::Debug).await;
452        assert_interests(
453            &container,
454            [(Severity::Debug, 1), (Severity::Info, 1), (Severity::Warn, 1)],
455        );
456
457        // Sending the same interest leads to tracking it twice, but no updates are sent since it's
458        // the same minimum interest.
459        container.update_interest([interest(&["foo", "bar"], Some(Severity::Debug))].iter(), &[]);
460        assert_interests(
461            &container,
462            [(Severity::Debug, 2), (Severity::Info, 1), (Severity::Warn, 1)],
463        );
464
465        // The first reset does nothing, since the new minimum interest remains the same (we had
466        // inserted twice, therefore we need to reset twice).
467        container.reset_interest(&[interest(&["foo", "bar"], Some(Severity::Debug))]);
468        assert_interests(
469            &container,
470            [(Severity::Debug, 1), (Severity::Info, 1), (Severity::Warn, 1)],
471        );
472
473        // The second reset causes a change in minimum interest -> now INFO.
474        container.reset_interest(&[interest(&["foo", "bar"], Some(Severity::Debug))]);
475        assert_severity(&log_sink, Severity::Info).await;
476        assert_interests(&container, [(Severity::Info, 1), (Severity::Warn, 1)]);
477
478        // If we pass a previous severity (INFO), then we undo it and set the new one (ERROR).
479        // However, we get WARN since that's the minimum severity in the set.
480        container.update_interest(
481            [interest(&["foo", "bar"], Some(Severity::Error))].iter(),
482            &[interest(&["foo", "bar"], Some(Severity::Info))],
483        );
484        assert_severity(&log_sink, Severity::Warn).await;
485        assert_interests(&container, [(Severity::Error, 1), (Severity::Warn, 1)]);
486
487        // When we reset warn, now we get ERROR since that's the minimum severity in the set.
488        container.reset_interest(&[interest(&["foo", "bar"], Some(Severity::Warn))]);
489        assert_severity(&log_sink, Severity::Error).await;
490        assert_interests(&container, [(Severity::Error, 1)]);
491
492        // When we reset ERROR , we get back to EMPTY since we have removed all interests from the
493        // set.
494        container.reset_interest(&[interest(&["foo", "bar"], Some(Severity::Error))]);
495        assert_eq!(
496            log_sink.wait_for_interest_change().await.unwrap().unwrap(),
497            FidlInterest::default()
498        );
499
500        assert_interests(&container, []);
501    }
502
503    fn interest(moniker: &[&str], min_severity: Option<Severity>) -> LogInterestSelector {
504        LogInterestSelector {
505            selector: ComponentSelector {
506                moniker_segments: Some(
507                    moniker.iter().map(|s| StringSelector::ExactMatch(s.to_string())).collect(),
508                ),
509                ..Default::default()
510            },
511            interest: FidlInterest { min_severity, ..Default::default() },
512        }
513    }
514
515    async fn assert_severity(proxy: &LogSinkProxy, severity: Severity) {
516        assert_eq!(
517            proxy.wait_for_interest_change().await.unwrap().unwrap().min_severity.unwrap(),
518            severity
519        );
520    }
521
522    fn assert_interests<const N: usize>(
523        container: &LogsArtifactsContainer,
524        severities: [(Severity, usize); N],
525    ) {
526        let mut expected_map = BTreeMap::new();
527        expected_map.extend(IntoIterator::into_iter(severities).map(|(s, c)| {
528            let interest = FidlInterest { min_severity: Some(s), ..Default::default() };
529            (interest.into(), c)
530        }));
531        assert_eq!(expected_map, container.state.lock().interests);
532    }
533}