Set Up OS Command Collection

Prerequisites for Setting Up Collection of OS Command Output

Complete the following prerequisite tasks before you set up log collection:

• Create a custom script consisting of OS command, the output of which can be collected in Oracle Log Analytics as logs. Th output of the script's STDOUT is sent as the payload by the agent to the cloud. The STDOUT payload can be a single log entry or multiple log entries. Ensure that the parser used in the Oracle Log Analytics source can parse it. Additionally, the script must be able to handle error conditions and check for prerequisites.

  Store your custom script under agent_inst/state/laStorage/os_cmd/scripts folder in the agent installation folder. Hence, the absolute path for storing the script is:

  • For Oracle Management Agent: /opt/oracle/mgmt_agent/agent_inst/state/laStorage/os_cmd/scripts
  • For Oracle Cloud Agent- Management Agent plugin: /var/lib/oracle-cloud-agent/plugins/oci-managementagent/polaris/agent_inst/state/laStorage/os_cmd/scripts

• Special file permissions may have to be provided to run particular commands in the script. Configure such permissions on the agent host manually. The script and any other commands/scripts that the script runs must have the execute permission for the Management Agent user.

Overall Flow for Collecting OS Command Logs

The following are the high-level tasks for collecting the output of an OS command script:

• Install Management Agent on the host where you want to run the OS command scripts and generate output that needs to be collected in Oracle Log Analytics. See Set Up Continuous Log Collection Using Management Agent.

• Create an entity to identify your agent host in Oracle Log Analytics. The entity must be on the same host as the Management Agent where the script will run. Remote OS command execution is not supported. Typically, the entity is automatically created when you install the Management Agent. See Create an Entity to Represent Your Log-Emitting Resource.

• Create a parser which can parse the output of the script. This parser must be used in the source that will be identified in the following step. See Create a Parser.
• Identify an existing source or create a log source of the type OS command. See Create an OS Command Source.
• Check if you want to configure the agent collection property customized_schedule to set the collection interval of the OS command collection. The default value is 30 seconds. You can update the schedule at agent level, source level, entity level, or association level using agent collection properties. See Agent Properties that You Can Modify and Modify Agent Properties.

• Associate the entities with the source that you created earlier. See Configure New Source-Entity Association.

  After the association is complete, the agent starts running the OS command on a periodic basis, the STDOUT of the command is collected as log data, and that log data starts flowing into Oracle Log Analytics.

• View log data in the Log Explorer by selecting the OS Command source that you created earlier. See Filter Logs by Source Attributes.

If the log data has not appeared in the Log Explorer after the set up is complete, you can check for agent collection warnings for any issues. The following warnings are specifically related to OS Command output collection:

• External Application Execution Failure: An error occurred while running the script or the OS command is unsupported.

• External Application Not Found: Script not found, No Read/Execute permissions on script.

See View Agent Collection Warnings.

Important Factors to Consider While Setting Up OS Command Collection

• Use complete path of commands in the scripts; For example, use /bin/sudo instead of sudo.

• The scripts run as the same user that the Management Agent is running as. This is important while reading or writing files in script.

• The output generated by the script on Standard Out (STDOUT) and Standard Error (STDERR) is collected as text to extract the log entries.

• The following words or prefixes are not supported in OS command or the name of the script: sh, bash, csh, zsh, ksh, dash, cmd

• The following characters are not supported in OS command or the name of the script: |, &, ;, >, <

• The following parent directory traversal sequences are not supported in OS command or the name of the script: /../ or \..\. Also, the OS command cannot end with /.. or \...

• The following environment variable is passed to the scripts from the agent. You can use the variable in the scripts.

  • LA_SOURCE_COMMAND_ID: This is internally generated pattern id of the command in the log source. It can be used to differentiate between script instances if the same script is given in multiple commands.