通用表达式语言输入

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

启动时，state 将如下所示

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

state.url 字段将存在，并且可能是 HTTP 端点或文件路径。如果存在文件 URL，则 CEL 程序有责任从文件 URL 中删除方案。state.url 字段可以在程序执行期间被修改，但修改后的状态不会在重启之间持久化。state.url 字段必须存在于返回值中，以确保它在下一次求值中可用，除非程序在资源地址中硬编码或可从游标获得。

其他字段可能存在于对象的根目录，如果程序可以容忍，则游标值可能不存在。只有游标在重启时持久化，但状态中的所有字段都会在处理循环的迭代之间保留，除了生成的事件数组，请参见下文。

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

程序执行完成后，应返回一个具有如下结构的单个对象

{
    "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 值，因此无需对程序控制做出贡献。

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

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

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

主机环境变量通过全局映射 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")
  }
}

一组命名的正则表达式，可以在 CEL 程序执行期间使用 regexp 扩展库。正则表达式使用的语法是 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 文档提供 XML 架构定义 (XSD)。提供 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 组织身份验证服务器交互以使用 okta.* 作用域生成令牌的 Okta 服务应用程序的 RSA JWK 私钥文件。

用于与 Okta 组织身份验证服务器交互以使用 okta.* 作用域生成令牌的 Okta 服务应用程序的 RSA JWK 私钥 JSON。

用于与 Okta 组织身份验证服务器交互以使用 okta.* 作用域生成令牌的 Okta 服务应用程序的 RSA JWK 私钥 PEM 块。

HTTP API 的 URL。必需。

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

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

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

此配置指定是否禁用 HTTP 端点的 keep-alive 连接。默认值：true。

所有主机之间的最大空闲连接数。零表示无限制。默认值：0。

每个主机要保留的最大空闲连接数。如果为零，则默认为两个。默认值：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 来为轮换的日志文件名添加时间戳。

这决定了是否应使用 gzip 压缩轮换的日志。

在调试级别日志记录期间，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 子字典下分组。如果自定义字段名称与 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。