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

# Drafting a trail specification

You can [create](#spec-for-create) and [edit](#spec-for-update) trails via the [CLI](../../cli/index.md) using YAML specifications. To create a new trail, create a specification from the `get` command output of a similar trail. To edit an existing trail, proceed based on the `get` command output of the same trail.

{% note tip %}

To create and manage multiple trails, use [Terraform](../tf-ref.md).

{% endnote %}

## Drafting a specification for a trail {#spec-for-create}

{% list tabs group=instructions %}

- CLI {#cli}

  1. [Get](get-info.md) information about the trail you want to edit or use as the basis for a new one:

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

      Result:

      ```text
      id: cnpmhbf7gsq3********
      folder_id: b1g681qpemb4********
      created_at: "2026-02-13T20:32:52.357Z"
      updated_at: "2026-02-13T20:32:52.357Z"
      name: create-me
      destination:
        object_storage:
          bucket_id: recreate-trails
      service_account_id: ajelprpohp7r********
      status: ACTIVE
      cloud_id: b1gia87mbaom********
      filtering_policy:
        management_events_filter:
          resource_scopes:
            - id: b1g681qpemb4********
              type: resource-manager.folder
        data_events_filters:
          - service: compute
            resource_scopes:
              - id: b1g681qpemb4********
                type: resource-manager.folder
      ```

  1. Save the information you got into a file, e.g., `my-trail-spec.yaml`.
  1. When editing a trail, rename the `id` field to `trail_id`.
  1. Delete these fields:
      * `folder_id` (only when editing a trail)
      * `created_at`
      * `updated_at`
      * `status`
      * `cloud_id`

  1. Optionally, delete obsolete sections, if any:
      * `filter`
      * `path_filter`
      * `event_filter`

  1. Edit relevant trail parameters.

      {% cut "Description of trail parameters" %}

      ```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`: [Bucket](../../storage/concepts/bucket.md#naming) name.
      
                  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).
      
              Specify the log group ID in the `log_group_id` parameter. 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`: Stream name. 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).
      * `service_account_id`: Service account [ID](../../iam/operations/sa/get-id.md).

      * `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 %}

      {% endcut %}

  1. Save the changes to the file.

{% endlist %}