Skip to content

Commit

Permalink
Update epilogue docs to show new opt-in logging (#2864)
Browse files Browse the repository at this point in the history
---------

Co-authored-by: Jason Daming <[email protected]>
  • Loading branch information
Daniel1464 and jasondaming authored Dec 26, 2024
1 parent 2ee8f5f commit 1081a50
Showing 1 changed file with 5 additions and 8 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Customizing your logging setup

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"``.

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.
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.

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.

Expand All @@ -73,8 +73,6 @@ The names of log entries can be changed using the ``name`` configuration option
- 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.
* - Importance
- 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``.
* - Strategy (class only)
- 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.
* - Logging Period
- Sets the amount of time between logging calls.
* - Logging Period Offset
Expand Down Expand Up @@ -164,12 +162,11 @@ The names of log entries can be changed using the ``name`` configuration option
}
}
@Logged(strategy = OPT_IN)
class Arm {
@Logged(name = "At Low Stop", importance = DEBUG)
public final Trigger atLowStop = new Trigger(...);
@Logged(name = "At High Stop", importance = DEBUG)
@Logged // defaults to an importance of DEBUG and the name as "atHighStop"
public final Trigger atHighStop = new Trigger(...);
@NotLogged // Redundant because the class strategy is opt-in
Expand All @@ -180,7 +177,7 @@ The names of log entries can be changed using the ``name`` configuration option
// ...
}
@Logged(name = "Speed", importance = CRITICAL)
@Logged
public Measure<Velocity<Angle>> getSpeed() {
// ...
}
Expand All @@ -191,9 +188,9 @@ The names of log entries can be changed using the ``name`` configuration option

```
/Robot/Arm/At Low Stop
/Robot/Arm/At High Stop
/Robot/Arm/atHighStop
/Robot/Arm/Position
/Robot/Arm/Speed
/Robot/Arm/getSpeed
```

The Epilogue Class
Expand Down

0 comments on commit 1081a50

Please sign in to comment.