[Yandex Cloud documentation](../../index.md) > [Yandex Audit Trails](../index.md) > [Concepts](index.md) > Data event audit log

# Data event audit log

Keep track of [data events](events-data-plane.md) to make sure only authorized users can access and update your data. This will help you ensure your cloud infrastructure's compliance with legal regulations and industry standards. For example, you can keep track of your employees' access permissions to sensitive data stored in buckets.

You can analyze data event logs to optimize the use of resources in your infrastructure. Thus, you can determine what resources are used most often and enhance their performance, or identify rarely used resources that can be grouped or removed to cut costs.

{% note warning %}

When setting up collection of data events for an Object Storage bucket, we do not recommend using the same bucket as a [destination object](trail.md#target) for uploading logs. This may cause automatic recursive generation of audit logs and, consequently, an increase in the size of generated logs (by about 16 MB per month for all events per trail saved to the bucket).

{% endnote %}

A data event audit log is a JSON object with a record of events that occurred to Yandex Cloud resources.

The log entry [format](#scheme) is universal for any event. The values of some fields are determined both by the source resource and the event type.

An event object is the service resource on which the operation is performed. An event subject is the account under which the operation is performed.

{% cut "Sample data audit log created when requesting the contents of a secret" %}

If a federated user requests the contents of a secret in Yandex Lockbox, the following entry is written in the audit log:

```json
{
    "event_id": "<event_ID>",
    "event_source": "lockbox",
    "event_type": "yandex.cloud.audit.lockbox.GetPayload",
    "event_time": "<event_date>",
    "authentication": {
        "authenticated": true,
        "subject_type": "FEDERATED_USER_ACCOUNT",
        "subject_id": "<user_ID>",
        "subject_name": "<username>",
        "federation_id": "<federation_ID>",
        "federation_name": "<federation_name>",
        "federation_type": "<federation_type>"
    },
    "authorization": {
        "authorized": true
    },
    "resource_metadata": {
        "path": [
            {
                "resource_type": "organization-manager.organization",
                "resource_id": "<organization_ID>",
                "resource_name": "<organization_name>"
            },
            {
                "resource_type": "resource-manager.cloud",
                "resource_id": "<cloud_ID>",
                "resource_name": "<cloud_name>"
            },
            {
                "resource_type": "resource-manager.folder",
                "resource_id": "<folder_ID>",
                "resource_name": "<folder_name>"
            }
        ]
    },
    "request_metadata": {
        "remote_address": "cloud.yandex",
        "user_agent": "Yandex Cloud",
        "request_id": "<request_ID>"
    },
    "event_status": "DONE",
    "details": {
        "secret_id": "<secret_ID>",
        "secret_name": "<secret_name>",
        "secret_version_id": "<secret_version_ID>",
        "secret_kms_key_id": "<ID_of_secret_encryption_key_in_KMS>",
        "secret_status": "<secret_status>",
        "secret_version_status": "<secret_version_status>",
        "secret_version_payload_entry_keys": [
            "<secret_version_entry_keys>"
        ]
    },
    "request_parameters": {
        "secret_id": "<secret_ID>",
        "version_id": "<secret_version_ID>"
    },
    "response": {
        "version_id": "<version_ID>",
        "entry_keys": [
            "<entry_keys>"
        ]
    }
}
```
{% endcut %}

## Data schema {#scheme}

```json
{
  "event_id": string,
  "event_source": string,
  "event_type": string,
  "event_time": string,
  "authentication": {
    "authenticated": boolean,
    "subject_type": string,
    "subject_id": string,
    "subject_name": string,
    "federation_id": string,
    "federation_name": string,
    "federation_type": string,
    "token_info": {
      "masked_iam_token": string,
      "iam_token_id": string,
      "impersonator_id": string,
      "impersonator_type": string,
      "impersonator_name": string,
      "impersonator_federation_id": string,
      "impersonator_federation_name": string,
      "impersonator_federation_type": string
    }
  },
  "authorization": {
    "authorized": boolean
  },
  "resource_metadata": {
    "path": [{
      "resource_type": string,
      "resource_id": string,
      "resource_name": string
    }]
  },
  "request_metadata": {
    "remote_address": string,
    "user_agent": string,
    "request_id": string
  },
  "event_status": string,
  "error": {
    "code": number,
    "message": string,
    "details": {
      object
    }
  },
  "details": {
    object
  },
  "request_parameters": {
    object
  },
  "response": {
    object
  }
}
```

Field | Description
--- | ---
`event_id` | **string**<br>Event ID
`event_source` | **string**<br>Name of the event source service.
`event_type` | **string**<br>Event type which is determined by the event source service. For more information, see [Data event reference](events-data-plane.md).
`event_time` | **string**<br>Event time.
`authentication` ^1^ | **object**<br>Event subject's authentication data.
`authentication.authenticated` | **boolean**<br>Authentication result. The possible values are:<ul><li>`true`: Authentication successful.</li><li>`false`: Authentication failed.</li>
`authentication.subject_type` | **string**<br>Type of the subject. The possible values are:<ul><li>`YANDEX_PASSPORT_USER_ACCOUNT`: Yandex account.</li><li>`SERVICE_ACCOUNT`: Service account.</li><li>`FEDERATED_USER_ACCOUNT`: Federated account.</li>
`authentication.subject_id` | **string**<br>ID of the subject.
`authentication.subject_name` | **string**<br>Subject name.
`authentication.federation_id` ^2^ | **string**<br>ID of the federation the federated user belongs to.
`authentication.federation_name` ^2^ | **string**<br>Name of the federation the federated user belongs to.
`authentication.federation_type` ^2^ | **string**<br>Federation type. The possible value is:<ul><li>`PRIVATE_FEDERATION`: Federation managed by Yandex Cloud clients.</li></ul>
`authentication.token_info` ^1^ | **object**<br>Event subject's authentication data.
`authentication.token_info.masked_iam_token` | **string**<br>Encrypted value of the IAM token the subject used to execute the request.
`authentication.token_info.iam_token_id` | **string**<br>ID of the encrypted IAM token.
`authentication.token_info.impersonator_id` | **string**<br>Subject ID when using [impersonation](../../iam/concepts/access-control/impersonation.md).
`authentication.token_info.impersonator_type` | **string**<br>Impersonator subject type. The possible values are:<ul><li>`YANDEX_PASSPORT_USER_ACCOUNT`: Yandex account.</li><li>`SERVICE_ACCOUNT`: Service account.</li><li>`FEDERATED_USER_ACCOUNT`: Federated account.</li>
`authentication.token_info.impersonator_name` | **string**<br>Impersonator subject name.
`authentication.token_info.impersonator_federation_id` ^2^ | **string**<br>ID of the federation the federated impersonator user belongs to.
`authentication.token_info.impersonator_federation_name`&nbsp;^2^ | **string**<br>Name of the federation the federated impersonator user belongs to.
`authentication.token_info.impersonator_federation_type`&nbsp;^2^ | **string**<br>Federation type. The possible value is:<ul><li>`PRIVATE_FEDERATION`: Federation managed by Yandex Cloud clients.</li></ul>
`authorization` ^1^ | **object**<br>Event subject's authorization data.
`authorization.authorized` | **boolean**<br>Authorization result. The possible values are:<ul><li>`true`: Authorization successful.</li><li>`false`: Authorization failed.</li>
`resource_metadata` ^1^ | **object**<br>Event object's metadata.
`resource_metadata.path[]` | **array**<br>Path to the resource the event occurred in.
`resource_metadata.path[].resource_type` | **string**<br>Resource type.
`resource_metadata.path[].resource_id` | **string**<br>Resource ID.
`resource_metadata.path[].resource_name` | **string**<br>Resource name.
`request_metadata` | **object**<br>Details of the request that triggered the event.
`request_metadata.remote_address` | **string**<br>IP address of the event subject.
`request_metadata.user_agent` | **string**<br>User-agent of the event subject.
`request_metadata.request_id` | **string**<br>Request ID.
`event_status` | **string**<br>Event status, which is determined by the source service and the event type. The possible values are:<ul><li>`STARTED`: Operation started.</li><li>`ERROR`: Operation completed with an error.</li><li>`DONE`: Operation completed successfully.</li><li>`CANCELLED`: Operation canceled.</li></ul>
`error` | **object**<br>Status error. [google.rpc.Status](https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto) object:<ul><li>`code`: [Error code](https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto).</li><li>`message`: Error description.</li><li>`details`: [Error details](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto).</li></ul>to fill out only in case of an error.
`details` | **object**<br>Event details, which are determined by the source service and the event type
`request_parameters` ^1^ | **object**<br>Request parameters.
`response` ^1^ | **object**<br>Obtained data.

<small>^1^ This field section is not for all event types.</small>
<small>^2^ This field is available when `subject_type` = `FEDERATED_USER_ACCOUNT`.</small>

{% note info %}

If the action was performed by one of the Yandex Cloud infrastructure services or a support employee, the following fields will be be set to the following special values:

* `remote_address`: `cloud.yandex`
* `user_agent`: `Yandex Cloud`

{% endnote %}

## Audit log format {#log-name}

Depending on the [destination object](trail.md#target) (a [bucket](../../storage/concepts/bucket.md), [log group](../../logging/concepts/log-group.md), or [data stream](../../data-streams/concepts/glossary.md#stream-concepts)), the message used by Audit Trails to transmit audit logs has a different structure and content:
* If the destination object is a bucket, the message is a file containing an array of [JSON objects](#scheme) of the audit log.
* If the destination object is a log group, the message includes a single JSON object of the audit log.
* If the destination object is a data stream, the message includes one or more JSON objects in [JSON Lines](https://jsonlines.org/) format.

### Audit log file in a bucket {#log-file-name}

Below is the template for the full name of an audit log file in a bucket:

`<object_prefix>/<trail_ID>/<year>/<month>/<day>/<file_name>.json`

### Log group entry {#logging-group-name}

Log group entries have the following values:
* **Time**: `event_time` value.
* **JSON**: JSON object of the event.
* **Level**: Calculated depending on the `event_status` value:
  * `ERROR`: For the `ERROR` value.
  * `WARN`: For the `CANCELLED` value.
  * `INFO`: In all other cases.
* **Message**: Contains the values of the `event_status`, `event_type`, `subject_name`, `cloud_name`, and `resource_name` fields.

When uploading to Cloud Logging, you may get duplicate events in a [log group](../../logging/concepts/log-group.md). To find duplicates, refer to the unique record ID, `json_payload.event_id`.

### Message to the data stream {#data-stream-message}

In Data Streams, events are transmitted in [messages](../../data-streams/concepts/glossary.md#message) as JSON objects in JSON Lines format. Each message may contain one or more events (JSONL strings).