Manage log storage with PHP SDK V2 - Object Storage Service

OSS generates access logs for every request made to your buckets. The log storage feature writes these logs as hourly files to a target bucket using a fixed naming convention.

All examples use the China (Hangzhou) region (cn-hangzhou) with the public endpoint. To access OSS from another Alibaba Cloud service in the same region, use the internal endpoint instead. For the full list of regions and endpoints, see Regions and endpoints for OSS.

Prerequisites

Before you begin, make sure you have:

The required permissions for each operation: To grant these permissions to a RAM user, see Attach a custom policy to a RAM user.

Operation	Required permission
Enable log storage	`oss:PutBucketLogging`
View log storage configurations	`oss:GetBucketLogging`
Disable log storage	`oss:DeleteBucketLogging`
Query user-defined log fields	`oss:GetUserDefinedLogFieldsConfig`

The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set with your AccessKey pair.

Operations covered

Operation	API method	Description
Enable log storage	`putBucketLogging`	Configures log storage for a bucket and sets the target bucket and prefix for log files
View log storage configurations	`getBucketLogging`	Returns the current log storage configuration for a bucket
Disable log storage	`deleteBucketLogging`	Removes the log storage configuration from a bucket
Configure user-defined log fields	`putUserDefinedLogFieldsConfig`	Sets custom request headers or query parameters to capture in real-time logs
Query user-defined log fields	`getUserDefinedLogFieldsConfig`	Returns the current user-defined log field configuration for a bucket
Delete user-defined log fields	`deleteUserDefinedLogFieldsConfig`	Removes user-defined log field configurations from a bucket

Enable log storage

Call PutBucketLogging to enable log storage and specify where OSS writes log files.

<?php

// Load SDK dependencies via Composer autoload.
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Define command-line arguments.
$optsdesc = [
    "region"   => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket"   => ['help' => 'The name of the bucket.', 'required' => True],
];

$longopts = \array_map(function ($key) { return "$key:"; }, array_keys($optsdesc));
$options  = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

// Load credentials from environment variables (OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET).
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

// Configure log storage: write logs to the same bucket under the "log/" prefix.
$request = new Oss\Models\PutBucketLoggingRequest(
    bucket: $bucket,
    bucketLoggingStatus: new Oss\Models\BucketLoggingStatus(
        loggingEnabled: new Oss\Models\LoggingEnabled(
            targetBucket: $bucket, // The destination bucket for log files.
            targetPrefix: 'log/'   // Prefix applied to all log file names.
        )
    )
);

$result = $client->putBucketLogging($request);

printf(
    'status code: ' . $result->statusCode . PHP_EOL .
    'request id: '  . $result->requestId
);

Key parameters

Parameter	Description	Example
`targetBucket`	The bucket where OSS writes log files.	`my-log-bucket`
`targetPrefix`	The prefix added to all log file names. Use this to organize logs within the target bucket.	`log/`

View log storage configurations

Call GetBucketLogging to retrieve the log storage configuration for a bucket.

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region"   => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket"   => ['help' => 'The name of the bucket.', 'required' => True],
];

$longopts = \array_map(function ($key) { return "$key:"; }, array_keys($optsdesc));
$options  = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

$request = new Oss\Models\GetBucketLoggingRequest(
    bucket: $bucket
);

$result = $client->getBucketLogging($request);

printf(
    'status code: '    . $result->statusCode . PHP_EOL .
    'request id: '     . $result->requestId  . PHP_EOL .
    'logging status: ' . var_export($result->bucketLoggingStatus, true) . PHP_EOL
);

Returned fields

Field	Description
`statusCode`	HTTP response status code
`requestId`	Unique ID for the request, used for troubleshooting
`bucketLoggingStatus`	Object containing the current log storage configuration, including `targetBucket` and `targetPrefix`

Disable log storage

Call DeleteBucketLogging to remove the log storage configuration from a bucket. OSS stops writing log files after the configuration is deleted.

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region"   => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket"   => ['help' => 'The name of the bucket.', 'required' => True],
];

$longopts = \array_map(function ($key) { return "$key:"; }, array_keys($optsdesc));
$options  = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

$request = new Oss\Models\DeleteBucketLoggingRequest(
    bucket: $bucket
);

$result = $client->deleteBucketLogging($request);

printf(
    'status code: ' . $result->statusCode . PHP_EOL .
    'request id: '  . $result->requestId
);

Configure user-defined log fields

Call PutUserDefinedLogFieldsConfig to capture additional context in real-time logs. This lets you record specific request headers or query parameters from OSS requests in the user_defined_log_fields field for later analysis.

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region"   => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket"   => ['help' => 'The name of the bucket.', 'required' => True],
];

$longopts = \array_map(function ($key) { return "$key:"; }, array_keys($optsdesc));
$options  = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

// Specify which query parameters and request headers to capture in real-time logs.
$request = new Oss\Models\PutUserDefinedLogFieldsConfigRequest(
    bucket: $bucket,
    userDefinedLogFieldsConfiguration: new Oss\Models\UserDefinedLogFieldsConfiguration(
        new Oss\Models\LoggingParamSet(parameters: ['param1', 'params2']), // Query parameters to capture.
        new Oss\Models\LoggingHeaderSet(headers: ['header1', 'header2'])   // Request headers to capture.
    )
);

$result = $client->putUserDefinedLogFieldsConfig($request);

printf(
    'status code: ' . $result->statusCode . PHP_EOL .
    'request id: '  . $result->requestId
);

Key parameters

Parameter	Class	Description	Example
`parameters`	`LoggingParamSet`	Query parameter names to capture from OSS requests	`['param1', 'params2']`
`headers`	`LoggingHeaderSet`	Request header names to capture from OSS requests	`['header1', 'header2']`

Query user-defined log fields

Call GetUserDefinedLogFieldsConfig to retrieve the current user-defined log field configuration for a bucket.

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region"   => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket"   => ['help' => 'The name of the bucket.', 'required' => True],
];

$longopts = \array_map(function ($key) { return "$key:"; }, array_keys($optsdesc));
$options  = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

$request = new Oss\Models\GetUserDefinedLogFieldsConfigRequest(bucket: $bucket);

$result = $client->getUserDefinedLogFieldsConfig($request);

printf(
    'status code: '               . $result->statusCode . PHP_EOL .
    'request id: '                . $result->requestId  . PHP_EOL .
    'user defined log fields config: ' . var_export($result->userDefinedLogFieldsConfiguration, true)
);

Returned fields

Field	Description
`statusCode`	HTTP response status code
`requestId`	Unique ID for the request
`userDefinedLogFieldsConfiguration`	Object containing the configured `LoggingParamSet` (query parameters) and `LoggingHeaderSet` (request headers)

Delete user-defined log fields

Call DeleteUserDefinedLogFieldsConfig to remove user-defined log field configurations from a bucket.

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

$optsdesc = [
    "region"   => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket"   => ['help' => 'The name of the bucket.', 'required' => True],
];

$longopts = \array_map(function ($key) { return "$key:"; }, array_keys($optsdesc));
$options  = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

$request = new Oss\Models\DeleteUserDefinedLogFieldsConfigRequest(bucket: $bucket);
$result  = $client->deleteUserDefinedLogFieldsConfig($request);

printf(
    'status code: ' . $result->statusCode . PHP_EOL .
    'request id: '  . $result->requestId
);

What's next

PutBucketLogging — API reference for enabling log storage
GetBucketLogging — API reference for viewing log storage configurations
DeleteBucketLogging — API reference for disabling log storage
PutUserDefinedLogFieldsConfig — API reference for configuring user-defined log fields
GetUserDefinedLogFieldsConfig — API reference for querying user-defined log fields
DeleteUserDefinedLogFieldsConfig — API reference for deleting user-defined log fields