[Yandex Cloud documentation](../../index.md) > [Yandex Audit Trails](../index.md) > [Step-by-step guides](index.md) > Creating a trail

# Creating a trail to upload audit logs


You can create a trail that will upload both [management](../concepts/format.md) and [data](../concepts/format-data-plane.md) event audit logs into one of the [destination objects](../concepts/trail.md#target):

* [Yandex Object Storage](../../storage/index.md) bucket.
* [Yandex Cloud Logging](../../logging/index.md) group.
* [Yandex Data Streams](../../data-streams/index.md) data stream.
* [Yandex EventRouter](../../serverless-integrations/index.md) bus.

{% note info %}

Currently, you can only create a trail with the **EventRouter** destination object using the [management console](https://console.yandex.cloud), Yandex Cloud [CLI](../../cli/index.md), and [API](../../api-design-guide/index.md).

{% endnote %}

## Getting started {#before-you-begin}

Depending on the selected [destination object](../concepts/trail.md#target) for logs, prepare the required infrastructure to create a trail:

{% list tabs group=trail-target %}

- Object Storage bucket {#bucket}

  1. [Create a bucket](../../storage/operations/buckets/create.md) with restricted access the audit logs will be uploaded to.
  1. (Optional) Enable encryption for the bucket:

      [Make sure](../../iam/operations/roles/get-assigned-roles.md) the account you are going to use to create an encryption key for the bucket has the `kms.editor` [role](../../kms/security/index.md#kms-editor) for the folder.
  1. [Create a service account](../../iam/operations/sa/create.md) for the trail.
  1. [Assign to the service account these roles](../../iam/operations/sa/assign-role-for-sa.md) for the trail to collect and upload logs:

      * [storage.uploader](../../storage/security/index.md#storage-uploader) for the [bucket](../../storage/concepts/bucket.md).
      * [kms.keys.encrypter](../../kms/security/index.md#kms-keys-encrypter) for the bucket [encryption key](../../kms/concepts/key.md).

          This role is only required if encryption was enabled for the bucket.

      * [audit-trails.viewer](../security/index.md#at-viewer) for a resource defining the [required log collection scope](../concepts/trail.md#collecting-area):
      
          * [Organization](../../organization/operations/add-role.md): To collect logs in selected clouds of the organization.
          * [Cloud](../../resource-manager/operations/cloud/set-access-bindings.md#access-to-sa): To collect logs in selected folders of the cloud.
          * [Folder](../../resource-manager/operations/folder/set-access-bindings.md#access-to-sa): To collect logs in this folder.
      
          Child resources inherit access permissions from their parent resources. For example, if a service account [gets a role for a cloud](../../resource-manager/operations/cloud/set-access-bindings.md), then the trail that uses this account will be able to collect logs for resources across all folders of this cloud. However, the trail will not be able to collect logs in other clouds owned by the organization: [a role for the organization](../../organization/operations/add-role.md) is required for that.

  1. [Make sure](../../iam/operations/roles/get-assigned-roles.md) the [account](../../iam/concepts/users/accounts.md) you are going to use to create a trail has the required roles:
     
     * [audit-trails.editor](../security/index.md#at-editor) for the folder to host the trail.
     * [iam.serviceAccounts.user](../../iam/security/index.md#iam-serviceAccounts-user) for the trail’s service account.

- Cloud Logging log group {#logging}

  1. [Create a log group](../../logging/operations/create-group.md) the audit logs will be uploaded to.
  1. [Create a service account](../../iam/operations/sa/create.md) for the trail.
  1. [Assign to the service account these roles](../../iam/operations/sa/assign-role-for-sa.md) for the trail to collect and upload logs:

      * [logging.writer](../../logging/security/index.md#logging-writer) for the [log group](../../logging/concepts/log-group.md).

      * [audit-trails.viewer](../security/index.md#at-viewer) for a resource defining the [required log collection scope](../concepts/trail.md#collecting-area):
      
          * [Organization](../../organization/operations/add-role.md): To collect logs in selected clouds of the organization.
          * [Cloud](../../resource-manager/operations/cloud/set-access-bindings.md#access-to-sa): To collect logs in selected folders of the cloud.
          * [Folder](../../resource-manager/operations/folder/set-access-bindings.md#access-to-sa): To collect logs in this folder.
      
          Child resources inherit access permissions from their parent resources. For example, if a service account [gets a role for a cloud](../../resource-manager/operations/cloud/set-access-bindings.md), then the trail that uses this account will be able to collect logs for resources across all folders of this cloud. However, the trail will not be able to collect logs in other clouds owned by the organization: [a role for the organization](../../organization/operations/add-role.md) is required for that.

  1. [Make sure](../../iam/operations/roles/get-assigned-roles.md) the [account](../../iam/concepts/users/accounts.md) you are going to use to create a trail has the required roles:
     
     * [audit-trails.editor](../security/index.md#at-editor) for the folder to host the trail.
     * [iam.serviceAccounts.user](../../iam/security/index.md#iam-serviceAccounts-user) for the trail’s service account.

- Data Streams {#data-streams}

  1. [Create a data stream](../../data-streams/operations/manage-streams.md#create-data-stream) the audit logs will be uploaded to.

      {% note tip %}

      We recommend enabling [autopartitioning](../../data-streams/concepts/glossary.md#autopartitioning) on the target data stream.

      When overloading individual [shards](../../data-streams/concepts/glossary.md#shard) or the entire [stream](../../data-streams/concepts/glossary.md#stream-concepts), some events may get lost. Autopartitioning automatically adds shards as needed and distributes the workloads to avoid losses. If autopartitioning is disabled, remember to manually check and increase the number of shards.

      {% endnote %}

  1. [Create a service account](../../iam/operations/sa/create.md) for the trail.
  1. [Assign to the service account these roles](../../iam/operations/sa/assign-role-for-sa.md) for the trail to collect and upload logs:

      * [yds.writer](../../data-streams/security/index.md#yds-writer) for the [data stream](../../data-streams/concepts/glossary.md#stream-concepts).

      * [audit-trails.viewer](../security/index.md#at-viewer) for a resource defining the [required log collection scope](../concepts/trail.md#collecting-area):
      
          * [Organization](../../organization/operations/add-role.md): To collect logs in selected clouds of the organization.
          * [Cloud](../../resource-manager/operations/cloud/set-access-bindings.md#access-to-sa): To collect logs in selected folders of the cloud.
          * [Folder](../../resource-manager/operations/folder/set-access-bindings.md#access-to-sa): To collect logs in this folder.
      
          Child resources inherit access permissions from their parent resources. For example, if a service account [gets a role for a cloud](../../resource-manager/operations/cloud/set-access-bindings.md), then the trail that uses this account will be able to collect logs for resources across all folders of this cloud. However, the trail will not be able to collect logs in other clouds owned by the organization: [a role for the organization](../../organization/operations/add-role.md) is required for that.

  1. [Make sure](../../iam/operations/roles/get-assigned-roles.md) the [account](../../iam/concepts/users/accounts.md) you are going to use to create a trail has the required roles:
     
     * [audit-trails.editor](../security/index.md#at-editor) for the folder to host the trail.
     * [iam.serviceAccounts.user](../../iam/security/index.md#iam-serviceAccounts-user) for the trail’s service account.

- EventRouter bus {#eventrouter}

  1. [Create](../../serverless-integrations/operations/eventrouter/bus/create.md) a Yandex EventRouter bus.

      {% note info %}

      Currently, you can only create an EventRouter bus [connector](../../serverless-integrations/concepts/eventrouter/connector.md) with the `Audit Trails` source type in the [management console](https://console.yandex.cloud) when creating or editing a trail, or using the [EventRouter API](../../serverless-integrations/eventrouter/api-ref/Connector/create.md).

      {% endnote %}

  1. [Create a service account](../../iam/operations/sa/create.md) for the trail.
  1. [Assign to the service account these roles](../../iam/operations/sa/assign-role-for-sa.md) for the trail to collect and upload logs:

      * [serverless.eventrouter.supplier](../../serverless-integrations/security/eventrouter.md#serverless-eventrouter-supplier) for the folder where the EventRouter [bus](../../serverless-integrations/concepts/eventrouter/bus.md) resides.

      * [audit-trails.viewer](../security/index.md#at-viewer) for a resource defining the [required log collection scope](../concepts/trail.md#collecting-area):
      
          * [Organization](../../organization/operations/add-role.md): To collect logs in selected clouds of the organization.
          * [Cloud](../../resource-manager/operations/cloud/set-access-bindings.md#access-to-sa): To collect logs in selected folders of the cloud.
          * [Folder](../../resource-manager/operations/folder/set-access-bindings.md#access-to-sa): To collect logs in this folder.
      
          Child resources inherit access permissions from their parent resources. For example, if a service account [gets a role for a cloud](../../resource-manager/operations/cloud/set-access-bindings.md), then the trail that uses this account will be able to collect logs for resources across all folders of this cloud. However, the trail will not be able to collect logs in other clouds owned by the organization: [a role for the organization](../../organization/operations/add-role.md) is required for that.

  1. [Make sure](../../iam/operations/roles/get-assigned-roles.md) the [account](../../iam/concepts/users/accounts.md) you are going to use to create a trail has the required roles:
     
     * [audit-trails.editor](../security/index.md#at-editor) for the folder to host the trail.
     * [iam.serviceAccounts.user](../../iam/security/index.md#iam-serviceAccounts-user) for the trail’s service account.

{% endlist %}

## Creating a trail {#create}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder to host the trail.
  1. Navigate to **Audit Trails**.
  1. Click **Create trail**.
  1. Enter a trail name. It must be unique within the folder.
  1. (Optional) Enter a description for your trail.
  1. Under **Destination**, select one of the destination objects and specify its settings:

      * **Object Storage**: Uploading audit logs to an Object Storage bucket. Recommended for long-term data storage. Configure log storage settings:

          * **Bucket**: Bucket you [created earlier](#before-you-begin).
          * **Object prefix**: [Prefix](../concepts/format.md#log-file-name) that will be assigned to the objects with audit logs in the bucket. It is an optional parameter used in the [full name](../concepts/format.md#log-file-name) of the audit log file.

              {% note info %}
              
              Use a [prefix](../../storage/concepts/object.md#key) to store audit logs and third-party data in the same bucket. Do not use the same prefix for logs and other bucket objects because that may cause logs and third-party objects to overwrite each other.
              
              {% endnote %}

          * **Encryption key**: Bucket encryption key. You only need to select it if encryption was enabled for the bucket.
      * **Cloud Logging**: Log group you [created earlier](#before-you-begin). Audit logs will be uploaded into this log group. Recommended for quick log collection and analysis.
      * **Data Streams**: Data stream you [created earlier](#before-you-begin). Audit logs will be uploaded into this stream. Recommended for streaming logs to other services or systems.
      * **EventRouter**: EventRouter bus connector. Recommended for detailed analysis of logs and their subsequent sending to various handlers and systems depending on the conditions specified in the bus.

          In the **Connector** field, select the EventRouter bus [connector](../../serverless-integrations/concepts/eventrouter/connector.md) with the `Audit Trails` source type or click **Create** to create a new connector in the bus.

  1. Under **Service account**, select the [previously created](#before-you-begin) service account the trail will operate under.

  1. Enable and configure event collection from one or two levels. Such events will end up in the audit logs.

      To configure **Collecting management events**:

      1. Select the [log collection scope](../concepts/trail.md): `Organization`, `Cloud`, or `Folder`. The logged events will be collected in the scope you specify.

          The permissions of the service account you [created earlier](#before-you-begin) must allow collecting logs from the specified scope.

      1. Depending on the log collection scope, select the clouds or folders to collect events from:

          * For the `Organization` collection scope, from the **Cloud** drop-down list, select one or more clouds to collect events from.

              Keep the default value (`All`) to collect events from all clouds in the organization.

          * For the `Cloud` collection scope, select from the **Folder** drop-down list one or more folders to collect events from.

              Keep the default value (`All`) to collect events from all folders in the cloud.

      To configure **Collecting data events**:

      {% note warning %}
      
      In the management console, collection of some [data events](../concepts/control-plane-vs-data-plane.md#data-plane-events) is on [by default](../concepts/trail.md#default). Their delivery is billed as per the [pricing policy](../pricing.md). If you do not need data events, disable their collection.
      
      {% endnote %}

      1. Select one or more services to collect events from.

      1. For each such service, select the [log collection scope](../concepts/trail.md): `Organization`, `Cloud`, or `Folder`. The logged events will be collected in the scope you specify.

          The permissions of the service account you [created earlier](#before-you-begin) must allow collecting logs from the specified scope.

      1. Depending on the log collection scope, select the clouds or folders to collect events from:

          * For the `Organization` collection scope, from the **Cloud** drop-down list, select one or more clouds to collect events from.

              Keep the default value (`All`) to collect events from all clouds in the organization.

          * For the `Cloud` collection scope, select from the **Folder** drop-down list one or more folders to collect events from.

              Keep the default value (`All`) to collect events from all folders in the cloud.

      1. For each such service, select one of the following filters by [events](../concepts/events-data-plane.md#dns):

          * `Receive all`: To collect all events within the service.
          * `Selected`: To collect only the selected events. Then proceed to select the events.
          * `Exclude`: To collect all events except for the selected ones. Then proceed to select the events.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  See the description of the [CLI](../../cli/index.md) trail creation command for details about the arguments you can use:

  ```bash
  yc audit-trails trail create --help
  ```

  You can create a trail by specifying its parameters in one of these two ways:

  {% cut "In the YAML specification" %}

  [Create a YAML specification](prepare-spec.md#spec-for-create) containing the trail parameters and specify this file in the command to create the trail.
  
  This method simplifies working with trail parameters and reduces error probability. In addition, you can only customize the registration of [data events](../concepts/control-plane-vs-data-plane.md#data-plane-events) using the YAML specification.

  1. Create a YAML file with the trail configuration:

      ```yaml
      name: <trail_name>
      folder_id: <folder_ID>
      destination:
        # Only one destination must be specified:
        # object_storage, cloud_logging, data_stream, or eventrouter
        # Settings for all destinations are provided for illustration purposes.
        object_storage:
          bucket_id: <bucket_name>
          object_prefix: <prefix_for_objects>
        cloud_logging:
          log_group_id: <log_group_ID>
        data_stream:
          stream_name: <YDS_name>
          database_id: <YDS_database_ID>
          codec: <event_compression_method>
        eventrouter:
          eventrouter_connector_id: <bus_connector_ID>
      service_account_id: <service_account_ID>
      filtering_policy:
        management_events_filter:
          resource_scopes:
            - id: <cloud_or_folder_organization_ID>
              type: <type>
        data_events_filters:
          - service: <service_name>
            resource_scopes:
              - id: <cloud_or_folder_organization_ID>
                type: <type>
            # You can specify either included_events or excluded_events,
            # or skip both parameters to collect all service events.
            # Both parameters are provided for illustration purposes.
            included_events:
              event_types:
                - <these_events_will_be_collected>
            excluded_events:
              event_types:
                - <these_events_will_not_be_collected>
      ```

      Where:

      * `name`: Trail name. It must be unique within the folder.
      * `folder_id`: [ID](../../resource-manager/operations/folder/get-id.md) of the folder the trail will reside in.
      * `destination`: Settings of the selected destination the audit logs will be uploaded to.

          {% note warning %}

          Destination settings are mutually exclusive. Using some settings makes it impossible to use others.

          {% endnote %}

          * `object_storage`: Uploading logs to a Yandex Object Storage [bucket](../../storage/concepts/bucket.md#naming):

              * `bucket_id`: [Name](../../storage/concepts/bucket.md#naming) of the bucket you created [earlier](#before-you-begin).

                  You can request the name of the bucket with the list of buckets in the folder (the default folder is used):

                  ```bash
                  yc storage bucket list
                  ```
              * `object_prefix`: [Prefix](../../storage/concepts/object.md#folder) that will be assigned to the objects with audit logs in the bucket. It is an optional parameter used in the [full name](../concepts/format.md#log-file-name) of the audit log file.

                  {% note info %}
                  
                  Use a [prefix](../../storage/concepts/object.md#key) to store audit logs and third-party data in the same bucket. Do not use the same prefix for logs and other bucket objects because that may cause logs and third-party objects to overwrite each other.
                  
                  {% endnote %}

          * `cloud_logging`: Uploading logs to a Yandex Cloud Logging [group](../../logging/concepts/log-group.md).

              In the `log_group_id` parameter, specify the ID of the log group you [created earlier](#before-you-begin). You can request the ID with the [list of log groups in the folder](../../logging/operations/list.md).
          * `data_stream`: Uploading logs to a [data stream](../../data-streams/concepts/glossary.md#stream-concepts) in Yandex Data Streams:

              * `stream_name`: Name of the data stream you [created earlier](#before-you-begin). You can request the name with the [list of data streams in the folder](../../data-streams/operations/manage-streams.md#list-data-streams).
              * `database_id`: ID of the YDB database used by Data Streams. You can request the ID with the [list of YDB databases in the folder](../../ydb/operations/manage-databases.md#list-db).
              * `codec`: Event compression method when writing to Data Streams. The possible values are `RAW` (no compression, default), `GZIP`, and `ZSTD`. Enable compression if you expect an event flow greater than 1 MB/s.
          * `eventrouter`: Uploading logs to a Yandex EventRouter [bus](../../serverless-integrations/concepts/eventrouter/bus.md):

              * `eventrouter_connector_id`: EventRouter bus [connector](../../serverless-integrations/concepts/eventrouter/connector.md) ID with the `Audit Trails` source type.
      * `service_account_id`: [ID](../../iam/operations/sa/get-id.md) of the service account you created [earlier](#before-you-begin).

      * `filtering_policy`: Settings of the filtering policy that determines which events to collect and include in the audit logs. The policy consists of filters pertaining to different levels of events.
      
          {% note warning %}
      
          You must configure at least one filter for the policy; otherwise, you will not be able to create a trail.
      
          {% endnote %}
      
          Available filters:
      
          * `management_events_filter`: Management event filter.
      
              {#filter-cli}
      
              Specify the [log collection scope](../concepts/trail.md#collecting-area) in the `resource_scopes` parameter:
      
              * `id`: Organization, cloud, or folder ID.
              * `type`: Scope type according to the specified ID:
      
                  * `organization-manager.organization`: [Organization](../../organization/concepts/organization.md).
                  * `resource-manager.cloud`: [Cloud](../../resource-manager/concepts/resources-hierarchy.md#cloud).
                  * `resource-manager.folder`: [Folder](../../resource-manager/concepts/resources-hierarchy.md#folder).
      
              You can combine several scopes belonging to the same organization in one `resource_scopes` parameter. For example, you can collect logs from one entire cloud and only from particular folders in another cloud:
      
              ```yaml
              resource_scopes:
              # Collecting logs from all of cloud 1
              - id: <ID_of_cloud_1>
                  type: resource-manager.cloud
              # Collecting logs from folder 1 of cloud 2
              - id: <folder_1_ID>
                  type: resource-manager.folder
              # Collecting logs from folder 2 of cloud 2
              - id: <folder_2_ID>
                  type: resource-manager.folder
              ```
      
              Service account permissions must allow collecting logs from the specified scopes.
      
          * `data_events_filters`: Data event filters. You can configure several filters of this type, one filter per service.
      
              A filter for one service has the following structure:
      
              * `service`: Service name. You can get it from the [data event reference](../concepts/events-data-plane.md).
      
              * `resource_scopes`: Places to collect data events from. You can configure this parameter the same way as the management event filter.
      
              * `*_events`: Data event filters.
      
                  * `included_events.event_types`: Collect only specified events.
                  * `excluded_events.event_types`: Collect all events other than the specified ones.
      
                  You can get a list of events from the [data event reference](../concepts/events-data-plane.md).
      
                  {% note warning %}
      
                  The `included_events` and `excluded_events` filters are mutually exclusive, so only one of them should be set up. If neither filter is set up, all events will be collected.
      
                  {% endnote %}

  1. Run this command:

      ```bash
      yc audit-trails trail create --file <file_path>
      ```

  {% endcut %}

  {% cut "In the command arguments:" %}

  Use this method if your trail configuration is simple and contains few parameters.

  {% note info %}

  You can only customize the registration of [data events](../concepts/control-plane-vs-data-plane.md#data-plane-events) using the YAML specification.

  {% endnote %}

  Run this command:

  ```bash
  yc audit-trails trail create \
    --name <trail_name> \
    --description <trail_description> \
    --labels <label_list> \
    --service-account-id <service_account_ID> \
    --destination-bucket <bucket_name> \
    --destination-bucket-object-prefix <prefix_for_objects> \
    --destination-log-group-id <log_group_ID> \
    --destination-yds-stream <YDS_name> \
    --destination-yds-database-id <YDS_database_ID> \
    --destination-yds-codec <event_compression_method> \
    --destination-eventrouter-connector-id <bus_connector_ID> \
    --filter-all-folder-id <folder_ID> \
    --filter-all-cloud-id <cloud_ID> \
    --filter-all-organisation-id <organization_ID> \
    --filter-some-folder-ids <cloud_folder_list> \
    --filter-from-cloud-id <cloud_ID_with_selected_folders> \
    --filter-some-cloud-ids <list_of_clouds_in_organization> \
    --filter-from-organisation-id <organization_ID_with_selected_clouds>
    ```

    Where:
    * `--name`: Name of the new trail.

    * `--description`: Trail description. This is an optional setting.
    * `--labels`: List of [labels](../../resource-manager/concepts/labels.md). This is an optional setting. You can specify one or more labels separated by commas in `<key1>=<value1>,<key2>=<value2>` format.
    * `--service-account-id`: Service account [ID](../../iam/operations/sa/get-id.md).
    * `--destination-bucket`: [Name](../../storage/concepts/bucket.md#naming) of the Yandex Object Storage bucket you want to upload audit logs to.
    
        You cannot use this parameter together with `--destination-log-group-id`, `--destination-yds-stream`, or `--destination-eventrouter-connector-id`.
    * `--destination-bucket-object-prefix`: [Prefix](../../storage/concepts/object.md#folder) that will be assigned to the objects with audit logs in the bucket. It is an optional parameter used in the [full name](../concepts/format.md#log-file-name) of the audit log file.
    
        {% note info %}
        
        Use a [prefix](../../storage/concepts/object.md#key) to store audit logs and third-party data in the same bucket. Do not use the same prefix for logs and other bucket objects because that may cause logs and third-party objects to overwrite each other.
        
        {% endnote %}
    
    * `--destination-log-group-id`: ID of the Yandex Cloud Logging [log group](../../logging/concepts/log-group.md) the audit logs will be uploaded to.
    
        You cannot use this parameter together with `--destination-bucket`, `--destination-yds-stream`, or `--destination-eventrouter-connector-id`.
    * `--destination-yds-stream`: Name of the Yandex Data Streams [data stream](../../data-streams/concepts/glossary.md#stream-concepts) the audit logs will be uploaded to.
    
        You cannot use this parameter together with `--destination-bucket`, `--destination-log-group-id`, or `--destination-eventrouter-connector-id`.
    * `--destination-yds-database-id`: ID of the YDB database used by Data Streams.
    * `--destination-yds-codec`: Event compression method when writing to Data Streams. The possible values are `RAW` (no compression, default), `GZIP`, `ZSTD`. Enable compression if you expect an event flow greater than 1 MB/s.
    * `--destination-eventrouter-connector-id`: [Connector](../../serverless-integrations/concepts/eventrouter/connector.md) ID of the EventRouter bus with the `Audit Trails` source type to upload audit logs to.
    
        You cannot use this parameter together with `--destination-bucket`, `--destination-log-group-id`, or `--destination-yds-stream`.
    * `--filter-all-folder-id`: Folder [ID](../../resource-manager/operations/folder/get-id.md). The system will be logging management events for all resources in this folder.
    * `--filter-all-cloud-id`: Cloud [ID](../../resource-manager/operations/cloud/get-id.md). The system will be logging management events for all resources in this cloud.
    * `--filter-all-organisation-id`: Organization [ID](../../organization/operations/organization-get-id.md). The system will be logging management events for all resources in this organization.
    * `--filter-some-folder-ids`: List of folder IDs. The system will be logging management events for all resources in those folders, in the cloud specified in `--filter-from-cloud-id`.
    
        This parameter can only be used together with `--filter-from-cloud-id`.
    * `--filter-from-cloud-id`: ID of the cloud housing the folders specified in the `--filter-some-folder-ids` parameter.
    
        This parameter can only be used together with `--filter-some-folder-ids`.
    * `--filter-some-cloud-ids`: List of cloud IDs. The system will be logging management events for all resources in those clouds, in the organization specified in `--filter-from-organisation-id`.
    
        This parameter can only be used together with `--filter-from-organisation-id`.
    * `--filter-from-organisation-id`: ID of the organization housing the clouds specified under `--filter-some-folder-ids`.
    
        This parameter can only be used together with `--filter-some-cloud-ids`.

  {% endcut %}

- Terraform {#tf}

  With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
  
  Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
  
  For more information about the provider resources, see the guides on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md).

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../terraform/authentication.md) using the appropriate method.

  1. In the configuration file, describe the parameters of the trail to collect audit logs:

      ```hcl
      resource "yandex_audit_trails_trail" "basic_trail" {
        name        = "<trail_name>"
        folder_id   = "<folder_ID>"
        description = "<trail_description>"
        labels = {
          key = "value"
        }
        service_account_id = "<service_account_ID>"
      
      
        # Only one destination must be specified:
        # storage_destination , logging_destination, data_stream_destination
        # Settings for all destinations are provided for illustration purposes.
      
        logging_destination {
          log_group_id = "<log_group_ID>"
        }
        storage_destination {
          bucket_name   = "<bucket_ID>"
          object_prefix = "<prefix>"
        }
        data_stream_destination {
          database_id = "<YDS_database_ID>"
          stream_name = "<YDS_name>"
          codec       = "<event_compression_method>"
        }
      
        # Filtering policy settings
      
        filtering_policy {
          management_events_filter {
            resource_scope {
              resource_id   = "<organization_ID>"
              resource_type = "organization-manager.organization"
            }
          }  
          data_events_filter {
            service = "<service>"
            included_events = ["<service_event_type>","<service_2_event_type>"]
            resource_scope {
              resource_id   = "<cloud_ID>"
              resource_type = "resource-manager.cloud"
            }
            resource_scope {
              resource_id   = "<folder_ID>"
              resource_type = "resource-manager.folder"
            }
          }
          data_events_filter {
            service = "<service_2>"
            resource_scope {
              resource_id   = "<ID_of_cloud_2>"
              resource_type = "resource-manager.cloud"
            }
            resource_scope {
              resource_id   = "<cloud_3_ID>"
              resource_type = "resource-manager.cloud"
            }
          }
          data_events_filter {
            service = "<service_3>"
            resource_scope {
              resource_id   = "<folder_2_ID>"
              resource_type = "resource-manager.folder"
            }
            resource_scope {
              resource_id   = "<folder_3_ID>"
              resource_type = "resource-manager.folder"
            }
          }
        }
      }
      ```

      Where:

      * `name`: Name of the new trail. The naming requirements are as follows:
      
          * Length: between 3 and 63 characters.
          * It can only contain lowercase Latin letters, numbers, and hyphens.
          * It must start with a letter and cannot end with a hyphen.
      
      * `folder_id`: [ID of the folder](../../resource-manager/operations/folder/get-id.md) to create the trail in.
      * `description`: Description of the trail to distinguish it from other trails, e.g., `My very first trail`. This is an optional parameter.
      * `labels`: List of [labels](../../resource-manager/concepts/labels.md) in `key=value` format. This is an optional parameter.
      * `service_account_id`: [ID](../../iam/operations/sa/get-id.md) of the service account the trail will use to upload audit log files to the bucket.
      
          Based on the audit log [collection scope](../concepts/trail.md#collecting-area), the [service account](../../iam/concepts/users/service-accounts.md) must have the `audit-trails.viewer` [role](../../iam/concepts/access-control/roles.md) for the organization, cloud, or folder whose audit logs the trail will collect.

      {% note warning %}
      
      Only one destination must be specified: `storage_destination`, `logging_destination`, or `data_stream_destination`.
      
      {% endnote %}
      
      * `logging_destination`: Uploading logs to a Yandex Cloud Logging [group](../../logging/concepts/log-group.md).
      
          * `log_group_id`: [ID of the log group](../../logging/operations/get-group.md) for the trail to save audit logs to.
      * `storage_destination`: Uploading logs to a Yandex Object Storage [bucket](../../storage/concepts/bucket.md):
      
          * `log_group_id`: Name of the bucket for the trail to save audit logs to.
          * `object_prefix`: [Prefix](../../storage/concepts/object.md#folder) that will be assigned to the objects with audit logs in the bucket. It is an optional parameter used in the [full name](../concepts/format.md#log-file-name) of the audit log file.
      
              {% note info %}
              
              Use a [prefix](../../storage/concepts/object.md#key) to store audit logs and third-party data in the same bucket. Do not use the same prefix for logs and other bucket objects because that may cause logs and third-party objects to overwrite each other.
              
              {% endnote %}
      
      * `data_stream_destination`: Uploading logs to a [data stream](../../data-streams/concepts/glossary.md#stream-concepts) in Yandex Data Streams:
      
          * `stream_name`: Name of the data stream for the trail to save audit logs to.
          * `database_id`: ID of the Yandex Managed Service for YDB database used by Data Streams.
          * `codec`: Event compression method when writing to Data Streams. The possible values are `RAW` (no compression, default), `GZIP`, `ZSTD`. Enable compression if you expect an event flow greater than 1 MB/s.

      * `filtering_policy`: Settings of the filtering policy that determines which events to collect and include in the audit logs. The policy consists of filters pertaining to different levels of events. It contains the `management_events_filter` and `data_events_filters` objects.
      
          * `management_events_filter`: Management event filter.
          * `resource_scopes`: [Log collection scope](../concepts/trail.md#collecting-area). You can combine several scopes belonging to the same organization in one `resource_scopes` parameter. For example, you can collect logs from one entire cloud and only from particular folders in another cloud. Service account permissions must allow collecting logs from the specified scopes.
      
              * `resource_id`: ID of the resource for whose resources audit logs will be collected. Based on the audit log collection scope, specify the organization [ID](../../organization/operations/organization-get-id.md) or the cloud [ID](../../resource-manager/operations/cloud/get-id.md) in this parameter.
              * `resource_type`: Scope type according to the specified ID:
      
                  * `organization-manager.organization`: [Organization](../../organization/concepts/organization.md).
                  * `resource-manager.cloud`: [Cloud](../../resource-manager/concepts/resources-hierarchy.md#cloud).
                  * `resource-manager.folder`: [Folder](../../resource-manager/concepts/resources-hierarchy.md#folder).
          * `data_events_filters`: Data event filters. You can configure several filters of this type, one filter per service. A filter for one service has the following structure:
      
              * `service`: Name of the service in which the trail will process events. You can get it from the [data event reference](../concepts/events-data-plane.md).
              * `resource_scopes`: Places to collect data events from. You can configure this parameter the same way as the management event filter.
              * `included_events`: Collect only specified events. This is an optional parameter. If not specified, all events will be collected. To collect all events except the specified ones, replace `included_events` with `excluded_events`. These parameters are mutually exclusive.
                  You can get a full list of events from the [data event reference](../concepts/events-data-plane.md).

      For more information about the `yandex_audit_trails_trail` resource properties in Terraform, see [this provider guide](../../terraform/resources/audit_trails_trail.md).

  1. Create the resources:

      1. In the terminal, navigate to the configuration file directory.
      1. Make sure the configuration is correct using this command:
      
         ```bash
         terraform validate
         ```
      
         If the configuration is valid, you will get this message:
      
         ```bash
         Success! The configuration is valid.
         ```
      
      1. Run this command:
      
         ```bash
         terraform plan
         ```
      
         You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
      1. Apply the configuration changes:
      
         ```bash
         terraform apply
         ```
      
      1. Type `yes` and press **Enter** to confirm the changes.

      Terraform will create all the required resources. You can check the new resources and their settings either in the [management console](https://console.yandex.cloud) or using this [CLI](../../cli/index.md) command:

     ```bash
     yc audit-trails trail get <trail_name>
     ```

- API {#api}

  Use the [create](../api-ref/Trail/create.md) REST API method for the [Trail](../api-ref/Trail/index.md) resource or the [TrailService/Create](../api-ref/grpc/Trail/create.md) gRPC API call.

  To make it easier to create a trail specification, you can get existing trail parameters using the [get](../api-ref/Trail/get.md) REST API method for the [Trail](../api-ref/Trail/index.md) resource or the [TrailService/Get](../api-ref/grpc/Trail/get.md) gRPC API call.

{% endlist %}

The trail will be created and start uploading audit logs to the selected destination object.

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`.

## Examples {#examples}

### Creating a trail with management and data event filters {#example-control-data-planes}

Create a trail with the following parameters:

* `sample-trail-all-planes`: Trail name.
* `folder0***`: ID of the folder the trail will reside in.
* Destination object: Object Storage bucket named `sample-logs-bucket`.
* The service account for the trail is the account with the `service0***` ID.
* Management event filter settings:

    The log collection scope is the organization with the ID `org1***`. Logs will be collected from all clouds that belong to this organization.

* Data event filter settings:

    * For [Managed Service for PostgreSQL](../../managed-postgresql/index.md), logs will be collected from the cloud with the ID `cloud1***` and the folder with the ID `folder1***`.

        All the [events](../concepts/events-data-plane.md#mpg) of the service will be collected except for the following:

        * `yandex.cloud.audit.mdb.postgresql.CreateDatabase`
        * `yandex.cloud.audit.mdb.postgresql.UpdateDatabase`

    * For [Object Storage](../../storage/index.md), logs will be collected from the clouds with the IDs `cloud2***` and `cloud3***`.

        Only the following [events](../concepts/events-data-plane.md#objstorage) will be collected:

        * `yandex.cloud.audit.storage.ObjectCreate`
        * `yandex.cloud.audit.storage.ObjectUpdate`
        * `yandex.cloud.audit.storage.ObjectDelete`

    * For [Compute Cloud](../../compute/index.md), logs will be collected from the folders with the IDs `folder2***` and `folder3***`.

        All [service events](../concepts/events-data-plane.md#compute) of the service will be collected.

{% list tabs group=instructions %}

- CLI {#cli}

  1. Create a YAML named `sample-trail-all-planes.yaml` with the trail configuration.

      {% cut "sample-trail-all-planes.yaml" %}

      ```yaml
      name: sample-trail-all-planes
      folder_id: folder0***
      destination:
        object_storage:
          bucket_id: sample-logs-bucket
      service_account_id: service0***
      filtering_policy:
        management_events_filter:
          resource_scopes:
            - id: org1***
              type: organization-manager.organization
        data_events_filters:
          - service: mdb.postgresql
            resource_scopes:
              - id: cloud1***
                type: resource-manager.cloud
              - id: folder1***
                type: resource-manager.folder
            excluded_events:
              event_types:
              - yandex.cloud.audit.mdb.postgresql.CreateDatabase
              - yandex.cloud.audit.mdb.postgresql.UpdateDatabase
          - service: storage
            resource_scopes:
              - id: cloud2***
                type: resource-manager.cloud
              - id: cloud3***
                type: resource-manager.cloud
            included_events:
              event_types:
                - yandex.cloud.audit.storage.ObjectCreate
                - yandex.cloud.audit.storage.ObjectUpdate
                - yandex.cloud.audit.storage.ObjectDelete
          - service: compute
            resource_scopes:
              - id: folder2***
                type: resource-manager.folder
              - id: folder3***
                type: resource-manager.folder
      ```

      {% endcut %}

  1. Run this command:

      ```bash
      yc audit-trails trail create --file sample-trail-all-planes.yaml
      ```

  This will create a trail with the specified properties.

- Terraform {#tf}

  1. In the Terraform configuration file, describe the properties of the trail to create:

      ```hcl
      resource "yandex_audit_trails_trail" "basic_trail" {
        name               = "sample-trail-all-planes"
        folder_id          = "folder0***"
        service_account_id = "service0***"

        storage_destination {
          bucket_name  = "sample-logs-bucket"
        }

        filtering_policy {
          management_events_filter {
            resource_scope {
              resource_id   = "org1***"
              resource_type = "resource-manager.organization"
            }
          }  
          data_events_filter {
            service = "mdb.postgresql"
            excluded_events = ["yandex.cloud.audit.mdb.postgresql.CreateDatabase","yandex.cloud.audit.mdb.postgresql.UpdateDatabase"]
            resource_scope {
              resource_id   = "cloud1***"
              resource_type = "resource-manager.cloud"
            }
            resource_scope {
              resource_id   = "folder1***"
              resource_type = "resource-manager.folder"
            }
          }
          data_events_filter {
            service = "storage"
            resource_scope {
              resource_id   = "cloud2***"
              resource_type = "resource-manager.cloud"
            }
            resource_scope {
              resource_id   = "cloud3***"
              resource_type = "resource-manager.cloud"
            }
          }
          data_events_filter {
            service = "compute"
            resource_scope {
              resource_id   = "folder2***"
              resource_type = "resource-manager.folder"
            }
            resource_scope {
              resource_id   = "folder3***"
              resource_type = "resource-manager.folder"
            }
          }
        }
      }
     ```

  1. Create the resources:

      1. In the terminal, navigate to the configuration file directory.
      1. Make sure the configuration is correct using this command:
      
         ```bash
         terraform validate
         ```
      
         If the configuration is valid, you will get this message:
      
         ```bash
         Success! The configuration is valid.
         ```
      
      1. Run this command:
      
         ```bash
         terraform plan
         ```
      
         You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
      1. Apply the configuration changes:
      
         ```bash
         terraform apply
         ```
      
      1. Type `yes` and press **Enter** to confirm the changes.

      This will create a trail with the specified properties. You can check the new trail using the [management console](https://console.yandex.cloud) or this [CLI](../../cli/index.md) command:

      ```bash
      yc audit-trails trail get sample-trail-all-planes
      ```

- API {#api}

  Use the [create](../api-ref/Trail/create.md) REST API method for the [Trail](../api-ref/Trail/index.md) resource.

  To use the examples, install [cURL](https://curl.haxx.se).

  The example below is for MacOS and Linux. To run it on Windows, [check the details on working with Bash in Microsoft Windows](../../overview/concepts/console-syntax-guide.md).

  1. [Get](../../iam/operations/index.md#authentication) an IAM token for API [authentication](../api-ref/authentication.md).

  1. Save the token to a variable and run this command in the terminal:

      ```bash
      export IAM_TOKEN=<IAM_token>
      ```

  1. Create a file named `body.json` with the following request body and a description of the new trail:

      ```json
      {
        "folderId": "folder0**",
        "name": "sample-trail-all-planes",
        "description": "sample-trail",
        "destination": {
          "objectStorage": {
            "bucketId": "sample-logs-bucket"
          }
        },
        "serviceAccountId": "service0***",
        "filteringPolicy": {
          "managementEventsFilter": {
            "resourceScopes": [
              {
                "id": "org1***",
                "type": "resource-manager.organization"
              }
            ]
          },
          "dataEventsFilters": [
            {
              "service": "mdb.postgresql",
              "excludedEvents": {
                "eventTypes": [
                  "yandex.cloud.audit.mdb.postgresql.CreateDatabase"
                  ,"yandex.cloud.audit.mdb.postgresql.UpdateDatabase"
                ]
              },
              "resourceScopes": [
                {
                  "id": "cloud1***",
                  "type": "resource-manager.cloud"
                },
                {
                  "id": "folder1***",
                  "type": "resource-manager.folder"
                }
              ]
            },
            {
              "service": "storage",
              "resourceScopes": [
                {
                  "id": "cloud2**",
                  "type": "resource-manager.cloud"
                },
                {
                  "id": "cloud3**",
                  "type": "resource-manager.cloud"
                }
              ]
            },
            {
              "service": "compute",
              "resourceScopes": [
                {
                  "id": "folder2**",
                  "type": "resource-manager.folder"
                },
                {
                  "id": "folder3**",
                  "type": "resource-manager.folder"
                }
              ]
            }
          ]
        }
      }
      ```

  1. Run this request in your terminal:

      ```bash
      curl \
        --request POST \
        --header "Authorization: Bearer ${IAM_TOKEN}" \
        --data "@<request_body_file>" \
        https://audittrails.api.cloud.yandex.net/audit-trails/v1/trails
      ```

      Where:
      * `<request_body_file>` is the path to the previously created request body file (`body.json`).

      Result:

      ```json
      {
      "done": true,
      "metadata": {
        "@type": "type.googleapis.com/yandex.cloud.audittrails.v1.CreateTrailMetadata",
        "trailId": "cnpvprd5pa66********"
      },
      "id": "cnp9qb9g8ldb********",
      "description": "operation_create",
      "createdAt": "2025-02-20T07:06:18.547321903Z",
      "createdBy": "ajevfb0tjfts********",
      "modifiedAt": "2025-02-20T07:06:18.547321903Z"
      }
      ```

{% endlist %}


## What's next {#whats-next}

* Learn more about the [audit log format](../concepts/format.md).
* Find out about the procedure for [uploading audit logs to SIEM](../concepts/export-siem.md).
* Learn how to [search for events in audit logs](../tutorials/search-events-audit-logs/index.md).