Use ossutil put-user-defined-log-fields-config to configure user-defined log fields - Object Storage Service

Adds custom request headers or query parameters as log fields to a bucket, enabling real-time filtering and analysis of request data.

Note

This command maps to the PutUserDefinedLogFieldsConfig API operation. For full parameter details, see PutUserDefinedLogFieldsConfig.

Prerequisites

Before you begin, ensure that you have:

An OSS bucket
The oss:PutUserDefinedLogFieldsConfig permission (required for RAM users and Security Token Service (STS) credentials; Alibaba Cloud root accounts have this permission by default). For details, see Grant a custom policy to a RAM user

Syntax

ossutil api put-user-defined-log-fields-config --bucket <value> --user-defined-log-fields-configuration <value> [flags]

Required parameters:

Parameter	Type	Description
`--bucket`	string	The bucket name.
`--user-defined-log-fields-configuration`	string	The log field configuration, specifying which request headers (`HeaderSet`) and query parameters (`ParamSet`) to capture as log fields. Accepts XML or JSON.

For supported global flags, see Global command-line options.

--user-defined-log-fields-configuration format

The --user-defined-log-fields-configuration option accepts XML syntax, JSON syntax, or a file path prefixed with file://.

XML syntax:

<HeaderSet>
  <header>string</header>
  ...
</HeaderSet>
<ParamSet>
  <parameter>string</parameter>
  ...
</ParamSet>

JSON syntax:

{
  "HeaderSet": {
    "header": ["string", ...]
  },
  "ParamSet": {
    "parameter": ["string", ...]
  }
}

Use the file:// prefix to load the configuration from a local file instead of passing it inline:

--user-defined-log-fields-configuration file://user-defined-log-fields-configuration.json

Examples

The following examples configure examplebucket to capture three custom request headers (header1, header2, header3) and two query parameters (param1, param2) as log fields. All three examples produce the same result — choose the format that fits your workflow.

Use an XML configuration file

Create a file named user-defined-log-fields-configuration.xml with the following content:

   <?xml version="1.0" encoding="UTF-8"?>
   <UserDefinedLogFieldsConfiguration>
     <HeaderSet>
       <header>header1</header>
       <header>header2</header>
       <header>header3</header>
     </HeaderSet>
     <ParamSet>
       <parameter>param1</parameter>
       <parameter>param2</parameter>
     </ParamSet>
   </UserDefinedLogFieldsConfiguration>

Run the command:

   ossutil api put-user-defined-log-fields-config --bucket examplebucket --user-defined-log-fields-configuration file://user-defined-log-fields-configuration.xml

Use a JSON configuration file

Create a file named user-defined-log-fields-configuration.json with the following content:

   {
     "HeaderSet": {
       "header": [
         "header1",
         "header2",
         "header3"
       ]
     },
     "ParamSet": {
       "parameter": [
         "param1",
         "param2"
       ]
     }
   }

Run the command:

   ossutil api put-user-defined-log-fields-config --bucket examplebucket --user-defined-log-fields-configuration file://user-defined-log-fields-configuration.json

Pass the configuration inline

Pass the JSON configuration directly in the command without creating a file:

ossutil api put-user-defined-log-fields-config --bucket examplebucket --user-defined-log-fields-configuration "{\"HeaderSet\":{\"header\":[\"header1\",\"header2\",\"header3\"]},\"ParamSet\":{\"parameter\":[\"param1\",\"param2\"]}}"