使用日志引入 API 将数据发送到 Azure Monitor 的示例代码

项目
07/01/2024

本文提供使用日志引入 API 的示例代码。每个示例都需要在运行代码之前创建以下组件。请参阅教程：使用日志引入 API（资源管理器模板）将数据发送到 Azure Monitor，从而了解创建这些配置为支持其中每个示例的组件的完整演练。

Log Analytics 工作区中的自定义表
用于将数据定向到目标表的数据收集规则(DCR)
有权访问 DCR 的 Microsoft Entra 应用程序
如果使用专用链接，则使用数据收集终结点 (DCE)。否则，请使用 DCR 日志终结点。

示例代码

安装 Azure Monitor 引入客户端库和 Azure 标识库。此示例中使用的身份验证需要 Azure 标识库。
```
dotnet add package Azure.Identity
dotnet add package Azure.Monitor.Ingestion
```
使用 Microsoft Entra 应用程序的值创建以下环境变量。这些值在 Azure 标识库中由 DefaultAzureCredential 使用。
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET

将以下示例代码中的变量替换为 DCR 中的值。你可能还想要将示例数据替换为自己的数据。

using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.Monitor.Ingestion;

// Initialize variables
var endpoint = new Uri("https://my-url.monitor.azure.cn");
var ruleId = "dcr-00000000000000000000000000000000";
var streamName = "Custom-MyTableRawData";

// Create credential and client
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 logs
try
{
    var response = await client.UploadAsync(ruleId, streamName, RequestContent.Create(data)).ConfigureAwait(false);
    if (response.IsError)
    {
        throw new Exception(response.ToString());
    }

    Console.WriteLine("Log upload completed using content upload");
}
catch (Exception ex)
{
    Console.WriteLine("Upload failed with Exception: " + ex.Message);
}

// Logs can also be uploaded in a List
var entries = new List<object>();
for (int i = 0; i < 10; i++)
{
    entries.Add(
        new
        {
            Time = currentTime,
            Computer = "Computer" + i.ToString(),
            AdditionalContext = new
            {
                InstanceName = "user" + i.ToString(),
                TimeZone = "Central Time",
                Level = 3,
                CounterName = "AppMetric1" + i.ToString(),
                CounterValue = i
            }
        }
    );
}

// Make the request
try
{
    var response = await client.UploadAsync(ruleId, streamName, entries).ConfigureAwait(false);
    if (response.IsError)
    {
        throw new Exception(response.ToString());
    }

    Console.WriteLine("Log upload completed using list of entries");
}
catch (Exception ex)
{
    Console.WriteLine("Upload failed with Exception: " + ex.Message);
}

执行代码，数据应在几分钟内到达 Log Analytics 工作区。

以下示例代码使用适用于 Go 的 Azure Monitor 引入日志客户端模块。

使用 go get 安装适用于 Go 的 Azure Monitor 引入日志和 Azure 标识客户端模块。此示例中使用的身份验证需要 Azure 标识模块。
```
go get github.com/Azure/azure-sdk-for-go/sdk/monitor/ingestion/azlogs
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
```
使用 Microsoft Entra 应用程序的值创建以下环境变量。这些值在 Azure 标识模块中由 DefaultAzureCredential 使用。
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET

将以下示例代码中的变量替换为 DCR 中的值。你可能还想要将示例数据替换为自己的数据。

package main

import (
    "context"
    "encoding/json"
    "strconv"
    "time" 

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/monitor/ingestion/azlogs"
)

// logs ingestion URI 
const endpoint = "https://my-url.monitor.azure.cn"
// data collection rule (DCR) immutable ID
const ruleID = "dcr-00000000000000000000000000000000"
// stream name in the DCR that represents the destination table
const streamName = "Custom-MyTableRawData"                 

type Computer struct {
    Time              time.Time
    Computer          string
    AdditionalContext string
}

func main() {
    // creating the client using DefaultAzureCredential
    cred, err := azidentity.NewDefaultAzureCredential(nil)

    if err != nil {
        //TODO: handle error
    }

    client, err := azlogs.NewClient(endpoint, cred, nil)

    if err != nil {
        //TODO: handle error
    }

    // generating logs
    // logs should match the schema defined by the provided stream
    var data []Computer

    for i := 0; i < 10; i++ {
        data = append(data, Computer{
            Time:              time.Now().UTC(),
            Computer:          "Computer" + strconv.Itoa(i),
            AdditionalContext: "context",
        })
    }

    // marshal data into []byte
    logs, err := json.Marshal(data)

    if err != nil {
        panic(err)
    }

    // upload logs
    _, err = client.Upload(context.TODO(), ruleID, streamName, logs, nil)

    if err != nil {
        //TODO: handle error
    }
}

执行代码，数据应在几分钟内到达 Log Analytics 工作区。

以下示例代码使用适用于 Java 的 Azure Monitor 引入客户端库。

包括日志引入包和 Azure 标识库中的 azure-identity 包。此示例中使用的身份验证需要 Azure 标识库。

注意

有关最新版本，请参阅适用于标识的 Microsoft Azure 客户端库和适用于 Azure Monitor 数据引入的 Microsoft Azure SDK 的 Maven 存储库。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-ingestion</artifactId>
    <version>{get-latest-version}</version>    
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>{get-latest-version}</version>
</dependency>

使用 Microsoft Entra 应用程序的值创建以下环境变量。这些值在 Azure 标识库中由 DefaultAzureCredential 使用。
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET

将以下示例代码中的变量替换为 DCR 中的值。你可能还想要将示例数据替换为自己的数据。

import com.azure.identity.DefaultAzureCredentialBuilder; 
import com.azure.monitor.ingestion.models.LogsUploadException;

import java.time.OffsetDateTime; 
import java.util.Arrays; 
import java.util.List; 

public class LogsUploadSample {
    public static void main(String[] args) { 

        LogsIngestionClient client = new LogsIngestionClientBuilder()
            .endpoint("https://my-url.monitor.azure.cn") 
            .credential(new DefaultAzureCredentialBuilder().build()) 
            .buildClient(); 

        List<Object> dataList = Arrays.asList( 
            new Object() { 
                OffsetDateTime time = OffsetDateTime.now(); 
                String computer = "Computer1"; 
                Object additionalContext = new Object() { 
                    String instanceName = "user4"; 
                    String timeZone = "Pacific Time"; 
                    int level = 4; 
                    String counterName = "AppMetric1"; 
                    double counterValue = 15.3; 
                }; 
            }, 
            new Object() { 
                OffsetDateTime time = OffsetDateTime.now(); 
                String computer = "Computer2"; 
                Object additionalContext = new Object() { 
                    String instanceName = "user2"; 
                    String timeZone = "Central Time"; 
                    int level = 3; 
                    String counterName = "AppMetric2"; 
                    double counterValue = 43.5; 
                }; 
            }); 

        try { 
            client.upload("dcr-00000000000000000000000000000000", "Custom-MyTableRawData", dataList);  
            System.out.println("Logs uploaded successfully"); 
        } catch (LogsUploadException exception) { 
            System.out.println("Failed to upload logs "); 
            exception.getLogsUploadErrors() 
                .forEach(httpError -> System.out.println(httpError.getMessage())); 
        } 
    }
}

执行代码，数据应在几分钟内到达 Log Analytics 工作区。

以下示例代码使用适用于 JavaScript 的 Azure Monitor 引入客户端库。

使用 npm 安装适用于 JavaScript 的 Azure Monitor 引入和 Azure 标识客户端库。此示例中使用的身份验证需要 Azure 标识库。
```
npm install --save @azure/monitor-ingestion
npm install --save @azure/identity
```
使用 Microsoft Entra 应用程序的值创建以下环境变量。这些值在 Azure 标识库中由 DefaultAzureCredential 使用。
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET

将以下示例代码中的变量替换为 DCR 中的值。你可能还想要将示例数据替换为自己的数据。

const { DefaultAzureCredential } = require("@azure/identity");
const { LogsIngestionClient, isAggregateLogsUploadError } = require("@azure/monitor-ingestion");

require("dotenv").config();

async function main() {
  const logsIngestionEndpoint = "https://my-url.monitor.azure.cn";
  const ruleId = "dcr-00000000000000000000000000000000";
  const streamName = "Custom-MyTableRawData";
  const credential = new DefaultAzureCredential();
  const client = new LogsIngestionClient(logsIngestionEndpoint, credential);
  const logs = [
    {
      Time: "2021-12-08T23:51:14.1104269Z",
      Computer: "Computer1",
      AdditionalContext: {
          "InstanceName": "user1",
          "TimeZone": "Pacific Time",
          "Level": 4,
          "CounterName": "AppMetric2",
          "CounterValue": 35.3    
      }
    },
    {
      Time: "2021-12-08T23:51:14.1104269Z",
      Computer: "Computer2",
      AdditionalContext: {
          "InstanceName": "user2",
          "TimeZone": "Pacific Time",
          "Level": 4,
          "CounterName": "AppMetric2",
          "CounterValue": 43.5    
      }
    },
  ];
  try{
    await client.upload(ruleId, streamName, logs);
  }
  catch(e){
    let aggregateErrors = isAggregateLogsUploadError(e) ? e.errors : [];
    if (aggregateErrors.length > 0) {
      console.log("Some logs have failed to complete ingestion");
      for (const error of aggregateErrors) {
        console.log(`Error - ${JSON.stringify(error.cause)}`);
        console.log(`Log - ${JSON.stringify(error.failedLogs)}`);
      }
    } else {
      console.log(e);
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
  process.exit(1);
});

执行代码，数据应在几分钟内到达 Log Analytics 工作区。

以下 PowerShell 代码使用 HTTP REST 基本信息将数据发送到终结点。

注意

本示例要求 PowerShell v7.0 或更高版本。

运行以下示例 PowerShell 命令，该命令会为脚本添加所需程序集。
```
Add-Type -AssemblyName System.Web
```

将“步骤 0”部分中的参数替换为应用程序和 DCR 中的值。你可能还希望将“Step 2”部分中的示例数据替换为你自己的数据。

### Step 0: Set variables required for the rest of the script.

# information needed to authenticate to AAD and obtain a bearer token
$tenantId = "00000000-0000-0000-00000000000000000" #Tenant ID the data collection endpoint resides in
$appId = " 000000000-0000-0000-00000000000000000" #Application ID created and granted permissions
$appSecret = "0000000000000000000000000000000000000000" #Secret created for the application

# information needed to send data to the DCR endpoint
$endpoint_uri = "https://my-url.monitor.azure.cn" #Logs ingestion URI for the DCR
$dcrImmutableId = "dcr-00000000000000000000000000000000" #the immutableId property of the DCR object
$streamName = "Custom-MyTableRawData" #name of the stream in the DCR that represents the destination table


### Step 1: Obtain a bearer token used later to authenticate against the DCR.

$scope= [System.Web.HttpUtility]::UrlEncode("https://monitor.azure.cn//.default")   
$body = "client_id=$appId&scope=$scope&client_secret=$appSecret&grant_type=client_credentials";
$headers = @{"Content-Type"="application/x-www-form-urlencoded"};
$uri = "https://login.partner.microsoftonline.cn/$tenantId/oauth2/v2.0/token"

$bearerToken = (Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers).access_token


### Step 2: Create some sample data. 

$currentTime = Get-Date ([datetime]::UtcNow) -Format O
$staticData = @"
[
{
    "Time": "$currentTime",
    "Computer": "Computer1",
    "AdditionalContext": {
        "InstanceName": "user1",
        "TimeZone": "Pacific Time",
        "Level": 4,
        "CounterName": "AppMetric1",
        "CounterValue": 15.3    
    }
},
{
    "Time": "$currentTime",
    "Computer": "Computer2",
    "AdditionalContext": {
        "InstanceName": "user2",
        "TimeZone": "Central Time",
        "Level": 3,
        "CounterName": "AppMetric1",
        "CounterValue": 23.5     
    }
}
]
"@;


### Step 3: Send the data to the Log Analytics workspace.

$body = $staticData;
$headers = @{"Authorization"="Bearer $bearerToken";"Content-Type"="application/json"};
$uri = "$endpoint_uri/dataCollectionRules/$dcrImmutableId/streams/$($streamName)?api-version=2023-01-01"

$uploadResponse = Invoke-RestMethod -Uri $uri -Method "Post" -Body $body -Headers $headers

注意

如果收到 Unable to find type [System.Web.HttpUtility]. 错误，请运行脚本第 1 部分中用于修复的最后一行并执行它。在取消注释的情况下将其作为脚本的一部分执行不能解决此问题。必须单独执行该命令。

执行脚本，你应看到 HTTP - 204 响应。数据应在几分钟内到达 Log Analytics 工作区。

以下示例代码使用适用于 Python 的 Azure Monitor 引入客户端库。

使用 pip 安装适用于 Python 的 Azure Monitor 引入和 Azure 标识客户端库。此示例中使用的身份验证需要 Azure 标识库。
```
pip install azure-monitor-ingestion
pip install azure-identity
```
使用 Microsoft Entra 应用程序的值创建以下环境变量。这些值在 Azure 标识库中由 DefaultAzureCredential 使用。
- AZURE_TENANT_ID
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET

将以下示例代码中的变量替换为 DCR 中的值。你可能还希望将“Step 2”部分中的示例数据替换为你自己的数据。

# information needed to send data to the DCR endpoint
endpoint_uri = "https://my-url.monitor.azure.cn" # logs ingestion endpoint of the DCR
dcr_immutableid = "dcr-00000000000000000000000000000000" # immutableId property of the Data Collection Rule
stream_name = "Custom-MyTableRawData" #name of the stream in the DCR that represents the destination table

# Import required modules
import os
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient
from azure.core.exceptions import HttpResponseError

credential = DefaultAzureCredential()
client = LogsIngestionClient(endpoint=endpoint_uri, credential=credential, logging_enable=True)

body = [
        {
        "Time": "2023-03-12T15:04:48.423211Z",
        "Computer": "Computer1",
            "AdditionalContext": {
                "InstanceName": "user1",
                "TimeZone": "Pacific Time",
                "Level": 4,
                "CounterName": "AppMetric2",
                "CounterValue": 35.3    
            }
        },
        {
            "Time": "2023-03-12T15:04:48.794972Z",
            "Computer": "Computer2",
            "AdditionalContext": {
                "InstanceName": "user2",
                "TimeZone": "Central Time",
                "Level": 3,
                "CounterName": "AppMetric2",
                "CounterValue": 43.5     
            }
        }
    ]

try:
    client.upload(rule_id=dcr_immutableid, stream_name=stream_name, logs=body)
except HttpResponseError as e:
    print(f"Upload failed: {e}")

执行代码，数据应在几分钟内到达 Log Analytics 工作区。

故障排除

本部分介绍你可能会遇到的不同错误情况，以及如何更正它们。

脚本返回错误代码 403

确保你的应用程序对该 DCR 有正确的权限。可能还需要等待长达 30 分钟的时间，权限才能传播完毕。

脚本在响应中返回错误代码 413 或 TimeoutExpired 警告以及消息 ReadyBody_ClientConnectionAbort

消息过大。最大消息大小目前为每个调用 1 MB。

脚本返回错误代码 429

已超出 API 限制。这些限制当前设置为每分钟 500 MB 的数据（已压缩和未压缩的数据），以及每分钟 300,000 个请求。在响应的 Retry-After 标头中列出的持续时间过后重试。

脚本返回错误代码 503

确保你的应用程序对该 DCR 有正确的权限。可能还需要等待长达 30 分钟的时间，权限才能传播完毕。

你未收到错误，但数据未显示在工作区中

数据可能需要一些时间才能引入，尤其是数据第一次发送到特定表时。所需时间应不会超过 15 分钟。

Log Analytics 中的 IntelliSense 无法识别新表

用于驱动 IntelliSense 的缓存可能需要长达 24 小时的时间才能更新。

通过

使用日志引入 API 将数据发送到 Azure Monitor 的示例代码

示例代码

故障排除

脚本返回错误代码 403

脚本在响应中返回错误代码 413 或 TimeoutExpired 警告以及消息 ReadyBody_ClientConnectionAbort

脚本返回错误代码 429

脚本返回错误代码 503

你未收到错误，但数据未显示在工作区中

Log Analytics 中的 IntelliSense 无法识别新表

后续步骤

其他资源