Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Simpan dan jalankan kembali kueri CloudWatch Logs Insights
<a name="CWL_Insights-Saving-Queries"></a>

Setelah Anda membuat kueri, Anda dapat menyimpannya, dan menjalankannya lagi nanti. Kueri disimpan dalam struktur folder, sehingga Anda dapat mengaturnya. Anda dapat menyimpan sebanyak 1000 kueri per wilayah dan per akun.

Kueri disimpan pada tingkat khusus Wilayah, bukan tingkat khusus pengguna. Jika Anda membuat dan menyimpan kueri, pengguna lain yang memiliki akses ke CloudWatch Log di Wilayah yang sama dapat melihat semua kueri yang disimpan dan struktur foldernya di Wilayah.

Untuk menyimpan kueri, Anda harus masuk ke peran yang memiliki izin`logs:PutQueryDefinition`. Untuk melihat daftar kueri yang disimpan, Anda harus masuk ke peran yang memiliki izin`logs:DescribeQueryDefinitions`.

**catatan**  
Anda dapat membuat dan menyimpan kueri dengan parameter — template yang dapat digunakan kembali dengan placeholder bernama. Alih-alih menyimpan beberapa variasi kueri yang sama dengan nilai yang berbeda, buat satu templat dan berikan nilai parameter yang berbeda saat Anda menjalankannya. Fungsionalitas ini saat ini didukung untuk kueri hanya menggunakan bahasa kueri Wawasan Log. Untuk informasi selengkapnya, lihat [Menggunakan kueri tersimpan dengan parameter](#CWL_Insights-Parameterized-Queries).

------
#### [ Console ]

**Untuk menyimpan kueri**

1. Buka CloudWatch konsol di [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. Di panel navigasi, pilih **Log**, lalu pilih **Wawasan Log**.

1. Buat kueri di editor kueri.

1. Pilih **Simpan**.

1. Masukkan nama untuk kueri.

1. (Opsional) Pilih folder tempat Anda ingin menyimpan kueri. Pilih **Create new** (Buat baru) untuk membuat folder. Jika Anda membuat folder baru, Anda dapat menggunakan karakter garis miring (/) dalam nama folder untuk menentukan struktur folder. Sebagai contoh, menamai folder baru dengan **folder-level-1/folder-level-2** akan membuat folder tingkat atas yang disebut **folder-level-1**, dengan folder lain yang bernama **folder-level-2** di dalam folder itu. Kueri disimpan dalam **folder-level-2**.

1. (Opsional) Ubah grup log kueri atau teks kueri.

1. (Opsional) Untuk menggunakan parameter dalam kueri Anda, ikuti langkah-langkah tambahan ini:

   1. **Tambahkan parameter ke kueri Anda.** Ganti nilai statis dengan placeholder menggunakan `{{parameter}}` sintaks (tanda kurung ganda sebelum dan sesudah nama parameter).

      Contoh: Kueri asli dengan nilai statis:

      ```
      fields @timestamp, @message
      | filter level = "Error"
      | filter applicationName = "OrderService"
      ```

      Kueri diperbarui dengan parameter:

      ```
      fields @timestamp, @message
      | filter level = {{logLevel}}
      | filter applicationName = {{applicationName}}
      ```

   1. **Tentukan parameter yang digunakan dalam kueri Anda.** Untuk setiap parameter placeholder, tentukan:
      + **Nama**: Harus sama persis dengan nama placeholder (misalnya,`logLevel`,`applicationName`).
      + **Nilai default** (opsional): Nilai yang akan digunakan jika tidak ada nilai parameter yang disediakan.
      + **Deskripsi** (opsional): Menjelaskan tujuan parameter.

   1. Query dengan parameter dapat dijalankan dengan menggunakan nama query dengan `$` awalan dan meneruskan nama parameter sebagai pasangan kunci-nilai. Lihat **Untuk menjalankan kueri tersimpan** untuk detailnya.

1. Pilih **Simpan**.

------
#### [ AWS CLI ]

**Untuk menyimpan kueri**, gunakan`put-query-definition`:

```
aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = \"ERROR\"" \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1
```

(Opsional) Untuk menyimpan kueri dengan parameter, tambahkan `--parameters` opsi dan gunakan `{{parameterName}}` placeholder dalam string kueri:

```
aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"},{"name":"applicationName","defaultValue":"OrderService","description":"Application name to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1
```

Untuk menyimpan kueri di folder, awali nama kueri dengan jalur folder:

```
aws logs put-query-definition \
  --name "my-folder/ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1
```

------
#### [ API ]

**Untuk menyimpan kueri**, hubungi [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html):

```
{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = \"ERROR\"",
  "logGroupNames": ["/aws/lambda/my-function"]
}
```

(Opsional) Untuk menyimpan kueri dengan parameter, sertakan `parameters` bidang dan gunakan `{{parameterName}}` placeholder dalam string kueri:

```
{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}",
  "logGroupNames": ["/aws/lambda/my-function"],
  "parameters": [
    {
      "name": "logLevel",
      "defaultValue": "ERROR",
      "description": "Log level to filter"
    },
    {
      "name": "applicationName",
      "defaultValue": "OrderService",
      "description": "Application name to filter"
    }
  ]
}
```

------

**Tip**  
 Anda dapat membuat folder untuk kueri yang disimpan dengan`PutQueryDefinition`. Untuk membuat folder untuk kueri yang disimpan, gunakan garis miring (/) untuk mengawali nama kueri yang Anda inginkan dengan nama folder yang Anda inginkan:. `<folder-name>/<query-name>` Untuk informasi lebih lanjut tentang tindakan ini, lihat [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html). 

------
#### [ Console ]

**Untuk menjalankan kueri yang disimpan**

1. Buka CloudWatch konsol di [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. Di panel navigasi, pilih **Log**, lalu pilih **Wawasan Log**.

1. Di sebelah kanan, pilih **Queries** (Kueri).

1. Pilih kueri Anda dari daftar **Kueri tersimpan**. Teks kueri muncul di editor kueri.

1. (Opsional) Untuk menggunakan kueri dengan parameter:

   1. Pilih **ikon\$1di** sebelah nama kueri di panel samping **Kueri tersimpan**.

   1. Kueri dengan parameter muncul di editor kueri. Misalnya, jika Anda memilih ikon **\$1** di sebelah`ErrorsByLevel`, editor kueri diisi dengan: `$ErrorsByLevel(level=, applicationName=)`

   1. Berikan nilai untuk parameter (level, applicationName) dan jalankan kueri. Misalnya: `$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")`

1. Pilih **Jalankan**.

------
#### [ AWS CLI ]

**Untuk menjalankan kueri tersimpan dengan parameter**

Gunakan `start-query` dengan `$QueryName()` sintaks:

```
aws logs start-query \
  --log-group-names "/aws/lambda/my-function" \
  --start-time 1707566400 --end-time 1707570000 \
  --query-string '$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")' \
  --region us-east-1
```

------
#### [ API ]

**Untuk menjalankan kueri tersimpan dengan parameter**

Panggil [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)dengan `$QueryName()` sintaks di `queryString` lapangan:

```
{
  "logGroupNames": ["/aws/lambda/my-function"],
  "startTime": 1707566400,
  "endTime": 1707570000,
  "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")"
}
```

------

**Untuk menyimpan versi baru dari kueri tersimpan**

1. Buka CloudWatch konsol di [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. Di panel navigasi, pilih **Log**, lalu pilih **Wawasan Log**.

1. Di sebelah kanan, pilih **Queries** (Kueri).

1. Pilih kueri dari daftar **Saved queries** (Kueri tersimpan). Itu akan muncul di editor kueri.

1. Modifikasi kueri. Jika Anda perlu menjalankannya untuk memeriksa pekerjaan Anda, pilih **Run query** (Jalankan kueri).

1. Saat Anda siap untuk menyimpan versi baru, pilih **Actions** (Tindakan), **Save as** (Simpan sebagai).

1. Masukkan nama untuk kueri.

1. (Opsional) Pilih folder tempat Anda ingin menyimpan kueri. Pilih **Create new** (Buat baru) untuk membuat folder. Jika Anda membuat folder baru, Anda dapat menggunakan karakter garis miring (/) dalam nama folder untuk menentukan struktur folder. Sebagai contoh, menamai folder baru dengan **folder-level-1/folder-level-2** akan membuat folder tingkat atas yang disebut **folder-level-1**, dengan folder lain yang bernama **folder-level-2** di dalam folder itu. Kueri disimpan dalam **folder-level-2**.

1. (Opsional) Ubah grup log kueri atau teks kueri.

1. Pilih **Simpan**.

Untuk menghapus kueri, Anda harus masuk ke peran yang memiliki izin `logs:DeleteQueryDefinition`.

**Untuk mengedit atau menghapus kueri tersimpan**

1. Buka CloudWatch konsol di [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. Di panel navigasi, pilih **Log**, lalu pilih **Wawasan Log**.

1. Di sebelah kanan, pilih **Queries** (Kueri).

1. Pilih kueri dari daftar **Saved queries** (Kueri tersimpan). Itu akan muncul di editor kueri.

1. Pilih **Actions** (Tindakan), **Edit** atau **Actions** (Tindakan), **Delete** (Hapus).

## Menggunakan kueri yang disimpan dengan parameter
<a name="CWL_Insights-Parameterized-Queries"></a>

Kueri tersimpan dengan parameter adalah templat kueri yang dapat digunakan kembali dengan placeholder bernama. Alih-alih mempertahankan beberapa salinan kueri yang hampir identik, Anda dapat menyimpan template dan memberikan nilai parameter yang berbeda saat menjalankan kueri. Parameter hanya didukung dalam bahasa kueri Wawasan CloudWatch Log.

 **Cara kerjanya** 

Saat menyimpan kueri, placeholder mengidentifikasi nilai yang dapat Anda berikan pada waktu eksekusi kueri. Placeholder menggunakan sintaks. `{{parameterName}}` Berikut ini adalah contoh dari query tersimpan bernama `ErrorsByLevel` dengan dua parameter `logLevel` dan`applicationName`.

```
fields @timestamp, @message
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}
```

Untuk menjalankan kueri tersimpan, Anda dapat memanggilnya menggunakan nama kueri yang diawali dengan `$` dan meneruskan nilai parameter. Mesin kueri CloudWatch Logs Insights menggantikan setiap placeholder. Jika parameter berisi nilai default, maka nilai-nilai tersebut digunakan jika tidak ada nilai lain yang disediakan.

```
# Run query by using query name and passing parameter values explicitly
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")

# Run query without specifying parameter values - default values are used in this case.
$ErrorsByLevel()
```

Nama kueri tersimpan yang berisi spasi atau karakter khusus harus diapit dengan backticks:

```
$`Errors By Level`(logLevel = "WARN")
```

### Contoh kueri yang disimpan dengan parameter
<a name="CWL_Insights-Parameterized-Queries-Examples"></a>

 **Menambahkan batas hasil sebagai parameter** 

Nama kueri: `ErrorsByLevel` dengan parameter `logLevel` (default:`"ERROR"`), `applicationName` (default:`"OrderService"`), dan `maxResults` (default:`50`)

```
fields @timestamp, @message, @logStream
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}
| sort @timestamp desc
| limit {{maxResults}}
```

```
# Run the query using the query name and passing parameter values
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService", maxResults = 100)
```

 **Menggunakan beberapa kueri tersimpan dengan parameter** 

 Contoh di bawah ini menggunakan `ErrorsByLevel` dan kueri tersimpan kedua `RecentN` yang didefinisikan sebagai `sort @timestamp desc | limit {{count}}` (dengan parameter`count`, default`20`). Mesin kueri CloudWatch Logs Insights memperluas setiap kueri sebelum menjalankannya.

```
# Using multiple queries with parameters in sequence
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")
| $RecentN(count = 10)

# Each of the queries is expanded, resulting in the following query when it is run.
fields @timestamp, @message
| filter level = "WARN"
| filter applicationName = "OrderService"
| sort @timestamp desc
| limit 10
```

### Kuota dan penanganan kesalahan
<a name="CWL_Insights-Parameterized-Queries-Quotas"></a>

**catatan**  
Setiap kueri yang disimpan dapat memiliki maksimum 20 parameter.

String kueri yang diperluas tidak dapat melebihi 10.000 karakter. Nama parameter harus dimulai dengan huruf atau garis bawah. Kueri tersimpan tidak dapat mereferensikan kueri lain yang disimpan (pemanggilan bersarang tidak didukung).


**Kesalahan umum**  

| Kesalahan | Penyebab | 
| --- | --- | 
| Parameter hanya didukung untuk bahasa kueri CWLI | Parameter hanya didukung dalam bahasa kueri Wawasan CloudWatch Log. | 
| Parameter yang diperlukan tidak ditemukan di QueryString | Nama parameter di `--parameters` tidak memiliki pencocokan `{{placeholder}}` dalam string kueri. | 
| Jumlah parameter melebihi maksimum 20 | Kueri yang disimpan saat ini hanya mendukung 20 parameter. | 
| Nama parameter duplikat | Definisi kueri memiliki parameter duplikat di`parameters`. | 

**catatan**  
Untuk membuat atau memperbarui kueri yang disimpan dengan parameter, Anda memerlukan `logs:PutQueryDefinition` izin. Untuk menjalankannya, Anda perlu `logs:StartQuery` dan`logs:DescribeQueryDefinitions`.