Tracking events on your IBM Cloud Object Storage buckets

IBM Cloud offers centralized logging services to track events performed on your resources. You can use these services to investigate abnormal activity and critical actions and comply with regulatory audit requirements.

Use these services to track events on your IBM Cloud® Object Storage buckets to provide a record of what is happening with your data. Enable these services on your bucket to receive detailed logs about data access and bucket configuration events.

When event tracking is enabled on your bucket, the default target service that captures these events is IBM Cloud® Activity Tracker. Ensure that you have an instance of Activity Tracker at the receiving location corresponding to your bucket location as specified in Object Storage Service Integration.

Alternatively, use IBM Cloud Activity Tracker Event Routing to send events to other target services or to send events to Activity Tracker instances in locations other than the bucket location.

This feature is not currently supported in Object Storage for Satellite.

This feature supports SCC monitoring.

Using IBM Cloud Activity Tracker to track bucket events

As of 28 March 2024 the IBM Log Analysis and IBM Cloud Activity Tracker services are deprecated and will no longer be supported as of 30 March 2025. Customers will need to migrate to IBM Cloud Logs, which replaces these two services, prior to 30 March 2025.

Tracking Object Storage events with IBM Cloud® Activity Tracker provides a record of what is happening with your data. The IBM Cloud Activity Tracker service provides the framework and functionality to monitor API calls to services on the IBM Cloud and produces the evidence to comply with corporate policies and market industry-specific regulations.

See Getting started with IBM Cloud Activity Tracker to learn more.

Using IBM Cloud Logs to track bucket events (Coming Soon)

IBM Cloud Logs will replace IBM Cloud Activity Tracker hosted event search. See the IBM Announcement to learn more.

IBM Cloud Logs gives you flexibility in how your data is processed for insights and trends, and where data is stored for high-speed search and long-term trend analysis. It provides the tools for you to maximize the value obtained while maintaining control on the total cost.

Migrate from IBM Cloud Activity Tracker to IBM Cloud Logs once available to avoid any disruption in event tracking.

Route Logs with IBM Cloud Activity Tracker Event Routing

Get started with IBM Cloud Activity Tracker Event Routing to configure routing for your IBM Cloud Object Storage auditing events. You can use Activity Tracker Event Routing, a platform service, to manage auditing events at the account-level by configuring targets and routes that define where auditing data is routed.

Activity Tracker Event Routing supports routing IBM COS bucket logs to the following targets

Configure Activity Tracking Events on your IBM Cloud Object Storage Bucket (Recommended)

Event tracking can be enabled on your IBM Cloud Object Storage bucket at the time of bucket provisioning, or by updating the bucket configuration after bucket creation. Event tracking will only apply to COS requests made after enablement.

By default, COS events that report on global actions, such as bucket creation, are collected automatically. You can monitor global actions through the Activity Tracker instance located in the Frankfurt location.

IBM COS also optionally supports tracking on these event types:

Management Events – Requests related to managing bucket and object configuration
Read Data Events – Requests related to object list and read requests
Write Data Events – These are all events related to writing and deleting objects

Refer to the COS API events to see the full list of Management, Read Data, and Write Data actions that produce events.

Use the COS Resource Configuration API to configure tracking of these events on your bucket

When event tracking is enabled, all events are sent to the default receiving location for IBM Cloud Activity Tracker Event Router that are based on the location of the bucket. Refer to IBM COS Service Integration to see this default mapping. Use Activity Tracker Event Router rules to route events to an alternative location or target service. See Managing Rules to learn more.

How to configure IBM Cloud Activity Tracker on your bucket (Recommended)

Select the UI, API or Terraform tab at the top of this topic to display the examples that show how to enable tracking of management, data read, and data write events in your bucket.

UI example for how to enable tracking of events in your bucket

From the IBM Cloud console resource list, select the service instance that contains the bucket you are interested in adding event tracking. This takes you to the Object Storage Console
Choose the bucket for which you want to enable event tracking.
Navigate to the configuration tab.
Scroll down to the advanced configuration section and toggle on the events you want to track for this bucket.
After a few minutes, any activity will be visible in the Activity Tracker web UI.

Examples

JAVA SDK

import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class ActivityTrackerExample {
   private static final String BUCKET_NAME = <BUCKET_NAME>;
   private static final String API_KEY = <API_KEY>;

   public static void main(String[] args) {
       IamAuthenticator authenticator = new IamAuthenticator.Builder()
               .apiKey(API_KEY)
               .build();
       ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);
       ActivityTracking activityTrackingConfig = new ActivityTracking().Builder()
               .readDataEvents(true)
               .writeDataEvents(true)
               .managementEvents(true)
               .build();
       BucketPatch bucketPatch = new BucketPatch.Builder().activityTracking(activityTrackingConfig).build();
       UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
               .Builder(BUCKET_NAME)
               .bucketPatch(bucketPatch.asPatch())
               .build();

       RC_CLIENT.updateBucketConfig(update).execute();
       GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
       Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();

       ActivityTracking activityTrackingResponse = bucket.getActivityTracking();
       System.out.println("Read Data Events : " + activityTrackingResponse.readDataEvents());
       System.out.println("Write Data Events : " + activityTrackingResponse.writeDataEvents());
       System.out.println("Management Events : " + activityTrackingResponse.managementEvents());
   }
}

NodeJS SDK

 const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
 IamAuthenticator      = require('ibm-cos-sdk-config/auth');

 var apiKey = "<API_KEY>"
 var bucketName = "<BUCKET_NAME>"

 authenticator = new IamAuthenticator({apikey: apiKey})
 rcConfig = {authenticator: authenticator}
 const client = new ResourceConfigurationV1(rcConfig);

 function addAT() {
     console.log('Updating bucket metadata...');

     var params = {
         bucket: bucketName,
         activityTracking: {
           "read_data_events": true,
           "write_data_events": true,
           "management_events": true
           }
     };

     client.updateBucketConfig(params, function (err, response) {
         if (err) {
             console.log("ERROR: " + err);
         } else {
             console.log(response.result);
         }
     });
 }

 addAT()

Python SDK

 from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
 from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

 api_key = "<API_KEY>"
 bucket_name = "<BUCKET_NAME>"

 authenticator = IAMAuthenticator(apikey=api_key)
 client = ResourceConfigurationV1(authenticator=authenticator)
 activity_tracking_config = {
                             'activity_tracking':
                               {
                                 'read_data_events':True,
                                 'write_data_events':True,
                                 'management_events':True
                               }
                             }
 client.update_bucket_config(bucket_name, bucket_patch=activity_tracking_config)

GO SDK example

 import (
 "github.com/IBM/go-sdk-core/core"
 rc "github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1"
 )

 apiKey := "<ApiKey>"
 bucketName := "<BucketName>"

 authenticator := new(core.IamAuthenticator)
 authenticator.ApiKey = apiKey
 optionsRC := new(rc.ResourceConfigurationV1Options)
 optionsRC.Authenticator = authenticator
 rcClient, _ := rc.NewResourceConfigurationV1(optionsRC)

 patchNameMap := make(map[string]interface{})
 patchNameMap["activity_tracking"] = &rc.ActivityTracking{
   ReadDataEvents:     core.BoolPtr(true),
   WriteDataEvents:    core.BoolPtr(true),
   ManagementEvents:    core.BoolPtr(true)
 }
 updateBucketConfigOptions := &rc.UpdateBucketConfigOptions{
   Bucket:      core.StringPtr(bucketName),
   BucketPatch: patchNameMap,
 }
 rcClient.UpdateBucketConfig(updateBucketConfigOptions)

Example

 resource "ibm_resource_instance" "cos_instance" {
   name              = "cos-instance"
   resource_group_id = data.ibm_resource_group.cos_group.id
   service           = "cloud-object-storage"
   plan              = "standard"
   location          = "global"
 }

 resource "ibm_cos_bucket" "activity_tracker_bucket" {
   bucket_name          = “Name-of-the-bucket”
   resource_instance_id = ibm_resource_instance.cos_instance.id
   region_location      = “us-south”
   storage_class        = “standard”
   activity_tracking {
   read_data_events     = true
     write_data_events    = true
     management_events    = true
       }
 }

Configure Activity Tracking Events on your IBM Cloud Object Storage Bucket (Legacy)

Enable IBM Activity Tracking on your COS bucket by specifying the target CRN of the Activity Tracker instance in the COS Resource Configuration API. Specify the CRN to define the route for COS events.

Management events are always enabled when a CRN is set on the Activity Tracking configuration

The legacy model also supports optionally enabling tracking on the following event types:

Read Data Events – Requests related to object list and read requests
Write Data Events – These are all events related to writing and deleting objects

IBM Cloud observability routing services are the standardized way for customers to manage routing of platform observability data. Service-specific routing configurations like COS are being deprecated.

It is recommended that customers remove these legacy routing configurations that use CRNs and instead use the IBM Activity Tracker Event Routing service to route events to other locations.

IBM COS will continue to support legacy configurations where a CRN was specified that differs from the default location.

Upgrading from Legacy to the Recommended Event Tracking on your COS bucket

To upgrade from the legacy configuration using the Resource Configuration API, remove the target Activity Tracker instance CRN. Events will now route to the default Activity Tracker Event Router receiving location as described in COS Service Integration. Provision an instance of Activity Tracker hosted event search at this location or define a routing rule prior to upgrading to ensure there’s no interruption in event logging.

Example patch to transition from the Legacy to Recommended event tracking configuration on your COS bucket

Select the UI, API, or Terraform tab at the top of this topic to see examples of patchs.

UI example patch to transition from the Legacy to Recommended event tracking configuration on your COS bucket

From the IBM Cloud console resource list, select the service instance that contains the bucket you wish to upgrade to the recommended event tracking configuration. This takes you to the Object Storage Console.
Choose the bucket for which you want to upgrade.
Navigate to the configuration tab.
Scroll down to the advanced configuration section and locate the configuration panel for Activity Tracker.
Click on the top right corner of the panel and select upgrade.
Confirm you would like to upgrade event tracking for this bucket.

Examples

JAVA SDK

import com.ibm.cloud.objectstorage.config.resource_configuration.v1.ResourceConfiguration;
import com.ibm.cloud.objectstorage.config.resource_configuration.v1.model.BucketPatch;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

public class ActivityTrackerExample {
   private static final String BUCKET_NAME = <BUCKET_NAME>;
   private static final String API_KEY = <API_KEY>;

   public static void main(String[] args) {
       IamAuthenticator authenticator = new IamAuthenticator.Builder()
               .apiKey(API_KEY)
               .build();
       ResourceConfiguration RC_CLIENT = new ResourceConfiguration("resource-configuration", authenticator);
       ActivityTracking activityTrackingConfig = new ActivityTracking().Builder()
             .activityTrackerCrn(AT_CRN)
             .readDataEvents(true)
             .writeDataEvents(true)
             .build();
       BucketPatch bucketPatch = new BucketPatch.Builder().activityTracking(activityTrackingConfig).build();
       UpdateBucketConfigOptions update = new UpdateBucketConfigOptions
               .Builder(BUCKET_NAME)
               .bucketPatch(bucketPatch.asPatch())
               .build();

       RC_CLIENT.updateBucketConfig(update).execute();
       GetBucketConfigOptions bucketOptions = new GetBucketConfigOptions.Builder(BUCKET_NAME).build();
       Bucket bucket = RC_CLIENT.getBucketConfig(bucketOptions).execute().getResult();

       ActivityTracking activityTrackingResponse = bucket.getActivityTracking();
       System.out.println("Read Data Events : " + activityTrackingResponse.readDataEvents());
       System.out.println("Write Data Events : " + activityTrackingResponse.writeDataEvents());
       System.out.println("Management Events : " + activityTrackingResponse.managementEvents());
   }
}

NodeJS SDK

 const ResourceConfigurationV1 = require('ibm-cos-sdk-config/resource-configuration/v1');
 IamAuthenticator      = require('ibm-cos-sdk-config/auth');

 var apiKey = "<API_KEY>"
 var bucketName = "<BUCKET_NAME>"

 authenticator = new IamAuthenticator({apikey: apiKey})
 rcConfig = {authenticator: authenticator}
 const client = new ResourceConfigurationV1(rcConfig);

 function addAT() {
     console.log('Updating bucket metadata...');

     };
     var params = {
         bucket: bucketName,
         activityTracking: {
           "activity_tracker_crn": at_crn,
           "read_data_events": true,
           "write_data_events": true
           }
     };

     client.updateBucketConfig(params, function (err, response) {
         if (err) {
             console.log("ERROR: " + err);
         } else {
             console.log(response.result);
         }
     });
 }

 addAT()

Python SDK

 from ibm_cos_sdk_config.resource_configuration_v1 import ResourceConfigurationV1
 from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

 api_key = "<API_KEY>"
 bucket_name = "<BUCKET_NAME>"

 authenticator = IAMAuthenticator(apikey=api_key)
 client = ResourceConfigurationV1(authenticator=authenticator)
 activity_tracking_config = {
                             'activity_tracking':
                               {
                                 'activity_tracker_crn':at_crn,
                                 'read_data_events':True,
                                 'write_data_events':True,
                               }
                             }

 client.update_bucket_config(bucket_name, bucket_patch=activity_tracking_config)

GO SDK

 import (
 "github.com/IBM/go-sdk-core/core"
 rc "github.com/IBM/ibm-cos-sdk-go-config/v2/resourceconfigurationv1"
 )

 apiKey := "<ApiKey>"
 bucketName := "<BucketName>"

 authenticator := new(core.IamAuthenticator)
 authenticator.ApiKey = apiKey
 optionsRC := new(rc.ResourceConfigurationV1Options)
 optionsRC.Authenticator = authenticator
 rcClient, _ := rc.NewResourceConfigurationV1(optionsRC)

 patchNameMap := make(map[string]interface{})
 patchNameMap["activity_tracking"] = &rc.ActivityTracking{
   ActivityTrackerCrn: core.StringPtr(activityTrackerCrn),
   ReadDataEvents:     core.BoolPtr(true),
   WriteDataEvents:    core.BoolPtr(true),
 }
 updateBucketConfigOptions := &rc.UpdateBucketConfigOptions{
   Bucket:      core.StringPtr(bucketName),
   BucketPatch: patchNameMap,
 }
 rcClient.UpdateBucketConfig(updateBucketConfigOptions)

Example

 resource "ibm_resource_instance" "cos_instance" {
   name              = "cos-instance"
   resource_group_id = data.ibm_resource_group.cos_group.id
   service           = "cloud-object-storage"
   plan              = "standard"
   location          = "global"
 }

 resource "ibm_cos_bucket" "activity_tracker_bucket" {
   bucket_name          = “bucket_name”
   resource_instance_id = ibm_resource_instance.cos_instance.id
   region_location      = “us-south”
   storage_class        = “standard”
   activity_tracking {
   read_data_events     = true
     write_data_events    = true
     activity_tracker_crn = “crn:v1:bluemix:public:logdnaat:us-south:a/2xxxxxxxxxxxxxxxxxxxxxxxxf:3xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxec::”
       }
 }