Configuration

Environment Variables

Prerequisites
For setting configuration file properties such as location and path:

  • First, you should set some environment variables for the locate configuration file.
    There are two options here, you can get the configuration file from a local drive or by using git.

For reading configuration files from a local drive:

  • Set OEC_CONF_SOURCE_TYPE and OEC_CONF_LOCAL_FILEPATH variables.

From reading configuration files from a git repository:

  • Set OEC_CONF_GIT_URL, OEC_CONF_GIT_FILEPATH, OEC_CONF_GIT_PRIVATE_KEY_FILEPATH, and OEC_CONF_GIT_PASSPHRASE variables.

📘

If you are using a public repository, you should use an https format of a git url and you do not need to set private key and passphrase.

KeyValue PropertiesExample
OEC_CONF_SOURCE_TYPEgit → For getting from git

local → For getting from local environment
OEC_CONF_SOURCE_TYPE=git
or
OEC_CONF_SOURCE_TYPE=local
OEC_CONF_LOCAL_FILEPATHfilepath with extension (.yaml, .yml or .json)
Default: ~/oec/config.json
OEC_CONF_LOCAL_FILEPATH=/home/Opsgenie/OECConfig.yaml
or
OEC_CONF_LOCAL_FILEPATH=~/OECConfig.json
OEC_CONF_GIT_URLHTTPS or SSH url of the git repositoryOEC_CONF_GIT_URL=[email protected]:metehan/test-private-conf-cem.git
or
OEC_CONF_GIT_URL=https://bitbucket.org/metehan_ozturk/test-conf-cem.git
OEC_CONF_GIT_FILEPATHfilepath in the git repository folder (.yaml, .yml or .json)OEC_CONF_GIT_FILEPATH=~/oec/config.json
OEC_CONF_GIT_PRIVATE_KEY_FILEPATHgit ssh key location in local driveOEC_CONF_GIT_PRIVATE_KEY_FILEPATH=~/.ssh/id_rsa
OEC_CONF_GIT_PASSPHRASEssh passphraseOEC_CONF_GIT_PASSPHRASE=1234

📘

‘~’ character can be used as home directory for running the program as a user in customer’s server.

Flag

Prometheus default metrics can be grabbed from http://localhost:<port-number>/metrics

  • To run multiple OEC in the same environment, -oec-metrics flag should be set as distinct port number values.
    -oec-metrics <port-number>

Logs

OEC log file is located:

  • On Windows: var/log/opsgenie/oec<pid>.log
  • On Linux: /var/log/opsgenie/oec<pid>.log
  • At the end of the file name of the log, there is program identifier (pid) to identify which process is running.

Configuration File

OEC supports json and yaml file extension with fields. Configuration filepath should be set on OEC_CONF_LOCAL_FILEPATH or OEC_CONF_GIT_FILEPATHaccording to local or git choice.

FieldTypeMandatoryDescription
apiKeystringtrueThe API key which is copied from Opsgenie’s OEC Integration page
baseUrlstringfalseThe API url of the Opsgenie mirror
* Default: 'https://api.opsgenie.com'
logLevelstringfalseLog level of the OEC
Default: ‘info'
Options: ‘info’, ‘debug’, 'trace’, ‘error’, ‘warn’
globalArgslist of stringfalseExecute arguments that applies to all actions
globalFlagsmap of string key-valuefalseExecute flags that applies to all actions
Map field consists flag keys and values.
Given flags might enforce to be parsed in action script or executable.
globalEnvlist of stringfalseEach element indicates one environment variable name and value separated with ‘=’ character. Applies to all actions. (e.g., “ENV1=value”)
actionMappingsmap of string key and mappedAction valuetrueMap of the alert action mappings
Each mapping has an action name(string) as a key which is defined in Opsgenie (e.g., Create).
At least one action should be existed.
actionMappingsmappedActionmaptrueEach mappedAction represents an action and includes an action properties sourceType, filepath, gitOptions and environmentVariables.
actionMappingsmappedActionsourceTypestringtrueType of script file location can be ‘local' or 'git’
actionMappingsmappedActionfilepathstringtrueLocation of script or executable file
* If “local”, full path should be provided (‘~’ can be used). If “git”, the path of the directory should be provided.
actionMappingsmappedActionstdoutstringfalsestdout filepath of action
actionMappingsmappedActionstderrstringfalsestderr filepath of action
actionMappingsmappedActionargslist of stringfalseExecute arguments that applies to specified action
actionMappingsmappedActionflagsmap of string key-valuefalseExecute flags that applies to specified action
Map field consists flag keys and values.
Given flags might enforce to be parsed in action script or executable.
actionMappingsmappedActionenvlist of stringfalseEach element indicates one environment variable name and value separated with ‘=’ character. Applies to specified action. (e.g., “ENV1=value”)
actionMappingsmappedActiongitOptionsmaptrue for git sourceThis field includes all three string properties,
which are
url (git repository url),
privateKeyFilePath (ssh key file),
passphrase (if any).
Properties are same git variables at which Environment Variables section.
* If soruceType is “git”, gitOptions should be set.
actionMappingsmappedActiongitOptionsurlstringtrue for git sourceHTTPS or SSH url of the git repository of the mappedAction
actionMappingsmappedActiongitOptionsprivateKeyFilepathstringfalsePrivate key filepath of the git repository of the mappedAction (if needed)
actionMappingsmappedActiongitOptionspassphrasestringfalsePassphrase of the git repository of the mappedAction (if needed)
pollerConfmapfalseThe field gets all three integer properties specifying behavior of the poller that poll the sqs queue of OEC.
pollerConfpollingWaitIntervalInMillisintegerfalseThe wait period of the poller when there is no new message in the queue or free job worker
Default: 100 (milliseconds)
Small values of this field (e.g., <100ms.) might cause high cpu usage.
pollerConfvisibilityTimeoutInSecondsintegerfalseThe visibility timeout of messages that are polled from sqs queue
* Default: 30 (seconds)
pollerConfmaxNumberOfMessagesintegerfalseMaximum number of messages that are received at a time
Default: 10
Limited by 10 at most.
poolConfmapfalseThe field gets all five integer properties specifying
behaviour of the worker pool that manages workers (go routines)
poolConfmaxNumberOfWorkerintegerfalseMaximum number of worker processing action
Default: 12
Cpu bound processes may not need higher values of maxNumberOfWorker.
* Higher values of maxNumberOfWorker may be meaningful for I/O bound processes.
poolConfminNumberOfWorkerintegerfalseMinimum number of worker processing action
Default: 4
When there is not much active process, minNumberOfWorker determines the lower limit of idle worker number.
poolConfqueueSizeintegerfalseInternal queue size of messages that are received from sqs queue
Default: 0
When all workers are busy, messages can be stored in internal queue.
* Enabling queue size is not recommended and may cause data loss if any program crash.
poolConfkeepAliveTimeInMillisintegerfalseAlive time limit for any worker that is idle when actual worker count is higher than minNumberOfWorker
* Default: 6000 (milliseconds)
poolConfmonitoringPeriodInMillisintegerfalseMonitoring interval to record pool metrics
* Default: 15000 (milliseconds)

🚧

Local variable of args, flags and env overrides global ones.

  • apiKey, opsgenieUrl (baseUrl) and payload (OEC callback as JSON) passes to args as flag format. These flags should be parsed in action scripts or executables.
  • Payload consists alert info and integration specific params. Integration-specific params will exist for “send via OEC” option.
  • OEC updates git repositories periodically every 1 minute.

❗️

OEC integration uses directly actual actions (e.g. Create, Close, Acknowledge, etc.), other integrations use primarily mappedAction related with themselves (e.g. addCommentToIssue, createIssue, etc. for Jira integration).

🚧

Example config files that contain mapped actions and integration-specific flags for each integration can be obtained from the oec-scripts repository.

{
    "appName": "OEC-Example",
    "apiKey" : "4w3a0df7-d5c8-40d7-96db-975986bx3cb4",
    "baseUrl" : "https://api.opsgenie.com",
    "logLevel" : "debug",
    "globalArgs" : ["globalArg"],
    "_globalFlags" : {
        "comment out" : "remove '_' sign to enable globalFlags",
        "flagKey" : "flagValue"
    },
    "globalEnv" : ["globalEnv1=value"],
    "actionMappings" : {
        "Create" : {
            "sourceType" : "local",
            "filepath" : "~/Desktop/executable",
            "args" : ["arg"],
            "_flags": {
                "comment out" : "remove '_' sign to enable flags",
                "flagKey" : "flagValue"
            },
            "env" : ["env1=value"],
            "stdout" : "~/Desktop/createOut.txt",
            "stderr" : "~/Desktop/createErr.txt"
        },
        "Acknowledge" : {
            "sourceType" : "git",
            "filepath" : "/executable",
            "gitOptions" : {
                "url" : "https://bitbucket.org/example/example.git"
            },
            "stdout" : "~/Desktop/ackOut.txt",
            "stderr" : "~/Desktop/ackErr.txt"
        },
        "Custom" : {
            "sourceType" : "git",
            "filepath" : "/executable",
            "gitOptions" : {
                "url" : "[email protected]:example/example.git",
                "privateKeyFilepath" : "~/.ssh/id_rsa",
                "passphrase" : "pass"
            }
        }
    },
    "pollerConf" : {
        "pollingWaitIntervalInMillis" : 100,
        "visibilityTimeoutInSeconds" : 30,
        "maxNumberOfMessages" : 10
    },
    "poolConf" : {
        "maxNumberOfWorker": 12,
        "minNumberOfWorker": 4,
        "queueSize" : 0,
        "keepAliveTimeInMillis" : 6000,
        "monitoringPeriodInMillis" : 15000
    }
}
---
appName: OEC-Example
apiKey: 4w3a0df7-d5c8-40d7-96db-975986bx3cb4
baseUrl: https://api.opsgenie.com
logLevel: debug
globalArgs:
- globalArg
_globalFlags:
  comment out: remove '_' sign to enable globalFlags
  flagKey: flagValue
globalEnv:
- globalEnv1=value
actionMappings:
  Create:
    sourceType: local
    filepath: "~/Desktop/executable"
    args:
    - arg
    _flags:
      comment out: remove '_' sign to enable flags
      flagKey: flagValue
    env:
    - env1=value
    stdout: "~/Desktop/createOut.txt"
    stderr: "~/Desktop/createErr.txt"
  Acknowledge:
    sourceType: git
    filepath: "/executable"
    gitOptions:
      url: https://bitbucket.org/example/example.git
    stdout: "~/Desktop/ackOut.txt"
    stderr: "~/Desktop/ackErr.txt"
  Custom:
    sourceType: git
    filepath: "/executable"
    gitOptions:
      url: [email protected]:example/example.git
      privateKeyFilepath: "~/.ssh/id_rsa"
      passphrase: pass
pollerConf:
  pollingWaitIntervalInMillis: 100
  visibilityTimeoutInSeconds: 30
  maxNumberOfMessages: 10
poolConf:
  maxNumberOfWorker: 12
  minNumberOfWorker: 4
  queueSize: 0
  keepAliveTimeInMillis: 6000
  monitoringPeriodInMillis: 15000