1/*
2 * libjingle
3 * Copyright 2012 Google Inc.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 *  1. Redistributions of source code must retain the above copyright notice,
9 *     this list of conditions and the following disclaimer.
10 *  2. Redistributions in binary form must reproduce the above copyright notice,
11 *     this list of conditions and the following disclaimer in the documentation
12 *     and/or other materials provided with the distribution.
13 *  3. The name of the author may not be used to endorse or promote products
14 *     derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28// This file contains a class used for gathering statistics from an ongoing
29// libjingle PeerConnection.
30
31#ifndef TALK_APP_WEBRTC_STATSCOLLECTOR_H_
32#define TALK_APP_WEBRTC_STATSCOLLECTOR_H_
33
34#include <map>
35#include <string>
36#include <vector>
37
38#include "talk/app/webrtc/mediastreaminterface.h"
39#include "talk/app/webrtc/peerconnectioninterface.h"
40#include "talk/app/webrtc/statstypes.h"
41#include "talk/app/webrtc/webrtcsession.h"
42
43namespace webrtc {
44
45class PeerConnection;
46
47// Conversion function to convert candidate type string to the corresponding one
48// from  enum RTCStatsIceCandidateType.
49const char* IceCandidateTypeToStatsType(const std::string& candidate_type);
50
51// Conversion function to convert adapter type to report string which are more
52// fitting to the general style of http://w3c.github.io/webrtc-stats. This is
53// only used by stats collector.
54const char* AdapterTypeToStatsType(rtc::AdapterType type);
55
56// A mapping between track ids and their StatsReport.
57typedef std::map<std::string, StatsReport*> TrackIdMap;
58
59class StatsCollector {
60 public:
61  // The caller is responsible for ensuring that the pc outlives the
62  // StatsCollector instance.
63  explicit StatsCollector(PeerConnection* pc);
64  virtual ~StatsCollector();
65
66  // Adds a MediaStream with tracks that can be used as a |selector| in a call
67  // to GetStats.
68  void AddStream(MediaStreamInterface* stream);
69
70  // Adds a local audio track that is used for getting some voice statistics.
71  void AddLocalAudioTrack(AudioTrackInterface* audio_track, uint32_t ssrc);
72
73  // Removes a local audio tracks that is used for getting some voice
74  // statistics.
75  void RemoveLocalAudioTrack(AudioTrackInterface* audio_track, uint32_t ssrc);
76
77  // Gather statistics from the session and store them for future use.
78  void UpdateStats(PeerConnectionInterface::StatsOutputLevel level);
79
80  // Gets a StatsReports of the last collected stats. Note that UpdateStats must
81  // be called before this function to get the most recent stats. |selector| is
82  // a track label or empty string. The most recent reports are stored in
83  // |reports|.
84  // TODO(tommi): Change this contract to accept a callback object instead
85  // of filling in |reports|.  As is, there's a requirement that the caller
86  // uses |reports| immediately without allowing any async activity on
87  // the thread (message handling etc) and then discard the results.
88  void GetStats(MediaStreamTrackInterface* track,
89                StatsReports* reports);
90
91  // Prepare a local or remote SSRC report for the given ssrc. Used internally
92  // in the ExtractStatsFromList template.
93  StatsReport* PrepareReport(bool local,
94                             uint32_t ssrc,
95                             const StatsReport::Id& transport_id,
96                             StatsReport::Direction direction);
97
98  // Method used by the unittest to force a update of stats since UpdateStats()
99  // that occur less than kMinGatherStatsPeriod number of ms apart will be
100  // ignored.
101  void ClearUpdateStatsCacheForTest();
102
103 private:
104  friend class StatsCollectorTest;
105
106  // Overridden in unit tests to fake timing.
107  virtual double GetTimeNow();
108
109  bool CopySelectedReports(const std::string& selector, StatsReports* reports);
110
111  // Helper method for AddCertificateReports.
112  StatsReport* AddOneCertificateReport(
113      const rtc::SSLCertificate* cert, const StatsReport* issuer);
114
115  // Helper method for creating IceCandidate report. |is_local| indicates
116  // whether this candidate is local or remote.
117  StatsReport* AddCandidateReport(const cricket::Candidate& candidate,
118                                  bool local);
119
120  // Adds a report for this certificate and every certificate in its chain, and
121  // returns the leaf certificate's report.
122  StatsReport* AddCertificateReports(const rtc::SSLCertificate* cert);
123
124  StatsReport* AddConnectionInfoReport(const std::string& content_name,
125      int component, int connection_id,
126      const StatsReport::Id& channel_report_id,
127      const cricket::ConnectionInfo& info);
128
129  void ExtractDataInfo();
130  void ExtractSessionInfo();
131  void ExtractVoiceInfo();
132  void ExtractVideoInfo(PeerConnectionInterface::StatsOutputLevel level);
133  void BuildSsrcToTransportId();
134  webrtc::StatsReport* GetReport(const StatsReport::StatsType& type,
135                                 const std::string& id,
136                                 StatsReport::Direction direction);
137
138  // Helper method to get stats from the local audio tracks.
139  void UpdateStatsFromExistingLocalAudioTracks();
140  void UpdateReportFromAudioTrack(AudioTrackInterface* track,
141                                  StatsReport* report);
142
143  // Helper method to get the id for the track identified by ssrc.
144  // |direction| tells if the track is for sending or receiving.
145  bool GetTrackIdBySsrc(uint32_t ssrc,
146                        std::string* track_id,
147                        StatsReport::Direction direction);
148
149  // Helper method to update the timestamp of track records.
150  void UpdateTrackReports();
151
152  // A collection for all of our stats reports.
153  StatsCollection reports_;
154  TrackIdMap track_ids_;
155  // Raw pointer to the peer connection the statistics are gathered from.
156  PeerConnection* const pc_;
157  double stats_gathering_started_;
158  ProxyTransportMap proxy_to_transport_;
159
160  // TODO(tommi): We appear to be holding on to raw pointers to reference
161  // counted objects?  We should be using scoped_refptr here.
162  typedef std::vector<std::pair<AudioTrackInterface*, uint32_t> >
163      LocalAudioTrackVector;
164  LocalAudioTrackVector local_audio_tracks_;
165};
166
167}  // namespace webrtc
168
169#endif  // TALK_APP_WEBRTC_STATSCOLLECTOR_H_
170