Configuring LogSources for API Script

Last updated on 03 January, 2023

You can use LogSources to view and configure log integrations in the LogicMonitor portal. LogSources provide an out-of-the-box setup and configuration for popular logsources. 

Many resources and services use APIs to access logs. This can be cumbersome to customize and doesn’t support API filters. The LogSources for API Script logsource type helps you set up the import of this type of logs to LogicMonitor. 

Creating LogSources

On the LogicMonitor portal go to Settings to create LogSources. For general information on how to set up a logsource, see Creating LogSources. The following describes configuration options that are specific to the LogSources for API Script type of logsource.

Configuration Options

The options described here configure a logsource that uses a script that calls an API and collects log data on a regular interval.

Attributes

In the Attributes section, add an import script in Groovy format to collect log data from resources specified in the AppliesTo section. In the Schedule drop-down, select the time interval at which you want the script to be executed. Default is one minute. 

Note: For the import to work, ensure that the AppliesTo criteria correctly matches the desired resources. You also need “Manage” permissions to at least one of the mapped resources. See Roles.

Include Filters

You can add filters to include resources of certain types, for example an application. The output matching the filter criteria is forwarded to the log ingestion process.

Available parameters

AttributesComparison operatorValue example
MessageContain, NotContain, RegexMatch, RegexNotMatch.Any string that is part of the message.

Log Fields/Tags

You can configure Log Fields/Tags to send additional metadata with the logs. 

Available parameters

MethodKey exampleValue exampleDescription
Static“Customer”“Customer_XYZ”
Dynamic(REGEX)“Host”“host=*”The query will run on the message field.
LM Property(Token)“Device”“##system.deviceId##”The DeviceID extracted from the existing device property in LM.

Resource Mapping

Configure the LM log property to match a monitored resource.

Available parameters

MethodKey exampleValue exampleDescription
Static“Customer_Id”“1921”
Dynamic(REGEX)“system.ServiceName”“service=*”The query will run on the message field. 
LM Property(Token)“token.resourceMap”“syslog_test_collector”The DeviceID extracted from the existing device property in LogicMonitor.

Script Examples

The following provides guidelines for creating import scripts for retrieving log events. Scripts are added to the Attributes section of the LogSource configuration.

A log event is a JSON object. When creating a JSON object for the output, ensure to follow these guidelines:

  • The JSON object contains all the mandatory and customized event attributes.
  • It contains a JSON array and other attributes indicating the status of the script, for example “status” and “message”.
  • The JSON array contains all the events that will be reported to LogicMonitor.

The following syntax describes the output JSON object:

output            ::= "{" "events" : "[" event ["," event]+ "]"," scriptAttribute]+ "}"
event             ::= "{" messageAttribute ["," customAttribute]+}
messageAttribute  ::= "message" ":" messageText
customAttribute   ::= attributeName ":" attributeValue
messageText       ::= <any string text>
attributeName     ::= <any valid name string allowed in system>
attributeValue    ::= <any string text>

Note: messageAttribute is mandatory. If a parameter in the output cannot be parsed, the corresponding log event is discarded as being invalid.

Example 1: Script output generating a single event

{
       "events": [
                           {
                                "Message":"This is the message of the event",
                                "customAttribute":"This is a custom attribute"
                           }
                        ]
}

Exit code

The import script should also include a successExitCode to indicate successful execution. 

  • It can be any integer value. Default value is “0” indicating successful execution.
  • The output is processed only if the script completes with exit code 0. If the exit code is not specified, the output is discarded to avoid partial event processing.

Example 2: Script output as json(println line)

This sample script provides output as “json (println line)”, and contains the return code “0” to indicate successful execution. The script also includes the mandatory “message” attribute in the event array.

import groovy.json.*
 def get = new URL("sone-url").openConnection();
 def getRC = get.getInputStream().getText() 
 def json = new JsonSlurper().parseText(getRC)
 json.each { it.putAt("message", it.getAt("description")) }
 json.each { it.remove("description") }
 JsonBuilder builder = new JsonBuilder(json)
 builder {
 events builder (json)
  }       println(builder.toPrettyString())
 return 0
In This Article