使用 Azure 監視器代理程式從 JSON 檔案收集記錄

發行項
12/17/2024

自訂 JSON 記錄是資料收集規則 (DCR) 中使用的資料來源其中之一。使用 Azure 監視器代理程式收集資料提供建立 DCR 的詳細資料。本文提供文字和 JSON 記錄類型的其他詳細資料。

許多應用程式和服務都會將資訊記錄到 JSON 檔案，而不是標準記錄服務，例如 Windows 事件記錄檔或 Syslog。您可以使用 Azure 監視器代理程式來收集此資料，並儲存在 Log Analytics 工作區中，以及從其他來源收集的資料。

必要條件

您至少擁有參與者權限所在的 Log Analytics 工作區。
資料收集端點 (DCE) 位於與 Log Analytics 工作區相同的區域中。如需詳細資訊，請參閱如何根據您的部署設定資料收集端點。
使用 Azure 監視器代理程式收集資料中所述的新 DCR 或現有 DCR。

基本作業

下圖顯示從 json 檔案收集記錄資料的基本作業。

代理程式會監看本機磁碟上符合指定名稱模式的任何記錄檔。
記錄中的每個項目都會收集並傳送至 Azure 監視器。使用者定義的傳入資料流可用來將記錄資料剖析成資料行。
如果傳入資料流的結構描述符合目標資料表的結構描述，則會使用預設轉換。

JSON 檔案需求和最佳做法

Azure 監視器代理程式正在監視的檔案必須符合下列需求：

檔案必須儲存在機器的本機磁碟機上，且該磁碟機的受監視目錄中具有 Azure 監視器代理程式。
每個記錄都必須以行結尾來劃定。
檔案必須使用 ASCII 或 UTF-8 編碼。不支援其他格式，例如 UTF-16。
新記錄應該附加至檔案結尾，而不是覆寫舊記錄。覆寫會導致資料遺失。
JSON 文字必須包含在單一資料列中。不支援 JSON 本文格式。請參閱以下範例。

請遵循下列建議，以確保您不會遇到資料遺失或效能問題：

每天建立新的記錄檔，以便您可以輕鬆地清除舊檔案。
持續清除受監視目錄中的記錄檔。追蹤可能會提升代理程式 CPU 和記憶體使用量的記錄檔。等候至少 2 天，以便有足夠的時間可以處理所有記錄。
請勿將符合檔案掃描模式的檔案重新命名為另一個也符合檔案掃描模式的名稱。這會導致擷取重複的資料。
請勿將符合檔案掃描模式的大型記錄檔重新命名或複製到受監視的目錄。如果有此必要，請勿每分鐘超過 50 MB。

自訂資料表

您必須先在 Log Analytics 工作區中建立自訂表格，才能從 JSON 檔案收集記錄資料。資料表結構描述必須符合傳入資料流中的資料行，或者您必須新增轉換，以確保輸出結構描述符合資料表。

警告

您不應該使用 Log Analytics 代理程式所使用的現有自訂資料表。一旦第一個 Azure 監視器代理程式寫入至該資料表，舊版代理程式就無法寫入其中。為 Azure 監視器代理程式建立新的資料表，以防止 Log Analytics 代理程式資料遺失。

例如，您可以使用下列 PowerShell 指令碼，來建立具有多個資料行的自訂表格。

$tableParams = @'
{
    "properties": {
        "schema": {
               "name": "{TableName}_CL",
               "columns": [
                    {
                        "name": "TimeGenerated",
                        "type": "DateTime"
                    }, 
                    {
                        "name": "MyStringColumn",
                        "type": "string"
                    },
                    {
                        "name": "MyIntegerColumn",
                        "type": "int"
                    },
                    {
                        "name": "MyRealColumn",
                        "type": "real"
                    },
                    {
                        "name": "MyBooleanColumn",
                        "type": "bool"
                    },
                    {
                        "name": "FilePath",
                        "type": "string"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    }
              ]
        }
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{WorkspaceName}/tables/{TableName}_CL?api-version=2021-12-01-preview" -Method PUT -payload $tableParams

建立 JSON 檔案的資料收集規則

注意

代理程式型 JSON 自訂檔案擷取目前處於預覽狀態，且入口網站中還沒有完整的 UI 體驗。雖然您可以使用入口網站建立 DCR，但您必須進行修改，以定義傳入資料流中的資料行。本節包含使用 ARM 範本建立 DCR 的詳細資料。

傳入資料流結構描述

注意

現在已提供使用時間戳分隔事件的多行支援

JSON 檔案包含具有每個值的屬性名稱，而 DCR 中的傳入資料流必須包含符合每個屬性名稱的資料行。您必須使用您記錄中的資料行來修改 ARM 範本的 columns 區段。

除了描述在您的記錄檔中定義資料的資料行以外，下表還描述您可包含的選用資料行。

資料行	類型	描述
`TimeGenerated`	datetime	產生記錄的時間。如果記錄未包含在傳入資料流中，則此值會自動填入記錄新增至 Log Analytics 工作區的時間。
`FilePath`	字串	如果您將此資料行新增至 DCR 中的傳入資料流，則會填入記錄檔的路徑。此資料行不會自動建立，且無法使用入口網站新增。您必須手動修改入口網站所建立的 DCR，或使用另一種方法建立 DCR，您可以在其中明確定義傳入資料流。
`Computer`	字串	如果您將此資料行新增至 DCR 中的傳入資料流，即會填入電腦的名稱與記錄檔。此資料行不會自動建立，且無法使用入口網站新增。您必須手動修改入口網站所建立的 DCR，或使用另一種方法建立 DCR，您可以在其中明確定義傳入資料流。

轉換

轉換可能會修改傳入資料流來篩選記錄，或修改結構描述以符合目標資料表。如果傳入資料流的結構描述與目標資料表相同，您則可使用 source 的預設轉換。如果不同，請使用傳回所需結構描述的 KQL 查詢，修改 tee ARM 範本的 transformKql 區段。

ARM 範本

使用下列 ARM 範本來建立 DCR 來收集 JSON 記錄檔，進行上一節所述的變更。下表描述部署範本時需要值的參數。

設定	描述
資料收集規則名稱	DCR 的唯一名稱。
資料收集端點資源識別碼	資料收集端點 (DCE) 的資源識別碼。
Location	DCR 的區域。必須與 Log Analytics 工作區相同的位置。
檔案模式	識別本機磁碟機上記錄檔的位置和名稱。針對檔名使用萬用字元，例如，每天使用新名稱建立新檔案時。您可以輸入多個以逗號分隔的檔案模式 (Linux 上多個檔案模式所需的 AMA 1.26 版或更高版本)。範例： - C:\Logs\MyLog.json - C:\Logs\MyLog.json - C:\App01\AppLog.json, C:\App02\AppLog.json - /var/mylog.json - /var/mylog.json
資料表名稱	Log Analytics 工作區中的目的地資料表名稱。
工作區資源識別碼	具有目標資料表之 Log Analytics 工作區的資源識別碼。
timeFormat	支援下列時間格式。使用 ARM 範本中的引號字串。請勿包含括弧中的範例時間。 - “yyyy-MM-ddTHH：mm：ssk” （2024-10-29T18：28：34） - “YYYY-MM-DD HH：MM：SS” （2024-10-29 18：28：34） - “M/D/YYYY HH：MM：SS AM/PM” （2024/10/29 06：28：34 PM） - “Mon DD， YYYY HH：MM：SS” （Oct[ober] 29， 2024 18：28：34） - “yyMMdd HH：mm：ss” （241029 18：28：34） - “ddMMyy HH：mm：ss” （291024 18：28：34） - “MMM d HH：mm：ss” （10 月 29 日 18：28：34） - “dd/MMM/yyyy：HH：mm：ss zzz” （14/Oct/2024：18：28：34 -00）

重要

當您使用 ARM 範本建立 DCR 時，您必須將 DCR 與將使用之的代理程式產生關聯。您可以如新增資源中所述，在 Azure 入口網站中編輯 DCR，並選取代理程式

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Unique name for the DCR. "
            }
        },
        "dataCollectionEndpointResourceId": {
            "type": "string",
            "metadata": {
              "description": "Resource ID of the data collection endpoint (DCE)."
            }
        },
        "location": {
            "type": "string",
            "metadata": {
                "description": "Region for the DCR. Must be the same location as the Log Analytics workspace. "
            }
        },
        "filePatterns": {
            "type": "string",
            "metadata": {
                "description": "Path on the local disk for the log file to collect. May include wildcards.Enter multiple file patterns separated by commas (AMA version 1.26 or higher required for multiple file patterns on Linux)."
            }
        },
        "tableName": {
            "type": "string",
            "metadata": {
                "description": "Name of destination table in your Log Analytics workspace. "
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Resource ID of the Log Analytics workspace with the target table."
            }
        },
        "timeFormat": {
            "type": "string"
            "metadata": {
                "discription": "The time format that you would like to use to split multi line imput"
            }
      }
    },
    "variables": {
        "tableOutputStream": "[concat('Custom-', parameters('tableName'))]"
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "apiVersion": "2022-06-01",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "properties": {
                "dataCollectionEndpointId": "[parameters('dataCollectionEndpointResourceId')]",
                "streamDeclarations": {
                    "Custom-Json-stream": {
                        "columns": [
                            {
                                "name": "TimeGenerated",
                                "type": "datetime"
                            },
                            {
                                "name": "FilePath",
                                "type": "string"
                            },
                            {
                                "name": "MyStringColumn",
                                "type": "string"
                            },
                            {
                                "name": "MyIntegerColumn",
                                "type": "int"
                            },
                            {
                                "name": "MyRealColumn",
                                "type": "real"
                            },
                            {
                                "name": "MyBooleanColumn",
                                "type": "boolean"
                            }
                        ]
                    }
                },
                "dataSources": {
                    "logFiles": [
                        {
                            "streams": [
                                "Custom-Json-stream"
                            ],
                            "filePatterns": [
                                "[parameters('filePatterns')]"
                            ],
                            "format": "json",
                            "name": "Custom-Json-stream",
                            "settings": {
                               "text": {
                                   "recordStartTimestampFormat": "[parameters('timeFormat')]"
                               }
                            }
                        }
                    ]
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "workspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-Json-stream"
                        ],
                        "destinations": [
                            "workspace"
                        ],
                        "transformKql": "source",
                        "outputStream": "[variables('tableOutputStream')]"
                    }
                ]
            }
        }
    ]
}

疑難排解

如果您從 JSON 記錄沒有收集到預期的資料，請執行下列步驟。

確認資料正在寫入所收集的記錄檔。
確認記錄檔的名稱和位置符合您指定的檔案模式。
確認 DCR 中連入資料流的結構描述符合記錄檔中的結構描述。
確認目標資料表的結構描述與傳入資料流相符，或您有能將傳入資料流轉換成正確結構描述的轉換。
請參閱確認作業以確認代理程式是否運作，以及是否正在接收資料。

下一步

深入了解：

共用方式為