From 1081a50fb3e84bfb7e3230d0a021eb97e1096c02 Mon Sep 17 00:00:00 2001 From: Daniel Chen <108989218+Daniel1464@users.noreply.github.com> Date: Wed, 25 Dec 2024 20:34:26 -0500 Subject: [PATCH] Update epilogue docs to show new opt-in logging (#2864) --------- Co-authored-by: Jason Daming --- .../telemetry/robot-telemetry-with-annotations.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/source/docs/software/telemetry/robot-telemetry-with-annotations.rst b/source/docs/software/telemetry/robot-telemetry-with-annotations.rst index 20209e4bf7..bd090f69f0 100644 --- a/source/docs/software/telemetry/robot-telemetry-with-annotations.rst +++ b/source/docs/software/telemetry/robot-telemetry-with-annotations.rst @@ -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. @@ -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 @@ -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 @@ -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> getSpeed() { // ... } @@ -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