Line data Source code
1 : /**
2 : *
3 : * Copyright (c) 2021 Project CHIP Authors
4 : *
5 : * Licensed under the Apache License, Version 2.0 (the "License");
6 : * you may not use this file except in compliance with the License.
7 : * You may obtain a copy of the License at
8 : *
9 : * http://www.apache.org/licenses/LICENSE-2.0
10 : *
11 : * Unless required by applicable law or agreed to in writing, software
12 : * distributed under the License is distributed on an "AS IS" BASIS,
13 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 : * See the License for the specific language governing permissions and
15 : * limitations under the License.
16 : */
17 :
18 : #pragma once
19 :
20 : #include <access/SubjectDescriptor.h>
21 : #include <app/EventPathParams.h>
22 : #include <app/util/basic-types.h>
23 : #include <lib/core/CHIPCore.h>
24 : #include <lib/core/Optional.h>
25 : #include <lib/core/TLV.h>
26 : #include <lib/support/LinkedList.h>
27 : #include <system/SystemPacketBuffer.h>
28 :
29 : inline constexpr size_t kNumPriorityLevel = 3;
30 : namespace chip {
31 : namespace app {
32 :
33 : /**
34 : * @brief
35 : * The Priority of the log entry.
36 : *
37 : * @details
38 : * Priority is used as a way to filter events before they are
39 : * actually emitted into the log. After the event is in the log, we
40 : * make no further provisions to expunge it from the log.
41 : * The priority level serves to prioritize event storage. If an
42 : * event of high priority is added to a full buffer, events are
43 : * dropped in order of priority (and age) to accommodate it. As such,
44 : * priority levels only have relative value. If a system is
45 : * using only one priority level, events are dropped only in order
46 : * of age, like a ring buffer.
47 : */
48 :
49 : enum class PriorityLevel : uint8_t
50 : {
51 :
52 : First = 0,
53 : /**
54 : * Debug priority denotes log entries of interest to the
55 : * developers of the system and is used primarily in the
56 : * development phase. Debug priority logs are
57 : * not accounted for in the bandwidth or power budgets of the
58 : * constrained devices; as a result, they must be used only over
59 : * a limited time span in production systems.
60 : */
61 :
62 : Debug = First,
63 : /**
64 : * Info priority denotes log entries that provide extra insight
65 : * and diagnostics into the running system. Info logging level may
66 : * be used over an extended period of time in a production system,
67 : * or may be used as the default log level in a field trial. On
68 : * the constrained devices, the entries logged with Info level must
69 : * be accounted for in the bandwidth and memory budget, but not in
70 : * the power budget.
71 : */
72 : Info = 1,
73 :
74 : /**
75 : * Critical priority denotes events whose loss would
76 : * directly impact customer-facing features. Applications may use
77 : * loss of Production Critical events to indicate system failure.
78 : * On constrained devices, entries logged with Critical
79 : * priority must be accounted for in the power and memory budget,
80 : * as it is expected that they are always logged and offloaded
81 : * from the device.
82 : */
83 : Critical = 2,
84 : Last = Critical,
85 : Invalid = Last + 1,
86 :
87 : };
88 :
89 : static_assert(sizeof(std::underlying_type_t<PriorityLevel>) <= sizeof(unsigned),
90 : "Logging that converts PriorityLevel to unsigned will be lossy");
91 :
92 : /**
93 : * @brief
94 : * The struct that provides an application set System or Epoch timestamp.
95 : */
96 : struct Timestamp
97 : {
98 : enum class Type : uint8_t
99 : {
100 : kSystem = 0,
101 : kEpoch
102 : };
103 676 : Timestamp() {}
104 5010 : Timestamp(Type aType, uint64_t aValue) : mType(aType), mValue(aValue) {}
105 : Timestamp(System::Clock::Timestamp aValue) : mType(Type::kSystem), mValue(aValue.count()) {}
106 4998 : static Timestamp Epoch(System::Clock::Timestamp aValue)
107 : {
108 4998 : Timestamp timestamp(Type::kEpoch, aValue.count());
109 4998 : return timestamp;
110 : }
111 12 : static Timestamp System(System::Clock::Timestamp aValue)
112 : {
113 12 : Timestamp timestamp(Type::kSystem, aValue.count());
114 12 : return timestamp;
115 : }
116 :
117 1324 : bool IsSystem() const { return mType == Type::kSystem; }
118 0 : bool IsEpoch() const { return mType == Type::kEpoch; }
119 :
120 : Type mType = Type::kSystem;
121 : uint64_t mValue = 0;
122 : };
123 :
124 : /**
125 : * The structure that provides options for the different event fields.
126 : */
127 : class EventOptions
128 : {
129 : public:
130 0 : EventOptions() : mPriority(PriorityLevel::Invalid) {}
131 662 : EventOptions(Timestamp aTimestamp) : mTimestamp(aTimestamp), mPriority(PriorityLevel::Invalid) {}
132 : ConcreteEventPath mPath;
133 : Timestamp mTimestamp;
134 : PriorityLevel mPriority = PriorityLevel::Invalid;
135 : // kUndefinedFabricIndex 0 means not fabric associated at all
136 : FabricIndex mFabricIndex = kUndefinedFabricIndex;
137 : };
138 :
139 : /**
140 : * @brief
141 : * Structure for copying event lists on output.
142 : */
143 : struct EventLoadOutContext
144 : {
145 2216 : EventLoadOutContext(TLV::TLVWriter & aWriter, PriorityLevel aPriority, EventNumber aStartingEventNumber) :
146 2216 : mWriter(aWriter), mPriority(aPriority), mStartingEventNumber(aStartingEventNumber), mCurrentEventNumber(0), mFirst(true)
147 2216 : {}
148 :
149 : TLV::TLVWriter & mWriter;
150 : PriorityLevel mPriority = PriorityLevel::Invalid;
151 : EventNumber mStartingEventNumber = 0;
152 : Timestamp mPreviousTime;
153 : Timestamp mCurrentTime;
154 : EventNumber mCurrentEventNumber = 0;
155 : size_t mEventCount = 0;
156 : const SingleLinkedListNode<EventPathParams> * mpInterestedEventPaths = nullptr;
157 : bool mFirst = true;
158 : Access::SubjectDescriptor mSubjectDescriptor;
159 : };
160 : } // namespace app
161 : } // namespace chip
|
