Compartir a través de

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

  • Artículo

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

Esta biblioteca le permite enviar datos desde prácticamente cualquier origen a tablas integradas admitidas 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.

Introducción

Requisitos previos

Inclusión del paquete

Inclusión del archivo BOM

Incluya en el azure-sdk-bom proyecto para tomar una dependencia de la versión estable más reciente de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, a continuación, incluya la dependencia directa en la sección dependencias sin la etiqueta de versión, como se muestra a continuación.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-ingestion</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-ingestion</artifactId>
    <version>1.1.1</version>
</dependency>

Creación del cliente

Se requiere un cliente autenticado para cargar registros en Azure Monitor. La biblioteca incluye formas sincrónicas y asincrónicas de los clientes. Para autenticarse, en los ejemplos siguientes se usa DefaultAzureCredentialBuilder el paquete azure-identity .

Autenticación mediante Azure Active Directory

Puede autenticarse con Azure Active Directory mediante la biblioteca de identidades de Azure. Para usar el proveedor DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, incluya el azure-identity paquete:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.1</version>
</dependency>

Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Cliente de ingesta de registros sincrónicos

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint>")
        .credential(tokenCredential)
        .buildClient();

Cliente de ingesta de registros asincrónicos

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionAsyncClient asyncClient = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint>")
        .credential(tokenCredential)
        .buildAsyncClient();

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 los valores de ingesta de Azure Monitor. En este artículo se proporciona información general sobre los puntos de conexión de recopilación de datos, incluidos su contenido y 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. Para obtener información sobre cómo recuperar un identificador de DCR, consulte este tutorial.

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:

Recuperación de registros

Los registros que se cargaron mediante esta biblioteca se pueden consultar mediante la biblioteca cliente de consultas de Azure Monitor .

Ejemplos

Carga de registros personalizados

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();
client.upload("<data-collection-rule-id>", "<stream-name>", logs);
System.out.println("Logs uploaded successfully");

Carga de registros personalizados con simultaneidad máxima

Si la colección de registros de entrada es demasiado grande, el cliente dividirá la entrada en varias solicitudes más pequeñas. Estas solicitudes se envían en serie de forma predeterminada, pero mediante la configuración de la simultaneidad máxima en LogsUploadOptions, estas solicitudes se pueden enviar simultáneamente al servicio, como se muestra en el ejemplo siguiente.

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();
LogsUploadOptions logsUploadOptions = new LogsUploadOptions()
        .setMaxConcurrency(3);
client.upload("<data-collection-rule-id>", "<stream-name>", logs, logsUploadOptions,
        Context.NONE);
System.out.println("Logs uploaded successfully");

Carga de registros personalizados con control de errores

Al cargar una gran colección de registros, el cliente divide la entrada en varias solicitudes de servicio más pequeñas. El método upload proporciona una opción para controlar errores de servicio individuales a través de un controlador de errores, como se muestra en el ejemplo siguiente. Este controlador de errores incluye los detalles de la excepción y la lista de todos los registros que no se pudieron cargar. Si no se proporciona un controlador de errores, el método de carga producirá una excepción de agregado que incluye todos los errores de servicio.

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();

LogsUploadOptions logsUploadOptions = new LogsUploadOptions()
        .setLogsUploadErrorConsumer(uploadLogsError -> {
            System.out.println("Error message " + uploadLogsError.getResponseException().getMessage());
            System.out.println("Total logs failed to upload = " + uploadLogsError.getFailedLogs().size());

            // throw the exception here to abort uploading remaining logs
            // throw uploadLogsError.getResponseException();
        });
client.upload("<data-collection-rule-id>", "<stream-name>", logs, logsUploadOptions,
        Context.NONE);

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

Puede encontrar más ejemplos aquí.

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, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones