Monitoring file or directory
After you install the Instana agent, the sensor for monitoring files or directories is automatically deployed and installed. You can view events that are related to a particular file or directory in the Instana UI.
Supported operating systems
The following operating systems are supported for monitoring file or directory:
- Linux
- Mac OS or OS X
- Windows
Configuring
Instana generates events for monitored files or directories based on the configuration settings of the local machine.
To obtain events of a particular file or directory in the Instana UI, you need to create a monitor with conditions, and set an event interval by configuring the following fields in the agent configuration file <agent_install_dir>/etc/instana/configuration.yaml
.
To enable the filemonitoring
sensor, set enabled: true
in the configuration.yaml
file and provide at least two valid monitors.
Event interval
The following example shows the configuration for setting up the event interval:
com.instana.plugin.filemonitoring:
enabled: true
file_events:
- event_intervals:
- interval_1: 30 # sec
- interval_2: 90 # sec
- interval_3: 50 # sec
- interval_4: 70 # sec
You can set a maximum of four event intervals (in seconds) at a time.
Monitors and conditions
The following example shows a configuration for setting up a monitor with a condition. The configuration adds a file monitoring rule for monitoring the number of files in a folder. The condition for triggering an event is set up such that when the number of files in the folder reaches 3, an event is triggered.
com.instana.plugin.filemonitoring:
enabled: true
file_events:
- event_intervals:
- interval_1: 30 # sec
- interval_2: 90 # sec
- interval_3: 50 # sec
- interval_4: 70 # sec
- path: '<path of the file or folder>' #eg for file: '/Users/username/Downloads/agent.log' #eg for directory: '/Users/username/Downloads/'
conditions:
- 'FILE_COUNT = <file count>' #eg: 3
name: '<name should be unique for each monitor>' #eg: 'Compare-filecount'
interval: '<interval variable as described in the event_interval section >' #eg: 'interval_1'
severity: '<WARNING or CRITICAL>' #eg: 'WARNING'
If necessary, you can create multiple monitors with multiple conditions. For more information about detailed attributes of the monitors and conditions, see Configurable stats for monitors and Configurable stats for conditions.
Events are generated based on the monitors and conditions that are specified in the agent configuration.yaml
file. The following types of relationships trigger events:
- AND: An event triggers when more than one condition exists within a monitor and all the condition thresholds are met.
- OR: An event triggers when more than one monitor exists for a file or directory path and any set of conditions within any of the monitors are met.
The AND relationship applies within monitors, while the OR relationship applies between monitors with the same path.
The following example shows the AND relation between conditions:
com.instana.plugin.filemonitoring:
enabled: true
file_events:
- event_intervals:
- interval_1: 30 # sec
- interval_2: 90 # sec
- interval_3: 50 # sec
- interval_4: 70 # sec
- path: '/Users/username/Downloads/agent.log' # file path
conditions:
- 'SIZE >= 3000' # file size in bytes
- 'LAST_MODIFIED_TIME < 2D:10H:30M' # last modified Day:Hour:Minute duration
name: 'filesize-filelastmodifiedtime' # name should be unique for each monitor
interval: 'interval_1' # interval variable as described in the event_interval section
severity: 'WARNING' # WARNING or CRITICAL
The following example shows the OR relation between monitors:
com.instana.plugin.filemonitoring:
enabled: true
file_events:
- event_intervals:
- interval_1: 30 # sec
- interval_2: 90 # sec
- interval_3: 50 # sec
- interval_4: 70 # sec
- path: '/Users/username/Downloads/agent.log' # file path
conditions:
- 'SIZE >= 3000' # file size in bytes
- 'LAST_MODIFIED_TIME < 2D:10H:30M' # last modified Day:Hour:Minute duration
name: 'filesizedatemodified' # name should be unique for each monitor
interval: 'interval_1' # interval variable as described in the event_interval section
severity: 'WARNING' # WARNING or CRITICAL
- path: '/Users/username/Downloads/agent.log' # file path
conditions:
- 'CHECKSUM != <Specify SHA-512 Checksum value>' # Use SHA-512 algorithm for generating checksum
name: 'filechecksum' # name should be unique for each monitor
interval: 'interval_2' # interval variable as described in the event_interval section
severity: 'WARNING' # WARNING or CRITICAL
checksum_file_size: 100 # for checking checksum please mention the file size (in MB) limit
To monitor a checksum, you must set a limit for the checksum_file_size
parameter. If you do not set a limit for the checksum_file_size
parameter, then the default value is 10 MB. You are recommended to use a smaller
file for checksum monitoring purposes.
Configurable stats for monitors
The following table outlines the stats for monitors:
Stats | Description |
---|---|
path |
Path of the file or directory. When you specify directory paths, the directory paths must end with / . For example, path: /Users/Instana/scripts/ . Here, scripts is a directory. |
conditions |
Conditions that trigger events. |
name |
A unique name for each monitor. |
interval |
Any interval that is specified within the event_intervals . |
severity |
WARNING or CRITICAL |
Configurable stats for conditions
The following table outlines the stats for conditions:
Stats | Description |
---|---|
SIZE |
The SIZE attribute sets events that are triggered against the specified size of a file. The size must be in bytes. |
FILE_COUNT |
The FILE_COUNT attribute sets the number of files that exist within the specified directory path. |
LAST_MODIFIED_TIME |
The LAST_MODIFIED_TIME attribute sets the last modified time of a file within the specified directory path. |
CHECKSUM |
The CHECKSUM attribute verifies the checksum of a file that exist within the specified directory path. To create the CHECKSUM , you must use SHA-512 as a preferred hashing algorithm. |
You can use any of the following operators with the configurable stats attributes in the condition:
Operators |
---|
> |
>= |
< |
<= |
= |
!= |
IN |
The following example shows the usage of the IN
operator:
com.instana.plugin.filemonitoring:
enabled: true
file_events:
- event_intervals:
- interval_1: 30 # sec
- interval_2: 90 # sec
- interval_3: 50 # sec
- interval_4: 70 # sec
- path: 'agent.log' # file that needs to be searched
conditions:
- 'agent.log IN (/Users/username/Instana/agent-installer/instana-agent/data/log/,/Users/username/Downloads/)' #specify Directory paths for searching the agent.log file
name: 'agent.log in folders' # name should be unique for each monitor
interval: 'interval_1' # interval variable as described in the event_interval section
severity: 'WARNING' # WARNING or CRITICAL
To check a file in a path, you can use the IN
operator. The IN
operator triggers an alert only if the specified file exists in the directory path. You can specify the directory path in the (path1,path2,..)
format.
Viewing events
To view the events, select Events from the navigation menu in the Instana UI. You can see all events on the Events dashboard.