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
    boolean
    includeIp
    Whether the caller's IP address should be resolved and recorded alongside whatever else the caller-identity resolver produces, instead of only as a fallback used when no identity is available.
    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

    • includeIp

      boolean includeIp
      Whether the caller's IP address should be resolved and recorded alongside whatever else the caller-identity resolver produces, instead of only as a fallback used when no identity is available.

      By default, an interceptor's caller-identity resolution is an either/or chain: an authenticated principal, if one resolves, takes priority over the caller's IP, which is then discarded. For most @Logged methods that is the right tradeoff — knowing who called is more useful than knowing where from, and recording both unconditionally would add IP address (personal data under most privacy frameworks) to every log line for no benefit.

      For a small set of security-sensitive operations — login, password reset, TOTP verification, admin mutations — the IP remains valuable for audit and rate-limiting purposes even when the call also resolves to an authenticated identity, and especially on a failed attempt, where the caller's identity may be unverified or entirely absent. Setting this to true on exactly those methods records the IP unconditionally, without changing IP resolution for every other @Logged method in the application.

      Returns:
      whether to record the caller's IP address in addition to caller identity, defaulting to false
      Default:
      false