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

# Managing a trail


You can update the [destination object](../concepts/trail.md#target), event [types](../concepts/control-plane-vs-data-plane.md) to collect, audit log [collection scopes](../concepts/trail.md#collecting-area), and [other trail settings](../concepts/trail.md#trail-settings), as well as [delete](#delete-trail) the trail.

## Updating a trail {#update-trail}

{% list tabs group=instructions %}

- Management console {#console}

  To update a trail:

  1. In the [management console](https://console.yandex.cloud), select the [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) containing the trail.
  1. Navigate to **Audit Trails**.
  1. In the row with the trail you need, click ![image](../../_assets/console-icons/ellipsis.svg) and select ![pencil](../../_assets/console-icons/pencil.svg) **Edit**.
  1. Edit the trail settings. For a list of trail settings you can edit, see [Trail settings](../concepts/trail.md#trail-settings).
  1. Click **Save**.

- 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 editing command for details about the arguments you can use:

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

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

  {% cut "In the YAML specification" %}

  Create a YAML specification containing the updated trail parameters and specify this file in the command for creating the trail.
  
  This method simplifies working with trail parameters and reduces the probability of error. 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 specification](prepare-spec.md#spec-for-update) with an updated trail configuration.
  1. To update a trail, run this command:

      ```bash
      yc audit-trails trail update --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 %}

  To update a trail, run this command:

  ```bash
  yc audit-trails trail update \
    --name <trail_name> \
    --new-name <new_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> \
    --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 trail you need to update. Instead of a name, you can provide the trail ID in the `--id` parameter.
    * `--new-name`: New trail name. The name must be unique within the folder. This is an optional setting.

    * `--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. To update a trail created with Terraform, open the Terraform configuration file and update the trail description fragment:

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

  To update a trail, use the [update](../api-ref/Trail/update.md) REST API method for the [Trail](../api-ref/Trail/index.md) resource or the [TrailService/Update](../api-ref/grpc/Trail/update.md) gRPC API call.

  To make it easier to create a trail specification, you can get 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 %}

## Deleting a trail {#delete-trail}

{% list tabs group=instructions %}

- Management console {#console}

  To delete a trail:

  1. In the [management console](https://console.yandex.cloud), select the [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) containing the trail.
  1. Navigate to **Audit Trails**.
  1. In the row with the trail you need, click ![image](../../_assets/console-icons/ellipsis.svg) and select ![trash-bin](../../_assets/console-icons/trash-bin.svg) **Delete**.
  1. In the window that opens, confirm the deletion.

- CLI {#cli}

  To delete a trail, run this command:

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

  To find out the names and IDs of available trails, use [this tutorial](get-list.md).

- Terraform {#tf}

  To delete a trail created using Terraform:

  1. Open the Terraform configuration file and delete the trail description section.

      Example of a trail description in a Terraform configuration:

      ```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"
            }
          }
        }
      }
      ```

  1. In the command line, navigate to the directory with the Terraform configuration file.
  1. Check the configuration 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.
  1. To make sure the trail has been deleted, use [this tutorial](get-list.md).

- API {#api}

  To delete a trail, use the [delete](../api-ref/Trail/delete.md) REST API method for the [Trail](../api-ref/Trail/index.md) resource or the [TrailService/Delete](../api-ref/grpc/Trail/delete.md) gRPC API call.

{% endlist %}