Added example script for retrieving all audit events across an OCI Tenancy (#44)

* Retrieve all audit events across an OCI Tenancy

This script retrieves all audit logs across an OCI Tenancy for a defined timespan.

This script relies on OCI config as per the format defined at
https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/sdkconfig.htm

This script will work at a tenancy level only.

The config file should have the following contents
User OCID
RSA private key in PEM format
Fingerprint
Tenancy OCID

* Changes based on review and file name.

Accommodated the changes suggested by @nathan-vu

The following is a summary of all the changes:
-file name from RetrieveAuditEvents.py to retrieve_audit_events.py
-instead of hard coding to start_time and end_time, they receive values on execution
-oci pagination is being used instead of custom definition
-removed the len(range(list)) for 
-get_regions() and get_compartments() now accept identity as their parameter
-region is updated with set_region()
-changes to variables name; they use snake_casing
-edited comments

* Changes based on 2nd review on 20180215

The following were the changes made in the latest version:
-start_time and end_time do not do any str operations and rely on datetime.datetime
-logs are retrieved only for the timespan of last 5 days instead of a month; this would be a better experience considering the time retrieve results
-changes to get_compartments; it will accept tenancy_id as its parameter and it will also be the added to the list even before ListCompartments api call is made
-unnecessary initializations were removed
-change of comment style for the description of functions
-parameter 'r' was removed from get_regions() which was originally put to demonstrate the region being used

Changes not made:
-No changes were made to the retrieval method i.e. it is still eagerly loading all the results

* list_of_audit_events relies on extend

* Updates to comments

Updated the following sections' comments:
-get_audit_events

* Change of order for import modules

Author: saurabhbangad

examples/retrieve_audit_events.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python
+#  coding: utf-8
+#  Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved.
+
+#  This script retrieves all audit logs across an OCI Tenancy.
+#  for a timespan defined by start_time and end_time.
+#  This sample script retrieves Audit events for last 5 days.
+#  This script will work at a tenancy level only.
+
+import datetime
+import oci
+
+
+def get_regions(identity):
+    '''
+    To retrieve the list of all available regions.
+    '''
+    list_of_regions = []
+    list_regions_response = identity.list_regions()
+    for r in list_regions_response.data:
+        list_of_regions.append(r.name)
+    return list_of_regions
+
+
+def get_compartments(identity, tenancy_id):
+    '''
+    Retrieve the list of compartments under the tenancy.
+    '''
+    compartment_ocids = []
+    #  Store tenancy id as the first compartment
+    compartment_ocids.append(tenancy_id)
+    list_compartments_response = oci.pagination.list_call_get_all_results(
+        identity.list_compartments,
+        compartment_id=tenancy_id).data
+    for c in list_compartments_response:
+        compartment_ocids.append(c.id)
+    return compartment_ocids
+
+
+def get_audit_events(audit, compartment_ocids, start_time, end_time):
+    '''
+    Get events iteratively for each compartment defined in 'compartments_ocids'
+    for the region defined in 'audit'.
+    This method eagerly loads all audit records in the time range and it does
+    have performance implications of lot of audit records.
+    Ideally, the generator method in oci.pagination should be used to lazily
+    load results.
+    '''
+    list_of_audit_events = []
+    for c in compartment_ocids:
+        list_events_response = oci.pagination.list_call_get_all_results(
+            audit.list_events,
+            compartment_id=c,
+            start_time=start_time,
+            end_time=end_time).data
+
+        #  Results for a compartment 'c' for a region defined
+        #  in 'audit' object.
+        list_of_audit_events.extend(list_events_response)
+        return list_of_audit_events
+
+
+#  Setting configuration
+#  Default path for configuration file is "~/.oci/config"
+config = oci.config.from_file()
+tenancy_id = config["tenancy"]
+
+#  Initiate the client with the locally available config.
+identity = oci.identity.IdentityClient(config)
+
+#  Timespan defined by variables start_time and end_time(today).
+#  ListEvents expects timestamps into RFC3339 format.
+#  For the purposes of sample script, logs of last 5 days.
+end_time = datetime.datetime.utcnow()
+start_time = end_time + datetime.timedelta(days=-5)
+
+# This array will be used to store the list of available regions.
+regions = get_regions(identity)
+
+# This array will be used to store the list of compartments in the tenancy.
+compartments = get_compartments(identity, tenancy_id)
+
+audit = oci.audit.audit_client.AuditClient(config)
+
+#  For each region get the logs for each compartment.
+for r in regions:
+    #  Intialize with a region value.
+    audit.base_client.set_region(r)
+    #  To separate results by region use print here.
+    audit_events = get_audit_events(
+        audit,
+        compartments,
+        start_time,
+        end_time)
+
+    #  Results for a region 'r' for each compartment.
+    if audit_events:
+        print audit_events