1 /* 2 * Copyright 2012 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 // This file contains structures used for retrieving statistics from an ongoing 12 // libjingle session. 13 14 #ifndef API_LEGACY_STATS_TYPES_H_ 15 #define API_LEGACY_STATS_TYPES_H_ 16 17 #include <algorithm> 18 #include <list> 19 #include <map> 20 #include <string> 21 #include <vector> 22 23 #include "api/scoped_refptr.h" 24 #include "api/sequence_checker.h" 25 #include "rtc_base/ref_count.h" 26 #include "rtc_base/system/rtc_export.h" 27 28 namespace webrtc { 29 30 class RTC_EXPORT StatsReport { 31 public: 32 // Indicates whether a track is for sending or receiving. 33 // Used in reports for audio/video tracks. 34 enum Direction { 35 kSend = 0, 36 kReceive, 37 }; 38 39 enum StatsType { 40 // StatsReport types. 41 // A StatsReport of `type` = "googSession" contains overall information 42 // about the thing libjingle calls a session (which may contain one 43 // or more RTP sessions. 44 kStatsReportTypeSession, 45 46 // A StatsReport of `type` = "googTransport" contains information 47 // about a libjingle "transport". 48 kStatsReportTypeTransport, 49 50 // A StatsReport of `type` = "googComponent" contains information 51 // about a libjingle "channel" (typically, RTP or RTCP for a transport). 52 // This is intended to be the same thing as an ICE "Component". 53 kStatsReportTypeComponent, 54 55 // A StatsReport of `type` = "googCandidatePair" contains information 56 // about a libjingle "connection" - a single source/destination port pair. 57 // This is intended to be the same thing as an ICE "candidate pair". 58 kStatsReportTypeCandidatePair, 59 60 // A StatsReport of `type` = "VideoBWE" is statistics for video Bandwidth 61 // Estimation, which is global per-session. The `id` field is "bweforvideo" 62 // (will probably change in the future). 63 kStatsReportTypeBwe, 64 65 // A StatsReport of `type` = "ssrc" is statistics for a specific rtp stream. 66 // The `id` field is the SSRC in decimal form of the rtp stream. 67 kStatsReportTypeSsrc, 68 69 // A StatsReport of `type` = "remoteSsrc" is statistics for a specific 70 // rtp stream, generated by the remote end of the connection. 71 kStatsReportTypeRemoteSsrc, 72 73 // A StatsReport of `type` = "googTrack" is statistics for a specific media 74 // track. The `id` field is the track id. 75 kStatsReportTypeTrack, 76 77 // A StatsReport of `type` = "localcandidate" or "remotecandidate" is 78 // attributes on a specific ICE Candidate. It links to its connection pair 79 // by candidate id. The string value is taken from 80 // http://w3c.github.io/webrtc-stats/#rtcstatstype-enum*. 81 kStatsReportTypeIceLocalCandidate, 82 kStatsReportTypeIceRemoteCandidate, 83 84 // A StatsReport of `type` = "googCertificate" contains an SSL certificate 85 // transmitted by one of the endpoints of this connection. The `id` is 86 // controlled by the fingerprint, and is used to identify the certificate in 87 // the Channel stats (as "googLocalCertificateId" or 88 // "googRemoteCertificateId") and in any child certificates (as 89 // "googIssuerId"). 90 kStatsReportTypeCertificate, 91 92 // A StatsReport of `type` = "datachannel" with statistics for a 93 // particular DataChannel. 94 kStatsReportTypeDataChannel, 95 }; 96 97 enum StatsValueName { 98 kStatsValueNameActiveConnection, 99 kStatsValueNameAecDivergentFilterFraction, 100 kStatsValueNameAudioInputLevel, 101 kStatsValueNameAudioOutputLevel, 102 kStatsValueNameBytesReceived, 103 kStatsValueNameBytesSent, 104 kStatsValueNameCodecImplementationName, 105 kStatsValueNameConcealedSamples, 106 kStatsValueNameConcealmentEvents, 107 kStatsValueNameDataChannelId, 108 kStatsValueNameFramesDecoded, 109 kStatsValueNameFramesEncoded, 110 kStatsValueNameJitterBufferDelay, 111 kStatsValueNameMediaType, 112 kStatsValueNamePacketsLost, 113 kStatsValueNamePacketsReceived, 114 kStatsValueNamePacketsSent, 115 kStatsValueNameProtocol, 116 kStatsValueNameQpSum, 117 kStatsValueNameReceiving, 118 kStatsValueNameSelectedCandidatePairId, 119 kStatsValueNameSsrc, 120 kStatsValueNameState, 121 kStatsValueNameTotalAudioEnergy, 122 kStatsValueNameTotalSamplesDuration, 123 kStatsValueNameTotalSamplesReceived, 124 kStatsValueNameTransportId, 125 kStatsValueNameSentPingRequestsTotal, 126 kStatsValueNameSentPingRequestsBeforeFirstResponse, 127 kStatsValueNameSentPingResponses, 128 kStatsValueNameRecvPingRequests, 129 kStatsValueNameRecvPingResponses, 130 kStatsValueNameSentStunKeepaliveRequests, 131 kStatsValueNameRecvStunKeepaliveResponses, 132 kStatsValueNameStunKeepaliveRttTotal, 133 kStatsValueNameStunKeepaliveRttSquaredTotal, 134 135 // Internal StatsValue names. 136 kStatsValueNameAccelerateRate, 137 kStatsValueNameActualEncBitrate, 138 kStatsValueNameAdaptationChanges, 139 kStatsValueNameAvailableReceiveBandwidth, 140 kStatsValueNameAvailableSendBandwidth, 141 kStatsValueNameAvgEncodeMs, 142 kStatsValueNameBandwidthLimitedResolution, 143 kStatsValueNameBucketDelay, 144 kStatsValueNameCaptureStartNtpTimeMs, 145 kStatsValueNameCandidateIPAddress, 146 kStatsValueNameCandidateNetworkType, 147 kStatsValueNameCandidatePortNumber, 148 kStatsValueNameCandidatePriority, 149 kStatsValueNameCandidateTransportType, 150 kStatsValueNameCandidateType, 151 kStatsValueNameChannelId, 152 kStatsValueNameCodecName, 153 kStatsValueNameComponent, 154 kStatsValueNameContentName, 155 kStatsValueNameContentType, 156 kStatsValueNameCpuLimitedResolution, 157 kStatsValueNameCurrentDelayMs, 158 kStatsValueNameDecodeMs, 159 kStatsValueNameDecodingCNG, 160 kStatsValueNameDecodingCTN, 161 kStatsValueNameDecodingCTSG, 162 kStatsValueNameDecodingMutedOutput, 163 kStatsValueNameDecodingNormal, 164 kStatsValueNameDecodingPLC, 165 kStatsValueNameDecodingCodecPLC, 166 kStatsValueNameDecodingPLCCNG, 167 kStatsValueNameDer, 168 kStatsValueNameDtlsCipher, 169 kStatsValueNameEchoDelayMedian, 170 kStatsValueNameEchoDelayStdDev, 171 kStatsValueNameEchoReturnLoss, 172 kStatsValueNameEchoReturnLossEnhancement, 173 kStatsValueNameEncodeUsagePercent, 174 kStatsValueNameExpandRate, 175 kStatsValueNameFingerprint, 176 kStatsValueNameFingerprintAlgorithm, 177 kStatsValueNameFirsReceived, 178 kStatsValueNameFirsSent, 179 kStatsValueNameFirstFrameReceivedToDecodedMs, 180 kStatsValueNameFrameHeightInput, 181 kStatsValueNameFrameHeightReceived, 182 kStatsValueNameFrameHeightSent, 183 kStatsValueNameFrameRateDecoded, 184 kStatsValueNameFrameRateInput, 185 kStatsValueNameFrameRateOutput, 186 kStatsValueNameFrameRateReceived, 187 kStatsValueNameFrameRateSent, 188 kStatsValueNameFrameWidthInput, 189 kStatsValueNameFrameWidthReceived, 190 kStatsValueNameFrameWidthSent, 191 kStatsValueNameHasEnteredLowResolution, 192 kStatsValueNameHugeFramesSent, 193 kStatsValueNameInitiator, 194 kStatsValueNameInterframeDelayMaxMs, // Max over last 10 seconds. 195 kStatsValueNameIssuerId, 196 kStatsValueNameJitterBufferMs, 197 kStatsValueNameJitterReceived, 198 kStatsValueNameLabel, 199 kStatsValueNameLocalAddress, 200 kStatsValueNameLocalCandidateId, 201 kStatsValueNameLocalCandidateType, 202 kStatsValueNameLocalCertificateId, 203 kStatsValueNameMaxDecodeMs, 204 kStatsValueNameMinPlayoutDelayMs, 205 kStatsValueNameNacksReceived, 206 kStatsValueNameNacksSent, 207 kStatsValueNamePlisReceived, 208 kStatsValueNamePlisSent, 209 kStatsValueNamePreemptiveExpandRate, 210 kStatsValueNamePreferredJitterBufferMs, 211 kStatsValueNameRemoteAddress, 212 kStatsValueNameRemoteCandidateId, 213 kStatsValueNameRemoteCandidateType, 214 kStatsValueNameRemoteCertificateId, 215 kStatsValueNameRenderDelayMs, 216 kStatsValueNameResidualEchoLikelihood, 217 kStatsValueNameResidualEchoLikelihoodRecentMax, 218 kStatsValueNameAnaBitrateActionCounter, 219 kStatsValueNameAnaChannelActionCounter, 220 kStatsValueNameAnaDtxActionCounter, 221 kStatsValueNameAnaFecActionCounter, 222 kStatsValueNameAnaFrameLengthIncreaseCounter, 223 kStatsValueNameAnaFrameLengthDecreaseCounter, 224 kStatsValueNameAnaUplinkPacketLossFraction, 225 kStatsValueNameRetransmitBitrate, 226 kStatsValueNameRtt, 227 kStatsValueNameSecondaryDecodedRate, 228 kStatsValueNameSecondaryDiscardedRate, 229 kStatsValueNameSendPacketsDiscarded, 230 kStatsValueNameSpeechExpandRate, 231 kStatsValueNameSrtpCipher, 232 kStatsValueNameTargetDelayMs, 233 kStatsValueNameTargetEncBitrate, 234 kStatsValueNameTimingFrameInfo, // Result of `TimingFrameInfo::ToString` 235 kStatsValueNameTrackId, 236 kStatsValueNameTransmitBitrate, 237 kStatsValueNameTransportType, 238 kStatsValueNameWritable, 239 kStatsValueNameAudioDeviceUnderrunCounter, 240 kStatsValueNameLocalCandidateRelayProtocol, 241 }; 242 243 class RTC_EXPORT IdBase : public rtc::RefCountInterface { 244 public: 245 ~IdBase() override; 246 StatsType type() const; 247 248 // Users of IdBase will be using the Id typedef, which is compatible with 249 // this Equals() function. It simply calls the protected (and overridden) 250 // Equals() method. Equals(const rtc::scoped_refptr<IdBase> & other)251 bool Equals(const rtc::scoped_refptr<IdBase>& other) const { 252 return Equals(*other.get()); 253 } 254 255 virtual std::string ToString() const = 0; 256 257 protected: 258 // Protected since users of the IdBase type will be using the Id typedef. 259 virtual bool Equals(const IdBase& other) const; 260 261 explicit IdBase(StatsType type); // Only meant for derived classes. 262 const StatsType type_; 263 264 static const char kSeparator = '_'; 265 }; 266 267 typedef rtc::scoped_refptr<IdBase> Id; 268 269 struct RTC_EXPORT Value { 270 enum Type { 271 kInt, // int. 272 kInt64, // int64_t. 273 kFloat, // float. 274 kString, // std::string 275 kStaticString, // const char*. 276 kBool, // bool. 277 kId, // Id. 278 }; 279 280 Value(StatsValueName name, int64_t value, Type int_type); 281 Value(StatsValueName name, float f); 282 Value(StatsValueName name, const std::string& value); 283 Value(StatsValueName name, const char* value); 284 Value(StatsValueName name, bool b); 285 Value(StatsValueName name, const Id& value); 286 287 ~Value(); 288 289 Value(const Value&) = delete; 290 Value& operator=(const Value&) = delete; 291 292 // Support ref counting. Note that for performance reasons, we 293 // don't use thread safe operations. Therefore, all operations 294 // affecting the ref count (in practice, creation and copying of 295 // the Values mapping) must occur on webrtc's signalling thread. AddRefValue296 int AddRef() const { 297 RTC_DCHECK_RUN_ON(&thread_checker_); 298 return ++ref_count_; 299 } ReleaseValue300 int Release() const { 301 RTC_DCHECK_RUN_ON(&thread_checker_); 302 int count = --ref_count_; 303 if (!count) 304 delete this; 305 return count; 306 } 307 308 // TODO(tommi): This compares name as well as value... 309 // I think we should only need to compare the value part and 310 // move the name part into a hash map. 311 bool Equals(const Value& other) const; 312 313 // Comparison operators. Return true iff the current instance is of the 314 // correct type and holds the same value. No conversion is performed so 315 // a string value of "123" is not equal to an int value of 123 and an int 316 // value of 123 is not equal to a float value of 123.0f. 317 // One exception to this is that types kInt and kInt64 can be compared and 318 // kString and kStaticString too. 319 bool operator==(const std::string& value) const; 320 bool operator==(const char* value) const; 321 bool operator==(int64_t value) const; 322 bool operator==(bool value) const; 323 bool operator==(float value) const; 324 bool operator==(const Id& value) const; 325 326 // Getters that allow getting the native value directly. 327 // The caller must know the type beforehand or else hit a check. 328 int int_val() const; 329 int64_t int64_val() const; 330 float float_val() const; 331 const char* static_string_val() const; 332 const std::string& string_val() const; 333 bool bool_val() const; 334 const Id& id_val() const; 335 336 // Returns the string representation of `name`. 337 const char* display_name() const; 338 339 // Converts the native value to a string representation of the value. 340 std::string ToString() const; 341 typeValue342 Type type() const { return type_; } 343 344 // TODO(tommi): Move `name` and `display_name` out of the Value struct. 345 const StatsValueName name; 346 347 private: 348 webrtc::SequenceChecker thread_checker_; 349 mutable int ref_count_ RTC_GUARDED_BY(thread_checker_) = 0; 350 351 const Type type_; 352 // TODO(tommi): Use C++ 11 union and make value_ const. 353 union InternalType { 354 int int_; 355 int64_t int64_; 356 float float_; 357 bool bool_; 358 std::string* string_; 359 const char* static_string_; 360 Id* id_; 361 } value_; 362 }; 363 364 typedef rtc::scoped_refptr<Value> ValuePtr; 365 typedef std::map<StatsValueName, ValuePtr> Values; 366 367 // Ownership of `id` is passed to `this`. 368 explicit StatsReport(const Id& id); 369 ~StatsReport(); 370 371 StatsReport(const StatsReport&) = delete; 372 StatsReport& operator=(const StatsReport&) = delete; 373 374 // Factory functions for various types of stats IDs. 375 static Id NewBandwidthEstimationId(); 376 static Id NewTypedId(StatsType type, const std::string& id); 377 static Id NewTypedIntId(StatsType type, int id); 378 static Id NewIdWithDirection(StatsType type, 379 const std::string& id, 380 Direction direction); 381 static Id NewCandidateId(bool local, const std::string& id); 382 static Id NewComponentId(const std::string& content_name, int component); 383 static Id NewCandidatePairId(const std::string& content_name, 384 int component, 385 int index); 386 id()387 const Id& id() const { return id_; } type()388 StatsType type() const { return id_->type(); } timestamp()389 double timestamp() const { return timestamp_; } set_timestamp(double t)390 void set_timestamp(double t) { timestamp_ = t; } empty()391 bool empty() const { return values_.empty(); } values()392 const Values& values() const { return values_; } 393 394 const char* TypeToString() const; 395 396 void AddString(StatsValueName name, const std::string& value); 397 void AddString(StatsValueName name, const char* value); 398 void AddInt64(StatsValueName name, int64_t value); 399 void AddInt(StatsValueName name, int value); 400 void AddFloat(StatsValueName name, float value); 401 void AddBoolean(StatsValueName name, bool value); 402 void AddId(StatsValueName name, const Id& value); 403 404 const Value* FindValue(StatsValueName name) const; 405 406 private: 407 // The unique identifier for this object. 408 // This is used as a key for this report in ordered containers, 409 // so it must never be changed. 410 const Id id_; 411 double timestamp_; // Time since 1970-01-01T00:00:00Z in milliseconds. 412 Values values_; 413 }; 414 415 // Typedef for an array of const StatsReport pointers. 416 // Ownership of the pointers held by this implementation is assumed to lie 417 // elsewhere and lifetime guarantees are made by the implementation that uses 418 // this type. In the StatsCollector, object ownership lies with the 419 // StatsCollection class. 420 typedef std::vector<const StatsReport*> StatsReports; 421 422 // A map from the report id to the report. 423 // This class wraps an STL container and provides a limited set of 424 // functionality in order to keep things simple. 425 class StatsCollection { 426 public: 427 StatsCollection(); 428 ~StatsCollection(); 429 430 typedef std::list<StatsReport*> Container; 431 typedef Container::iterator iterator; 432 typedef Container::const_iterator const_iterator; 433 434 const_iterator begin() const; 435 const_iterator end() const; 436 size_t size() const; 437 438 // Creates a new report object with `id` that does not already 439 // exist in the list of reports. 440 StatsReport* InsertNew(const StatsReport::Id& id); 441 StatsReport* FindOrAddNew(const StatsReport::Id& id); 442 StatsReport* ReplaceOrAddNew(const StatsReport::Id& id); 443 444 // Looks for a report with the given `id`. If one is not found, null 445 // will be returned. 446 StatsReport* Find(const StatsReport::Id& id); 447 448 private: 449 Container list_; 450 webrtc::SequenceChecker thread_checker_; 451 }; 452 453 } // namespace webrtc 454 455 #endif // API_LEGACY_STATS_TYPES_H_ 456