Package io.github.pimak.ntfy.log4j2

Class NtfyLog4j2Appender.Builder

java.lang.Object
org.apache.logging.log4j.core.filter.AbstractFilterable.Builder<NtfyLog4j2Appender.Builder>
org.apache.logging.log4j.core.appender.AbstractAppender.Builder<NtfyLog4j2Appender.Builder>
io.github.pimak.ntfy.log4j2.NtfyLog4j2Appender.Builder
All Implemented Interfaces:
org.apache.logging.log4j.core.util.Builder<NtfyLog4j2Appender>
Enclosing class:
NtfyLog4j2Appender
public static class NtfyLog4j2Appender.Builder extends org.apache.logging.log4j.core.appender.AbstractAppender.Builder<NtfyLog4j2Appender.Builder> implements org.apache.logging.log4j.core.util.Builder<NtfyLog4j2Appender>
Plugin builder for the <Ntfy .../> element. name, filter and ignoreExceptions come from AbstractAppender.Builder; everything below is ntfy's own.

Every attribute is typed String on purpose. log4j2 leaves an absent attribute at its field default, so a primitive int/boolean field would arrive as 0/false and be indistinguishable from an operator who really wrote maxStackFrames="0" or enabled="false" — silently clobbering ntfy-core's defaults. A String stays null when unset, so the corresponding NtfyConfig.Builder setter is applied ONLY when the operator actually supplied a value. This is the same "boxed, applied only when set" logic the Logback appender uses.

Malformed values never throw during logging initialization: each parse is guarded, warns on the StatusLogger, and leaves the core default in place.

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • setUrl

      public NtfyLog4j2Appender.Builder setUrl(String url)
      Base URL of the ntfy server, e.g. https://ntfy.sh.
      Parameters:
      url - the server base URL
      Returns:
      this builder

    • setTopic

      public NtfyLog4j2Appender.Builder setTopic(String topic)
      Topic alerts are published to.
      Parameters:
      topic - the ntfy topic
      Returns:
      this builder

    • setToken

      public NtfyLog4j2Appender.Builder setToken(String token)
      Bearer token authentication (takes precedence over username/password).
      Parameters:
      token - the ntfy access token
      Returns:
      this builder

    • setUsername

      public NtfyLog4j2Appender.Builder setUsername(String username)
      Basic-authentication user name.
      Parameters:
      username - the user name
      Returns:
      this builder

    • setPassword

      public NtfyLog4j2Appender.Builder setPassword(String password)
      Basic-authentication password.
      Parameters:
      password - the password
      Returns:
      this builder

    • setTitle

      public NtfyLog4j2Appender.Builder setTitle(String title)
      Fixed notification title; overrides the derived appName - RootCause title.
      Parameters:
      title - the notification title
      Returns:
      this builder

    • setAppName

      public NtfyLog4j2Appender.Builder setAppName(String appName)
      Application name used as the title prefix when no explicit title is set.
      Parameters:
      appName - the application name
      Returns:
      this builder

    • setMaxStackFrames

      public NtfyLog4j2Appender.Builder setMaxStackFrames(String maxStackFrames)
      Maximum root-cause stack frames included in the notification body (integer).
      Parameters:
      maxStackFrames - the frame cap, as a decimal string
      Returns:
      this builder

    • setConnectTimeout

      public NtfyLog4j2Appender.Builder setConnectTimeout(String connectTimeout)
      HTTP connect timeout as a duration string (bare int = ms, Nms/Ns/Nm/Nh/Nd, or ISO-8601).
      Parameters:
      connectTimeout - the connect timeout
      Returns:
      this builder

    • setRequestTimeout

      public NtfyLog4j2Appender.Builder setRequestTimeout(String requestTimeout)
      HTTP request timeout as a duration string (bare int = ms, Nms/Ns/Nm/Nh/Nd, or ISO-8601).
      Parameters:
      requestTimeout - the request timeout
      Returns:
      this builder

    • setMaxAlertsPerWindow

      public NtfyLog4j2Appender.Builder setMaxAlertsPerWindow(String maxAlertsPerWindow)
      Individual alerts allowed per suppression window before digesting kicks in (integer).
      Parameters:
      maxAlertsPerWindow - the per-window allowance, as a decimal string
      Returns:
      this builder

    • setSuppressionWindow

      public NtfyLog4j2Appender.Builder setSuppressionWindow(String suppressionWindow)
      Length of the rate-limiting/digest window as a duration string (bare int = ms, Nms/Ns/Nm/Nh/Nd, or ISO-8601).
      Parameters:
      suppressionWindow - the window length
      Returns:
      this builder

    • setErrorPriority

      public NtfyLog4j2Appender.Builder setErrorPriority(String errorPriority)
      ntfy Priority header for individual error alerts.
      Parameters:
      errorPriority - the priority value
      Returns:
      this builder

    • setDigestPriority

      public NtfyLog4j2Appender.Builder setDigestPriority(String digestPriority)
      ntfy Priority header for the aggregated digest.
      Parameters:
      digestPriority - the priority value
      Returns:
      this builder

    • setErrorTags

      public NtfyLog4j2Appender.Builder setErrorTags(String errorTags)
      ntfy Tags header for individual error alerts.
      Parameters:
      errorTags - the comma-separated tag list
      Returns:
      this builder

    • setDigestTags

      public NtfyLog4j2Appender.Builder setDigestTags(String digestTags)
      ntfy Tags header for the aggregated digest.
      Parameters:
      digestTags - the comma-separated tag list
      Returns:
      this builder

    • setWarnTopic

      public NtfyLog4j2Appender.Builder setWarnTopic(String warnTopic)
      The topic WARN-level events are published to. A non-blank value is the entire opt-in for WARN alerting: unset (the default), this appender alerts on ERROR and above only. It also lowers the level NtfyLog4j2Installer attaches the appender at, so warnings actually reach it. Set it to the same value as topic to alert on warnings through the main topic at a different priority.
      Parameters:
      warnTopic - the ntfy topic for warnings, or null to keep alerting ERROR-only
      Returns:
      this builder

    • setWarnPriority

      public NtfyLog4j2Appender.Builder setWarnPriority(String warnPriority)
      ntfy Priority header for WARN alerts and the WARN digest; default default.
      Parameters:
      warnPriority - the ntfy priority value
      Returns:
      this builder

    • setWarnTags

      public NtfyLog4j2Appender.Builder setWarnTags(String warnTags)
      ntfy Tags header for WARN alerts and the WARN digest; default warning.
      Parameters:
      warnTags - the comma-separated tag list
      Returns:
      this builder

    • setClickUrl

      public NtfyLog4j2Appender.Builder setClickUrl(String clickUrl)
      URL opened when a notification is tapped (ntfy Click header).
      Parameters:
      clickUrl - the click-through URL
      Returns:
      this builder

    • setActions

      public NtfyLog4j2Appender.Builder setActions(String actions)
      Action buttons as a raw ntfy Actions header value (short format, e.g. "view, View logs, https://grafana.example.com/d/abc").
      Parameters:
      actions - the raw Actions header value
      Returns:
      this builder

    • setExcludedLoggers

      public NtfyLog4j2Appender.Builder setExcludedLoggers(String excludedLoggers)
      A single comma-separated value of logger-name prefixes to exclude from alerting.
      Parameters:
      excludedLoggers - the comma-separated prefix list
      Returns:
      this builder

    • setExcludedExceptionTypes

      public NtfyLog4j2Appender.Builder setExcludedExceptionTypes(String excludedExceptionTypes)
      A single comma-separated value of fully qualified exception class names. An event whose cause chain contains any of them never alerts — matched anywhere in the chain, not just on the surface throwable.
      Parameters:
      excludedExceptionTypes - the comma-separated list of fully qualified class names
      Returns:
      this builder

    • setCache

      public NtfyLog4j2Appender.Builder setCache(String cache)
      false asks the server not to store the message (Cache: no). Subscribers who are offline at that moment never receive it. Default true.

      A String rather than a boolean, for the reason applyBoolean(java.lang.String, java.lang.String, java.util.function.Consumer<java.lang.Boolean>, io.github.pimak.ntfy.core.Diagnostics) exists: log4j2's converter maps everything that is not "true" to false, so cache="yes" would turn caching OFF and cost every offline subscriber their alerts without a word.

      Parameters:
      cache - whether the server may cache the message
      Returns:
      this builder

    • setFirebase

      public NtfyLog4j2Appender.Builder setFirebase(String firebase)
      false asks the server not to forward the message to Firebase (Firebase: no). Default true.
      Parameters:
      firebase - whether the server may forward the message to FCM
      Returns:
      this builder

    • setIcon

      public NtfyLog4j2Appender.Builder setIcon(String icon)
      URL of the icon shown beside the notification (ntfy Icon header). Must be an http/https URL; a value that is not one is dropped with a diagnostic. ntfy renders JPEG and PNG only, but that is a property of the bytes served, not of the path, so a URL whose extension names another format is warned about and still sent.
      Parameters:
      icon - the icon URL
      Returns:
      this builder

    • setIconsByLogger

      public NtfyLog4j2Appender.Builder setIconsByLogger(String iconsByLogger)
      Per-logger icon overrides as prefix=url pairs separated by commas. The longest prefix matching an alert's logger wins; anything unmatched keeps the default icon. Alerts only — a notification has no logger to match on.
      Parameters:
      iconsByLogger - the comma-separated prefix=url pairs
      Returns:
      this builder

    • setIncludeMdcKeys

      public NtfyLog4j2Appender.Builder setIncludeMdcKeys(String includeMdcKeys)
      A single comma-separated allow-list of MDC keys whose values are rendered into alert bodies, one key: value line each. Empty by default, and there is deliberately no wildcard form: log4j2's ThreadContext is application-owned and free-form, so only the keys named here are ever published.
      Parameters:
      includeMdcKeys - the comma-separated allow-list
      Returns:
      this builder

    • setLocale

      public NtfyLog4j2Appender.Builder setLocale(String locale)
      Language of notification bodies and diagnostics as a BCP 47 tag (e.g. fr, de-DE). Defaults to English; an unknown/unshipped locale silently uses English.
      Parameters:
      locale - the BCP 47 language tag
      Returns:
      this builder

    • setEnabled

      public NtfyLog4j2Appender.Builder setEnabled(String enabled)
      Master switch; "false" keeps the appender inert even with a complete configuration.
      Parameters:
      enabled - "true" or "false"
      Returns:
      this builder

    • setAsync

      public NtfyLog4j2Appender.Builder setAsync(String async)
      Opt into asynchronous (offloaded) delivery: individual error alerts are handed to the engine's bounded work queue and published by a daemon worker, so a slow/unreachable ntfy server never blocks the logging thread. Off by default (synchronous delivery).
      Parameters:
      async - "true" or "false"
      Returns:
      this builder

    • setAsyncQueueCapacity

      public NtfyLog4j2Appender.Builder setAsyncQueueCapacity(String asyncQueueCapacity)
      Bounded async delivery queue capacity; only consulted when async is "true".
      Parameters:
      asyncQueueCapacity - the capacity, as a decimal string
      Returns:
      this builder

    • setRequireHttpsForCredentials

      public NtfyLog4j2Appender.Builder setRequireHttpsForCredentials(String requireHttpsForCredentials)
      Strict mode: refuse engine activation (rather than only warn) when credentials would be sent over a cleartext http:// endpoint. Off by default (warn-and-activate).
      Parameters:
      requireHttpsForCredentials - "true" or "false"
      Returns:
      this builder

    • setStartupPing

      public NtfyLog4j2Appender.Builder setStartupPing(String startupPing)
      Opt-in startup self-test verifying at boot that the configured endpoint, credentials and topic actually work — instead of finding out when the first real error alert fails to deliver.
      Parameters:
      startupPing - "off" (default), "probe" (read-only reachability check, publishes nothing) or "publish" (a real low-priority test notification); an unrecognized value keeps the default and is reported on the status logger
      Returns:
      this builder

    • setStartupPingFailFast

      public NtfyLog4j2Appender.Builder setStartupPingFailFast(String startupPingFailFast)
      Whether a failed startup self-test aborts application startup instead of only warning. Off by default; enabling it also makes the self-test run inline, adding at most connect+request timeout to boot. Aimed at CI/staging rather than production.
      Parameters:
      startupPingFailFast - "true" or "false"
      Returns:
      this builder

    • setStartupPingWarn

      public NtfyLog4j2Appender.Builder setStartupPingWarn(String startupPingWarn)
      Startup self-test for the optional WARN route, independent of startupPing.
      Parameters:
      startupPingWarn - "off" (default), "probe" or "publish"
      Returns:
      this builder

    • setStartupPingNotifyFailures

      public NtfyLog4j2Appender.Builder setStartupPingNotifyFailures(String startupPingNotifyFailures)
      Whether a failed self-test is announced on a route that passed. On by default.
      Parameters:
      startupPingNotifyFailures - "true" or "false"
      Returns:
      this builder

    • build

      public NtfyLog4j2Appender build()
      Instantiates the appender. Returns null — log4j2's contract for "this element cannot be built", which drops the appender with a status error instead of failing the whole configuration — when no name was given.
      Specified by:
      build in interface org.apache.logging.log4j.core.util.Builder<NtfyLog4j2Appender>
      Returns:
      the configured, not-yet-started appender, or null when unbuildable