Menyerap data dengan sink Serilog ke Azure Data Explorer

Serilog adalah kerangka kerja pengelogan populer untuk aplikasi .NET. Serilog memungkinkan pengembang untuk mengontrol pernyataan log mana yang dihasilkan dengan granularitas sewenang-wenang berdasarkan nama pencatat, tingkat pencatat, dan pola pesan. Sink Serilog, juga dikenal sebagai appender, mengalirkan data log Anda ke tabel Anda, di mana Anda dapat menganalisis dan memvisualisasikan log Anda secara real time.

Artikel ini memperlihatkan cara menyerap data dengan Serilog.

Untuk daftar lengkap konektor data, lihat Gambaran umum integrasi data.

Prasyarat

.NET SDK 6.0 atau yang lebih baru
Kluster dan database Azure Data Explorer dengan kebijakan cache dan retensi default
Lingkungan kueri Azure Data Explorer
URI kluster Kusto Anda untuk nilai TargetURI dalam format https://ingest-<kluster>.<region>.kusto.windows.net. Untuk informasi selengkapnya, lihat Tambahkan koneksi kluster.

Otentikasi

Autentikasi Microsoft Entra digunakan untuk aplikasi yang perlu mengakses tabel database KQL Anda tanpa ada pengguna. Untuk menyerap data menggunakan konektor Serilog, Anda dapat menggunakan salah satu metode autentikasi berikut:

Prinsipal layanan Microsoft Entra adalah identitas keamanan yang digunakan oleh aplikasi untuk mengakses sumber daya Azure tertentu. Identitas ini digunakan untuk mengautentikasi konektor ke database KQL Anda menggunakan ID klien dan kata sandi, dan dapat digunakan untuk aplikasi yang berjalan di luar Azure.
Identitas terkelola digunakan untuk mengautentikasi konektor ke database KQL Anda menggunakan ID klien. Identitas terkelola digunakan untuk aplikasi yang berjalan dalam Azure.

Autentikasi Microsoft Entra service principal
Autentikasi Identitas Terkelola

Membuat perwakilan layanan Microsoft Entra

Buat prinsipal layanan Microsoft Entra lalu otorisasi prinsipal layanan ini sebagai identitas yang digunakan oleh konektor untuk mengirim data ke database KQL Anda.

Perwakilan layanan Microsoft Entra dapat dibuat melalui portal Azure atau secara terprogram, seperti dalam contoh berikut.

Anda nantinya akan memberikan izin bagi perwakilan layanan ini untuk mengakses sumber daya Kusto.

Masuk ke langganan Azure Anda melalui Azure CLI. Kemudian autentikasi di browser.
```
az login
```
Pilih langganan untuk menghosting komponen utama. Langkah ini diperlukan saat Anda memiliki beberapa langganan.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```

Buat entitas layanan. Dalam contoh ini, perwakilan layanan disebut my-service-principal.

az ad sp create-for-rbac -n "my-service-principal" --role Contributor --scopes /subscriptions/{SubID}

Dari data JSON yang dikembalikan, salin appId, password, dan tenant untuk penggunaan di masa mendatang.

{
  "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "displayName": "my-service-principal",
  "name": "my-service-principal",
  "password": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "tenant": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

Anda telah membuat aplikasi Microsoft Entra dan prinsipal layanan Anda.

Buat identitas terkelola

Buat identitas terkelola dan otorisasi identitas tersebut sebagai identitas yang digunakan oleh konektor untuk memasukkan data ke dalam database KQL Anda. Untuk informasi selengkapnya tentang membuat Identitas Terkelola, lihat Mengelola identitas terkelola yang ditetapkan pengguna.

Masuk ke langganan Azure Anda melalui Azure CLI. Kemudian autentikasi di browser.
```
az login
```
Pilih langganan untuk menghosting identitas terkelola. Langkah ini diperlukan saat Anda memiliki beberapa langganan.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
Membuat managed identity yang dikelola dan ditetapkan oleh pengguna. Dalam contoh ini, identitas terkelola disebut my-managed-identity.
```
az identity create --name "my-managed-identity" --resource-group "my-resource-group"
```
Tetapkan peran Kontributor untuk cakupan langganan di identitas terkelola. Dalam contoh ini, identitas terkelola disebut my-managed-identity.
```
az role assignment create --role "Contributor" --assignee "<clientId>" --scope /subscriptions/YOUR_SUBSCRIPTION_GUID
```

Dari data JSON yang dikembalikan, salin clientId untuk digunakan di masa mendatang. JSON memiliki format berikut:

{
  "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "id": "/subscriptions/00001111-aaaa-2222-bbbb-3333cccc4444/resourceGroups/my-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/my-managed-identity",
  "location": "eastus",
  "name": "my-managed-identity",
  "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
  "resourceGroup": "my-resource-group",
  "tags": {},
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Anda telah membuat identitas terkelola yang ditetapkan oleh pengguna.

Membuat tabel target dan pemetaan penyerapan

Buat tabel target untuk data masuk dan pemetaan penyerapan untuk memetakan kolom data yang diserap ke kolom dalam tabel target. Dalam langkah-langkah berikut, skema tabel dan pemetaan sesuai dengan data yang dikirim dari aplikasi sampel.

Jalankan perintah pembuatan tabel berikut di editor kueri Anda, ganti TableName dengan nama tabel target:

.create table <TableName> (Timestamp: datetime, Level: string, Message: string, Exception: string, Properties: dynamic, Position: dynamic, Elapsed: int)

Jalankan perintah .create ingestion mapping berikut, ganti TableName pengganti dengan nama tabel target dan TableNameMapping dengan nama pemetaan penyerapan:

.create table <TableName> ingestion csv mapping '<TableNameMapping>' '[{"Name":"Timestamp","DataType":"","Ordinal":"0","ConstValue":null},{"Name":"Level","DataType":"","Ordinal":"1","ConstValue":null},{"Name":"Message","DataType":"","Ordinal":"2","ConstValue":null},{"Name":"Exception","DataType":"","Ordinal":"3","ConstValue":null},{"Name":"Properties","DataType":"","Ordinal":"4","ConstValue":null},{"Name":"Position","DataType":"","Ordinal":"5","ConstValue":null},{"Name":"Elapsed","DataType":"","Ordinal":"6","ConstValue":null}]'

Berikan izin peran ingestor database kepada perwakilan layanan dari Membuat perwakilan layanan Microsoft Entra untuk bekerja dengan database. Untuk informasi selengkapnya, lihat Contoh. Ganti tempat penampung DatabaseName dengan nama database target dan ApplicationID dengan nilai yang AppId Anda simpan saat membuat perwakilan layanan Microsoft Entra.
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'
```

Menggunakan Serilog di aplikasi ASP.NET Core Anda

Bagian ini menjelaskan cara mengintegrasikan Serilog ke dalam aplikasi ASP.NET Core Anda untuk mencatat data dan mengirimkannya ke tabel KQL Anda.

Menginstal paket

Tambahkan paket pustaka Serilog.Sinks.AzureDataExplorer NuGet. Gunakan perintah Install-Package yang menentukan nama paket NuGet.

Install-Package Serilog.Sinks.AzureDataExplorer

Menambahkan sink Serilog ke aplikasi Anda

Gunakan langkah-langkah berikut untuk:

Tambahkan sink Serilog ke aplikasi Anda.
Konfigurasikan variabel yang digunakan oleh penyerap data.
Buat dan jalankan aplikasi.

Tambahkan kode berikut ke aplikasi Anda:
```
using Serilog.Sinks.AzureDataExplorer;
```

Konfigurasikan sink Serilog, ganti tempat penampung menggunakan informasi dalam tabel berikut:

Autentikasi Microsoft Entra service principal
Autentikasi Identitas Terkelola

Untuk autentikasi perwakilan layanan Microsoft Entra, gunakan kode berikut:

var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(new AzureDataExplorerSinkOptions
{
    IngestionEndpointUri = "<TargetURI>",
    DatabaseName = "<MyDatabase>",
    TableName = "<MyTable>",
    BufferBaseFileName = "<BufferBaseFileName>"
})
.CreateLogger();

Untuk autentikasi Identitas Terkelola, gunakan kode berikut:

var log = new LoggerConfiguration()
.WriteTo.AzureDataExplorerSink(
    new AzureDataExplorerSinkOptions
            {
                IngestionEndpointUri = "<TargetURI>",
                DatabaseName = "<MyDatabase>",
                TableName = "<MyTable>",
                BufferBaseFileName = "<BufferBaseFileName>"
            }).WithAadUserAssignedManagedIdentity("<ManagedIdentityClientId>")
.CreateLogger();

Gunakan tabel di bawah ini untuk mengatur nilai untuk opsi sink:

Variabel	Deskripsi
`IngestionEndPointUri`	URI penyerapan.
`DatabaseName`	Nama peka huruf besar/kecil dari database target.
`TableName`	Nama peka huruf besar/kecil dari tabel target yang ada. Misalnya, SerilogTest adalah nama tabel yang dibuat di Membuat tabel target dan pemetaan penyerapan.
`AppId`	ID Klien Aplikasi yang diperlukan untuk autentikasi principal layanan Microsoft Entra. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
`AppKey`	Kunci aplikasi yang diperlukan untuk otentikasi principal layanan Microsoft Entra. Anda menyimpan nilai ini sebagai `password` dalam Membuat prinsipal layanan Microsoft Entra.
`Tenant`	ID penyewa di mana aplikasi terdaftar pada saat menggunakan otentikasi prinsipal layanan Microsoft Entra. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
`BufferBaseFileName`	Nama file dasar opsional untuk file buffer. Atur nilai ini jika Anda memerlukan log Anda agar tahan terhadap kehilangan data yang disebabkan oleh kegagalan koneksi ke kluster Anda. Contohnya,`C:/Temp/Serilog`.
`ManagedIdentityClientId`	ID klien identitas terkelola yang ditetapkan pengguna, saat menggunakan autentikasi Identitas Terkelola.

Untuk opsi lebih lanjut, lihat Opsi Sink.

Kirim data ke database Anda menggunakan sink Serilog. Contohnya:

log.Verbose("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
log.Information("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
log.Warning("Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
log.Error(new Exception(), "Processed {@Position} in {Elapsed:000} ms.", position, elapsedMs);
log.Debug("Processed {@Position} in {Elapsed:000} ms. ", position, elapsedMs);

Buat dan jalankan aplikasi. Misalnya, jika Anda menggunakan Visual Studio, tekan F5.
Verifikasi bahwa data ada di tabel Anda. Jalankan kueri berikut dengan menggantikan placeholder dengan nama tabel yang dibuat di langkah sebelumnya.
```
<TableName>
| take 10
```

Menjalankan contoh aplikasi

Jika Anda tidak memiliki data Anda sendiri untuk diuji, Anda dapat menggunakan aplikasi generator log sampel dengan data sampel untuk menguji konfigurasi dan penggunaan sink Serilog.

Kloning repositori git dari Serilog sink menggunakan perintah git berikut:
```
git clone https://github.com/Azure/serilog-sinks-azuredataexplorer
```

Atur variabel lingkungan berikut untuk mengonfigurasi sink Serilog:

Variabel	Deskripsi
`IngestionEndPointUri`	URI penyerapan.
`DatabaseName`	Nama peka huruf besar/kecil dari database target.
`TableName`	Nama peka huruf besar/kecil dari tabel target yang ada. Misalnya, SerilogTest adalah nama tabel yang dibuat di Membuat tabel target dan pemetaan penyerapan.
`AppId`	ID aplikasi klien diperlukan untuk otentikasi prinsipal layanan Microsoft Entra. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
`AppKey`	Diperlukan kunci aplikasi untuk autentikasi prinsipal layanan Microsoft Entra. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
`Tenant`	ID penyewa di mana aplikasi terdaftar pada saat menggunakan otentikasi prinsipal layanan Microsoft Entra. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
`BufferBaseFileName`	Nama file dasar untuk file buffer. Atur nilai ini jika Anda memerlukan log Anda agar tahan terhadap kehilangan data yang disebabkan oleh kegagalan koneksi ke kluster Anda. Misalnya: `C:/Temp/Serilog`
`ManagedIdentityClientId`	ID klien identitas terkelola yang ditetapkan pengguna, saat menggunakan autentikasi Identitas Terkelola.

Anda dapat mengatur variabel lingkungan secara manual atau menggunakan perintah berikut:

Windows
Mac/Linux

$env:ingestionURI="<ingestionURI>"
$env:appId="<appId>"
$env:appKey="<appKey>"
$env:tenant="<tenant>"
$env:databaseName="<databaseName>"
$env:tableName="<tableName>"
$env:managedIdentityClientId="<managedIdentityClientId>"

export ingestionURI="<ingestionURI>"
export appId="<appId>"
export appKey="<appKey>"
export tenant="<tenant>"
export databaseName="<databaseName>"
export tableName="<tableName>"
export managedIdentityClientId="<managedIdentityClientId>"

Di terminal Anda, telusuri ke folder akar repositori kloning dan jalankan perintah .NET berikut untuk membangun aplikasi:
```
dotnet build src
```
Di terminal Anda, telusuri ke folder sampel dan jalankan perintah .NET berikut untuk menjalankan aplikasi:
```
dotnet build run
```

Di lingkungan kueri, pilih database target, dan jalankan kueri berikut untuk menjelajahi data yang sudah dimasukkan, mengganti TableName dengan nama tabel target.
```
<TableName>
| take 10
```
Output Anda akan terlihat mirip dengan gambar berikut:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-02-25