Skip to content

Latest commit

 

History

History
227 lines (192 loc) · 7.66 KB

CONTRIBUTING.md

File metadata and controls

227 lines (192 loc) · 7.66 KB
Raw

How to Contribute

Third-party patches are essential for enhancing webhook integrations. We simply can't create or maintain all of the possible endpoints webhook integration enables. We want to keep it as easy as possible to contribute changes that provide the integration you need in your environment. There are a few guidelines that we need contributors to follow outlined below.

Basic Concepts

  • Incoming webhook formats -- You need to know what the format of the incoming webhook payload is. The payloads for Log Insight and vRealize Operations Manager are outlined below.
  • Shim framework -- Web service and helper functions for parsing input
  • Webhook payload translation shims (aka shims) -- Two primary shim formats exist today:
  • Fire and forget -- for systems that you do not care about handling state (e.g. Slack) or automatically support handling state (e.g. PagerDuty)
  • Check, fire, and forget -- for systems that you do care about handling state (e.g. ServiceNow)

In general, contributions will be made to the shims. Shims should provide format conversation, logging and error handling. If the destination system expects one POST per log event, the shim should iterate over the alert's messages key. If posting to the destination fails, the shim should return a non-200 HTTP status back to Log Insight.

Getting Started

  • Make sure you have a GitHub account
  • If you are fixing a bug, open an issue, assuming one does not already exist.
  • Clearly describe the issue including steps to reproduce.
  • Fork the repository on GitHub

Making Changes

  • Create a topic branch from where you want to base your work.
  • This is usually the master branch.
  • To quickly create a topic branch based on master; git checkout -b fix/master/my_contribution master. Please avoid working directly on the master branch.
  • Make commits of logical units.
  • Make sure you have added the necessary tests for your changes.
  • Run all the tests (outlined below) to assure nothing else was accidentally broken.

Running Tests

Some of the tests require a connection to a live server. Others use unittests and/or requests_mock. Ensure the system you are running the tests from have access to the Internet and proper DNS configuration.

To get started:

virtualenv loginsightwebhookdemo
cd loginsightwebhookdemo
source bin/activate
git clone https://github.com/vmw-loginsight/webhook-shims.git
cd webhook-shims/
pip install -r test-requirements.txt
tox

Submitting Changes

  • Push your changes to a topic branch in your fork of the repository.
  • Submit a pull request to the repository.
  • Update the issue, if applicable, and include a link to the pull request.
  • Wait for feedback from the review team
  • Address feedback if provided

Revert Policy

If an issue is discovered with a commit that was not uncovered by tests then the change may be reverted by the maintainers. Maintainers will attempt to either address or contact the committer beforehand if possible.

Incoming Webhook Formats

Log Insight Webhook Formats

The output of a LI webhook depends on the type of webhook (i.e. user or system) and type of query (user only). Let's see an example for each:

System Notification

{
    "AlertName":" Admin Alert: Worker node has returned to service  (Host = 127.0.0.2)",
    "messages":[
       {
          "text":"This notification was generated from Log Insight node (Host = 127.0.0.2, Node Identifier = a31cad22-65c2-4131-8e6c-27790892a1f9).\n\nA worker node has returned to service after having been in maintenance mode.\n\nThe Log Insight master node (Host: <a href='https://10.113.236.182:9443/'>https://10.113.236.182:9443/</a>, Node Identifier: 88fc9956-bf9a-428b-806a-22ff07636273) reports that worker node has finished maintenance and exited maintenance mode. The node will resume receiving configuration changes and serving queries. The node is also now ready to start receiving incoming log messages. If an external load balancer is configured to distribute messages among workers, the administrator should add this node back to the pool of nodes receiving incoming messages.\n\nThis message was generated by your Log Insight installation, visit the <a href='https://www.vmware.com/support/pubs/log-insight-pubs.html'>Documentation Center</a> for more information.",
          "timestamp":1458665320514,"fields":[]
       }
    ]
}

User Alert: Message Query

{
    "AlertType":1,
    "AlertName":"Hello World Alert",
    "SearchPeriod":300000,
    "HitCount":0.0,
    "HitOperator":2,
    "messages":[
       {
          "text":"hello world 1",
          "timestamp":1451940578545,
          "fields":[
             {
                "name":"Field_1",
                "content":"Content 1"
             },
             {
                "name":"Field_2",
                "content":"Content 2"
             }
          ]
       },
       {
          "text":"hello world 2",
          "timestamp":1451940561008,
          "fields":[
             {
                "name":"Field_1",
                "content":"Content 1_2"
             },
             {
                "name":"Field_2",
                "content":"Content 2_2"
             }
          ]
       }
    ],
    "HasMoreResults":false,
    "Url":"https://10.11.12.13/s/8pgzq6",
    "EditUrl":"https://10.11.12.13/s/56monr",
    "Info":"This is an alert for all the Hello World messages",
    "NumHits":2
}

User Alert: Aggregation Query

{
    "AlertType":2,
    "AlertName":"field_1 aggregated alert",
    "SearchPeriod":300000,
    "HitCount":2.0,
    "HitOperator":2,
    "messages":[
       {
          "fields":[
             {
                "name":"Field_1",
                "content":"Content 1"
             }
          ]
       }
    ],
    "HasMoreResults":false,
    "Url":"https://10.11.12.13/s/r25g3s",
    "EditUrl":"https://10.11.12.13/s/n3gsed",
    "Info":null,
    "NumHits":1
}

User Alert: Test Query

{
    "AlertType":1,
    "AlertName":"Hello World Alert",
    "SearchPeriod":300000,
    "HitCount":0.0,
    "HitOperator":2,
    "messages":[],
    "HasMoreResults":false,
    "Url":null,
    "EditUrl":null,
    "Info": "This is an alert for all the Hello World messages",
    "Recommendation":null,
    "NumHits":2
}

vRealize Operations Manager Webhook Formats

vRealize Operations Manager >= 6.2

{
    "startDate":1369757346267,
    "criticality":"ALERT_CRITICALITY_LEVEL_WARNING",
    "resourceId":"sample-object-uuid",
    "alertId":"sample-alert-uuid",
    "status":"ACTIVE",
    "subType":"ALERT_SUBTYPE_AVAILABILITY_PROBLEM",
    "cancelDate":1369757346267,
    "resourceKind":"sample-object-type",
    "attributeKeyID":5325,
    "adapterKind":"sample-adapter-type",
    "type":"ALERT_TYPE_APPLICATION_PROBLEM",
    "resourceName":"sample-object-name",
    "updateDate":1369757346267,
    "info":"sample-info"
}

vRealize Operations Manager < 6.2

{
   "startDate":1369757346267,
   "criticality":"ALERT_CRITICALITY_LEVEL_WARNING",
   "Risk":4.0,
   "resourceId":"sample-object-uuid",
   "alertId":"sample-alert-uuid",
   "status":"ACTIVE",
   "subType":"ALERT_SUBTYPE_AVAILABILITY_PROBLEM",
   "cancelDate":1369757346267,
   "resourceKind":"sample-object-type",
   "alertName":"Invalid IP Address for connected Leaf Switch",
   "attributeKeyID":5325,
   "Efficiency":1.0,
   "adapterKind":"sample-adapter-type",
   "Health":1.0,
   "type":"ALERT_TYPE_APPLICATION_PROBLEM",
   "resourceName":"sample-object-name",
   "updateDate":1369757346267,
   "info":"sample-info"
}

Simulating Tests

You can simulate payloads using tools such as curl. For example:

$ curlj=$(curl -H "content-type: application/json")
$ curlj -X POST -d '<payload_above>' http://user:pass@localhost:5001/endpoint/test