Compartir a través de

Biblioteca cliente de ingesta de Azure Monitor para .NET: versión 1.1.1

  • Artículo

La biblioteca cliente de ingesta de Azure Monitor se usa para enviar registros personalizados a Azure Monitor.

Esta biblioteca permite enviar datos desde prácticamente cualquier origen a tablas integradas compatibles o a tablas personalizadas que cree en el área de trabajo de Log Analytics. Incluso puede extender el esquema de las tablas integradas con columnas personalizadas.

Recursos:

Introducción

Requisitos previos

Instalar el paquete

Instale la biblioteca cliente de ingesta de Azure Monitor para .NET con NuGet:

dotnet add package Azure.Monitor.Ingestion

Autenticar el cliente

Se requiere un cliente autenticado para ingerir datos. Para autenticarse, cree una instancia de una TokenCredential clase. Páselo al constructor de la LogsIngestionClient clase .

Para autenticarse, en el ejemplo siguiente se usa DefaultAzureCredential desde el Azure.Identity paquete:

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

Configuración del cliente para la nube soberana de Azure

De forma predeterminada, LogsIngestionClient está configurado para conectarse a la nube pública de Azure. Para conectarse a una nube soberana en su lugar, establezca la LogsIngestionClientOptions.Audience propiedad . Por ejemplo:

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

Carga de los registros

Para obtener ejemplos de ingesta de registros, consulte la sección Ejemplos .

Conceptos clave

Punto de conexión de recopilación de datos

Los puntos de conexión de recopilación de datos (DCE) permiten configurar de forma única las opciones de ingesta para Azure Monitor. En este artículo se proporciona información general sobre los DCE, incluido su contenido, su estructura y cómo puede crearlos y trabajar con ellos.

Regla de recopilación de datos

Las reglas de recopilación de datos (DCR) definen los datos recopilados por Azure Monitor y especifican cómo y dónde se deben enviar o almacenar esos datos. La llamada API de REST debe especificar una DCR que se usará. Un único DCE puede admitir varias DCR, por lo que puede especificar una DCR diferente para orígenes y tablas de destino distintos.

La DCR debe comprender la estructura de los datos de entrada y la estructura de la tabla de destino. Si las dos no coinciden, puede usar una transformación para convertir los datos de origen para que coincidan con la tabla de destino. También puede usar la transformación para filtrar los datos de origen y realizar cualquier otro cálculo o conversión.

Para más información, consulte Reglas de recopilación de datos en Azure Monitor.

Tablas del área de trabajo de Log Analytics

Los registros personalizados pueden enviar datos a cualquier tabla personalizada que cree y a determinadas tablas integradas en el área de trabajo de Log Analytics. La tabla de destino debe existir antes de poder enviarle datos. Actualmente se admiten las tablas integradas siguientes:

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Este diseño garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de clienteAcceso a la respuesta | Operaciones | de larga duraciónControl de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

Puede familiarizarse con diferentes API mediante ejemplos.

Registro del cliente con inserción de dependencias

Para registrarse LogsIngestionClient con el contenedor de inserción de dependencias (DI), invoque el AddLogsIngestionClient método . Para obtener más información, vea Registrar cliente.

Carga de registros personalizados

Puede cargar registros mediante el LogsIngestionClient.Upload método o LogsIngestionClient.UploadAsync . Anote los límites de ingesta de datos. Este método tiene un parámetro opcional: string contentEncoding. Esto hace referencia a la codificación de RequestContent que se pasa. Si pasa contenido que ya está manipulado, establezca el parámetro contentEncoding. Por ejemplo, si el contenido está descomprimido, establezca contentEncoding como "gzip". Si no se establece este parámetro, el comportamiento predeterminado es gzip toda la entrada.

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

Carga de registros personalizados como IEnumerable

También puede cargar registros mediante el LogsIngestionClient.Upload método o en el LogsIngestionClient.UploadAsync que los registros se pasan en un tipo genérico IEnumerable junto con un parámetro opcional LogsUploadOptions . El LogsUploadOptions parámetro incluye un serializador, una simultaneidad y un 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);

Carga de registros personalizados como IEnumerable con EventHandler

Puede cargar registros mediante el LogsIngestionClient.Upload método o LogsIngestionClient.UploadAsync . En estos dos métodos, los registros se pasan en un tipo genérico IEnumerable . Además, hay un LogsUploadOptionsparámetro con tipo en el que se puede establecer un serializador, la simultaneidad y EventHandler. El serializador predeterminado se establece System.Text.Jsonen , pero puede pasar el serializador que desea usar. La MaxConcurrency propiedad establece el número de subprocesos que se usarán en el UploadAsync método . El valor predeterminado es 5 y este parámetro no se usa en el Upload método . EventHandler se usa para el control de errores. Proporciona al usuario la opción de anular la carga si se produce un error en un lote y acceder a los registros con errores y a la excepción correspondiente. Sin EventHandler, si se produce un error en una carga, se producirá una AggregateException excepción .

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

Comprobación de registros

Puede comprobar que los datos se han cargado correctamente mediante la biblioteca de consultas de Azure Monitor . Ejecute primero el ejemplo Cargar registros personalizados antes de comprobar los registros.

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

Solución de problemas

Para más información sobre cómo diagnosticar varios escenarios de error, consulte nuestra guía de solución de problemas.

Pasos siguientes

Para más información sobre Azure Monitor, consulte la documentación del servicio Azure Monitor.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente. Por ejemplo, etiquetas y comentarios. Siga las instrucciones que le dará el bot. Solo tiene que firmar la CLA una vez en todos los repositorios mediante nuestra CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes sobre el código de conducta o póngase en contacto con opencode@microsoft.com cualquier pregunta o comentario.

Impresiones