# oss-logging

Part of **OSS**

<!-- intent-backlink:auto -->

> 💡 **Path Selection**: This skill is one implementation path for [Configure storage access logging and monitoring](../../intent/oss-configure-monitoring/SKILL.md). If you're unsure which path to take, check the routing skill first.

# Object Storage Service Logging CLI Reference

## Command Overview

| Command | Purpose | Syntax |
|--------|---------|--------|
| `logging` | Manage bucket access logging (enable, disable, query) | `ossutil logging --method [put\|get\|delete] [flags]` |
| `put-user-defined-log-fields-config` | Configure custom log fields for a bucket | `ossutil api put-user-defined-log-fields-config [flags]` |
| `get-user-defined-log-fields-config` | Retrieve custom log field configuration | `ossutil api get-user-defined-log-fields-config [flags]` |
| `delete-user-defined-log-fields-config` | Remove custom log field configuration | `ossutil api delete-user-defined-log-fields-config [flags]` |

## Command Details

### logging

**Purpose**: Manage bucket access logging by enabling, disabling, or retrieving logging rules. Logs record requests made to the source bucket and are stored in a specified target bucket.

**Syntax**:
```bash
ossutil logging --method [put|get|delete] oss://source-bucket [oss://target-bucket[/prefix]] [local-file] [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--method` | — | string | Yes | Operation type: `put`, `get`, or `delete` |
| `--loglevel` | — | string | No | Log verbosity: `info` (default) or `debug` |

```bash
# Enable logging: store logs from bucket1 in bucket2 under "logs/" prefix
ossutil logging --method put oss://bucket1 oss://bucket2/logs

# Enable logging without prefix (logs stored at root of target bucket)
ossutil logging --method put oss://srcbucket oss://destbucket

# Retrieve current logging config and save to local file
ossutil logging --method get oss://examplebucket /tmp/logging.xml

# Retrieve and display config directly in terminal
ossutil logging --method get oss://examplebucket

# Disable logging for a bucket
ossutil logging --method delete oss://examplebucket
```

**Example Output**:
```text
<?xml version="1.0" encoding="UTF-8"?>
<BucketLoggingStatus>
    <LoggingEnabled>
        <TargetBucket>destbucket</TargetBucket>
        <TargetPrefix></TargetPrefix>
    </LoggingEnabled>
</BucketLoggingStatus>

0.109979(s) elapsed
```

### put-user-defined-log-fields-config

**Purpose**: Configure custom fields (e.g., specific HTTP headers or query parameters) to be included in real-time access logs for enhanced analysis.

**Syntax**:
```bash
ossutil api put-user-defined-log-fields-config --bucket <name> --user-defined-log-fields-configuration <config> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--bucket` | — | string | Yes | Name of the bucket to configure |
| `--user-defined-log-fields-configuration` | — | string | Yes | Configuration in JSON/XML format or path to file (prefixed with `file://`) |

```bash
# Configure using an XML file
ossutil api put-user-defined-log-fields-config --bucket examplebucket --user-defined-log-fields-configuration file://config.xml

# Configure using a JSON file
ossutil api put-user-defined-log-fields-config --bucket examplebucket --user-defined-log-fields-configuration file://config.json

# Configure inline JSON (escaped)
ossutil api put-user-defined-log-fields-config --bucket examplebucket --user-defined-log-fields-configuration "{\"HeaderSet\":{\"header\":[\"x-custom-header\"]},\"ParamSet\":{\"parameter\":[\"utm_source\"]}}"
```

### get-user-defined-log-fields-config

**Purpose**: Retrieve the current user-defined log fields configuration for a bucket.

**Syntax**:
```bash
ossutil api get-user-defined-log-fields-config --bucket <name> [--output-format <format>]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--bucket` | — | string | Yes | Name of the bucket |
| `--output-format` | — | string | No | Output format: `json` (default) or `yaml` |

```bash
# Get config in default JSON format
ossutil api get-user-defined-log-fields-config --bucket examplebucket

# Explicitly request JSON
ossutil api get-user-defined-log-fields-config --bucket examplebucket --output-format json

# Request YAML output
ossutil api get-user-defined-log-fields-config --bucket examplebucket --output-format yaml
```

**Example Output**:
```json
{"userDefinedLogFieldsConfig": {"fields": ["field1", "field2"]}}
```

### delete-user-defined-log-fields-config

**Purpose**: Remove all user-defined log field settings from a bucket, reverting to default logging fields.

**Syntax**:
```bash
ossutil api delete-user-defined-log-fields-config --bucket <name>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| `--bucket` | — | string | Yes | Name of the bucket |

```bash
# Delete custom log field config for examplebucket
ossutil api delete-user-defined-log-fields-config --bucket examplebucket
```

## Common Scenarios

### Scenario 1: Enable Access Logging with Custom Prefix
```bash
# Step 1: Enable logging for production-bucket, storing logs in audit-bucket under "prod-access/" prefix
ossutil logging --method put oss://production-bucket oss://audit-bucket/prod-access

# Step 2: Verify the configuration was applied
ossutil logging --method get oss://production-bucket
```

### Scenario 2: Configure and Audit Custom Log Fields
```bash
# Step 1: Set up custom headers and parameters to log
ossutil api put-user-defined-log-fields-config --bucket app-data --user-defined-log-fields-configuration file://custom-fields.json

# Step 2: Confirm the configuration is active
ossutil api get-user-defined-log-fields-config --bucket app-data --output-format json

# Step 3: Later, remove custom fields if no longer needed
ossutil api delete-user-defined-log-fields-config --bucket app-data
```

## Environment Setup

### Installation
Install `ossutil` by downloading the appropriate binary for your OS from the official Alibaba Cloud OSS documentation. Ensure it is executable and added to your system PATH.

### Configuration
Configure credentials and region using:
```bash
ossutil config
```
Alternatively, use flags (`-i`, `-k`, `-e`) or environment variables (`OSS_ACCESS_KEY_ID`, `OSS_ACCESS_KEY_SECRET`, `OSS_ENDPOINT`). The destination bucket must be in the same region as the source bucket and owned by the same Alibaba Cloud account.

## FAQ

Q: How do I configure credentials for ossutil?
A: Run `ossutil config` to interactively set AccessKey ID, Secret, and endpoint. Alternatively, pass them via `-i`, `-k`, and `-e` flags, or set environment variables.

Q: What permissions are required to manage bucket logging?
A: You need `oss:PutBucketLogging`, `oss:GetBucketLogging`, or `oss:DeleteBucketLogging` permissions for the source bucket, and write access to the target bucket.

Q: Can I store logs in a bucket in a different region or account?
A: No. The target bucket must be in the same region and under the same Alibaba Cloud account as the source bucket.

Q: Why am I getting a 403 error when enabling logging?
A: This usually indicates insufficient permissions. Verify that your credentials have the required `oss:PutBucketLogging` permission on the source bucket and write access to the target bucket.

Q: How can I verify that logging is working?
A: After enabling logging, make a few test requests to the bucket. Check the target bucket after several hours—log files are delivered periodically and follow naming conventions like `YYYY-MM-DD-HH-MM-SS-UniqueID`.