Object Storage Service:Enable logging (Python SDK V1)

Prerequisites

Before you begin, ensure that you have:

• Python SDK 2.6.x or later installed

• The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set

How it works

Enabling SDK logging takes two steps:

1. Call oss2.set_file_logger() to specify the log file path and log level.

2. Run OSS operations as usual — the SDK writes logs automatically.

Logs follow this format: <time><name><level><threadId><message>

The supported log levels, from highest to lowest severity, are:

CRITICAL > ERROR > WARNING > INFO > DEBUG > NOTSET

Setting a log level records logs at that level and all higher levels. For example, setting INFO captures CRITICAL, ERROR, WARNING, and INFO logs.

Tip: Use INFO for normal operations. Switch to DEBUG when troubleshooting for more detailed logs.

Enable logging

The following example enables logging at the INFO level, then lists objects and retrieves object metadata to generate log entries.

# -*- coding: utf-8 -*-

import os
import logging
import oss2
from itertools import islice
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Specify the log file path.
# If you provide only a file name (e.g., examplelogfile.log), the file is
# saved to the project root directory by default.
log_file_path = "D:\\localpath\\examplelogfile.log"

# Enable logging at the INFO level.
oss2.set_file_logger(log_file_path, 'oss2', logging.INFO)

# Load credentials from environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Set the endpoint for your bucket's region.
# Example: China (Hangzhou) -> https://oss-cn-hangzhou.aliyuncs.com
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Specify the region that matches the endpoint. Required for V4 signatures.
region = "cn-hangzhou"

# Replace examplebucket with your bucket name.
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

# List the first 10 objects in the bucket.
for b in islice(oss2.ObjectIterator(bucket), 10):
    print(b.key)

# Get object metadata.
# Specify the full object path, excluding the bucket name.
object_meta = bucket.get_object_meta('exampledir/exampleobject.txt')

The example uses the public endpoint for the China (Hangzhou) region. To access OSS from another Alibaba Cloud service in the same region, use the internal endpoint instead. For a full list of endpoints, see Regions and endpoints. To create an OSSClient instance using a custom domain or Security Token Service (STS), see Initialization.

Read log output

Each log entry shows the timestamp, logger name, level, thread ID, and message. The following example output was captured when exampledir/exampleobject.txt did not exist in the bucket:

2018-11-20 16:37:46,437 oss2.api [INFO] 26716 : Exception: {
    'status': 404,
    'x-oss-request-id': '5BF3C7DA236B3A201CE64679',
    'details': {
        'HostId': 'examplebucket.oss-cn-shenzhen.aliyuncs.com',
        'Message': 'The specified key does not exist.',
        'Code': 'NoSuchKey',
        'RequestId': '5BF3C7DA236B3A201CE64679',
        'Key': 'exampledir/exampleobject.txt'
    }
}

The NoSuchKey error (status 404) indicates the requested object does not exist. For more detailed logs, change the log level to DEBUG.

What's next

• Regions and endpoints — Find the endpoint for your region

• Initialization — Create an OSSClient instance with a custom domain or STS