通用表达式语言输入

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

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

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

state.url 字段将存在，并且可能是 HTTP 端点或文件路径。如果文件 URL 中存在方案，则由 CEL 程序负责从文件中删除该方案。 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 值，因此不需要为程序控制做出贡献。

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

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

除了上面列出的软件包中提供的扩展之外，还提供了一个全局变量 useragent，它允许用户 CEL 程序访问 filebeat 用户代理字符串。

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 输入支持以下配置选项以及稍后描述的通用选项。

interval编辑

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

program编辑

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

max_executions编辑

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

state编辑

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

state.cursor编辑

游标是一个作为 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}
    })

regexp编辑

一组命名的正则表达式，可以在 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)'

xsd编辑

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"/>

auth.basic.enabled编辑

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

auth.basic.user编辑

要进行身份验证的用户。

auth.basic.password编辑

要使用的密码。

auth.digest.enabled编辑

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

auth.digest.user编辑

要进行身份验证的用户。

auth.digest.password编辑

要使用的密码。

auth.digest.no_reuse编辑

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

auth.oauth2.enabled编辑

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

auth.oauth2.provider编辑

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

auth.oauth2.client.id编辑

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

auth.oauth2.client.secret编辑

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

auth.oauth2.user编辑

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

auth.oauth2.password编辑

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

auth.oauth2.scopes编辑

将在 OAuth2 流程中请求的作用域列表。对于所有提供程序，它都是可选的。

auth.oauth2.token_url编辑

将在 OAuth2 流程中用于生成令牌的端点。如果未指定提供程序，则需要它。

auth.oauth2.endpoint_params编辑

将在每次请求 token_url 时发送的值集。每个参数键可以有多个值。可以为除 google 之外的所有提供程序设置。

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

auth.oauth2.azure.tenant_id编辑

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

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

auth.oauth2.azure.resource编辑

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

auth.oauth2.google.credentials_file编辑

Google 的凭据文件。

auth.oauth2.google.credentials_json编辑

您的凭据信息，采用原始 JSON 格式。

auth.oauth2.google.jwt_file编辑

Google 的 JWT 帐号密钥文件。

auth.oauth2.google.jwt_json编辑

JWT 帐号密钥文件，采用原始 JSON 格式。

auth.oauth2.google.delegated_account编辑

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

auth.oauth2.okta.jwk_file编辑

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

auth.oauth2.okta.jwk_json编辑

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

auth.oauth2.okta.jwk_pem编辑

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

resource.url编辑

HTTP API 的 URL。必需。

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

resource.timeout编辑

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

resource.ssl编辑

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

resource.keep_alive.disable编辑

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

resource.keep_alive.max_idle_connections编辑

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

resource.keep_alive.max_idle_connections_per_host编辑

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

resource.keep_alive.idle_connection_timeout编辑

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

resource.retry.max_attempts编辑

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

resource.retry.wait_min编辑

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

resource.retry.wait_max编辑

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

resource.redirect.forward_headers编辑

如果设置为 true，则在重定向时转发请求标头。默认值：false。

resource.redirect.headers_ban_list编辑

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

resource.redirect.max_redirects编辑

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

resource.rate_limit.limit编辑

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

resource.rate_limit.burst编辑

最大突发大小。突发是指可以超过总体速率限制的最大资源请求数。

resource.tracer.filename编辑

可以在 CEL 程序中将 HTTP 请求和响应记录到本地文件系统以调试配置。可以通过设置 resource.tracer.filename 值来启用此选项。还有其他选项可用于调整日志轮换行为。

为了区分从不同输入实例生成的跟踪文件，可以在文件名中添加占位符 *，并将其替换为输入实例 ID。例如，http-request-trace-*.ndjson。

启用此选项会危及安全性，因此仅应用于调试。

resource.tracer.maxsize编辑

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

resource.tracer.maxage编辑

这指定要保留轮换后的日志文件的天数。如果未设置，则日志文件将无限期保留。

resource.tracer.maxbackups编辑

要保留的旧日志数。如果未设置，则所有旧日志都将保留，但需遵守 resource.tracer.maxage 设置。

resource.tracer.localtime编辑

是使用主机的本地时间还是使用 UTC 对轮换后的日志文件名进行时间戳记。

resource.tracer.compress编辑

这决定是否应 gzip 压缩轮换后的日志。

redact编辑

在调试级别日志记录期间，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，因此不需要编辑。因此，如果可能，最好使用这些字段进行身份验证，而不是上面显示的请求构造。

redact.fields编辑

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

redact.delete编辑

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

指标编辑

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

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

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

enabled编辑

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

tags编辑

Filebeat 包含在每个已发布事件的 tags 字段中的标签列表。标签可以轻松地在 Kibana 中选择特定事件或在 Logstash 中应用条件过滤。这些标签将附加到常规配置中指定的标签列表中。

示例

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

fields编辑

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

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

fields_under_root编辑

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

processors编辑

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

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

pipeline编辑

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

keep_null编辑

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

index编辑

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

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

publisher_pipeline.disable_host编辑

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