Azure Monitor-Erfassungsclientbibliothek für .NET– Version 1.1.1

  • Artikel

Die Azure Monitor-Erfassungsclientbibliothek wird verwendet, um benutzerdefinierte Protokolle an Azure Monitor zu senden.

Mit dieser Bibliothek können Sie Daten aus praktisch jeder Quelle an unterstützte integrierte Tabellen oder an benutzerdefinierte Tabellen senden, die Sie im Log Analytics-Arbeitsbereich erstellen. Sie können sogar das Schema integrierter Tabellen mit benutzerdefinierten Spalten erweitern.

Ressourcen:

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Monitor Ingestion-Clientbibliothek für .NET mit NuGet:

dotnet add package Azure.Monitor.Ingestion

Authentifizieren des Clients

Ein authentifizierter Client ist erforderlich, um Daten zu erfassen. Erstellen Sie zum Authentifizieren eine instance einer TokenCredential Klasse. Übergeben Sie ihn an den Konstruktor der LogsIngestionClient -Klasse.

Für die Authentifizierung wird im folgenden Beispiel aus dem Azure.Identity Paket verwendetDefaultAzureCredential:

var endpoint = new Uri("<data_collection_endpoint_uri>");
var credential = new DefaultAzureCredential();
var client = new LogsIngestionClient(endpoint, credential);

Konfigurieren des Clients für Azure Sovereign Cloud

Standardmäßig LogsIngestionClient ist für die Verbindung mit der öffentlichen Azure-Cloud konfiguriert. Um stattdessen eine Verbindung mit einer Sovereign Cloud herzustellen, legen Sie die LogsIngestionClientOptions.Audience -Eigenschaft fest. Beispiel:

var endpoint = new Uri("<data_collection_endpoint_uri>");
var credential = new DefaultAzureCredential();
var clientOptions = new LogsIngestionClientOptions
{
    Audience = LogsIngestionAudience.AzureChina
};
var client = new LogsIngestionClient(endpoint, credential, clientOptions);

Hochladen der Protokolle

Beispiele für die Protokollerfassung finden Sie im Abschnitt Beispiele .

Wichtige Begriffe

Datensammlungsendpunkt

Mit Datensammlungsendpunkten (Data Collection Endpoint, DCEs) können Sie Erfassungseinstellungen für Azure Monitor eindeutig konfigurieren. Dieser Artikel bietet eine Übersicht über DCEs, einschließlich ihres Inhalts, ihrer Struktur und wie Sie sie erstellen und damit arbeiten können.

Datensammlungsregel

Datensammlungsregeln (Data Collection Rules, DCRs) definieren von Azure Monitor gesammelte Daten und geben an, wie und wo diese Daten gesendet oder gespeichert werden sollen. Der REST-API-Aufruf muss eine zu verwendende DCR angeben. Eine einzelne DCR kann mehrere DCRs unterstützen, weshalb Sie eine andere DCR für verschiedene Quellen und Zieltabellen angeben können.

Das DCR muss die Struktur der Eingabedaten und die Struktur der Zieltabelle erkennen. Wenn die beiden nicht übereinstimmen, kann eine Transformation durchgeführt werden, um die Quelldaten so zu konvertieren, dass sie mit der Zieltabelle kompatibel sind. Sie können die Transformation auch verwenden, um Quelldaten zu filtern und andere Berechnungen oder Konvertierungen durchzuführen.

Weitere Informationen finden Sie unter Datensammlungsregeln in Azure Monitor.

Log Analytics-Arbeitsbereichstabellen

Benutzerdefinierte Protokolle können Daten an jede von Ihnen erstellte benutzerdefinierte Tabelle und an bestimmte integrierte Tabellen in Ihrem Log Analytics-Arbeitsbereich senden. Die Zieltabelle muss existieren, bevor Sie Daten an sie senden können. Die folgenden integrierten Tabellen werden derzeit unterstützt:

Threadsicherheit

Wir garantieren, dass alle Client-instance Methoden threadsicher und unabhängig voneinander sind (Richtlinie). Dieser Entwurf stellt sicher, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Zusätzliche Konzepte

Clientoptionen | Zugreifen auf die Antwort | Vorgänge | mit langer AusführungsdauerBehandeln von Fehlern | Diagnose | Spott | Clientlebensdauer

Beispiele

Mithilfe von Beispielen können Sie sich mit verschiedenen APIs vertraut machen.

Registrieren des Clients mit Abhängigkeitsinjektion

Rufen AddLogsIngestionClient Sie die -Methode auf, um sich beim Abhängigkeitsinjektionscontainer (Dependency Injection, DI) zu registrierenLogsIngestionClient. Weitere Informationen finden Sie unter Registrieren des Clients.

Hochladen von benutzerdefinierten Protokollen

Sie können Protokolle entweder mit der LogsIngestionClient.Upload -Methode oder der LogsIngestionClient.UploadAsync -Methode hochladen. Beachten Sie die Grenzwerte für die Datenerfassung. Diese Methode verfügt über einen optionalen Parameter: string contentEncoding. Dies bezieht sich auf die Codierung von RequestContent, die übergeben wird. Wenn Sie inhalte übergeben, die bereits bearbeitet wurden, legen Sie den contentEncoding-Parameter fest. Wenn Ihr Inhalt beispielsweise gzippt ist, legen Sie contentEncoding auf "gzip" fest. Wenn dieser Parameter nicht festgelegt ist, ist das Standardverhalten, dass alle Eingaben gzipiert werden.

var endpoint = new Uri("<data_collection_endpoint>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";

var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);
DateTimeOffset currentTime = DateTimeOffset.UtcNow;

// Use BinaryData to serialize instances of an anonymous type into JSON
BinaryData data = BinaryData.FromObjectAsJson(
    new[] {
        new
        {
            Time = currentTime,
            Computer = "Computer1",
            AdditionalContext = new
            {
                InstanceName = "user1",
                TimeZone = "Pacific Time",
                Level = 4,
                CounterName = "AppMetric1",
                CounterValue = 15.3
            }
        },
        new
        {
            Time = currentTime,
            Computer = "Computer2",
            AdditionalContext = new
            {
                InstanceName = "user2",
                TimeZone = "Central Time",
                Level = 3,
                CounterName = "AppMetric1",
                CounterValue = 23.5
            }
        },
    });

// Upload our logs
Response response = await client.UploadAsync(
    ruleId,
    streamName,
    RequestContent.Create(data)).ConfigureAwait(false);

Hochladen von benutzerdefinierten Protokollen als IEnumerable

Sie können Protokolle auch mithilfe der LogsIngestionClient.Upload -Methode oder hochladen, in der LogsIngestionClient.UploadAsync Protokolle in einem generischen IEnumerable Typ zusammen mit einem optionalen LogsUploadOptions Parameter übergeben werden. Der LogsUploadOptions Parameter enthält ein Serialisierungsprogramm, eine Parallelität und einen EventHandler.

var endpoint = new Uri("<data_collection_endpoint_uri>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";

var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);

DateTimeOffset currentTime = DateTimeOffset.UtcNow;

var entries = new List<Object>();
for (int i = 0; i < 100; i++)
{
    entries.Add(
        new {
            Time = currentTime,
            Computer = "Computer" + i.ToString(),
            AdditionalContext = i
        }
    );
}

// Upload our logs
Response response = await client.UploadAsync(ruleId, streamName, entries).ConfigureAwait(false);

Hochladen benutzerdefinierter Protokolle als IEnumerable mit EventHandler

Sie können Protokolle entweder mit der LogsIngestionClient.Upload -Methode oder der LogsIngestionClient.UploadAsync -Methode hochladen. In diesen beiden Methoden werden Protokolle in einem generischen IEnumerable Typ übergeben. Darüber hinaus gibt es einen LogsUploadOptions-typed-Parameter, in dem ein Serialisierer, Parallelität und EventHandler festgelegt werden können. Das Standardserialisierungsprogramm ist auf System.Text.Jsonfestgelegt, aber Sie können das Serialisierungsprogramm übergeben, das Sie verwenden möchten. Die MaxConcurrency -Eigenschaft legt die Anzahl der Threads fest, die in der UploadAsync -Methode verwendet werden. Der Standardwert ist 5, und dieser Parameter wird in der Upload -Methode nicht verwendet. Der EventHandler wird für die Fehlerbehandlung verwendet. Es bietet dem Benutzer die Möglichkeit, den Upload abzubrechen, wenn ein Batch fehlschlägt, und auf die fehlerhaften Protokolle und die entsprechende Ausnahme zuzugreifen. Wenn ein Upload fehlschlägt, wird ohne den EventHandler eine AggregateException ausgelöst.

var endpoint = new Uri("<data_collection_endpoint_uri>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";

var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);

DateTimeOffset currentTime = DateTimeOffset.UtcNow;

var entries = new List<Object>();
for (int i = 0; i < 100; i++)
{
    entries.Add(
        new {
            Time = currentTime,
            Computer = "Computer" + i.ToString(),
            AdditionalContext = i
        }
    );
}
// Set concurrency and EventHandler in LogsUploadOptions
LogsUploadOptions options = new LogsUploadOptions();
options.MaxConcurrency = 10;
options.UploadFailed += Options_UploadFailed;

// Upload our logs
Response response = await client.UploadAsync(ruleId, streamName, entries, options).ConfigureAwait(false);

Task Options_UploadFailed(LogsUploadFailedEventArgs e)
{
    // Throw exception from EventHandler to stop Upload if there is a failure
    IReadOnlyList<object> failedLogs = e.FailedLogs;
    // 413 status is RequestTooLarge - don't throw here because other batches can successfully upload
    if ((e.Exception is RequestFailedException) && (((RequestFailedException)e.Exception).Status != 413))
        throw e.Exception;
    else
        return Task.CompletedTask;
}

Überprüfen von Protokollen

Sie können überprüfen, ob Ihre Daten ordnungsgemäß hochgeladen wurden, indem Sie die Azure Monitor-Abfragebibliothek verwenden. Führen Sie zuerst das Beispiel Zum Hochladen von benutzerdefinierten Protokollen aus, bevor Sie die Protokolle überprüfen.

var workspaceId = "<log_analytics_workspace_id>";
var tableName = "<table_name>";

var credential = new DefaultAzureCredential();
LogsQueryClient logsQueryClient = new(credential);

LogsBatchQuery batch = new();
string query = tableName + " | Count;";
string countQueryId = batch.AddWorkspaceQuery(
    workspaceId,
    query,
    new QueryTimeRange(TimeSpan.FromDays(1)));

Response<LogsBatchQueryResultCollection> queryResponse =
    await logsQueryClient.QueryBatchAsync(batch).ConfigureAwait(false);

Console.WriteLine("Table entry count: " +
    queryResponse.Value.GetResult<int>(countQueryId).Single());

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung.

Nächste Schritte

Weitere Informationen zu Azure Monitor finden Sie in der Dokumentation zum Azure Monitor-Dienst.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen. Beispielsweise Bezeichnungen und Kommentare. Folgen Sie den Anweisungen des Bots. Sie müssen die CLA nur einmal für alle Repositorys mit unserer CLA signieren.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex , oder wenden Sie sich bei opencode@microsoft.com Fragen oder Kommentaren an.

Aufrufe