使用 Azure Monitor 代理从文本文件收集日志

项目
12/18/2024

自定义文本日志是数据收集规则 (DCR) 中使用的数据源之一。有关创建 DCR 的详细信息，请参阅使用 Azure Monitor 代理收集数据。本文提供有关文本日志类型的其他详细信息。

许多应用程序和服务将信息记录到文本文件，而不是标准日志记录服务（例如 Windows 事件日志或 Syslog）。可以使用 Azure Monitor 代理收集此数据，并将其存储在 Log Analytics 工作区中，其中包含从其他源收集的数据。

先决条件

Log Analytics 工作区，你在其中至少拥有参与者权限。
与 Log Analytics 工作区位于同一区域的数据收集终结点 (DCE)。有关详细信息，请参阅如何根据部署设置数据收集终结点。
使用 Azure Monitor 代理收集数据中描述的新 DCR 或现有 DCR。

基本操作

下图显示了从文本文件收集日志数据的基本操作。

该代理监视与本地磁盘上的指定名称模式匹配的任何日志文件。
将收集日志中的每个条目并将其发送到 Azure Monitor。传入流包括单个列中的整个日志条目。
如果使用默认转换，则整个日志条目将发送到目标表中的单个列。
如果使用自定义转换，则可以将日志条目解析为目标表中的多个列。

文本文件要求和最佳做法

Azure Monitor 代理所监视的文件必须满足以下要求：

文件必须存储在运行 Azure Monitor 代理的计算机本地驱动器上所监视的目录中。
每条记录都必须具有行尾符。
文件必须使用 ASCII 或 UTF-8 编码。不支持其他格式，如 UTF-16。
新记录应附加到文件末尾，而不是覆盖旧记录。覆盖将导致数据丢失。

遵循以下建议，确保不会遇到数据丢失或性能问题：

每天创建一个新的日志文件，以便可以轻松清理旧文件。
持续清理受监视目录中的日志文件。跟踪过多日志文件可能会提高代理 CPU 和内存使用率。请至少等待 2 天，以便有足够的时间处理所有日志。
请勿将与文件扫描模式匹配的文件重命名为同样与文件扫描模式匹配的其他名称。这将导致引入重复数据。
请勿重命名与文件扫描模式匹配的大型日志文件或将其复制到受监视的目录。如果必须这样做，则每分钟不得超过 50MB。

传入流

注意

使用时间戳分隔事件的多行支持功能现已可用。在门户 UI 中添加支持之前，必须使用资源管理模板部署。

数据的传入流包括下表中的列。

列	类型	说明
`TimeGenerated`	datetime	生成记录的时间。此值将会自动填充记录添加到 Log Analytics 工作区的时间。可以替代此值，方法是使用转换将 `TimeGenerated` 设置为其他值。
`RawData`	string	单个列中的整个日志条目。如果要在发送到表之前将此数据细分为多个列，则可以使用转换。
`FilePath`	string	如果将此列添加到 DCR 中的传入流，则会使用日志文件的路径进行填充。此列不是自动创建的，无法使用门户进行添加。必须手动修改门户创建的 DCR，或使用另一种可以显式定义传入流的方法来创建 DCR。
`Computer`	string	如果将此列添加到 DCR 中的传入流，则会通过日志文件使用计算机的名称填充它。此列不是自动创建的，无法使用门户进行添加。必须手动修改门户创建的 DCR，或使用另一种可以显式定义传入流的方法来创建 DCR。

自定义表

在从文本文件收集日志数据之前，必须在 Log Analytics 工作区中创建一个自定义表来接收数据。表架构必须与要收集的数据匹配，或者必须添加转换，以确保输出架构与表匹配。

警告

为了避免数据丢失，请务必不要使用 MMA 代理当前正在使用的现有自定义日志表。将任何 AMA 代理写入现有自定义日志表后，MMA 代理将无法再写入该表。相反，应为 AMA 代理创建一个新表，以确保从一个代理顺利过渡到另一个代理。

例如，可以使用以下 PowerShell 脚本来创建包含 RawData、FilePath 和 Computer 的自定义表。不需要对此表进行转换，因为该模式与传入流的默认架构匹配。

$tableParams = @'
{
    "properties": {
        "schema": {
               "name": "{TableName}_CL",
               "columns": [
                    {
                        "name": "TimeGenerated",
                        "type": "DateTime"
                    }, 
                    {
                        "name": "RawData",
                        "type": "String"
                    },
                    {
                        "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

按照使用 Azure Monitor 代理收集数据中的说明，创建数据收集规则。在收集和传递步骤中，从“数据源类型”下拉列表中选择“自定义文本日志”。

设置	说明
文件模式	标识本地磁盘上日志文件的位置和名称。对不同的文件名使用通配符，例如每天用新名称创建新文件时。可以输入以逗号分隔的多个文件模式。示例： - C:\Logs\MyLog.txt - C:\Logs\MyLog.txt - C:\App01\AppLog.txt, C:\App02\AppLog.txt - /var/mylog.log - /var/mylog.log
表名	Log Analytics 工作区中目标表的名称。
记录分隔符	目前未使用，但会保留以供将来使用，允许使用除当前支持的行尾符 (`/r/n`) 以外的分隔符。
转换	引入时转换，用于筛选记录或设置目标表的传入数据的格式。使用 `source` 使传入的数据保持不变。

使用以下 ARM 模板创建用于收集文本日志文件的 DCR，并做出前面部分中所述的更改。下表描述了在部署模板时需要值的参数。

设置	说明
文件模式	标识本地磁盘上日志文件的位置和名称。对不同的文件名使用通配符，例如每天用新名称创建新文件时。可以输入以逗号分隔的多个文件模式。示例： - C:\Logs\MyLog.txt - C:\Logs\MyLog.txt - C:\App01\AppLog.txt, C:\App02\AppLog.txt - /var/mylog.log - /var/mylog.log
表名	Log Analytics 工作区中目标表的名称。
记录分隔符	目前未使用，但会保留以供将来使用，允许使用除当前支持的行尾符 (`/r/n`) 以外的分隔符。
转换	引入时转换，用于筛选记录或设置目标表的传入数据的格式。使用 `source` 使传入的数据保持不变。
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” (10/29/2024 06:28:34 PM) - “Mon DD, YYYY HH:MM:SS” (10 月 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/10/2024:18:28:34 -000)

使用以下 ARM 模板创建或修改用于收集文本文件的 DCR。除了参数值外，可能还需要修改模板中的以下值：

columns：删除 FilePath 列（如果不想收集它）。
transformKql：如果要修改或筛选传入流，请修改默认转换，例如，将日志条目解析为多个列。转换的输出架构必须与目标表的架构相匹配。

重要

如果使用 ARM 模板创建 DCR，则仍必须将 DCR 与要使用的代理相关联。可以在 Azure 门户中编辑 DCR，然后选择代理，如添加资源中所述。如果用 JSON 中较低位置的字符串替换 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",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2022-06-01",
            "properties": {
                "dataCollectionEndpointId": "[parameters('dataCollectionEndpointResourceId')]",
                "streamDeclarations": {
                    "Custom-Text-stream": {
                        "columns": [
                            {
                                "name": "TimeGenerated",
                                "type": "datetime"
                            },
                            {
                                "name": "RawData",
                                "type": "string"
                            },
                            {
                                "name": "FilePath",
                                "type": "string"
                            },
                            {
                                "name": "Computer",
                                "type": "string"
                            }
                        ]
                    }
                },
                "dataSources": {
                    "logFiles": [
                        {
                            "streams": [
                                "Custom-Text-stream"
                            ],
                            "filePatterns": [
                                "[parameters('filePatterns')]"
                            ],
                            "format": "text",
                            "name": "Custom-Text-dataSource",
                            "settings": {
                               "text": {
                                      "recordStartTimestampFormat": "[parameters('timeFormat')]"
                               }
                            }
                        }
                    ]
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "workspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-Text-dataSource"
                        ],
                        "destinations": [
                            "workspace"
                        ],
                        "transformKql": "source",
                        "outputStream": "[variables('tableOutputStream')]"
                    }
                ]
            }
        }
    ]
}

带分隔符的日志文件

许多文本日志文件都包含由逗号等字符分隔的条目。若要将此数据解析为单独的列，请使用具有 split 函数的转换。

例如，请考虑使用包含以下逗号分隔数据的文本文件。这些字段可以描述为：Time、Code、Severity、Module 和 Message。

2024-06-21 19:17:34,1423,Error,Sales,Unable to connect to pricing service.
2024-06-21 19:18:23,1420,Information,Sales,Pricing service connection established.
2024-06-21 21:45:13,2011,Warning,Procurement,Module failed and was restarted.
2024-06-21 23:53:31,4100,Information,Data,Nightly backup complete.

以下转换将数据解析为单独的列。由于 split 返回动态数据，因此必须使用 tostring 和 toint 等函数将数据转换为正确的标量类型。还需要为与目标表中的列名匹配的每个条目提供一个名称。请注意，此示例提供了 TimeGenerated 值。如果未提供，则会使用引入时间。

source | project d = split(RawData,",") | project TimeGenerated=todatetime(d[0]), Code=toint(d[1]), Severity=tostring(d[2]), Module=tostring(d[3]), Message=tostring(d[4])

使用日志查询检索此数据将返回以下结果。

故障排除

如果没有从预期的文本日志中收集到数据，请执行以下步骤。

验证数据是否正在写入到所收集的日志文件。
验证日志文件的名称和位置是否与指定的文件模式匹配。
验证目标表的架构是否与传入流匹配，或者你是否具有将传入流转换为正确架构的转换。
请参阅验证操作，以验证代理是否正在运行，以及是否正在接收数据。

后续步骤

了解有关以下方面的详细信息：

通过