13 Event Notifications

Oracle Traffic Director allows users to subscribe to notifications about events that it detects. To receive such notifications, you can provide an HTTP endpoint URL of your choice. Oracle Traffic Director sends information about the events that it has detected through a HTTP POST message to this URL.

The HTTP POST request contains event information in JSON format. Oracle Traffic Director supports notifications for the following two events:

Origin server status change event

Oracle Traffic Director sends notifications to configured HTTP endpoint URL when it detects a change in the origin server status.

The origin server status change event is said to occur when one of the two events occur:

OTD marks the origin server as offline.
OTD marks the origin server back as online from offline.

A notification message is sent when there is a status change of any origin server that is part of the configuration. You cannot receive notifications for a particular origin server of interest while subscribing to the notifications.

Multiple notifications can be sent when there is a change in the status of an origin server that is part of multiple origin server pools or multiple Oracle Traffic Director instances.

Subscribing to origin server status change event Using WLST

Creating an event subscription

To create an event subscription, run the otd_createEventSubscription command, as shown in the example.
```
props = {}
props['configuration'] = 'foo'
props['event-subscription'] = 'bar'
props['url'] = 'http://example.com:7777/subscriber'
otd_createEventSubscription(props)
```
The first command subscribes to the URL: http://example.com:7777/subscriber
Viewing a list of event subscriptions

To view a list of subscribed event subscriptions, run the otd_listEventSubscriptions command.

For example, to display the event subscriptions scheduled for instances of the configuration:
```
props = {}
props['configuration'] = 'foo'
otd_listEventSubscriptions(props)
```
Deleting an event subscription

To delete an event subscription, run the otd_deleteEventSubscription command, as shown in the example.
```
props = {}
props['configuration'] = 'foo'
props['event-subscription'] = 'bar'
otd_deleteEventSubscription(props)
```
Setting an event subscription properties

When you create an event subscription, it is enabled automatically.

The command otd_setEventSubscriptionProperties with 'enabled' as 'false' can be used to disable event subscriptions.

To disable an event, set the enabled property to false.
```
props = {}
props['configuration'] = 'foo'
props['event-subscription'] = 'bar'
props['enabled'] = 'true'
otd_setEventSubscriptionProperties(props)
```
Getting an event subscription properties

The command otd_getEventSubscriptionProperties with 'enabled' as 'true' must be used to get the event subscription properties.

To enable an event, set the enabled property to true:
```
props = {}
props['configuration'] = 'foo'
props['event-subscription'] = 'bar'
otd_getEventSubscriptionProperties(props)
```

For more information about the WLST commands mentioned in this section, see WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

To know the details of the command and its each parameter/option, use help, as shown below:

 help('otd_createEventSubscription')

Subscribing to origin server status event using Fusion Middleware Control

Log in to Fusion Middleware Control for Traffic Director, as described in Displaying Fusion Middleware Control.
Click the WebLogic Domain button at the upper left (or) right corner of the page.
Select Administration > OTD Configurations.

A list of available OTD Configurations is displayed.

Select a configuration for which Event Subscriptions will be enabled.
Select Configuration > Advanced Configuration > Event Subscriptions.

The Events Subscriptions page is displayed.
In the Common Tasks pane, click Create under Event Subscription.

The New Event Subscription wizard starts.

Description of the illustration GUID-6C4E7C20-7DCC-4A1F-B4AA-0331F40628F7-default.gif
Follow the on-screen prompts to complete the creation of the Event Subscription by using the details- Name of the subscription, URL, and so on - that you decided earlier.
Click OK on the Results screen.

After the Event Subscription is created, the Results screen of the New Event Subscription wizard displays a message confirming the successful creation of the Event Subscription.

Notification format

When a notification to a subscribed URL is sent, the Content-type header value is set to application/json. When an event occurs, the OTD sends HTTP POST to the endpoint with a message body that contains a JSON document with the name/value pairs as described in this section.

Table 13-1 JSON properties common to all events

JSON property	Description
event-type	Type of the event. Value: `origin-server-status-change`.
domain-name	Name of the domain where Oracle Traffic Director instance is configured.
instance-name	Name of the Oracle Traffic Director instance.
timestamp	The time when the event occurred and detected by OTD.

Table 13-2 JSON property specific to origin-server-status-change event

JSON property	Description
pool-name	Origin server pool name to which the origin server is associated with.
host	Origin server host for which the status being sent.
port	Origin server port.
status	Online or offline.
reason	Reason for Oracle Traffic Director marking the origin server as offline or online.
protocol	Health check protocol used.

JSON Schema

{   
   "$schema":"http://json-schema.org/draft-04/schema#",
   "id":"",
   "type":"object",
   "properties":{   
      "v1.0":{   
         "id":"/v1.0",
         "type":"object",
         "properties":{   
            "event-type":{   
               "id":"/v1.0/event-type",
               "type":"string"
            },
            "domain-name":{   
               "id":"/v1.0/domain-name",
               "type":"string"
            },
            "instance-name":{   
               "id":"/v1.0/instance-name",
               "type":"string"
            },
            "origin-server":{   
               "id":"/v1.0/origin-server",
               "type":"object",
               "properties":{   
                  "pool-name":{   
                     "id":"/v1.0/origin-server/pool-name",
                     "type":"string"
                  },
                  "host":{   
                     "id":"/v1.0/origin-server/host",
                     "type":"string"
                  },
                  "port":{   
                     "id":"/v1.0/origin-server/port",
                     "type":"integer"
                  },
                  "health-check":{   
                     "id":"/v1.0/origin-server/health-check",
                     "type":"object",
                     "properties":{   
                        "protocol":{   
                           "id":"/v1.0/origin-server/health-check/protocol",
                           "type":"string"
                        },
                        "status":{   
                           "id":"/v1.0/origin-server/health-check/status",
                           "type":"string"
                        },
                        "reason":{   
                           "id":"/v1.0/origin-server/health-check/reason",
                           "type":"string"
                        }
                     },
                     "required":[   
                        "status"
                     ]
                  }
               },
               "required":[   
                  "host",
                  "port",
                  "health-check"
               ]
            },
            "timestamp":{   
               "id":"/v1.0/timestamp",
               "type":"string"
            }
         },
         "required":[   
            "event-type",
            "domain-name",
            "instance-name",
            "origin-server",
            "timestamp"
         ]
      }
   },
   "required":[   
      "v1.0"
   ]
}

Example

Content-Type: application/json
 
Content:
 
{   
   "v1.0":{   
      "event-type":"origin-server-status-change",
      "domain-name":"base_domain",
      "instance-name":"otd1",
      "origin-server":{   
         "pool-name":"testpool",
         "host":"slc06cdz",
         "port":7777,
         "health-check":{   
            "protocol":"HTTP",
            "status":"offline",
            "reason":"Server not reachable"
         }
      },
      "timestamp":"Mon, 18 Apr 2016 04:34:23 -07:00"
   }
}

Error handling

When a subscriber responds with an error code, Oracle Traffic Director:

Logs the following warning message to the server log:
- Event Dispatcher: response code <http_response_code> received from subscriber <subscription_url>
- Event Dispatcher: unable to post event <json_notification_data> to subscriber <subscription_url>
- Discards the event.

When a subscriber is not reachable, Oracle Traffic Director:

Tries re posting the event three times
Logs the following warning message to the server log:
- Event Dispatcher: unable to receive response from subscriber <subscription_url>
- Event Dispatcher: unable to post event <json_notification_data> to subscriber <subscription_url>
Discards the event.