HTTP 过滤器插件

• 插件版本：v2.0.0
• 发布日期：2024-12-18
• 更新日志

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

有关插件的问题，请在 Discuss 论坛上开帖讨论。有关 bug 或功能请求，请在 Github 上开 issue。有关 Elastic 支持的插件列表，请查阅 Elastic 支持矩阵。

HTTP 过滤器提供与外部 Web 服务/REST API 的集成。

该插件包含合理的默认值，这些值会根据 ECS 兼容模式 而变化。当针对 ECS 版本时，请求头将设置为 @metadata，并且 target_body 是一个必需的选项。请参阅 target_body 和 target_headers。

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

还有多个与 HTTP 连接相关的配置选项

另请参阅 通用选项 以获取所有过滤器插件支持的选项列表。

• 值类型可以是 字符串、数字、数组 或 哈希
• 没有默认值

要发送的 HTTP 请求的正文。

一个发送 body 作为 json 的示例

http {
  body => {
    "key1" => "constant_value"
    "key2" => "%{[field][reference]}"
  }
  body_format => "json"
}

• 值类型可以是 "json" 或 "text"
• 默认值为 "text"

如果设置为 "json" 并且 body 是 数组 或 哈希 类型，则正文将被序列化为 JSON。否则，将按原样发送。

• 值类型为 字符串

• 支持的值为

  • disabled：不使用 ECS 兼容的字段名（例如，响应头默认指向 headers 字段）
  • v1、v8：避免可能与 Elastic Common Schema (ECS) 冲突的字段名（例如，请求头将作为元数据添加）

• 默认值取决于正在运行的 Logstash 版本

  • 当 Logstash 提供 pipeline.ecs_compatibility 设置时，将使用其值作为默认值。
  • 否则，默认值为 disabled。

控制此插件与 Elastic Common Schema (ECS) 的兼容性。此设置的值会影响 target_body 和 target_headers 的 *默认* 值。

• 值为 hash
• 没有默认值

要在请求中发送的 HTTP 请求头。请求头的名称及其值都可以引用事件字段中的值。

• 值为 hash
• 没有默认值

定义要发送到 HTTP 请求的查询字符串参数（键值对）。

• 值为 hash

• 默认值取决于 ecs_compatibility 是否启用

  • ECS 兼容性已禁用：`"[body]"`
  • ECS 兼容性已启用：无默认值，需要显式指定

定义用于放置 HTTP 响应正文的目标字段。

• 值为 hash

• 默认值取决于 ecs_compatibility 是否启用

  • ECS 兼容性已禁用："[headers]"
  • ECS 兼容性已启用："[@metadata][filter][http][response][headers]"

定义用于放置 HTTP 响应头的目标字段。

• 值类型为 字符串
• 没有默认值

要发送请求的 URL。该值可以从事件字段中获取。

• 值类型可以是 "GET"、"HEAD"、"PATCH"、"DELETE"、"POST"、"PUT"
• 默认值为 "GET"

用于 HTTP 请求的动词。

• 值类型为number
• 默认值为 1

客户端应重试失败 URL 的次数。我们强烈建议在启用 keepalive 时不要将此值设置为零。某些服务器会过早错误地结束 keepalive，需要重试！注意：如果设置了 retry_non_idempotent，则只会重试 GET、HEAD、PUT、DELETE、OPTIONS 和 TRACE 请求。

• 值类型为number
• 默认值为 10

建立连接的超时时间（秒）。默认为 10s。

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

启用 cookie 支持。启用此选项后，客户端将在请求之间持久化 cookie，就像普通的网络浏览器一样。默认启用。

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

是否应遵循重定向？默认为 true。

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

打开此选项以启用 HTTP keepalive 支持。我们强烈建议将 automatic_retries 设置为至少一次，以修复与损坏的 keepalive 实现的交互。

• 值为 password
• 此设置没有默认值。

与用户名一起用于 HTTP 身份验证的密码。

• 值类型为number
• 默认值为 50

最大并发连接数。默认为 50。

• 值类型为number
• 默认值为 25

到单个主机的最大并发连接数。默认为 25。

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

如果您想使用 HTTP 代理。支持多种配置语法。

1. 代理主机格式： http://proxy.org:1234
2. 代理主机格式： {host => "proxy.org", port => 80, scheme => 'http', user => 'username@host', password => 'password'}
3. 代理主机格式： {url => 'http://proxy.org:1234', user => 'username@host', password => 'password'}

• 值类型为number
• 默认值为 60

整个请求的超时时间（秒）。

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

如果启用了 automatic_retries，这将导致重试非幂等 HTTP 动词（如 POST）。

• 值类型为number
• 默认值为 10

套接字数据等待超时时间（秒）。默认为 10s。

• 值类型为 路径
• 此设置没有默认值。

用于向服务器进行身份验证的 SSL 证书。此证书应为 OpenSSL 样式的 X.509 证书文件。

• 值为 path 列表
• 此设置没有默认值。

用于验证服务器证书的 .cer 或 .pem CA 文件。

• 值为 string 列表
• 此设置没有默认值。

要使用的密码套件列表，按优先级排序。支持的密码套件因 Java 和协议版本而异。

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

启用 SSL/TLS 安全通信。对于其他 ssl_ 选项生效，此项必须为 true。

• 值类型为 路径
• 此设置没有默认值。

与 ssl_certificate 对应的 OpenSSL 风格 RSA 私钥。

• 值为 password
• 此设置没有默认值。

设置密钥库密码

• 值类型为 路径
• 此设置没有默认值。

用于向服务器提供证书的密钥库。可以是 .jks 或 .p12。

• 值可以是： jks, pkcs12
• 如果未提供，将从密钥库文件名中推断该值。

密钥库文件的格式。它必须是 jks 或 pkcs12。

• 值类型为 字符串
• 允许的值为： 'TLSv1.1', 'TLSv1.2', 'TLSv1.3'
• 默认值取决于所使用的 JDK。使用最新的 Logstash，默认值为 ['TLSv1.2', 'TLSv1.3']。'TLSv1.1' 不被认为是安全的，仅供旧版应用程序使用。

建立到 HTTP 端点连接时要使用的允许的 SSL/TLS 版本列表。

对于 Java 8，'TLSv1.3' 仅在 8u262 (AdoptOpenJDK) 中支持，但需要您在 Logstash 中设置 LS_JAVA_OPTS="-Djdk.tls.client.protocols=TLSv1.3" 系统属性。

• 值为 password
• 此设置没有默认值。

设置信任库密码

• 值类型为 路径
• 此设置没有默认值。

用于验证服务器证书的信任库。可以是 .jks 或 .p12。

• 值可以是： jks, pkcs12
• 如果未提供，将从信任库文件名中推断该值。

信任库文件的格式。它必须是 jks 或 pkcs12。

• 值类型为 字符串
• 支持的值为： full, none
• 默认值为 full

控制服务器证书的验证。full 选项会验证提供的证书是否由受信任的证书颁发机构 (CA) 签名，并且服务器的主机名（或 IP 地址）是否与证书中标识的名称匹配。

none 设置不对服务器证书进行任何验证。此模式会禁用 SSL/TLS 的许多安全优势，并且只能在谨慎考虑后使用。它主要用作在尝试解决 TLS 错误时的临时诊断机制。强烈不建议在生产环境中使用 none。

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

用于所有请求的 HTTP 身份验证的用户名。请注意，您也可以为每个 URL 设置此项。如果设置了此项，则还必须设置 password 选项。

• 值类型为number
• 默认值为 200

在检查陈旧连接以确定是否需要 keepalive 请求之前等待的时间。如果您经常遇到连接错误，请考虑将此值设置得低于默认值，甚至为 0。

此客户端基于 Apache Commons。以下是 Apache Commons 文档 中对此选项的描述：“定义持久连接在被租借给消费者之前必须重新验证的不活动周期（以毫秒为单位）。传递给此方法的非正值将禁用连接验证。此检查有助于检测在池中保持不活动状态而可能已过期的连接（半关闭）。”

所有过滤器插件都支持这些配置选项

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

如果此过滤器成功，则将任意字段添加到此事件中。字段名可以是动态的，并包含事件中的部分内容，使用 %{{field}}。

示例

filter {
  http {
    add_field => { "foo_%{somefield}" => "Hello world, from %{host}" }
  }
}

# You can also add multiple fields at once:
filter {
  http {
    add_field => {
      "foo_%{somefield}" => "Hello world, from %{host}"
      "new_field" => "new_static_value"
    }
  }
}

如果事件字段为 "somefield" == "hello"，此过滤器在成功后将添加字段 foo_hello（如果存在），并带有上述值，同时将 %{{host}} 部分替换为事件中的值。第二个示例还将添加一个硬编码字段。

• 值类型为 数组
• 默认值是 []

如果此过滤器成功，则将任意标签添加到事件中。标签可以是动态的，并包含事件中的部分内容，使用 %{{field}} 语法。

示例

filter {
  http {
    add_tag => [ "foo_%{somefield}" ]
  }
}

# You can also add multiple tags at once:
filter {
  http {
    add_tag => [ "foo_%{somefield}", "taggedy_tag"]
  }
}

如果事件字段为 "somefield" == "hello"，此过滤器在成功后将添加标签 foo_hello（第二个示例当然会添加一个 taggedy_tag 标签）。

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

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

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

为插件配置添加一个唯一的 ID。如果未指定 ID，Logstash 将生成一个。强烈建议在配置中设置此 ID。当您有两个或更多相同类型的插件时（例如，您有两个 http 过滤器），这尤其有用。在这种情况下，添加一个命名的 ID 将有助于在使用监控 API 时监控 Logstash。

filter {
  http {
    id => "ABC"
  }
}

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

以固定的间隔调用过滤器的 flush 方法。可选。

• 值类型为 数组
• 默认值是 []

如果此过滤器成功，则从事件中删除任意字段。字段名可以是动态的，并包含事件中的部分内容，使用 %{{field}}。示例：

filter {
  http {
    remove_field => [ "foo_%{somefield}" ]
  }
}

# You can also remove multiple fields at once:
filter {
  http {
    remove_field => [ "foo_%{somefield}", "my_extraneous_field" ]
  }
}

如果事件字段为 "somefield" == "hello"，此过滤器在成功后将删除字段 foo_hello（如果存在）。第二个示例还将删除一个额外的、非动态字段。

• 值类型为 数组
• 默认值是 []

如果此过滤器成功，则从事件中删除任意标签。标签可以是动态的，并包含事件中的部分内容，使用 %{{field}} 语法。

示例

filter {
  http {
    remove_tag => [ "foo_%{somefield}" ]
  }
}

# You can also remove multiple tags at once:
filter {
  http {
    remove_tag => [ "foo_%{somefield}", "sad_unwanted_tag"]
  }
}

如果事件字段为 "somefield" == "hello"，此过滤器在成功后将删除标签 foo_hello（如果存在）。第二个示例还将删除一个令人不快的、不需要的标签。