Gegevens opnemen met de Serilog-sink in Azure Data Explorer

Serilog is een populair framework voor logboekregistratie voor .NET-toepassingen. Met Serilog kunnen ontwikkelaars bepalen welke logboekinstructies worden uitgevoerd met willekeurige granulariteit op basis van de naam, het logboekniveau en het berichtpatroon van de logger. De Serilog-sink, ook wel een toevoeger genoemd, streamt uw logboekgegevens naar uw tabel, waar u uw logboeken in realtime kunt analyseren en visualiseren.

In dit artikel wordt beschreven hoe u gegevens opneemt met Serilog.

Zie het overzicht van gegevensintegraties voor een volledige lijst met gegevensconnectors.

Vereiste voorwaarden

.NET SDK 6.0 of hoger
Een Azure Data Explorer-cluster en -database met het standaardcache- en bewaarbeleid.
Azure Data Explorer-queryomgeving
Uw Kusto-cluster-URI voor de TargetURI-waarde in het formaat https://ingest-<cluster>.<region>.kusto.windows.net. Zie Een clusterverbinding toevoegenvoor meer informatie.

Authenticatie

Microsoft Entra-verificatie wordt gebruikt voor toepassingen die toegang nodig hebben tot uw KQL-databasetabel zonder dat een gebruiker aanwezig is. Als u gegevens wilt opnemen met behulp van de Serilog-connector, kunt u een van de volgende verificatiemethoden gebruiken:

Een Microsoft Entra-service-principal is een beveiligingsidentiteit die door toepassingen wordt gebruikt voor toegang tot specifieke Azure-resources. Deze identiteit wordt gebruikt om de connector te verifiëren bij uw KQL-database met behulp van een client-id en -wachtwoord en kan worden gebruikt voor toepassingen die buiten Azure worden uitgevoerd.
Een beheerde identiteit wordt gebruikt om de connector te verifiëren bij uw KQL-database met behulp van een client-id. Beheerde identiteiten worden gebruikt voor toepassingen die worden uitgevoerd in Azure.

Authenticatie van de serviceprincipal van Microsoft Entra
beheerde identiteitverificatie

Een Microsoft Entra-service-principal maken

Maak een Microsoft Entra-service-principal en autoriseer vervolgens deze principal als de identiteit die door de connector wordt gebruikt om gegevens op te nemen in uw KQL-database.

De Microsoft Entra-service-principal kan worden gemaakt via de Azure portal of via een programma, zoals in het volgende voorbeeld.

U zult later machtigingen verlenen aan deze serviceprincipal voor toegang tot Kusto-resources.

Meld u aan bij uw Azure-abonnement via Azure CLI. Verifieer vervolgens in de browser.
```
az login
```
Kies het abonnement om de hoofdgebruiker te hosten. Deze stap is nodig wanneer u meerdere abonnementen hebt.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```

Maak de service-principal. In dit voorbeeld wordt de service-principal genoemd my-service-principal.

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

Kopieer vanuit de geretourneerde JSON-gegevens de appId, passworden tenant voor toekomstig gebruik.

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

U hebt uw Microsoft Entra-toepassing en service-principal gemaakt.

Een beheerde identiteit maken

Maak een beheerde identiteit en autoriseer deze als de identiteit die door de connector wordt gebruikt om gegevens naar uw KQL-database op te nemen. Zie Door de gebruiker toegewezen beheerde identiteiten beheren voor meer informatie over het maken van een beheerde identiteit.

Meld u aan bij uw Azure-abonnement via Azure CLI. Verifieer vervolgens in de browser.
```
az login
```
Kies het abonnement om de beheerde identiteit te hosten. Deze stap is nodig wanneer u meerdere abonnementen hebt.
```
az account set --subscription YOUR_SUBSCRIPTION_GUID
```
Maak een door de gebruiker toegewezen beheerde identiteit. In dit voorbeeld wordt de beheerde identiteit aangeroepen my-managed-identity.
```
az identity create --name "my-managed-identity" --resource-group "my-resource-group"
```
Wijs de rol Inzender voor het abonnementsbereik toe aan de beheerde identiteit. In dit voorbeeld wordt de beheerde identiteit aangeroepen my-managed-identity.
```
az role assignment create --role "Contributor" --assignee "<clientId>" --scope /subscriptions/YOUR_SUBSCRIPTION_GUID
```

Kopieer vanuit de geretourneerde JSON-gegevens het clientId voor toekomstig gebruik. De JSON heeft de volgende indeling:

{
  "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": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "resourceGroup": "my-resource-group",
  "tags": {},
  "tenantId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

U hebt uw door de gebruiker toegewezen beheerde identiteit gemaakt.

Een doeltabel en gegevensinlaadtoewijzing maken

Maak een doeltabel voor de binnenkomende gegevens en een invoertoewijzing om de ingevoerde gegevenskolommen te koppelen aan de kolommen in de doeltabel. In de volgende stappen zijn het tabelschema en de toewijzing afgestemd op de gegevens die vanuit de voorbeeld-app zijn verzonden.

Voer de volgende opdracht voor het maken van de tabel uit in de query-editor, waarbij u de tijdelijke aanduiding TableName vervangt door de naam van de doeltabel:
```
.create table <TableName> (Timestamp: datetime, Level: string, Message: string, Exception: string, Properties: dynamic, Position: dynamic, Elapsed: int)
```

Voer de volgende opdracht voor het maken van opnametoewijzing uit, waarbij u de tijdelijke aanduidingen TableName vervangt door de naam van de doeltabel en TableNameMapping door de naam van de opnametoewijzing:

.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}]'

Verleen de service-principal van Een Microsoft Entra-service-principal maken database-ingestor rolrechten om met de database te werken. Zie Voorbeeldenvoor meer informatie. Vervang de tijdelijke aanduiding DatabaseName door de naam van de doeldatabase en ApplicationID- door de AppId waarde die u hebt opgeslagen bij het maken van een Microsoft Entra-service-principal.
```
.add database <DatabaseName> ingestors ('aadapp=<ApplicationID>') 'App Registration'
```

Serilog gebruiken in uw ASP.NET Core-toepassing

In deze sectie wordt uitgelegd hoe u Serilog integreert in uw ASP.NET Core-toepassing om gegevens te registreren en naar uw KQL-tabel te verzenden.

Installeer het pakket

Voeg het NuGet-bibliotheekpakket Serilog.Sinks.AzureDataExplorer toe. Gebruik de opdracht Install-Package die de naam van het NuGet-pakket opgeeft.

Install-Package Serilog.Sinks.AzureDataExplorer

De Serilog-sink toevoegen aan uw app

Voer de volgende stappen uit om:

Voeg de Serilog-sink toe aan uw app.
Configureer de variabelen die door de sink worden gebruikt.
Bouw en voer de app uit.

Voeg de volgende code toe aan uw app:
```
using Serilog.Sinks.AzureDataExplorer;
```

Configureer de Serilog-sink en vervang tijdelijke aanduidingen door de informatie in de volgende tabel te gebruiken:

Authenticatie van de serviceprincipal van Microsoft Entra
beheerde identiteitverificatie

Gebruik de volgende code voor authenticatie van de Microsoft Entra-service-principal:

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

Gebruik voor verificatie van beheerde identiteit de volgende code:

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

Gebruik de onderstaande tabel om de waarden voor de afvoeropties in te stellen.

Veranderlijk	Beschrijving
`IngestionEndPointUri`	De opname-URI.
`DatabaseName`	De hoofdlettergevoelige naam van de doeldatabase.
`TableName`	De hoofdlettergevoelige naam van een bestaande doeltabel. SerilogTest is bijvoorbeeld de naam van de tabel die is gemaakt in Een doeltabel maken en opnametoewijzing.
`AppId`	De toepassing client-id die vereist is voor authenticatie van de Microsoft Entra service-principal. U hebt deze waarde opgeslagen in Een Microsoft Entra-service-principal maken.
`AppKey`	De toepassingssleutel die is vereist voor verificatie van de Microsoft Entra-service-principal. U hebt deze waarde opgeslagen als `password` in Een Microsoft Entra-service-principal maken.
`Tenant`	De ID van de tenant waarin de toepassing is geregistreerd, bij het gebruik van verificatie van de service-principal van Microsoft Entra. U hebt deze waarde opgeslagen in Een Microsoft Entra-service-principal maken.
`BufferBaseFileName`	Optionele basisbestandsnaam voor het bufferbestand. Stel deze waarde in als u wilt dat uw logboeken duurzaam zijn tegen verlies als gevolg van storingen in uw cluster. Bijvoorbeeld: `C:/Temp/Serilog`.
`ManagedIdentityClientId`	De client-id van de door de gebruiker toegewezen beheerde identiteit bij gebruik van beheerde identiteitverificatie.

Zie Sink-opties voor meer opties.

Gegevens naar uw database verzenden met behulp van de Serilog-sink. Voorbeeld:

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);

Bouw en voer de app uit. Als u bijvoorbeeld Visual Studio gebruikt, drukt u op F5.
Controleer of de gegevens zich in de tabel bevinden. Voer de volgende query uit om de tijdelijke aanduiding te vervangen door de naam van de tabel die in een vorige stap is gemaakt:
```
<TableName>
| take 10
```

De voorbeeld-app uitvoeren

Als u geen eigen gegevens hebt om te testen, kunt u de voorbeeldlogboekgenerator-app gebruiken met voorbeeldgegevens om de configuratie en het gebruik van de Serilog-sink te testen.

Kloon de Git-opslagplaats van de Serilog-sink met behulp van de volgende Git-opdracht:
```
git clone https://github.com/Azure/serilog-sinks-azuredataexplorer
```

Stel de volgende omgevingsvariabelen in om de Serilog-sink te configureren:

Veranderlijk	Beschrijving
`IngestionEndPointUri`	De opname-URI.
`DatabaseName`	De hoofdlettergevoelige naam van de doeldatabase.
`TableName`	De hoofdlettergevoelige naam van een bestaande doeltabel. SerilogTest is bijvoorbeeld de naam van de tabel die is gemaakt in Een doeltabel maken en opnametoewijzing.
`AppId`	Toepassingsclient-id vereist voor authenticatie van de Microsoft Entra-service-principal. U hebt deze waarde opgeslagen in Een Microsoft Entra-service-principal maken.
`AppKey`	Toepassingssleutel vereist voor authenticatie van de Microsoft Entra service-principal. U hebt deze waarde opgeslagen in Een Microsoft Entra-service-principal maken.
`Tenant`	De ID van de tenant waarin de toepassing is geregistreerd, bij het gebruik van verificatie van de service-principal van Microsoft Entra. U hebt deze waarde opgeslagen in Een Microsoft Entra-service-principal maken.
`BufferBaseFileName`	De basisbestandsnaam voor het bufferbestand. Stel deze waarde in als u wilt dat uw logboeken duurzaam zijn tegen verlies als gevolg van storingen in uw cluster. Bijvoorbeeld `C:/Temp/Serilog`
`ManagedIdentityClientId`	De client-id van de door de gebruiker toegewezen beheerde identiteit bij gebruik van beheerde identiteitverificatie.

U kunt de omgevingsvariabelen handmatig instellen of de volgende opdrachten gebruiken:

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

Blader in de terminal naar de hoofdmap van de gekloonde opslagplaats en voer de volgende .NET-opdracht uit om de app te bouwen:
```
dotnet build src
```
Blader in de terminal naar de map met voorbeelden en voer de volgende .NET-opdracht uit om de app uit te voeren:
```
dotnet build run
```

Selecteer in de queryomgeving de doeldatabase en voer de volgende query uit om de opgenomen gegevens te verkennen, waarbij u de tijdelijke aanduiding TableName vervangt door de naam van de doeltabel:
```
<TableName>
| take 10
```
De uitvoer moet er ongeveer uitzien als in de volgende afbeelding:

Overzicht van gegevensintegraties
Overzicht van Kusto Query Language (KQL)

Feedback

Is deze pagina nuttig?

Last updated on 2025-06-09