Menyerap data dengan sink Serilog ke Azure Data Explorer

Artikel
07/21/2024

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 kluster> formathttps://ingest-<.<region.kusto.windows.net>. Untuk informasi selengkapnya, lihat Menambahkan koneksi kluster.

Membuat perwakilan layanan Microsoft Entra

Autentikasi aplikasi Microsoft Entra digunakan untuk aplikasi yang perlu mengakses tabel database KQL Anda tanpa ada pengguna. Untuk menyerap data menggunakan konektor Serilog, Anda perlu membuat dan mendaftarkan perwakilan layanan Microsoft Entra, lalu mengotorisasi perwakilan ini sebagai identitas yang digunakan oleh konektor untuk menyerap 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 perwakilan. Langkah ini diperlukan saat Anda memiliki beberapa langganan.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```

Buat perwakilan 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 perwakilan layanan Anda.

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 tempat penampung dengan nama tabel target:

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

Jalankan perintah pemetaan penyerapan .create berikut, ganti tableName tempat penampung 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 perwakilan layanan dari Membuat izin peran ingestor database utama 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.

Pasang 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 sink.
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:

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

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 diperlukan untuk autentikasi. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
AppKey	Kunci aplikasi diperlukan untuk autentikasi. Anda menyimpan nilai ini seperti `password` dalam Membuat perwakilan layanan Microsoft Entra.
Penyewa	ID penyewa tempat aplikasi terdaftar. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
BufferBaseFileName	Nama file dasar opsional untuk file buffer. Atur nilai ini jika Anda mengharuskan log Anda tahan lama terhadap kehilangan yang mengakibatkan kegagalan koneksi ke kluster Anda. Contohnya,`C:/Temp/Serilog`.

Untuk opsi lainnya, 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 mengganti tempat penampung 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 sink Serilog 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 klien aplikasi diperlukan untuk autentikasi. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
AppKey	Kunci aplikasi diperlukan untuk autentikasi. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
Penyewa	ID penyewa tempat aplikasi terdaftar. Anda menyimpan nilai ini di Membuat perwakilan layanan Microsoft Entra.
BufferBaseFileName	Nama file dasar untuk file buffer. Atur nilai ini jika Anda mengharuskan log Anda tahan lama terhadap kehilangan yang mengakibatkan kegagalan koneksi ke kluster Anda. Misalnya: `C:/Temp/Serilog`

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

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

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 diserap, mengganti tableName tempat penampung dengan nama tabel target:
```
<TableName>
| take 10
```
Output Anda akan terlihat mirip dengan gambar berikut:

Bagikan melalui

Menyerap data dengan sink Serilog ke Azure Data Explorer

Prasyarat

Membuat perwakilan layanan Microsoft Entra

Membuat tabel target dan pemetaan penyerapan

Menggunakan Serilog di aplikasi ASP.NET Core Anda

Pasang paket

Menambahkan sink Serilog ke aplikasi Anda

Menjalankan contoh aplikasi

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Menyerap data dengan sink Serilog ke Azure Data Explorer

Prasyarat

Membuat perwakilan layanan Microsoft Entra

Membuat tabel target dan pemetaan penyerapan

Menggunakan Serilog di aplikasi ASP.NET Core Anda

Pasang paket

Menambahkan sink Serilog ke aplikasi Anda

Menjalankan contoh aplikasi

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: