› ›

Azure 事件中心插件

编辑

Azure 事件中心插件

编辑

插件版本：v1.5.0
发布日期：2024-10-25
变更日志

其他版本，请参见版本化插件文档。

获取帮助

编辑

如有任何关于插件的问题，请在 Discuss 论坛中发起讨论。如发现错误或有功能需求，请在 Github 中提交 issue。有关 Elastic 支持的插件列表，请查阅 Elastic 支持矩阵。

描述

编辑

此插件从 Azure 事件中心使用事件，这是一个高度可扩展的数据流平台和事件摄取服务。事件生产者将事件发送到 Azure 事件中心，此插件使用这些事件与 Logstash 一起使用。

许多 Azure 服务都与 Azure 事件中心集成。Azure Monitor 例如，与 Azure 事件中心集成以提供基础结构指标。

此插件需要到端口 tcp/443、tcp/9093、tcp/5671 和 tcp/5672 的出站连接，如 Microsoft 事件中心文档中所述。

事件中心连接字符串

编辑

该插件使用连接字符串访问 Azure 事件中心。您可以在此处找到连接字符串：Azure 门户-> 事件中心 -> 共享访问策略。`event_hub_connections` 选项传递用于基本配置的事件中心连接字符串。

连接字符串示例

Endpoint=sb://logstash.servicebus.windows.net/;SharedAccessKeyName=activity-log-read-only;SharedAccessKey=mm6AbDcEfj8lk7sjsbzoTJ10qAkiSaG663YykEAG2eg=;EntityPath=insights-operational-logs

Blob 存储和连接字符串

编辑

Azure Blob 存储帐户是 Azure 到 Logstash 配置的重要组成部分。Blob 存储帐户是一个中心位置，使 Logstash 的多个实例能够协同处理事件。它记录已处理事件的偏移量（位置）。重新启动后，Logstash 将从中断的地方继续处理。

配置说明

强烈建议将 Blob 存储帐户与该插件一起使用，生产服务器可能需要它。
storage_connection 选项传递 blob 存储连接字符串。
配置所有 Logstash 实例以使用相同的 storage_connection，以获得共享处理的优势。

Blob 存储连接字符串示例

DefaultEndpointsProtocol=https;AccountName=logstash;AccountKey=ETOPnkd/hDAWidkEpPZDiXffQPku/SZdXhPSLnfqdRTalssdEuPkZwIcouzXjCLb/xPZjzhmHfwRCGo0SBSw==;EndpointSuffix=core.windows.net

您可以在此处找到 Blob 存储的连接字符串：Azure 门户-> Blob 存储帐户 -> 访问密钥。

最佳实践

编辑

以下是一些指导原则，可帮助您避免可能导致事件丢失的数据冲突。

创建 Logstash 使用者组

编辑

为 Logstash 创建一个新的使用者组。不要使用 $default 或任何可能已经被使用的其他使用者组。在不相关的使用者之间重复使用使用者组可能会导致意外行为，并可能导致事件丢失。所有 Logstash 实例都应使用相同的使用者组，以便它们可以协同工作来处理事件。

避免使用多个事件中心覆盖偏移量

编辑

事件中心的偏移量（位置）存储在配置的 Azure Blob 存储中。Azure Blob 存储使用类似于文件系统的路径来存储偏移量。如果多个事件中心的路径重叠，则偏移量可能存储不正确。

为避免重复的文件路径，请使用高级配置模型，并确保每个事件中心至少有一个选项不同

storage_connection
storage_container（如果未定义，则默认为事件中心名称）
consumer_group

正确设置线程数

编辑

默认情况下，用于服务所有事件中心的线程数为 16。虽然这对于大多数用例可能足够，但可以通过改进此数字来提高吞吐量。当在一个或多个事件中心中服务大量分区时，设置更高的值可能会提高性能。线程的最大数量并不严格受正在服务的总分区数的限制，但设置的值远高于此值可能意味着某些线程处于空闲状态。

线程数必须大于或等于事件中心数加一。

目前，线程仅作为单个 azure_event_hubs 输入定义中所有事件中心的全局设置可用。但是，如果您的配置包含多个 azure_event_hubs 输入，则线程设置将独立应用于每个输入。

示例：单个事件中心

如果您正在从一个事件中心实例收集活动日志，则只需要 2 个线程。

事件中心 = 1
最小线程数 = 2（1 个事件中心 + 1）

示例：多个事件中心

如果您正在从多个事件中心实例收集活动日志，则每个事件中心至少需要 1 个线程。

事件中心 = 4
最小线程数 = 5（4 个事件中心 + 1）

当您每个事件中心使用多个分区时，您可能需要分配更多线程。一个好的基准级别是 (1 + 事件中心数 * 分区数)。也就是说，所有事件中心中每个分区一个线程。

配置模型

编辑

此插件支持两种配置模型：基本和高级。对于大多数用例，建议使用基本配置，本主题中的示例对此进行了说明。

基本配置（默认）

编辑

基本配置是默认配置，支持从多个事件中心使用数据。除连接字符串外，所有事件中心共享相同的配置。

您提供一个事件中心连接字符串列表，其中包含定义事件中心名称的事件中心 EntityPath。所有其他配置设置都是共享的。

input {
   azure_event_hubs {
      event_hub_connections => ["Endpoint=sb://example1...EntityPath=insights-logs-errors", "Endpoint=sb://example2...EntityPath=insights-metrics-pt1m"]
      threads => 8
      decorate_events => true
      consumer_group => "logstash"
      storage_connection => "DefaultEndpointsProtocol=https;AccountName=example...."
   }
}

高级配置

编辑

高级配置模型适应不同的事件中心需要不同配置的部署。可以针对每个事件中心配置选项。您可以通过 event_hubs 选项提供事件中心名称列表。在每个名称下，指定该事件中心的配置。可以在全局或每个事件中心中定义选项。

如果相同的配置选项同时出现在全局部分和 event_hub 部分中，则更具体的（event_hub）设置优先。

对于大多数用例，不需要或不建议使用高级配置。

input {
   azure_event_hubs {
     config_mode => "advanced"
     threads => 8
     decorate_events => true
     storage_connection => "DefaultEndpointsProtocol=https;AccountName=example...."
     event_hubs => [
        {"insights-operational-logs" => {
         event_hub_connection => "Endpoint=sb://example1..."
         initial_position => "beginning"
         consumer_group => "iam_team"
        }},
      {"insights-metrics-pt1m" => {
         event_hub_connection => "Endpoint=sb://example2..."
         initial_position => "end"
         consumer_group => "db_team"
       }}
     ]
   }
}

在此示例中，storage_connection 和 decorate_events 在全局应用。这两个事件中心各自都有自己的 consumer_groups 和 initial_position 设置。

Azure 事件中心配置选项

编辑

此插件支持以下配置选项以及稍后描述的通用选项。

设置	输入类型	必需
`config_mode`	字符串，(`basic` 或 `advanced`)	否
`event_hubs`	数组	是，当 `config_mode => advanced` 时
`event_hub_connections`	数组	是，当 `config_mode => basic` 时
`event_hub_connection`	字符串	是，当 `config_mode => advanced` 时
`checkpoint_interval`	数字	否
`consumer_group`	字符串	否
`decorate_events`	布尔值	否
`initial_position`	字符串，(`beginning`、`end` 或 `look_back`)	否
`initial_position_look_back`	数字	否，除非 `initial_position => look_back`
`max_batch_size`	数字	否
`storage_connection`	字符串	否
`storage_container`	字符串	否
`threads`	数字	否

另请参见通用选项，了解所有输入插件支持的选项列表。

所有事件中心选项对于基本配置和高级配置都是通用的，但以下例外情况除外。基本配置使用 event_hub_connections 来支持多个连接。高级配置使用 event_hubs 和 event_hub_connection（单数）。

`config_mode`

编辑

值类型为字符串
有效条目为 basic 或 advanced
默认值为 basic

将配置设置为基本配置（默认）或高级配置。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"  , "Endpoint=sb://example2...;EntityPath=event_hub_name2"  ]
}

`event_hubs`

编辑

值类型为数组
无默认值
对于基本配置被忽略
高级配置所需

定义要读取的事件中心。哈希数组，其中每个条目都是事件中心名称及其配置选项的哈希。

azure_event_hubs {
  config_mode => "advanced"
  event_hubs => [
      { "event_hub_name1" => {
          event_hub_connection => "Endpoint=sb://example1..."
      }},
      { "event_hub_name2" => {
          event_hub_connection => "Endpoint=sb://example2..."
          storage_connection => "DefaultEndpointsProtocol=https;AccountName=example...."
          storage_container => "my_container"
     }}
   ]
   consumer_group => "logstash" # shared across all Event Hubs
}

`event_hub_connections`

编辑

值类型为数组
无默认值
基本配置所需

连接字符串列表，用于标识要读取的事件中心。连接字符串包含事件中心的 EntityPath。

event_hub_connections 选项是针对每个事件中心定义的。所有其他配置选项在事件中心之间共享。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"  , "Endpoint=sb://example2...;EntityPath=event_hub_name2"  ]
}

`event_hub_connection`

编辑

值类型为字符串
无默认值
仅适用于高级配置

标识要读取的事件中心的连接字符串。可以为每个事件中心设置高级配置选项。此选项修改 event_hub_name，应嵌套在其下。（参见示例）此选项仅接受一个连接字符串。

azure_event_hubs {
   config_mode => "advanced"
   event_hubs => [
     { "event_hub_name1" => {
        event_hub_connection => "Endpoint=sb://example1...;EntityPath=event_hub_name1"
     }}
   ]
}

`checkpoint_interval`

编辑

值类型为数字
默认值为 5 秒
设置为 0 以禁用。

在批处理期间写入检查点的间隔（秒）。检查点告诉 Logstash 在重新启动后从哪里恢复处理。无论此设置如何，检查点都会在每个批处理结束时自动写入。

过于频繁地写入检查点可能会不必要地减慢处理速度。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"]
   checkpoint_interval => 5
}

`consumer_group`

编辑

值类型为字符串
默认值为 $Default

用于读取事件中心(s)的消费者组。为 Logstash 创建一个专门的消费者组。然后确保所有 Logstash 实例都使用该消费者组，以便它们可以一起正常工作。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"]
   consumer_group => "logstash"
}

`decorate_events`

编辑

值类型为布尔值
默认值为 false

添加有关事件中心的元数据，包括事件中心名称、consumer_group、processor_host、分区、偏移量、序列、时间戳和 event_size。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"]
   decorate_events => true
}

`initial_position`

编辑

值类型为字符串
有效参数为 beginning、end、look_back
默认值为 beginning

首次从事件中心读取时，从此位置开始。

beginning 读取事件中心中所有预先存在的事件
end 不读取事件中心中任何预先存在的事件
look_back 读取 end 减去一定秒数的预先存在的事件。您可以使用 initial_position_look_back 选项控制秒数。

注意：如果设置了 storage_connection，则 initial_position 值仅在 Logstash 首次从事件中心读取时使用。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"]
   initial_position => "beginning"
}

`initial_position_look_back`

编辑

值类型为数字
默认值为 86400
仅当 initial_position 设置为 look-back 时使用

查找预先存在事件的初始位置时回溯的秒数。仅当 initial_position 设置为 look_back 时才使用此选项。如果设置了 storage_connection，则此配置仅在 Logstash 首次从事件中心读取时适用。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"]
   initial_position => "look_back"
   initial_position_look_back => 86400
}

`max_batch_size`

编辑

值类型为数字
默认值为 125

一起检索和处理的事件的最大数量。每个批次之后都会创建一个检查点。增加此值可能会提高性能，但需要更多内存。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"]
   max_batch_size => 125
}

`storage_connection`

编辑

值类型为字符串
无默认值

Blob 帐户存储的连接字符串。Blob 帐户存储会保留重启之间的偏移量，并确保 Logstash 的多个实例处理不同的分区。设置此值后，重启将从处理中断的地方继续。未设置此值时，每次重启都将使用 initial_position 值。

我们强烈建议您为生产环境定义此值。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"]
   storage_connection => "DefaultEndpointsProtocol=https;AccountName=example...."
}

`storage_container`

编辑

值类型为字符串
如果未定义，则默认为事件中心名称

用于持久化偏移量并允许 Logstash 的多个实例一起工作的存储容器的名称。

azure_event_hubs {
   event_hub_connections => ["Endpoint=sb://example1...;EntityPath=event_hub_name1"]
   storage_connection => "DefaultEndpointsProtocol=https;AccountName=example...."
   storage_container => "my_container"
}

为了避免覆盖偏移量，您可以使用不同的存储容器。如果您正在监视两个名称相同的事件中心，这一点尤其重要。您可以使用高级配置模型来配置不同的存储容器。

azure_event_hubs {
     config_mode => "advanced"
     consumer_group => "logstash"
     storage_connection => "DefaultEndpointsProtocol=https;AccountName=example...."
     event_hubs => [
        {"insights-operational-logs" => {
         event_hub_connection => "Endpoint=sb://example1..."
         storage_container => "insights-operational-logs-1"
        }},
        {"insights-operational-logs" => {
         event_hub_connection => "Endpoint=sb://example2..."
         storage_container => "insights-operational-logs-2"
        }}
     ]
   }

`threads`

编辑

值类型为数字
最小值为 2
默认值为 16

用于处理事件的线程总数。您在此处设置的值适用于所有事件中心。即使使用高级配置，此值也是全局设置，不能按事件中心设置。

azure_event_hubs {
   threads => 16
}

线程数应为事件中心数加一或更多。有关详细信息，请参见最佳实践。

常用选项

编辑

所有输入插件都支持这些配置选项

设置	输入类型	必需
`add_field`	hash	否
`codec`	codec	否
`enable_metric`	布尔值	否
`id`	字符串	否
`tags`	数组	否
`type`	字符串	否

`add_field`

编辑

值类型为哈希表
默认值为 {}

向事件添加字段

`codec`

编辑

值类型为编解码器
默认值为 "plain"

用于输入数据的编解码器。输入编解码器是在数据进入输入之前对其进行解码的一种便捷方法，无需在 Logstash 管道中使用单独的过滤器。

`enable_metric`

编辑

值类型为布尔值
默认值为 true

禁用或启用此特定插件实例的指标日志记录，默认情况下，我们会记录所有可以记录的指标，但您可以为特定插件禁用指标收集。

`id`

编辑

值类型为字符串
此设置没有默认值。

向插件配置添加唯一的 ID。如果未指定 ID，Logstash 将生成一个。强烈建议您在配置中设置此 ID。当您拥有两种或更多相同类型的插件时，例如，如果您拥有 2 个 azure_event_hubs 输入，这将特别有用。在这种情况下，添加命名 ID 将有助于在使用监控 API 时监控 Logstash。

input {
  azure_event_hubs {
    id => "my_plugin_id"
  }
}

id 字段中的变量替换仅支持环境变量，不支持使用密钥存储中的值。

`tags`

编辑

值类型为数组
此设置没有默认值。

向您的事件添加任意数量的标签。

这可以帮助以后进行处理。

`type`

编辑

值类型为字符串
此设置没有默认值。

向此输入处理的所有事件添加 type 字段。

类型主要用于过滤器激活。

类型存储为事件本身的一部分，因此您也可以使用类型在 Kibana 中搜索它。

如果您尝试在一个已经具有类型的事件上设置类型（例如，当您将事件从发件人发送到索引器时），则新的输入不会覆盖现有的类型。即使发送到另一个 Logstash 服务器，在发件人处设置的类型也会一直保留在该事件中。

« 输入插件 Beats 输入插件 »