Using REST API

Use the following API operations to manage ObjectCollectionRule:

• Create ObjectCollectionRule

• Update ObjectCollectionRule

• Delete ObjectCollectionRule

• List ObjectCollectionRule

• Get ObjectCollectionRule

Using CLI

For information about using the CLI, see Command Line Interface (CLI).

For a complete list of flags and options available for CLI commands, see Command Line Reference.

Run the following CLI commands to manage ObjectCollectionRule:

• Create ObjectCollectionRule:

  oci log-analytics object-collection-rule create --from-json <json_file_name> --namespace-name <namespace_name>

  For Example:

  oci log-analytics object-collection-rule create --from-json file://create.json --namespace-name MyNamespace

  In the above example command, the referred sample create.json:

  {
      "name": "<Rule_Name>",
      "compartmentId": "<Compartment_OCID>",
      "osNamespace": "<Namespace>",
      "osBucketName": "<Bucket_Name>",
      "logGroupId": "<Log_Group_OCID>",
      "logSourceName": "<Log_Source>"
  }

  The following mandatory properties must be provided in the json:

  • name: A unique name given to the ObjectCollectionRule. The name must be unique within the tenancy, and cannot be modified.
  • compartmentId: The OCID of the compartment in which the ObjectCollectionRule is located.
  • osNamespace: The object storage namespace.
  • osBucketName: The name of the object storage bucket.
  • logGroupId: Logging AnalyticsLogging Analytics log group OCID to associate the processed logs with.
  • logSourceName: Name of the Logging Analytics source to use for the processing.

  In addition to the mandatory properties, you can also optionally specify the following properties:

  • collectionType: The type of collection. Allowed values are LIVE, HISTORIC, and HISTORIC_LIVE.
  • charEncoding: Example values ISO_8859_1, UTF-16
  • definedTags: Defined tags for this resource. Each key is predefined and scoped to a namespace. For example, {"foo-namespace": {"bar-key": "value"}}
  • description: A string that describes the details of the rule, not more than 400 characters long.
  • entityId: OCID of the Logging Analytics entity with which the collected logs will be associated.
  • freeformTags: Simple key-value pair that is applied without any predefined name, type or scope. Exists for cross-compatibility only. For example, {"bar-key": "value"}
  • isEnabled: true by default.
  • objectNameFilters: For examples, see Perform Selective Object Collection by Applying Filters on Object Names.
  • overrides: For examples, see Override ObjectCollectionRule Configuration to Process Specific Objects.
  • pollSince: Example value 2019-10-12T07:20:50.52Z in RFC3339 format.
  • pollTill: Example value 2019-10-12T07:20:50.52Z in RFC3339 format.

  For more details about the properties for ObjectCollectionRule, see ObjectCollectionRule API Reference.

  Sample response of the above example command:

  {
      "id": "ocid1.loganalyticsobjectcollectionrule.oc1..exampleuniqueID",
      "name": "My Rule",
      "compartmentId": "ocid.compartment.oc1..exampleuniqueID",
      "osNamespace": "MyNamespace",
      "osBucketName": "MyBucket1",
      "collectionType": "LIVE",
      "pollSince": "2020-09-08 14:06:28.028",
      "logGroupId": "ocid1.loganalyticsloggroup.oc1.. exampleuniqueID",
      "logSourceName": "MyLogSource",
      "lifecycleState": "ACTIVE",
      "timeCreated": "2020-09-08T14:06:28.028Z",
      "timeUpdated": "2020-09-08T14:06:28.028Z"
  }

• Update ObjectCollectionRule: Following is a sample command to update a log source. Similarly, log group, entity, or any other resource can also be updated.

  oci log-analytics object-collection-rule update --namespace-name <Namespace> --object-collection-rule-id <object-collection-rule-OCID> --log-source-name <Log-Source>

  For Example:

  oci log-analytics object-collection-rule update --namespace-name “My Namespace” --object-collection-rule-id ocid1.loganalyticsobjectcollectionrule.oc1..exampleuniqueID --log-source-name MyLogSource

• Delete ObjectCollectionRule :

  oci log-analytics object-collection-rule delete --namespace-name <Namespace> --object-collection-rule-id <object-collection-rule-OCID>

  For Example:

  oci log-analytics object-collection-rule delete --namespace-name “My Namespace” --object-collection-rule-id ocid1.loganalyticsobjectcollectionrule.oc1..exampleuniqueID

• List ObjectCollectionRule:

  oci log-analytics object-collection-rule list --namespace-name <Namespace> --compartment-id <compartment-OCID>

  For Example:

  oci log-analytics object-collection-rule list --namespace-name “My Namespace” --compartment-id ocid.compartment.oc1..exampleuniqueID

• Get ObjectCollectionRule:

  oci log-analytics object-collection-rule get --namespace-name <Namespace> --object-collection-rule-id <object-collection-rule-OCID>

  For Example:

  oci log-analytics object-collection-rule get --namespace-name “My Namespace” --object-collection-rule-id ocid1.loganalyticsobjectcollectionrule.oc1..exampleuniqueID

• Add Overrides to ObjectCollectionRule:

  If the ObjectCollectionRule already exists, create an override json, for example update_override.json, with the override conditions that you want to add to ObjectCollectionRule:

  {
    "overrides":{"items":[{"matchType":"contains","matchValue":"audit","propertyName":"logSourceName","propertyValue":"myLOGANAuditSource"}]} 
  }

  Now update the ObjectCollectionRule to include the override:

  oci log-analytics object-collection-rule update --namespace-name <Namespace> --object-collection-rule-id <object-collection-rule-OCID> --from-json file://path-to/file

  For Example:

  oci log-analytics object-collection-rule update --namespace-name “My Namespace” --object-collection-rule-id ocid1.loganalyticsobjectcollectionrule.oc1..exampleuniqueID --from-json file:///scratch/update_override.json

  For more details about overrides in ObjectCollectionRule, see Override ObjectCollectionRule Configuration to Process Specific Objects.

• Remove Overrides from ObjectCollectionRule:

  If you want to remove all the override conditions from the ObjectCollectionRule, then create a json, for example remove_overrides.json, that details the override property as follows:

  {
    "overrides":{"items":[]} 
  }

  Now update the ObjectCollectionRule:

  oci log-analytics object-collection-rule update --namespace-name <Namespace> --object-collection-rule-id <object-collection-rule-OCID> --from-json file://path-to/file

  For Example:

  oci log-analytics object-collection-rule update --namespace-name “My Namespace” --object-collection-rule-id ocid1.loganalyticsobjectcollectionrule.oc1..exampleuniqueID --from-json file:///scratch/remove_overrides.json

  For more details about overrides in ObjectCollectionRule, see Override ObjectCollectionRule Configuration to Process Specific Objects.

• Add objectNameFilters to ObjectCollectionRule:

  If the ObjectCollectionRule already exists, create a filters json, for example filters.json, with the filters on object names that you want to add to ObjectCollectionRule:

  {
    "objectNameFilters":["a/*","*audit*"]
  }

  Note
  
  You can update an existing ObjectCollectionRule with ObjectNameFilters only if it is of the type LIVE or HISTORIC_LIVE. Type HISTORIC is not supported for this operation.

  Now update the ObjectCollectionRule to include the filters:

  oci log-analytics object-collection-rule update --namespace-name <Namespace> --object-collection-rule-id <object-collection-rule-OCID> --from-json file://path-to/file

  For Example:

  oci log-analytics object-collection-rule update --namespace-name “My Namespace” --object-collection-rule-id ocid1.loganalyticsobjectcollectionrule.oc1..exampleuniqueID --from-json file:///scratch/filters.json

  For more details about filters in ObjectCollectionRule, see Perform Selective Object Collection by Applying Filters on Object Names.

Policies To Be Added in the Guest Tenant

Here is an example of policy statements which allow the IAM group Host_User_Group from the host tenant Host_Tenant and the Oracle Logging Analytics service to access the objects in the guest compartment Guest_Compartment in the guest tenancy:

define group <Host_User_Group> as <Host_User_Group_OCID>
define tenancy <Host_Tenant> as <Host_Tenant_OCID>
admit group <Host_User_Group> of tenancy <Host_Tenant> to use buckets in compartment <Guest_Compartment>
allow service loganalytics to read buckets in compartment <Guest_Compartment>
allow service loganalytics to read objects in compartment <Guest_Compartment>
allow service loganalytics to manage cloudevents-rules in compartment <Guest_Compartment>
allow service loganalytics to inspect compartments in tenancy
allow service loganalytics to use tag-namespaces in tenancy where all {target.tag-namespace.name = /oracle-tags /}

Policies To Be Added in the Host Tenant

Here is an example of policy statements which allow the host IAM group Host_User_Group to have USE access to the buckets in the guest tenancy Guest_Tenant:

define tenancy <Guest_Tenant> as <Guest_Tenant_OCID>
endorse group <Host_User_Group> to use buckets in tenancy <Guest_Tenant>
allow group <Host_User_Group> to use loganalytics-object-collection-rule in compartment <Rule_Compartment>
allow group <Host_User_Group> to {LOG_ANALYTICS_LOG_GROUP_UPLOAD_LOGS} in compartment <LogGroup_Compartment>
allow group <Host_User_Group> to {LOG_ANALYTICS_SOURCE_READ} in tenancy

Optionally, define this policy if ObjectCollectionRule has associated entities:

allow group <Host_User_Group> to {LOG_ANALYTICS_ENTITY_UPLOAD_LOGS} in compartment <Entity_Compartment>

In the above policies,

• Rule_Compartment: The compartment in which ObjectCollectionRule must be created.

• LogGroup_Compartment: The compartment of Oracle Logging Analytics log group in which the logs must be stored.

• Entity_Compartment: The compartment of Oracle Logging Analytics entity.

After the required policies are created, you can create ObjectCollectionRule to collect the logs from guest tenancy Object Storage. Provide the namespace osNamespace and bucket name osBucketName of the guest tenant in the JSON file, as shown in the following example:

{
 "name": "<My_Rule>",
 "compartmentId": "<Compartment_OCID>",
 "osNamespace": "<Guest_Tenant_Namespace>", // Namespace of the guest tenant
"osBucketName": "<Guest_Tenant__Bucket1>", // Bucket in the guest tenant object store namespace
"logGroupId": "<Log_Group_OCID>",
 "logSourceName": "<My_Log_Source>"
 }

For details about creating ObjectCollectionRule, see ObjectCollectionRule Operations.