Azure SDK for Java Reference Documentation
Azure Monitor Ingestion client library for Java
The Azure Monitor Ingestion client library is used to send custom logs to Azure Monitor.
This library allows you to send data from virtually any source to supported built-in tables or to custom tables that you create in Log Analytics workspace. You can even extend the schema of built-in tables with custom columns.
Getting started
Prerequisites
- A Java Development Kit (JDK), version 8 or later.
- Azure Subscription
- A Data Collection Endpoint
- A Data Collection Rule
- A Log Analytics workspace
Include the package
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-monitor-ingestion</artifactId>
<version>1.0.0-beta.1</version>
</dependency>
Create the client
An authenticated client is required to upload logs to Azure Monitor. The library includes both synchronous and asynchronous forms of the clients. To authenticate,
the following examples use DefaultAzureCredentialBuilder from the com.azure:azure-identity package.
Authenticating using Azure Active Directory
You can authenticate with Azure Active Directory using the Azure Identity library.
To use the DefaultAzureCredential provider shown below, or other credential providers provided with the Azure SDK, please include the azure-identity package:
md5-029ae70175d914fb7bfdfc4b1af6f74e
Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: AZURECLIENTID, AZURETENANTID, AZURECLIENTSECRET.
Synchronous Logs Ingestion client
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
LogsIngestionClient client = new LogsIngestionClientBuilder()
.endpoint("<data-collection-endpoint>")
.credential(tokenCredential)
.buildClient();
Asynchronous Logs Ingestion client
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
LogsIngestionAsyncClient asyncClient = new LogsIngestionClientBuilder()
.endpoint("<data-collection-endpoint>")
.credential(tokenCredential)
.buildAsyncClient();
Key concepts
Data Collection Endpoint
Data Collection Endpoints (DCEs) allow you to uniquely configure ingestion settings for Azure Monitor. This article provides an overview of data collection endpoints including their contents and structure and how you can create and work with them.
Data Collection Rule
Data collection rules (DCR) define data collected by Azure Monitor and specify how and where that data should be sent or stored. The REST API call must specify a DCR to use. A single DCE can support multiple DCRs, so you can specify a different DCR for different sources and target tables.
The DCR must understand the structure of the input data and the structure of the target table. If the two don't match, it can use a transformation to convert the source data to match the target table. You may also use the transform to filter source data and perform any other calculations or conversions.
For more details, refer to Data collection rules in Azure Monitor.
Log Analytics Workspace Tables
Custom logs can send data to any custom table that you create and to certain built-in tables in your Log Analytics workspace. The target table must exist before you can send data to it. The following built-in tables are currently supported:
Examples
Upload custom logs
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
LogsIngestionClient client = new LogsIngestionClientBuilder()
.endpoint("<data-collection-endpoint")
.credential(tokenCredential)
.buildClient();
List<Object> logs = getLogs();
UploadLogsResult result = client.upload("<data-collection-rule-id>", "<stream-name>", logs);
System.out.println("Logs upload result status " + result.getStatus());
Upload custom logs with max concurrency
If the in input logs collection is too large, the client will split the input into multiple smaller requests. These
requests are sent serially, by default, but by configuring the max concurrency in UploadLogsOptions, these requests
can be concurrently sent to the service as shown in the example below.
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
LogsIngestionClient client = new LogsIngestionClientBuilder()
.endpoint("<data-collection-endpoint")
.credential(tokenCredential)
.buildClient();
List<Object> logs = getLogs();
UploadLogsOptions uploadLogsOptions = new UploadLogsOptions()
.setMaxConcurrency(3);
UploadLogsResult result = client.upload("<data-collection-rule-id>", "<stream-name>", logs, uploadLogsOptions,
Context.NONE);
System.out.println("Logs upload result status " + result.getStatus());
Troubleshooting
Enabling Logging
Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and expedite their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help locate the root issue. View the logging wiki for guidance about enabling logging.
Next steps
More samples can be found here.
Contributing
This project welcomes contributions and suggestions. 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. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.