› › › › ›

自定义过滤器

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

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

创建摄取管道过滤器编辑

摄取节点管道指定一系列以特定方式转换数据的处理器。转换发生在索引之前——不会对被监控的应用程序造成任何性能开销。管道是过滤或模糊处理 Elastic APM 数据的灵活且简单的方法。

教程：屏蔽敏感信息编辑

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

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

创建管道

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

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

下面定义的处理器将位于此数组中。

添加 JSON 处理器

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

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

添加设置处理器

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

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

添加转换处理器

使用转换处理器将 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
  }
}

添加移除处理器

最后，使用移除处理器移除 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 模板，或在上面的表格中用 @custom 替换 -namespace。例如，要定位应用程序跟踪，您将创建一个名为 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 服务器之前操作或丢弃 APM 事件的方法。有关更多信息和示例，请参阅相关代理的文档。

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

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