通用表达式语言输入

为输入提供的执行环境包括 mito 库提供的函数、宏和全局变量。单个 JSON 对象作为输入提供，可通过 state 变量访问。 state 包含一个字符串 url 字段，并且可能包含通过输入的 state 配置配置的其他任意字段。如果 CEL 程序在程序执行之间保存游标状态，则配置的 state.cursor 值将在执行之前被保存的游标替换。

启动时，state 将类似于以下内容

{
    "url": <resource address>,
    "cursor": { ... },
    ...
}

state.url 字段将存在，并且可能为 HTTP 端点或文件路径。CEL 程序负责处理从文件 URL 中删除方案（如果存在）。state.url 字段可以在程序执行期间发生变异，但变异的状态不会在重启之间持久化。 state.url 字段必须存在于返回值中，以确保它在下次评估中可用，除非程序在其中硬编码了资源地址或它可从游标中获得。

对象的根目录中可能存在其他字段，如果程序容忍它，则游标值可能不存在。只有游标在重启后持久化，但在处理循环的每次迭代之间，状态中的所有字段都将保留，除了生成的 events 数组，如下所示。

如果游标存在，程序应根据其值执行和处理请求。如果游标不存在，程序必须具有确定要发出哪些请求的替代逻辑。

在程序执行完成后，它应该返回一个结构如下所示的单个对象

{
    "events": [ 
        {...},
        ...
    ],
    "cursor": [ 
        {...},
        ...
    ],
    "url": <resource address>,
    "status_code": <HTTP request status code if a network request>,
    "header": <HTTP response headers if a network request>,
    "rate_limit": <HTTP rate limit map if required by API>, 
    "want_more": false 
}

如果程序没有与 HTTP API 端点交互，则可以省略 status_code、header 和 rate_limit 值，因此不需要它们来参与程序控制。

CEL 输入将在以 DEBUG 级别记录时记录评估后的完整状态。这将包括 state 对象中保留的任何敏感或机密信息，因此在生产环境中，当 state 对象中保留敏感信息时，不应使用 DEBUG 级别日志记录。请参阅 redact 配置参数以获取排除 DEBUG 日志中敏感字段的设置。

如上所述，cel 输入提供函数、宏和全局变量来扩展语言。

除了上面列出的包中提供的扩展之外，还提供了全局变量 useragent，它使用户 CEL 程序能够访问 filebeat 用户代理字符串。默认情况下，此值将分配给所有请求的用户代理标头，除非 CEL 程序已设置用户代理标头值。希望不提供用户代理的程序应将此标头设置为空字符串 ""。

主机环境变量通过全局映射 env 提供。只有通过 allowed_environment 配置列表列入白名单的环境变量对 CEL 程序可见。

CEL 环境使用此处定义的版本启用 可选类型 库 此处。

此外，它还支持通过基本身份验证、摘要身份验证或 OAuth2 进行身份验证。

带有身份验证的示例配置

filebeat.inputs:
- type: cel
  auth.basic:
    user: [email protected]
    password: P@$$W0₹D
  resource.url: https://127.0.0.1

filebeat.inputs:
- type: cel
  auth.digest:
    user: [email protected]
    password: P@$$W0₹D
  resource.url: https://127.0.0.1

filebeat.inputs:
- type: cel
  auth.oauth2:
    client.id: 12345678901234567890abcdef
    client.secret: abcdef12345678901234567890
    token_url: https://127.0.0.1/oauth2/token
  resource.url: https://127.0.0.1

filebeat.inputs:
- type: cel
  auth.oauth2:
    client.id: 12345678901234567890abcdef
    client.secret: abcdef12345678901234567890
    token_url: https://127.0.0.1/oauth2/token
    user: [email protected]
    password: P@$$W0₹D
  resource.url: https://127.0.0.1

cel 输入在请求之间保持运行时状态。CEL 程序可以访问此状态，并且它可能包含任意对象。

状态必须包含一个 url 字符串，并且可以包含用户希望存储在其中的任何对象。

所有对象都存储在运行时，除了 cursor，它的值在重启之间持久化。

cel 输入支持以下配置选项以及稍后描述的 通用选项。

重复请求之间的时间间隔。如果启用了分页，它可能会根据初始请求发出其他分页请求。默认值：60s。

每个轮询周期执行的 CEL 程序。此字段是必需的。

max_executions 是 CEL 程序可以使用 want_more 字段请求重新运行的最大次数。这用于确保意外的无限循环不会停止处理。当执行预算超出时，将在下一个间隔重新开始执行，并在日志中写入警告。默认值：1000。

state 是一个可选对象，在第一次执行时传递给 CEL 程序。它作为 state 变量提供给正在执行的程序。在输入的生命周期中，它会提供给程序的后续执行，作为先前执行的返回值，但 state.events 字段除外。除了 state.cursor 字段外，state 在重启时不会持久化。

游标是一个可作为 state.cursor 获取的对象，可以在其中存储任意值。游标状态在输入重启之间保留，并在请求的每个事件发布后更新。当使用游标时，CEL 程序必须为程序返回的每个事件创建一个游标状态，或者创建一个反映完整事件集游标的单个游标。

filebeat.inputs:
# Fetch your public IP every minute and note when the last request was made.
- type: cel
  interval: 1m
  resource.url: https://api.ipify.org/?format=json
  program: |
    bytes(get(state.url).Body).as(body, {
        "events": [body.decode_json().with({
            "last_requested_at": has(state.cursor) && has(state.cursor.last_requested_at) ?
                state.cursor.last_requested_at
            :
                now
        })],
        "cursor": {"last_requested_at": now}
    })

将对 CEL 执行环境可见的主机环境变量列表。默认情况下，没有环境变量可见。

filebeat.inputs:
# Publish the list of files in $PATH every minute.
- type: cel
  interval: 1m
  resource.url: ""
  allowed_environment:
    - PATH
  program: |
{
  "events": {
    "message": env.?PATH.orValue("").split(":")
      .map(p, try(dir(p)))
      .filter(d, type(d) != type(""))
      .flatten()
      .collate("name")
  }
}

一组命名的正则表达式，可以使用 regexp 扩展库在 CEL 程序执行期间使用。正则表达式使用的语法为 RE2。

filebeat.inputs:
- type: cel
  # Define two regular expressions, 'products' and 'solutions' for use during CEL execution.
  regexp:
    products: '(?i)(Elasticsearch|Beats|Logstash|Kibana)'
    solutions: '(?i)(Search|Observability|Security)'

XML 文档可能需要其他类型信息才能启用正确的解析和摄取。此信息可以使用 xsd 选项作为 XML 模式定义 (XSD) 提供给 XML 文档。提供 XSD 信息的键可以通过 decode_xml CEL 扩展访问。

filebeat.inputs:
- type: cel
  # Provide an XSD, 'order', for use during CEL execution (truncated for example).
  xsd:
    order: |
       <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
         <xs:element name="order">
           <xs:complexType>
             <xs:sequence>
               <xs:element name="sender" type="xs:string"/>
               <xs:element name="address">
                 <xs:complexType>
                   <xs:sequence>
                     <xs:element name="name" type="xs:string"/>
                     <xs:element name="company" type="xs:string"/>

设置为 false 时，禁用基本身份验证配置。默认值：true。

用于身份验证的用户。

要使用的密码。

设置为 false 时，禁用摘要身份验证配置。默认值：true。

用于身份验证的用户。

要使用的密码。

设置为 true 时，不会重用摘要身份验证质询。

设置为 false 时，禁用 oauth2 配置。默认值：true。

用于配置支持的 oauth2 提供程序。每个支持的提供程序都需要特定的设置。默认情况下未设置。支持的提供程序包括：azure、google、okta。

用作身份验证流程一部分的客户端 ID。除了使用 google 作为提供程序外，它始终是必需的。以下提供程序需要此项：default、azure、okta。

用作身份验证流程一部分的客户端密钥。除了使用 google 或 okta 作为提供程序外，它始终是必需的。以下提供程序需要此项：default、azure。

用作身份验证流程一部分的用户。它对于身份验证 - 授予类型密码是必需的。它仅适用于提供程序 default。

用作身份验证流程一部分的密码。它对于身份验证 - 授予类型密码是必需的。它仅适用于提供程序 default。

将在 oauth2 流程期间请求的一系列范围。对于所有提供程序，它都是可选的。

将在 oauth2 流程期间用于生成令牌的端点。如果未指定提供程序，则需要此项。

将发送到 token_url 的每个请求的一组值。每个参数键可以具有多个值。可以为除 google 之外的所有提供程序设置。

- type: cel
  auth.oauth2:
    endpoint_params:
      Param1:
        - ValueA
        - ValueB
      Param2:
        - Value

在使用 azure 提供程序时用于身份验证。由于它用于生成 token_url 的过程中，因此不能与之结合使用。它不是必需的。

有关在哪里查找它的信息，您可以参考 https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal。

在使用 azure 提供程序时访问的 WebAPI 资源。它不是必需的。

Google 的凭据文件。

您的凭据信息（原始 JSON 格式）。

Google 的 JWT 帐户密钥文件。

JWT 帐户密钥文件（原始 JSON 格式）。

用于创建凭据的委托帐户的电子邮件（通常是管理员）。与 auth.oauth2.google.jwt_file 或 auth.oauth2.google.jwt_json 结合使用。

您的 Okta 服务应用程序的 RSA JWK 私钥文件，用于与 Okta Org 身份验证服务器交互以使用 okta.* 范围生成令牌。

您的 Okta 服务应用程序的 RSA JWK 私钥 JSON，用于与 Okta Org 身份验证服务器交互以使用 okta.* 范围生成令牌。

您的 Okta 服务应用程序的 RSA JWK 私钥 PEM 块，用于与 Okta Org 身份验证服务器交互以使用 okta.* 范围生成令牌。

HTTP API 的 URL。必需。

可以通过在 URL 方案中添加 +unix 或 +npipe 来通过 unix 套接字和 Windows 命名管道访问 API 端点，例如 http+unix:///var/socket/。

在声明 HTTP 客户端连接超时之前的持续时间。有效的时间单位为 ns、us、ms、s、m、h。默认值：30s。

这指定 SSL/TLS 配置。如果缺少 ssl 部分，则主机 CA 用于 HTTPS 连接。有关更多信息，请参阅 SSL。

这指定是否禁用 HTTP 端点的保持活动连接。默认值：true。

所有主机上的空闲连接的最大数量。零表示没有限制。默认值：0。

每个主机保持的空闲连接的最大数量。如果为零，则默认为 2。默认值：0。

空闲连接在关闭自身之前保持空闲的最大时间量。有效的时间单位为 ns、us、ms、s、m、h。零表示没有限制。默认值：0s。

HTTP 客户端的最大重试次数。默认值：5。

尝试重试之前等待的最小时间。默认值：1s。

尝试重试之前等待的最大时间。默认值：60s。

设置为 true 时，在重定向的情况下转发请求标头。默认值：false。

当 redirect.forward_headers 设置为 true 时，将转发除此列表中定义的标头之外的所有标头。默认值：[]。

请求要跟随的最大重定向次数。默认值：10。

指定最大总体资源请求速率的响应值。

最大突发大小。突发是指在整体速率限制之上可以发出的最大资源请求数。

可以在 CEL 程序中将 HTTP 请求和响应记录到本地文件系统，以调试配置。通过将 resource.tracer.enabled 设置为 true 并设置 resource.tracer.filename 值来启用此选项。可以使用其他选项来调整日志轮转行为。要删除现有日志，请将 resource.tracer.enabled 设置为 false，而无需取消设置文件名选项。

启用此选项会影响安全性，仅应用于调试。

为了区分不同输入实例生成的跟踪文件，可以在文件名中添加占位符 *，它将被替换为输入实例 ID。例如，http-request-trace-*.ndjson。将 resource.tracer.filename 与 resource.tracer.enable 设置为 false 一起设置会导致删除与文件名选项匹配的任何现有跟踪日志。

此值设置日志文件在轮转之前将达到的最大大小（以兆字节为单位）。默认情况下，日志在轮转之前允许达到 1MB。

这指定保留已轮转日志文件的日期数。如果未设置，则无限期保留日志文件。

要保留的旧日志数。如果未设置，则根据 resource.tracer.maxage 设置保留所有旧日志。

是否使用主机本地时间而不是 UTC 来为已轮转日志文件名设置时间戳。

这决定是否应压缩已轮转的日志。

在调试级别日志记录期间，state 对象和结果评估结果包含在日志中。这可能导致泄露机密信息。为了防止这种情况，可以从记录的 state 中删除或屏蔽字段。 redact 配置允许用户配置此字段屏蔽行为。出于安全原因，如果缺少 redact 配置，则会记录警告。

在不需要屏蔽的情况下，应使用空的 redact.fields 配置来消除记录的警告。

- type: cel
  redact:
    fields: ~

例如，如果在 CEL 程序中使用了用户构建的基本身份验证请求，则可以如下屏蔽密码

filebeat.inputs:
- type: cel
  resource.url: https://127.0.0.1:9200/_search
  state:
    user: [email protected]
    password: P@$$W0₹D
  redact:
    fields:
      - password
    delete: true

请注意，auth 配置层次结构下的字段不会公开到 state，因此不需要屏蔽。因此，在可能的情况下，最好将这些字段用于身份验证，而不是上面显示的请求构建。

这指定在调试日志记录之前要屏蔽的 state 中的字段。此数组中列出的字段将被替换为 * 或完全从发送到调试日志的消息中删除。

这指定是将字段替换为 * 还是完全从发送到调试日志的消息中删除。如果 delete 为 true，则将删除字段，而不是替换。

此输入在 HTTP 监控端点 下公开指标。这些指标在 /inputs 路径下公开。它们可用于观察输入的活动。

在 Elastic Mito 存储库中提供了一个独立的 CEL 环境，它实现了 CEL 输入的大多数注释表达式语言功能。可以使用此工具帮助开发输入将使用的 CEL 程序。可以通过运行 go install github.com/elastic/mito/cmd/mito@latest 从源代码安装，并且需要 Go 工具链。

所有输入都支持以下配置选项。

使用 enabled 选项启用和禁用输入。默认情况下，enabled 设置为 true。

Filebeat 包含在每个发布事件的 tags 字段中的一组标签。标签使在 Kibana 中选择特定事件或在 Logstash 中应用条件过滤变得容易。这些标签将附加到通用配置中指定的标签列表中。

示例

filebeat.inputs:
- type: cel
  . . .
  tags: ["json"]

您可以指定的可选字段，以向输出添加其他信息。例如，您可以添加可用于过滤日志数据的字段。字段可以是标量值、数组、字典或这些值的任何嵌套组合。默认情况下，您在此处指定的字段将在输出文档中的 fields 子字典下分组。要将自定义字段存储为顶级字段，请将 fields_under_root 选项设置为 true。如果在通用配置中声明了重复字段，则其值将被此处声明的值覆盖。

filebeat.inputs:
- type: cel
  . . .
  fields:
    app_id: query_engine_12

如果将此选项设置为 true，则自定义 fields 将存储为输出文档中的顶级字段，而不是在 fields 子字典下分组。如果自定义字段名称与 Filebeat 添加的其他字段名称冲突，则自定义字段会覆盖其他字段。

要应用于输入数据的处理器列表。

有关在配置中指定处理器的信息，请参阅 处理器。

为此输入生成的事件设置的摄取管道 ID。

如果将此选项设置为 true，则将在输出文档中发布值为 null 的字段。默认情况下，keep_null 设置为 false。

如果存在，此格式化字符串将覆盖此输入事件的索引（对于 elasticsearch 输出），或设置事件元数据的 raw_index 字段（对于其他输出）。此字符串只能引用代理名称和版本以及事件时间戳；要访问动态字段，请使用 output.elasticsearch.index 或处理器。

示例值："%{[agent.name]}-myindex-%{+yyyy.MM.dd}" 可能会扩展为 "filebeat-myindex-2019.11.01"。

默认情况下，所有事件都包含 host.name。可以将此选项设置为 true 以禁用将此字段添加到所有事件。默认值为 false。