Skip to main content
Operating system & services

Log Keyword

Scan log files on Windows, Linux and macOS for keywords and get alerted about new matches since the previous run.

The Log Keyword check scans text files such as application logs for keywords. It reports only lines written since the previous run; content that already exists when you set it up never raises an alert. The check runs on Windows, Linux, and macOS (each as an x64 and an Arm64 build), every 5 minutes by default. For the Windows Event Log, use the Event Log check instead; for journald or Unified Logging, use the System Log check.

Prerequisites

  • You need the Monitoring Check Management permission.
  • The target device has a connected octoja agent on Windows, Linux, or macOS.
  • The agent can read the log files.

Steps

  1. Open the device under Devices and switch to the Checks tab.
  2. Click Add Check → Log Keyword.
  3. Under Log files, enter at least one absolute path or pattern, for example /var/log/app/*.log or C:\Logs\app-*.log.
  4. Under Keywords, enter the terms that should raise a finding, for example ERROR or Exception.
  5. Adjust the remaining settings if needed.
  6. Click Add Check.

The first run only establishes the baseline and reports OK. The check reports findings from the next run onward. To roll the check out to many devices at once, add it to a config package — see Assign checks with config packages.

Settings

FieldTypeRequiredDefaultDescription
Log filesList of stringsYes—Absolute paths or patterns. The wildcards * and ? work only in the file name, not in the folder path. The check skips files and folders that do not exist.
Scan modeChoiceNoNew lines onlyNew lines only scans only the part appended since the previous run. Whole file when changed scans the entire file again as soon as its content has changed.
KeywordsList of stringsYes—A line containing any of these terms is reported.
Ignore keywordsList of stringsNo—A line containing any of these terms is skipped, even when a keyword matches.
Ignore caseYes/NoNoOnApplies to keywords and ignore keywords.
EncodingChoiceNoUTF-8Character encoding of the files: UTF-8, ASCII, or UTF-16 LE.
Include subfoldersYes/NoNoOffAlso searches subfolders for matching files. Applies to patterns only.
Report findings as warningYes/NoNoOffReports findings as a warning instead of critical.
Maximum findingsIntegerNo20Maximum number of findings reported per run. The check treats values below 1 as 20.
Maximum filesIntegerNo100Maximum number of matching files. The check treats values below 1 as 100.

Keywords are matched as substrings, not as regular expressions. The check ignores empty entries and leading or trailing spaces. If several keywords match one line, it counts as one finding.

If you change Log files, Scan mode, Keywords, Ignore keywords, Ignore case, or Encoding, the check starts over with a new baseline. Lines written between the last run and the change are then no longer reported.

Results

SituationStatus
First run: baseline establishedOK
No new findingsOK
At least one findingCritical, Warning with Report findings as warning
No paths or no keywords enteredWarning
None of the specified files were foundWarning
More matching files than Maximum filesWarning; the check then scans no file
The check cannot save its read positionFailure
Unexpected error, for example missing read permissionsFailure, with the error message

The result shows the number of checked and changed files and each finding with its file path and line text. The line text is cut off after 300 characters. When a run reaches Maximum findings, the check stops searching for that run and marks the list as truncated.

How the check detects new lines

  • New files: A file the check sees for the first time is only added to the baseline. Its existing content is never reported, even for a newly created file that a pattern finds later. Only lines appended afterwards can raise findings.
  • Incomplete lines: The check evaluates a line without a line ending only once it has been written completely.
  • Rotation: If a file has become shorter or its first bytes have changed, it is treated as rotated or replaced. The check then scans it from the beginning.
  • Large growth: The check reads about 64 MB per file and run at most. It reads the rest on the next run.
  • Whole file when changed: When the content changes, the check scans the whole file and reports older matching lines again too. It skips unchanged files.

FAQ

The first run only establishes the baseline so that old entries do not raise an alert. The check reports only lines written afterwards. The same applies after you change paths, scan mode, keywords, ignore keywords, case handling, or encoding.

Each run evaluates only the lines that are new since the previous run. If no new findings appear, the next run reports OK again. In Whole file when changed mode, the check reports all matching lines again every time the file changes.

See also: Set up alerts for a check