Skip to content

Commit 1081a50

Browse files
Update epilogue docs to show new opt-in logging (#2864)
--------- Co-authored-by: Jason Daming <jason.daming@intralox.com>
1 parent 2ee8f5f commit 1081a50

File tree

1 file changed

+5
-8
lines changed

1 file changed

+5
-8
lines changed

source/docs/software/telemetry/robot-telemetry-with-annotations.rst

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ Customizing your logging setup
6060

6161
The default logging behavior is to log *every* non-static field (public or private) and public method in a class annotated with ``@Logged``, where the associated log entries will use the name of the element. For example, a field declared as ``private double m_someValue`` will appear in logs under the entry ``"m_someValue"``, and a method declared as ``public double getSomeValue()`` will appear under the entry ``"getSomeValue"``.
6262

63-
You can change what gets logged and what doesn't by configuring the class-level ``@Logged`` annotation with ``strategy = OPT_IN``. This will tell the annotation processor to *only* log fields and methods that you place a ``@Logged`` annotation on, rather than the default behavior of logging everything that doesn't have a ``@NotLogged`` annotation.
63+
If you desire to only log certain fields or methods within a class, you can remove the ```@Logged``` annotation from the class itself and place it on individual fields/methods within the class. This allows you to opt-in on logging within a class instead of logging every value.
6464

6565
The names of log entries can be changed using the ``name`` configuration option on fields and methods (on a class-level annotation, it changes the name of the autogenerated logger class for avoiding name conflicts and does not change the log names of any instance of that class). For example, a ``private double m_someValue`` field with an ``@Logged(name = "Motor Temperature")`` will appear in logs as ``"Motor Temperature"`` instead of the default ``"m_someValue"`` that would be used.
6666

@@ -73,8 +73,6 @@ The names of log entries can be changed using the ``name`` configuration option
7373
- Sets a specific name to use for the annotated element. If placed on a class, this controls the name of the generated logger class for avoiding name conflicts.
7474
* - Importance
7575
- Sets the specific importance level for the annotated element, which can be used by the runtime ``minimumImportance`` configuration to control what data to log. If placed on a class, this sets the *default* importance level for all contained elements, which can be overridden on an element-by-element basis. Defaults to ``DEBUG``.
76-
* - Strategy (class only)
77-
- Sets the opt-in/opt-out strategy to use for logging elements in the annotated class. Defaults to opt-out, which means every loggable element in the class will be logged unless opted out using the ``@NotLogged`` annotation. Setting this to opt-in gives finer control over what gets logged, but takes more work to set up by manually annotating all the opted-in elements. Setting this option on a field or method has no effect.
7876
* - Logging Period
7977
- Sets the amount of time between logging calls.
8078
* - Logging Period Offset
@@ -164,12 +162,11 @@ The names of log entries can be changed using the ``name`` configuration option
164162
}
165163
}
166164
167-
@Logged(strategy = OPT_IN)
168165
class Arm {
169166
@Logged(name = "At Low Stop", importance = DEBUG)
170167
public final Trigger atLowStop = new Trigger(...);
171168
172-
@Logged(name = "At High Stop", importance = DEBUG)
169+
@Logged // defaults to an importance of DEBUG and the name as "atHighStop"
173170
public final Trigger atHighStop = new Trigger(...);
174171
175172
@NotLogged // Redundant because the class strategy is opt-in
@@ -180,7 +177,7 @@ The names of log entries can be changed using the ``name`` configuration option
180177
// ...
181178
}
182179
183-
@Logged(name = "Speed", importance = CRITICAL)
180+
@Logged
184181
public Measure<Velocity<Angle>> getSpeed() {
185182
// ...
186183
}
@@ -191,9 +188,9 @@ The names of log entries can be changed using the ``name`` configuration option
191188

192189
```
193190
/Robot/Arm/At Low Stop
194-
/Robot/Arm/At High Stop
191+
/Robot/Arm/atHighStop
195192
/Robot/Arm/Position
196-
/Robot/Arm/Speed
193+
/Robot/Arm/getSpeed
197194
```
198195

199196
The Epilogue Class

0 commit comments

Comments
 (0)