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.