Package com.fayupable.logged.core.annotation

Annotation Interface Logged

@Target(METHOD) @Retention(RUNTIME) public @interface Logged
Marks a method for automatic observability: invocation logging and metrics collection through an AOP-based interceptor provided by an adapter module (for example logged-spring).

This annotation intentionally does not capture method arguments or return values. Only structural information is recorded: which method was called, when, how long it took, whether it succeeded, and who called it. This design avoids leaking sensitive data (passwords, tokens, personal information) into logs by construction, rather than relying on masking rules that could be misconfigured or forgotten.

This annotation can only be applied to methods (ElementType.METHOD). It cannot be applied to fields, constructors, or types, so it can never be placed on an injected dependency (for example a repository field) or on a class declaration itself.

Example usage: 


 @Logged(slowThresholdMs = 300, sampleRate = 0.1)
 public void updateUserProfile(Long userId) {
     // ...
 }

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    double
    sampleRate
    The fraction of invocations that should actually be logged, expressed as a value between 0.0 (never log) and 1.0 (always log).
    long
    slowThresholdMs
    The duration, in milliseconds, above which an invocation is considered slow.

  • Element Details

    • slowThresholdMs

      long slowThresholdMs
      The duration, in milliseconds, above which an invocation is considered slow. Interceptor implementations may use this value to raise the log level (for example from INFO to WARN) for slow calls, so that performance regressions stand out without requiring every call to be inspected manually.
      Returns:
      the slow-call threshold in milliseconds, defaulting to 1000
      Default:
      1000L

    • sampleRate

      double sampleRate
      The fraction of invocations that should actually be logged, expressed as a value between 0.0 (never log) and 1.0 (always log).

      Sampling is evaluated independently for every single call using a random check. It is not a counter, so it does not guarantee that exactly one in every N calls is logged; instead, over a large number of calls the proportion of logged calls converges to this value. This approach requires no shared state, so it remains correct across threads and across multiple application instances.

      Sampling only reduces log volume. It never affects metrics (invocation counters, duration histograms, error counters), which are always recorded so that dashboards and alerts remain accurate.

      The default of 1.0 is intended for critical write operations (create, update, delete). Lowering this value is most useful for high-traffic read endpoints where logging every call would create excessive noise.

      Returns:
      the sampling rate, defaulting to 1.0 (log every call)
      Default:
      1.0