Introducing Apache NiFi Deprecation Logging
Introduction
Deprecation is an important part of formal software development, providing a standard method for highlighting features that should no longer be used. By establishing a public interface contract, projects indicate stable capabilities. In the course of development, new versions may include features that provide better performance or flexibility than earlier versions. As part of the improvement process, less optimal features can be flagged for future removal.
For projects adhering to Semantic Versioning, deprecation enables developers to indicate features that will be removed in subsequent major version releases. Users and services that depend on stable versioning have the opportunity to make adjustments in response to deprecation warnings, prior to upgrading to the next major version, thus avoiding breaking changes.
Apache NiFi 1.18.0 incorporates deprecation logging as a configurable part of standard deployments. Monitoring deprecation logs enables administrators to identify components, properties, features that will be removed in future versions. Understanding the source and structure of deprecation warnings not only supports incremental upgrade strategies, but also promotes configuration optimization.
Deprecation Logging
NiFi deprecation logging builds on standard runtime logging features and writes messages at the warning level. The NiFi
Administrator’s Guide includes a new section on
logging configuration
with specific details on managing
deprecation logging.
Deployments that use the default logging configuration will have a new log file named nifi-deprecation.log in the
logs directory.
An empty nifi-deprecation.log indicates that the current runtime configuration does not include references to
deprecated components or features. Runtime execution of deprecated capabilities will produce one or more warnings that
include a short description of the problem as well as a stack trace referencing the invocation chain. These elements
should provide sufficient information to locate the source of elements that need to be modified or replaced.
Component Deprecation Notices
NiFi supports a large number of extension components, including some that the project has targeted for removal. Component documentation indicates deprecated status, but these notices are not visible without opening the usage details. Deprecation logging writes a standard message when the framework adds a flagged component to the flow configuration. These warning messages occur both when building a new flow configuration and when the system builds the runtime flow configuration on startup.
The following log provides an example of deprecation warnings written when adding a flagged component to the flow configuration, with additional line separators for easier reading.
WARN [NiFi Web Server-1000] deprecation.org.apache.nifi.processors.twitter.GetTwitter
Added Deprecated Component GetTwitter[id=fdf25a77-0183-1000-ca0a-b76ec1bf66b0]
See alternatives [ConsumeTwitter]
org.apache.nifi.deprecation.log.DeprecationException:
Reference Class [org.apache.nifi.processors.twitter.GetTwitter]
ClassLoader [org.apache.nifi.nar.NarClassLoader[./work/nar/extensions/nifi-social-media-nar-1.18.0.nar-unpacked]]
The warning log includes a number of important details for tracking down the component described.
The logger name of deprecation.org.apache.nifi.processors.twitter.GetTwitter provides an unambiguous reference to the
component class.
The Added Deprecated Component portion of the message includes the component simple name of GetTwitter as well as
the component instance identifier of fdf25a77-0183-1000-ca0a-b76ec1bf66b0, which can be used to find the component
when viewing the flow configuration in a web browser.
The See alternatives portion highlights recommended replacement components with similar functionality, in this case
ConsumeTwitter is listed.
The Reference Class and ClassLoader sections provide additional pointers to the class and package containing the
component listed. These details are less useful when considering deprecated components, but they provide helpful context
for more granular deprecation of specific features.
All components tagged with the standard DeprecationNotice annotation will produce this type of deprecation warning.
Feature Implementation Warnings
Several feature implementation classes have been deprecated for multiple releases, and the system will log warnings when
instantiating one of these classes. The PersistentProvenanceRepository is one example of a deprecated feature
implementation that should be replaced with the current default implementation: WriteAheadProvenanceRepository. The
nifi-deprecation.log will include the following message when instantiating the legacy class.
WARN [Thread-1] deprecation.org.apache.nifi.provenance.PersistentProvenanceRepository
PersistentProvenanceRepository should be replaced with WriteAheadProvenanceRepository
for [nifi.provenance.repository.implementation] in nifi.properties
Reference Class [org.apache.apache.nifi.provenance.PersistentProvenanceRepository]
The warning message notes both the nifi.properties configuration file that needs to be changed, and the specific
property that needs to be updated.
Property Deprecation Warnings
In the process of maintaining and extending various components, some properties no longer provide the best configuration approach. Removing these properties would cause some components to become invalid after upgrading, so new minor releases have maintained support for duplicative configuration options.
The InvokeHTTP Processor is one example of a component with duplicative properties. The Processor supports access
through a proxy server using either individual properties or a Proxy Configuration Service. The Proxy Configuration
Service supports reusable server settings across multiple components, and it provides the recommended approach.
InvokeHTTP will log a deprecation message when configured using the direct Proxy Host property as shown in the
following warning.
WARN [Thread-1] deprecation.org.apache.nifi.processors.standard.InvokeHTTP
InvokeHTTP[id=7501aed0-4a72-41c5-b2e7-471ac79b2494]
[Proxy Host] Property should be replaced with [Proxy Configuration Service] property
Reference Class [org.apache.nifi.processors.standard.InvokeHTTP]
As shown in component deprecation notices, the log includes the component identifier for locating the instance of
InvokeHTTP that should be changed.
Method Deprecation Warnings
Deprecation logging also covers public interface methods that should no longer be used. This applies to features such as Controller Service interfaces which provide a public contract that would break integrating components if it were to be removed.
Deployments that use standard Processors should not see method warnings for Controller Services, but custom components compiled against older versions of NiFi could be impacted.
The SSLContextService is one example of a public Controller Service interface with deprecated methods. The
StandardSSLContextService and StandardRestrictedSSLContextService log the following warnings for invocation of
deprecated createSSLContext() methods.
WARN [Thread-1] deprecation.org.apache.nifi.ssl.StandardSSLContextService
StandardSSLContextService[id=094eb6b5-8d71-4e6d-83a7-be3057791dc9]
createSSLContext() should be replaced with createContext()
Reference Class [org.apache.nifi.ssl.StandardSSLContextService]
Resolving method deprecation warnings requires compiling custom code against a more recent version of NiFi and adjusting method references.
Configuration Options
The default logback configuration in NiFI 1.18.0 includes a DEPRECATION_FILE appender definition that includes
settings to avoid retaining large amounts of deprecation warnings. The appender configuration sets a maximum file size
of 10 MB and a maximum history of 10. Together with a total size limit of 100 MB, these default settings ensure that
unmonitored deprecation logs will not consume an unlimited amount of storage resources.
Deprecation logger names use the reference class name prefixed with the word deprecation, which allows deprecation
logging to be distinguished from standard logging. All deprecation messages will be logged at the WARN level.
Disabling Deprecation Logging
Deprecation warnings are important to review when preparing to upgrade, but can be repetitive for production systems that have infrequent opportunities for modification. In these environments, scheduling required changes and disabling selected deprecation warnings can be a useful interim solution.
As described in the
Deprecation Logging section
of the NiFi Administrator’s Guide, warnings can be disabled for specific components using a named logger element in
the logback.xml configuration. Setting OFF as the level attribute disables deprecation logging as shown in the
following example for the InvokeHTTP Processor.
<logger name="deprecation.org.apache.nifi.processors.standard.InvokeHTTP" level="OFF" />
Implementation Notes
The deprecation logging implementation is a simple wrapper around SLF4J. The nifi-deprecation-log module has a single runtime dependency on the SLF4J API, and the DeprecationLogger interface follows the same structural conventions of the SLF4J Logger. This approach provides straightforward integration across the project, avoiding unnecessary dependencies and complicated configuration.
The NiFi Developer’s Guide includes an extended section on deprecating components and features, outlining a general strategy and including several code examples. This section should be consulted when evaluating removal of components or specific capabilities. As a means of communication between project developers and administrators, deprecation warnings should contain pointers to recommended alternatives.
Conclusion
Deprecation logging does not rank among headline features, but it is an important part of a consistent software versioning strategy. Clear and accessible deprecation warnings provide a strong line of communication from maintainers to users, reducing unexpected issues when implementing and releasing new features. With an understanding of these concepts, both developers and administrators will be in a position to adapt to advances across software releases.