Accessing OSS generates numerous access logs. You can enable logging to store these logs in a specified CloudBox bucket. Log files are generated hourly and follow a fixed naming convention. You can then analyze the stored logs by using tools such as Simple Log Service or by building a Spark cluster.
Prerequisites
OSS on CloudBox is available only in the China (Hangzhou), China (Shanghai), China (Shenzhen), China (Heyuan), China (Beijing), and China (Chengdu) regions.
You have contacted technical support to request a SingleTunnel network type for your CloudBox's VPC.
Usage notes
If the source bucket has a region attribute, the target bucket must belong to the same account and region. It can be the same as or different from the source bucket.
When the source and target buckets are the same, the log push operation generates additional logs, which creates a loop. Use different source and target buckets to avoid this.
For a source bucket without a region attribute, the target bucket must be the same as the source bucket.
Log files can take up to 48 hours to generate. Requests may appear in adjacent time period files, so logs for a specific period are not guaranteed to be complete or timely.
OSS generates a log file every hour until you disable logging. Delete unneeded log files to reduce storage costs.
To prevent service disruption or data contamination when configuring log shipping for a bucket with OSS-HDFS enabled, do not set the Log Prefix to.dlsdata/.
OSS may add new fields to logs. Design your log processing tools to handle additions. For example, the Bucket ARN field will be added to logs starting September 17, 2025.
Avoid delivering logs to a bucket with ObjectWorm enabled. ObjectWorm prevents log deletion during the retention period, causing storage costs to increase steadily.
The timestamp in year, month, day, hour, minute, and second format. Logs use hourly granularity: HH=01 covers 01:00:00 to 01:59:59. MM and SS are always 00.
UniqueString
A system-generated unique identifier for the log file.
In the left-side navigation pane, choose Data Service > OSS on CloudBox Buckets. Then, in the bucket list, click the name of the target bucket.
In the left-side navigation pane, choose Logging > Logging.
Enable logging, and then configure the following parameters.
Log Storage Bucket: From the drop-down list, select the bucket to store the log records. You can select only a bucket that is in the same region and belongs to the same Alibaba Cloud account.
Log Prefix: The destination directory for the log files. If you specify a prefix, the log files are saved to the specified directory in the target bucket. If you do not specify a prefix, the log files are saved to the root directory of the target bucket. For example, if you set the log prefix to log/, the log files are stored in the log/ directory.
Click Save.
Use an Alibaba Cloud SDK
You can enable logging by using the OSS SDK for Java, Python, or Go (Java SDK 3.15.0 or later, Python SDK V2 1.1.1 or later, or Go SDK V2 v1.2.1 or later). For OSS on CloudBox, the Python and Go SDKs are called in the same way as they are in public cloud OSS. For information about how to create a client, see SDK support.
import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.SetBucketLoggingRequest;
import com.aliyun.oss.common.auth.DefaultCredentialProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
public class Demo {
public static void main(String[] args) throws Exception {
// Specify the data endpoint of the CloudBox bucket.
String endpoint = "https://cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com";
// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
// Specify the name of the CloudBox bucket for which you want to enable logging, for example, examplebucket.
String bucketName = "examplebucket";
// Specify the name of the target CloudBox bucket to store log files. The targetBucketName and bucketName can be the same or different.
String targetBucketName = "destbucket";
// Set the directory to store log files to log/. If you specify this parameter, log files are saved to the specified directory in the target bucket. If you do not specify this parameter, log files are saved to the root directory of the target bucket.
String targetPrefix = "log/";
// Specify the region where the CloudBox bucket is located.
String region = "cn-hangzhou";
// Specify the CloudBox ID.
String cloudBoxId = "cb-f8z7yvzgwfkl9q0h****";
// Create an OSSClient instance.
// When the OSSClient instance is no longer needed, call the shutdown method to release resources.
ClientBuilderConfiguration conf = new ClientBuilderConfiguration();
conf.setSignatureVersion(SignVersion.V4);
OSS ossClient = OSSClientBuilder.create()
.endpoint(endpoint)
.credentialsProvider(new DefaultCredentialProvider(credentialsProvider.getCredentials()))
.clientConfiguration(conf)
.region(region)
.cloudBoxId(cloudBoxId)
.build();
try {
SetBucketLoggingRequest request = new SetBucketLoggingRequest(bucketName);
request.setTargetBucket(targetBucketName);
request.setTargetPrefix(targetPrefix);
ossClient.setBucketLogging(request);
} catch (OSSException oe) {
System.out.println("Caught an OSSException, which means your request made it to OSS, "
+ "but was rejected with an error response for some reason.");
System.out.println("Error Message:" + oe.getErrorMessage());
System.out.println("Error Code:" + oe.getErrorCode());
System.out.println("Request ID:" + oe.getRequestId());
System.out.println("Host ID:" + oe.getHostId());
} catch (ClientException ce) {
System.out.println("Caught an ClientException, which means the client encountered "
+ "a serious internal problem while trying to communicate with OSS, "
+ "such as not being able to access the network.");
System.out.println("Error Message:" + ce.getMessage());
} finally {
if (ossClient != null) {
ossClient.shutdown();
}
}
}
}
import alibabacloud_oss_v2 as oss
# Obtain access credentials from environment variables. Before running this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()
# Use the default configuration of the SDK.
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
# Specify the region in which the CloudBox bucket is located, such as cn-hangzhou.
cfg.region = "cn-hangzhou"
# Specify the CloudBox ID. After you set the CloudBox ID, the SDK automatically switches the signing product to oss-cloudbox.
cfg.cloud_box_id = "cb-f8z7yvzgwfkl9q0h****"
# Specify the data domain of the CloudBox bucket in the CloudboxId.Region.oss-cloudbox.aliyuncs.com format.
cfg.endpoint = "cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com"
# Create an OSS client.
client = oss.Client(cfg)
# Enable logging. Store access logs in the log/ directory of the target CloudBox bucket (destbucket).
result = client.put_bucket_logging(oss.PutBucketLoggingRequest(
bucket="examplebucket",
bucket_logging_status=oss.BucketLoggingStatus(
logging_enabled=oss.LoggingEnabled(
target_bucket="destbucket",
target_prefix="log/",
),
),
))
print(f'status code: {result.status_code}, request id: {result.request_id}')
package main
import (
"context"
"log"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)
func main() {
// Use the default configuration of the SDK and obtain access credentials from environment variables.
// Before running this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
cfg := oss.LoadDefaultConfig().
WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
// Specify the region in which the CloudBox bucket is located, such as cn-hangzhou.
WithRegion("cn-hangzhou").
// Specify the data domain of the CloudBox bucket in the CloudboxId.Region.oss-cloudbox.aliyuncs.com format.
WithEndpoint("cb-f8z7yvzgwfkl9q0h****.cn-hangzhou.oss-cloudbox.aliyuncs.com").
// Specify the CloudBox ID. After you set the CloudBox ID, the SDK automatically switches the signing product to oss-cloudbox.
WithCloudBoxId("cb-f8z7yvzgwfkl9q0h****")
// Create an OSS client.
client := oss.NewClient(cfg)
// Enable logging. Store access logs in the log/ directory of the target CloudBox bucket (destbucket).
request := &oss.PutBucketLoggingRequest{
Bucket: oss.Ptr("examplebucket"),
BucketLoggingStatus: &oss.BucketLoggingStatus{
LoggingEnabled: &oss.LoggingEnabled{
TargetBucket: oss.Ptr("destbucket"),
TargetPrefix: oss.Ptr("log/"),
},
},
}
result, err := client.PutBucketLogging(context.TODO(), request)
if err != nil {
log.Fatalf("failed to put bucket logging %v", err)
}
log.Printf("put bucket logging result:%#v\n", result)
}
Ossutil
For more information about how to use ossutil to configure logging, see put-bucket-logging.
REST API
If your application has high customization requirements, you can initiate REST API requests directly. This requires you to manually write code to calculate the signature. For more information, see PutBucketLogging.