| copyright | lastupdated | keywords | subcollection | ||
|---|---|---|---|---|---|
|
2024-07-08 |
events, activity, logging, api, buckets, tracking, legacy, python, java, node, go, logs |
cloud-object-storage |
{{site.data.keyword.attribute-definition-list}}
{: #at}
{{site.data.keyword.cloud_notm}} 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 {{site.data.keyword.cos_full}} 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 {{site.data.keyword.at_full}}. Ensure that you have an instance of Activity Tracker at the receiving location corresponding to your bucket location as specified in {{site.data.keyword.cos_short}} 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. {: note}
This feature supports SCC monitoring. {: note}
{: #at-at}
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. {: deprecated}
Tracking {{site.data.keyword.cos_short}} events with {{site.data.keyword.at_full}} provides a record of what is happening with your data. The {{site.data.keyword.at_full_notm}} 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 {{site.data.keyword.at_full_notm}} to learn more.
{: #at-logs}
IBM Cloud Logs will replace {{site.data.keyword.at_full_notm}} 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 {{site.data.keyword.at_full_notm}} to IBM Cloud Logs once available to avoid any disruption in event tracking.
{: #at-route-logs}
Get started with {{site.data.keyword.at_full_notm}} 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
- Another COS Bucket
- Activity Tracker Instance (Deprecated)
- Event Streams
- IBM Cloud Logs (Coming Soon)
{: #at-configure}
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.
{: #at-examples-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.
{: #at-ui-example-recommended} {: ui}
- 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.
{: #at-api-example-recommended} {: api}
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());
}
}{: codeblock}
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(){: codeblock}
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){: codeblock}
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){: codeblock}
{: #at-terraform-example-recommended} {: terraform}
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
}
}{: codeblock}
{: #at-configure-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. {: note}
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.
{: #at-legacy-upgrade}
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
{: #at-legacy-upgrade-examples}
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
{: #at-ui-example-legacy} {: ui}
- 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.
{: #at-api-example-legacy} {: api}
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());
}
}{: codeblock}
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(){: codeblock}
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){: codeblock}
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){: codeblock}
{: #at-terraform-example-legacy} {: terraform}
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::”
}
}{: codeblock}