› › › › ›

自定义过滤器

自定义过滤器允许您在摄取时过滤或编辑其他类型的 APM 数据

摄取管道	在摄取时应用。支持所有代理和字段。数据离开检测的服务。对检测的服务没有性能开销影响。
APM 代理过滤器	并非所有代理都支持。数据在离开检测的服务之前进行清理。对检测的服务有潜在的开销影响

创建摄取管道过滤器编辑

摄取节点管道指定了一系列以特定方式转换数据的处理器。转换发生在索引之前，不会对受监控的应用程序产生性能开销。管道是一种灵活且简便的过滤或混淆 Elastic APM 数据的方式。

教程：编辑敏感信息编辑

假设您决定捕获 HTTP 请求正文，但很快注意到敏感信息正在 http.request.body.original 字段中收集

{
  "email": "[email protected]",
  "password": "hunter2"
}

创建管道

要混淆存储在请求正文中的密码，您可以使用一系列摄取处理器。首先，创建一个具有简单描述和空处理器数组的管道

{
  "pipeline": {
    "description": "redact http.request.body.original.password",
    "processors": [] 
  }
}

下面定义的处理器将放入此数组中

添加 JSON 处理器

将您的第一个处理器添加到处理器数组。由于代理将请求正文捕获为字符串，请使用JSON 处理器将原始字段值转换为结构化的 JSON 对象。将此 JSON 对象保存在一个新字段中

{
  "json": {
    "field": "http.request.body.original",
    "target_field": "http.request.body.original_json",
    "ignore_failure": true
  }
}

添加 set 处理器

如果 body.original_json 不为 null，即它存在，我们将使用set 处理器编辑 password，方法是将 body.original_json.password 的值设置为 "redacted"

{
  "set": {
    "field": "http.request.body.original_json.password",
    "value": "redacted",
    "if": "ctx?.http?.request?.body?.original_json != null"
  }
}

添加 convert 处理器

使用convert 处理器将 body.original_json 的 JSON 值转换为字符串，并将其设置为 body.original 值

{
  "convert": {
    "field": "http.request.body.original_json",
    "target_field": "http.request.body.original",
    "type": "string",
    "if": "ctx?.http?.request?.body?.original_json != null",
    "ignore_failure": true
  }
}

添加 remove 处理器

最后，使用remove 处理器删除 body.original_json 字段

{
  "remove": {
    "field": "http.request.body.original",
    "if": "ctx?.http?.request?.body?.original_json != null",
    "ignore_failure": true
  }
}

注册管道

现在我们将把它们放在一起。使用创建或更新管道 API在 Elasticsearch 中注册新管道。将管道命名为 apm_redacted_body_password

PUT _ingest/pipeline/apm_redacted_body_password
{
  "description": "redact http.request.body.original.password",
  "processors": [
    {
      "json": {
        "field": "http.request.body.original",
        "target_field": "http.request.body.original_json",
        "ignore_failure": true
      }
    },
    {
      "set": {
        "field": "http.request.body.original_json.password",
        "value": "redacted",
        "if": "ctx?.http?.request?.body?.original_json != null"
      }
    },
    {
      "convert": {
        "field": "http.request.body.original_json",
        "target_field": "http.request.body.original",
        "type": "string",
        "if": "ctx?.http?.request?.body?.original_json != null",
        "ignore_failure": true
      }
    },
    {
      "remove": {
        "field": "http.request.body.original_json",
        "if": "ctx?.http?.request?.body?.original_json != null",
        "ignore_failure": true
      }
    }
  ]
}

测试管道

在启用此新管道之前，您可以使用模拟管道 API对其进行测试。此 API 允许您通过管道运行多个文档，以确保它正常工作。

下面的请求模拟通过管道运行三个不同的文档

POST _ingest/pipeline/apm_redacted_body_password/_simulate
{
  "docs": [
    {
      "_source": { 
        "http": {
          "request": {
            "body": {
              "original": """{"email": "[email protected]", "password": "hunter2"}"""
            }
          }
        }
      }
    },
    {
      "_source": { 
        "some-other-field": true
      }
    },
    {
      "_source": { 
        "http": {
          "request": {
            "body": {
              "original": """["invalid json" """
            }
          }
        }
      }
    }
  ]
}

	此文档包含与上面原始示例相同的敏感数据
	此文档仅包含一个不相关的字段
	此文档包含无效的 JSON

API 响应应类似于此

{
  "docs" : [
    {
      "doc" : {
        "_source" : {
          "http" : {
            "request" : {
              "body" : {
                "original" : {
                  "password" : "redacted",
                  "email" : "[email protected]"
                }
              }
            }
          }
        }
      }
    },
    {
      "doc" : {
        "_source" : {
          "nobody" : true
        }
      }
    },
    {
      "doc" : {
        "_source" : {
          "http" : {
            "request" : {
              "body" : {
                "original" : """["invalid json" """
              }
            }
          }
        }
      }
    }
  ]
}

正如预期的那样，只有第一个模拟文档具有编辑后的密码字段。所有其他文档均不受影响。

创建一个 @custom 管道

此过程的最后一步是从您要编辑的数据流的 @custom 管道调用新创建的 apm_redacted_body_password 管道。

@custom 管道特定于每个数据流，并遵循类似的命名约定：<type>-<dataset>@custom。提醒一下，默认的 APM 数据流是

应用程序跟踪：traces-apm-<namespace>
RUM 和 iOS 代理应用程序跟踪：traces-apm.rum-<namespace>
APM 内部指标：metrics-apm.internal-<namespace>
APM 事务指标：metrics-apm.transaction.<metricset.interval>-<namespace>
APM 服务目标指标：metrics-apm.service_destination.<metricset.interval>-<namespace>
APM 服务事务指标：metrics-apm.service_transaction.<metricset.interval>-<namespace>
APM 服务摘要指标：metrics-apm.service_summary.<metricset.interval>-<namespace>
应用程序指标：metrics-apm.app.<service.name>-<namespace>
APM 错误/异常日志记录：logs-apm.error-<namespace>
应用程序 UI 日志记录：logs-apm.app.<service.name>-<namespace>

要将自定义摄取管道与数据流匹配，请遵循 <type>-<dataset>@custom 模板，或者在上面的表格中将 -namespace 替换为 @custom。例如，要以应用程序跟踪为目标，您需要创建一个名为 traces-apm@custom 的管道。

使用创建或更新管道 API在 Elasticsearch 中注册新管道。将管道命名为 traces-apm@custom

PUT _ingest/pipeline/traces-apm@custom
{
  "processors": [
    {
      "pipeline": {
        "name": "apm_redacted_body_password" 
      }
    }
  ]
}

我们先前创建的管道的名称

如果您喜欢使用 GUI，则可以改为使用 Kibana 中的 摄取管道页面。要打开 摄取管道，请在主菜单中找到 堆栈管理或使用全局搜索字段。单击 创建管道并使用前面解释的相同命名约定，以确保您的新管道与正确的 APM 数据流匹配。

就这样！现在密码将从您的 APM HTTP 正文数据中编辑。

要了解有关摄取管道的更多信息，请参阅查看 Elasticsearch 索引模板。

APM 代理过滤器编辑

某些 APM 代理提供了一种在将 APM 事件发送到 APM Server 之前操作或删除 APM 事件的方法。请参阅相关代理的文档以获取更多信息和示例

.NET：过滤器 API。
Node.js：addFilter()。
Python：自定义处理器。
Ruby：add_filter()。

« 内置数据过滤器删除敏感数据 »