Apache NiFi logging configuration: what your team gets from it
Logback configuration controls what a NiFi node writes to its log files, and log shipping copies those files to a central store so one search can cover the whole cluster. A team needs both when an incident touches several nodes and the evidence sits in separate files on each host. By default, NiFi writes nifi-app.log for framework and component activity, nifi-user.log for user and access events, and nifi-bootstrap.log for startup and the Java process that launches NiFi. Each file has a different owner and a different use during an investigation, so the first decision is which of them must reach the central store. The NiFi System Administrator's Guide describes the default logging setup for your release. Confirm it before you change anything.
The value of centralized logs depends on whether each line can be traced back to the work that produced it. NiFi uses mapped diagnostic context (MDC), which attaches identifiers to log lines so that messages from one processor or request can be grouped. Confirm which MDC keys your NiFi version attaches, and test that a search on one of them returns the same activity from every node. Per-component log levels let you raise detail for one processor or controller service without flooding the store with debug output from the whole flow. Ask your team to name which components need elevated levels during an incident, who approves the change, and how it is reverted. Deprecation logging is useful too, because it flags settings that will break during an upgrade.
Logs do not replace NiFi's own evidence. Bulletins show processor warnings and errors in the user interface and can be routed to alerts, while provenance records what happened to each FlowFile as it moved through the flow. Logs show what the framework and JVM were doing at the time, which is the view you need when provenance does not explain a failure. Log files can also contain sensitive data, so decide access, retention and redaction before shipping them. Shipping to Grafana Loki or OpenSearch moves that responsibility to the central platform, and the platform's access controls must match the sensitivity of the flow data.
Which NiFi log file answers which question
The application log is where most troubleshooting starts. It records what the NiFi framework and its processors do while flows run, including errors, warnings and messages that processors and controller services write during execution. When a processor fails, a connection stalls or a cluster node reports a problem, this is usually the first file to read.
- Question it answers: What did the flow or framework do, and what failed while it ran?
- Where it is written: Confirm the default directory and file name in the administration guide, because the location depends on your install layout.
- What changes it: Logger levels in the logback configuration file set verbosity for the root logger and for individual packages or components.
- Rotation and retention: Check the rolling policy in the logback configuration, since the size and number of retained files decide how far back you can search.
- Cluster behavior: Each node writes its own copy, so collect the log from every node involved in an event.
Before changing any level, confirm the current logback settings on each node so you know the baseline verbosity.
The user log records authentication and access activity: who signed in, which authentication provider handled the request, and which actions for users in the UI and API were allowed or refused. It is the file that security teams and auditors use to answer questions about access, and it is usually read in a different workflow from the application log.
- Question it answers: Who signed in, from where, and was each request authorized?
- Authentication events: Login attempts and failures for the providers you enabled, such as single-user, LDAP, OpenID Connect, SAML 2.0 or client certificates.
- Authorization decisions: Denied requests, which often point to policy gaps or group mappings that do not match the identity provider.
- Where it is written: Confirm the file name and location in the administration guide, and check whether your logback configuration sends it to its own appender.
- Shipping implications: This file often holds usernames and IP addresses, so confirm retention and access rules with your privacy and compliance owners before forwarding it anywhere.
Check that the user log is separated from the application log in your configuration, because a combined file makes access reviews slower.
The bootstrap log captures what happens when the NiFi process starts and stops. It shows the Java command the bootstrap process builds from its configuration, JVM startup problems and shutdown events. It answers why NiFi did not start or why it restarted, including failures that happen before the application logging system is available to record them.
- Question it answers: Why did the process fail to start, stop or restart?
- Startup settings: The bootstrap configuration file controls the Java runtime path, JVM arguments and heap settings that appear here. Confirm the Java 21 path and arguments on each host.
- Early failures: Problems such as an unreadable keystore, a missing property or a port conflict can appear here first.
- Where it is written: Confirm the default location in the administration guide, and whether your service manager also captures standard output in a separate place.
- Diagnostics link: Record the JVM arguments the bootstrap process used when you collect diagnostics, so a later restart can be compared with the previous run.
Compare the bootstrap log with the service manager's journal after any unexpected restart, since the two sources may record timing differently.
Deprecation logging records use of components, properties or behaviors that a future NiFi release is expected to remove. It does not show a failure today, so teams often never read it. It matters most when planning the move from NiFi 1.x to 2.x, where the migration guidance lists changes that break existing flows and custom code.
- Question it answers: Which parts of our flows or custom code will break on upgrade?
- Upgrade inventory: Use deprecation entries as one input to the inventory, alongside the migration steps in the guidance, such as moving to 1.27.0 before 2.0.0.
- Known 2.0 changes: Entries may point to the removal of the variable registry expression language scope or the renamed distributed map cache components described in the migration guidance.
- Where it is written: Confirm how the deprecation logger is configured in logback for your version, since it is often separate from the application log.
- Load coverage: Some deprecated code paths run only in specific flows or on batch schedules, so capture entries across a full business cycle, including jobs that run infrequently.
Export the deprecation entries before each upgrade step so the migration plan reflects what your flows actually did.
How logback controls NiFi log levels and appenders
NiFi writes its logs through logback, and the logback configuration file decides three things: where each log line goes, how files roll over and how long they are kept, and how verbose each logger is. The file defines appenders, which are the destinations such as the application log, the user log and the bootstrap log. Each appender has a rollover policy that sets when a file is rotated, typically by size or by time, and a retention rule that sets how many rotated files survive. Before you change anything, confirm the exact file name, appender names and property keys in the System Administrator's Guide for your NiFi version, since these have shifted between the 1.x and 2.x lines. The Apache NiFi System Administrator's Guide is the reference for this.
Logger levels sit on top of the appenders. A root level sets the default for the whole JVM, and named loggers override it for a package or class. This is how you raise one component's detail without flooding the rest of the log. For a processor or controller service, the usual approach is a logger scoped to its implementation class, set to DEBUG for a bounded investigation and then returned to INFO. Keep a record of every temporary change, because a DEBUG logger left on for weeks fills disks and buries the lines you need. Deprecation logging is a separate signal: it reports use of deprecated properties and APIs, and it is the early warning to review before an upgrade. Treat its output as a work list, not as noise.
Mapped diagnostic context (MDC) adds fields such as the component or request identifiers to each line, so you can filter a shipped log stream by a single processor or user action. Confirm which MDC keys your version writes and whether the pattern layout includes them, because a log shipper can only index fields that appear in the line. Decide this before building dashboards, since changing the pattern later breaks existing parsing rules. A short illustrative check is to trigger one processor error and confirm the resulting line carries the expected identifier when read on the node.
Logging options and when each fits
This table compares the ways to keep, tune and ship NiFi application, user and bootstrap logs. Read each row for the fit, the cost in log volume or operator effort, and the one thing to confirm before you choose it. Most teams combine a local baseline with shipping, and the right mix depends on your retention rules and which backend you already run.
| Option | Fit and cost | Confirm before choosing |
|---|---|---|
| Keep logs local on each node | Simplest baseline; logs stay in the NiFi logs directory on each node. Cost is manual searching across nodes and risk of losing history if a node or disk fails. | Whether node-local retention and rotation in logback.xml meet your audit and incident response needs |
| Raise level for one component | Adds detail for a single processor or service without flooding all logs. Cost is extra volume only while enabled, and the change must be reverted after the investigation. | The logger name for the component and who owns reverting the level |
| Lower level for a noisy component | Cuts volume from chatty components so shipped logs stay useful. Cost is that warnings or errors from that component may be hidden if the level is set too high. | That the component emits no errors you need to keep at the chosen level |
| Enable deprecation logging during upgrades | Surfaces use of deprecated APIs or components before a NiFi 2 upgrade. Cost is a short review of the log output and a test window on a non-production cluster. | That the flows and custom code under test cover the deprecated features you actually use |
| Ship through Grafana Alloy to Loki | Central search and retention in Loki on object storage. Cost is a log shipper to run and operate, and Loki storage and tenancy to design and secure. | Your Loki deployment mode, retention period, and the reverse proxy that provides authentication |
| Ship through Fluent Bit or Fluentd | Lightweight or flexible shipping to Loki or other stores. Cost is parser and label configuration maintained by your team across nodes. | That your chosen shipper supports the output and parsing you need for multi-line NiFi stack traces |
| Ship to OpenSearch ingestion | Search and dashboards in OpenSearch with role-based access and audit logs from the Security plugin. Cost is index sizing, lifecycle policies and cluster operations. | Whether your team already runs OpenSearch and how index lifecycle and access roles will be managed |
Setting up logging and a shipper step by step
This sequence moves a NiFi node from default logging to a tuned logback configuration with predictable rollover, then ships the app, user and bootstrap logs to a backend where a known line can be found with its node and component fields. Each step ends with a check so a problem is caught before the next change is made.
Back up the current logback configuration
Before any change, copy the existing logback.xml from the NiFi conf directory on every node to a dated file kept outside the NiFi installation directory, so the original can be restored if a later change breaks startup. Your platform or operations team should do this on each node, since the cluster nodes may have drifted from one another. The step is done when the backup files exist on every node and a checksum or diff confirms they match the original content. Keep the backup with your other configuration records so that it is available during a recovery.
Change one logger level at a time
Edit logback.xml to adjust a single logger, such as a specific NiFi package or a component class, and leave every other logger unchanged. Logback picks up configuration changes on a scan interval when the scan setting is enabled, so confirm that setting in your file before relying on it, and otherwise plan a controlled restart. Verify the change by generating the activity that the logger covers and checking that the expected lines appear, and that unrelated log output has not changed. Only then make the next change, because changing several levels together makes it hard to tell which one caused noise or missing lines.
Confirm rollover and retention on disk
Check the appender settings for the app, user and bootstrap logs, including the rollover pattern, the maximum file size and the number of retained history files. Watch the log directory on a node under normal load and confirm that files rotate at the expected point and that old files are removed when the retention limit is reached. Also confirm that the log volume has enough free space for the retained files plus growth, since a full log partition can affect the node. The step is complete when rollover has happened at least once on each node and the file count matches the configured retention.
Install the shipper on each node
Install the log shipper on every NiFi node so that each one reads its own local log files, because the shipper must see the files the node writes. Grafana Alloy is the shipper Grafana supports for Loki, and Fluent Bit or Fluentd are also accepted by Loki, while OpenSearch environments commonly use a shipper of the team's choice. Configure it to read the app, user and bootstrap log paths and to add the node name as a field, and do not point several nodes at the same shared file. The step is done when the shipper service runs on each node and its own status or self-metrics show it is reading the expected files without errors.
Configure the shipper pipeline and parsing
Define the pipeline that reads the log lines, parses the timestamp, level and logger name, and attaches labels or fields for the node and the component or logger that produced the line. Keep label cardinality low when shipping to Loki, because high-cardinality labels such as request IDs make queries slow and storage costly, and place those values in the log body or structured metadata instead. Test the parser against sample lines copied from each log file, including multi-line stack traces, which must stay together. The step is done when sample lines parse into the expected fields with no unexpected dropped or merged records.
Connect the shipper to the chosen backend
Point the shipper at the Loki or OpenSearch endpoint, and configure the tenant header or index naming, authentication and TLS as the backend requires. Loki identifies tenants with the X-Scope-OrgID header when multi-tenancy is enabled, and Loki has no built-in authentication layer, so an authenticating reverse proxy must sit in front of it. Test the shipper against the chosen backend's current documentation, since configuration keys and supported options change between releases. The step is done when the shipper reports successful writes and the backend accepts the records without authentication or tenant errors.
Verify a known log line arrives with its fields
Write a uniquely marked test line through a known logger on one node, such as a message with a random token, and search for that token in the backend. Confirm that the record carries the correct node name and component or logger fields, and that the timestamp matches the node's clock. Repeat the test on each node, because a single successful node does not prove the others are configured the same way. The step is done when the marked line is found with the expected fields on every node, and the result is recorded with the configuration version so later changes can be compared against it.
Securing log data and access in transit and at rest
Logs from NiFi and the shipping path to Loki or OpenSearch often hold more sensitive material than teams expect: parameter values, user actions and tenant data. The cards below pair each exposure with a control you can apply and a point to confirm with the vendor before go-live.
Sensitive values in log output
Log lines can carry parameter values, connection details, query text or payloads that a processor echoes on error. Treat log level as a security setting: keep component debug logging off in production, and review which loggers you raise to DEBUG or TRACE during an incident. Confirm with your team how sensitive parameter values are rendered in bulletins and app logs in the NiFi version you run, and whether your shipper can redact or drop fields before they leave the node.
Unauthenticated Loki endpoints
Loki has no built-in authentication layer, so the push and query APIs are open to anything that can reach them. Place an authenticating reverse proxy such as nginx, HAProxy, OAuth2 Proxy or Pomerium in front of Loki, bind the backend to a private network, and allow only the NiFi or Alloy hosts to write. Confirm which proxy your security team has approved and how it passes identity to Loki.
Tenant mix-ups in Loki
When auth_enabled is true, Loki separates data by the X-Scope-OrgID header, and that header is trusted only as far as the layer that sets it. If the proxy lets clients choose the tenant, one team can read another team's NiFi logs. Map tenants from authenticated identity at the proxy, strip client-supplied tenant headers, and test cross-tenant reads before onboarding a second team.
Weak TLS between shipper and backend
Logs travel from NiFi hosts or Alloy agents to the backend, and shipped copies often sit on a network path that nobody reviewed. Require TLS on every hop, pin trusted certificate authorities for the shipper, and rotate certificates on a schedule your operations team can keep. Ask your OpenSearch or Loki provider which TLS versions and cipher settings are supported in your release, and verify them with a scanner rather than assuming defaults.
Access to user action logs
NiFi user logs record who changed a flow, who viewed data and who started or stopped components, which makes them sensitive in their own right. Restrict query access to a named group, separate it from application log access, and keep the copy in the backend under the same roles. In OpenSearch, use role-based access control, field-level security and audit logs for this index. Confirm how your chosen backend exposes those controls in your version.
Encryption and retention at rest
Shipped logs persist in object storage or index shards, often longer than the NiFi host logs they came from. Decide per data class how long each log type is kept, enable retention deliberately, and encrypt the storage volume or bucket under your key management policy. Loki retention is disabled by default, so logs are kept until you enable it, which is the setting to check first.
Choosing Loki or OpenSearch for NiFi logs
The choice between Grafana Loki and OpenSearch for NiFi logs comes down to how you will search and retain them. Loki indexes only labels and keeps compressed log chunks and its index in object storage, so it suits teams that mostly filter by stream labels such as NiFi host, logger or log file and then read the matching lines. Loki documents three deployment modes: monolithic, which it describes as a single binary for up to about 20 GB of logs per day, simple scalable, and microservices for very large clusters. The simple scalable mode is being deprecated and will be removed with Loki 4.0, so confirm the mode you choose against the current Loki deployment modes documentation before you build. Also confirm that retention is turned on deliberately, because the compactor's retention is disabled by default and logs are kept indefinitely until you enable it.
OpenSearch indexes full text and fields, which makes ad hoc searches across NiFi app, user and bootstrap logs faster to write and more flexible, at the cost of heavier storage and cluster sizing. Its software is released under the Apache License, Version 2.0, and the OpenSearch FAQ does not describe a paid edition. Its Security plugin provides role-based access control, document and field-level security, field masking, audit logs and TLS, and supports SAML, OpenID Connect, LDAP and other authentication backends, which can matter if NiFi log content is sensitive. Installation options include Docker, Helm, the OpenSearch Kubernetes Operator, tarballs and packages. Confirm sizing, node counts and current release details for your own daily volume with the vendor before you commit.
Licensing is the main difference to record in your decision. Grafana Labs moved Loki and its other core projects from Apache License 2.0 to AGPLv3 in April 2021, so Loki is AGPLv3 licensed while OpenSearch is Apache 2.0. Have your legal or compliance team confirm whether AGPLv3 obligations fit how you distribute or host the service. Loki also has no built-in authentication, so you must place an authenticating reverse proxy in front of it, and you must set auth_enabled and the X-Scope-OrgID tenant header if you run multiple tenants. Whichever backend you choose, plan the Alloy, Fluent Bit or OpenTelemetry shipper configuration and the access model before go-live.
Limits to confirm before you ship NiFi logs
Log shipping for NiFi depends on limits that sit outside NiFi itself: the Loki deployment mode, the object store, retention and the shipper. Confirm each one against your own log volumes and NiFi version before you choose the design.
Daily log volume against deployment mode
Measure how many gigabytes of NiFi application, user and bootstrap logs your nodes write per day, including debug output from any per-component log levels you plan to raise. Compare that figure with the sizing guidance for each Loki mode. Monolithic mode is documented for up to about 20 GB per day, and simple scalable mode is documented for approaching 1 TB per day. Your measured volume, not the average, decides the mode.
Simple scalable mode is being deprecated
The Loki documentation states that simple scalable deployment mode is being deprecated and will be removed with the Loki 4.0 release. If your sizing points to that mode, plan a path to microservices or monolithic mode before you build the cluster, rather than discovering the gap during an upgrade. Ask Grafana Labs or your partner which mode they recommend for your volume and the Loki version you will run.
Production object store choice
Loki keeps compressed chunks and its index in object storage. The documented production options are Amazon S3, Google Cloud Storage and Azure Blob Storage. MinIO, S3-compatible stores and the local filesystem are supported but are not typically recommended for production. If you run on-premises object storage, confirm durability, versioning and access controls with your storage team before you commit to it.
Retention settings and compactor
Retention is disabled by default, so logs accumulate until you set retention_enabled. Retention can apply globally, per tenant or per stream selector, and each stream rule must cover at least 24 hours. Decide how long audit-relevant NiFi user logs and operational logs must be kept, and set separate rules where the periods differ. Confirm that the compactor runs and that the object store is sized for the retained volume.
Shipper support for NiFi log files
Grafana Alloy is Grafana's supported log shipper for Loki, and Loki also accepts OpenTelemetry logs over HTTP, Fluent Bit, Fluentd and the Docker logging driver. NiFi writes multi-line stack traces and rolls its files, so confirm that your shipper handles multi-line joining, file rotation and the file names created by your logback appenders. Test with a real rollover before you rely on it.
Logback behavior across 1.x and 2.x
The logback configuration file, appender names and deprecation logging behavior can differ between NiFi 1.x and 2.x, and 1.x is no longer maintained. Before you copy a logback file from one version to another, confirm the appender and logger names against the release you run. Test per-component log levels and the mapped diagnostic context fields on a non-production node, because a silent mismatch leaves your shipper with no data.
Questions teams ask about NiFi logging and log shipping
What drives the cost of NiFi logging and log shipping work?
The cost depends on how many NiFi nodes you run, how much log data they produce, which backend receives it, and what compliance evidence you need to keep. Your team pays for the infrastructure that stores logs, such as object storage for Loki or data nodes for OpenSearch, and for the time spent on logback configuration, parsing and dashboards. Recurring costs come from storage growth and retention periods, which often matter more than the one-time setup. Ask any partner for a quote that separates one-time configuration from ongoing hosting, storage and support, and that states which nodes, backends and retention rules are in scope. DeployOpen quotes follow from a written scope.
How long does it take to ship NiFi logs to Loki or OpenSearch?
Duration depends mainly on the number of nodes, whether your backend already exists, and how many log sources need parsing. A single-node test with an existing backend can move quickly, while a multi-node cluster with separate app, user and bootstrap log streams, per-component levels and retention rules takes longer because each piece needs verification. Plan time for backend sizing, agreeing on labels or fields, and testing alert queries against real NiFi output. Your partner should confirm a timeline in the written scope rather than assume one from general experience.
What does our team need to provide before log shipping starts?
You need to provide access to the NiFi nodes and their conf directory, a decision on the backend, and named owners for each log stream and retention rule. Access should include permission to edit logback.xml and restart nodes in a change window. For Loki, you also need an object store or an agreed filesystem location, and an authenticating reverse proxy, because Loki has no built-in authentication layer. For OpenSearch, you need decisions on index lifecycle and access roles. Without named owners, retention and access decisions tend to stall after go-live.
Can our in-house team configure NiFi logging and log shipping alone?
Yes, a team with Linux, Java and log platform experience can configure logback and a shipper such as Grafana Alloy or Fluent Bit. The work is well documented, and the NiFi administration guide describes the logback setup. The harder parts are usually not the initial file edits but the operating model: choosing labels that keep queries fast, handling multi-line Java stack traces, setting retention, locking down access, and testing that logs survive a node restart. Teams with no one on call for the log platform often benefit from a partner review of the design before rollout.
Do NiFi logs replace provenance or bulletins?
No. Application logs record what the NiFi process and its components report, and they help with diagnosing the JVM and component behavior. Provenance records the lineage of each FlowFile as it moves through the flow, and bulletins are the warnings and errors shown in the UI and available for alerting. Each serves a different purpose, so an audit or incident review usually needs all three. Keep provenance and bulletin storage in their own planned locations, and treat log shipping as an addition to them.
Does log volume affect the design of the backend?
Yes. Log volume decides which Loki deployment mode fits, how much object storage you need, and how large an OpenSearch cluster must be. Loki's documentation describes monolithic mode for up to about 20 GB of logs per day, and simple scalable mode for much larger volumes approaching 1 TB per day, but that mode is being deprecated and removed with Loki 4.0. Measure real output from a representative node before choosing, and reduce noise by setting per-component log levels deliberately, since verbose debug output from one processor can dominate the stream.
What compliance questions should we answer before shipping NiFi logs?
Confirm what log content may leave the NiFi nodes, because flow names, error messages and sometimes payload fragments can contain personal or regulated data. Decide retention periods per stream and who may read them, and record those decisions in your change management records. Loki retention is disabled by default, so logs persist until you enable it, which can conflict with a deletion policy. DeployOpen prepares systems, controls and evidence for compliance assessments, but auditors and certification bodies issue the assessment outcome, so confirm the required control mapping with your assessor.
How DeployOpen scopes and supports NiFi logging work
DeployOpen plans, implements, hardens and documents self-hosted open-source platforms inside the client's own infrastructure, including their cloud accounts, data centers and restricted networks. For NiFi logging, that means the work covers the logback.xml changes for application, user and bootstrap logs, the per-component log levels, the mapped diagnostic context fields, and the shipping path into Loki or OpenSearch, all running in your environment. The written scope defines which of those pieces are in, which log destination is chosen, who owns the log store, and what evidence is handed over at the end.
Most engagements are fixed-scope. Before any configuration change is made, the scope, deliverables and timelines are agreed in writing, and a quote follows from that document rather than from a generic price list. Ask for the quote to separate the one-time work (logging design, configuration changes, shipper setup, verification and documentation) from anything that recurs, such as storage sizing for your log volume, retention policy reviews and upgrades of NiFi, the shipper or the log platform. Confirm which items depend on your own teams, for example access to the NiFi nodes, a log store you already operate, or sign-off from your security team on what log content may leave the cluster.
Ongoing support is available as a retainer for teams that want someone to watch the pipeline after handover. A retainer typically covers reviewing log volume and retention as the flow grows, adjusting levels after incidents, and applying upgrades to the shipper and log store when your change process allows. DeployOpen prepares configurations, runbooks and evidence that your internal or external auditors can review, but it does not issue audit reports, attestations or certifications. Those decisions remain with your independent assessor.
