フィルタープロセッサー

フィルタプロセッサを使用して、特定の条件に基づいてテレメトリを含めたり除外したりします。コンポーネントの設定方法については、続きをお読みください。

フィルタプロセッサは、その構成で定義した条件に基づいてスパン、メトリック、またはログをフィルタリングする OpenTelemetry Collector コンポーネントです。フィルタプロセッサの一般的な使用例は、データのノイズを減らすために、重要ではないログやスパンなど、観測されたシステムに関連しないテレメトリを削除することです。

フィルタ処理は、正規表現とリソース属性に基づいてテレメトリを含めるか除外する許可リストと拒否リストを介して機能します。OpenTelemetry Transformation Language（OTTL）を使用して、フィルタリングする信号をより適切に記述することもできます。プロセッサは、すべてのパイプラインタイプをサポートします。詳細については「パイプラインでデータを処理する」を参照してください。

フィルタープロセッサーは、以下の基準に基づいてテレメトリを含むことも除外することもできます：

シグナル

基準とマッチタイプ

スパン

OTTL 条件、スパン名称（strict あるいは regexp）、リソース属性（strict または regexp）です。スパンイベントのフィルタリングは OTTL 条件のみをサポートします。

メトリクス

OTTL 条件、メトリクス名（strict または regexp）、およびメトリクス属性（expr）。データポイントのフィルタリングは、OTTL 条件のみをサポートします。

ログ

OTTL条件、リソース属性( strict または regexp )。

フィルタープロセッサーが使用する正規表現エンジンは re2 です。

注: スパン、ログ、またはメトリクスの属性を削除せずに再編集または変換するには、属性プロセッサを使用します。 「属性プロセッサ」を参照してください。

はじめに

Splunk Distribution of OpenTelemetry Collectorには、パイプラインにデフォルトでフィルタプロセッサが含まれています。パイプラインのフィルタプロセッサを有効にするには、設定の processors セクションに filter を追加します。例：

processors:
  filter/includemetrics:
    metrics:
        # Drop nonmatching metrics from the pipeline
        include:
          match_type: strict
          metric_names:
            - good_metric
            - great_metric
  filter/excludemetrics:
    metrics:
      # Drop matching metrics from the pipeline
      exclude:
        match_type: strict
        metric_names:
          - a_metric
          - another_metric
          - a_third_metric
  filter/mixedlogs:
    logs:
       # Include filters are applied before exclude filters
       include:
         match_type: strict
         record_attributes:
           - key: host.name
             value: "(host1|anotherhost2)"
       exclude:
         match_type: strict
         record_attributes:
           - key: host.name
             value: wrong_host_.*

その後、互換性のあるパイプラインにフィルタプロセッサを追加することができます。例：

:emphasize-lines: 6, 14, 15, 23

service:
  pipelines:
    traces:
      receivers: [jaeger, otlp, zipkin]
      processors:
      - filter/traces
      - memory_limiter
      - batch
      - resourcedetection
      exporters: [otlphttp, signalfx]
    metrics:
      receivers: [hostmetrics, otlp, signalfx]
      processors:
      - filter/includemetrics
      - filter/excludemetrics
      - memory_limiter
      - batch
      - resourcedetection
      exporters: [signalfx]
    logs:
      receivers: [fluentforward, otlp]
      processors:
      - filter/mixedlogs
      - memory_limiter
      - batch
      - resourcedetection
      exporters: [splunk_hec]

パラメータの完全なリストについては、「Settings」をご確認ください。

サンプル構成

以下のサンプル構成は、さまざまな基準を使用してスパン、メトリクス、およびログをフィルターする方法を示しています。

注: 例の完全なリストは、https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/filterprocessor/testdata のコンフィギュレーションスニペットを参照してください。

スパンをフィルターする

リソース属性または OTTL 条件を使用して、スパンをトレースから除外または含めることができます。例：

filter/spans:
  spans:
    include:
      match_type: strict
      services:
        - ponygame
        - ponytest
      attributes:
        - key: an_attribute
          value: "(valid_value|another_value)"
    exclude:
      match_type: regexp
      attributes:
        - key: bad_attributes
          value: "(invalid_value|another_value)"

filter/ottl:
  traces:
    span:
      - 'attributes["test"] == "value"'
      - 'attributes["test"] == "value2"'
注: インクルードフィルターは、どのフィルタープロセッサーのインスタンスでも、常に除外フィルターの前に適用されます。

フィルター・メトリクス

メトリクス名、式、または OTTL 条件を使用して、メトリクスを除外または含めることができます。例：

filter/mixed:
  metrics:
    # Include using metric names
    include:
      match_type: strict
      metric_names:
        - a_metric
        - another_metric
    # Exclude using regular expressions
    exclude:
      match_type: regexp
      metric_names:
        - prefix/.*
        - prefix_.*
        - .*/suffix
        - .*_suffix
        - .*/contains/.*
        - .*_contains_.*
        - full/name/match
        - full_name_match

filter/expr:
  metrics:
    include:
      match_type: expr
      expressions:
        - Label("label1") == "text"
        - HasLabel("label2")

filter/ottl:
  metrics:
    metric:
      - 'name == "a_name"'
   datapoint:
      - 'attributes["attributename"] == "value"'

フィルターログ

リソース属性または OTTL 条件を使用して、ログを除外または含めることができます。例：

filter/mixed:
  logs:
    include:
      match_type: strict
      resource_attributes:
        - key: should_include
          value: "true"
    exclude:
      match_type: regexp
      resource_attributes:
        - key: host.name
          value: banned_host_.*

filter/severity:
  logs:
    exclude:
      match_type: strict
      severity_texts:
        - "DEBUG"
        - "DEBUG2"
        - "DEBUG3"
        - "DEBUG4"
    include:
      match_type: regexp
      severity_texts:
        - "INFO[2-4]?"

filter/recordattributes:
  logs:
    exclude:
      match_type: strict
      record_attributes:
        - key: should_exclude
          value: "true"

filter/includeexclude:
  logs:
    include:
      severity_number:
        min: "INFO"
        match_undefined: true
   exclude:
      severity_number:
        min: "ERROR"

filter/ottl:
  logs:
    log_record:
      - 'attributes["test"] == "pass"'

Kubernetesエレメントのフィルターリング

コンテナ、ポッド、ノード、名前空間、クラスターなどのKubernetes要素を除外または含めるには、次のように設定します：

agent:
  config:
    processors:
      # Exclude specific metrics from containers named 'containerXName' or 'containerYName'
      filter/exclude_metrics_from_container:
        metrics:
          exclude:
            match_type: regexp
            resource_attributes:
              - key: k8s.container.name
                value: '^(containerXName|containerYName)$'

      # Exclude logs from pods named 'podNameX'
      filter/exclude_logs_from_pod:
        logs:
          exclude:
            match_type: regexp
            resource_attributes:
              - key: k8s.pod.name
                value: '^(podNameX)$'

      # Exclude logs from nodes named 'nodeNameX'
      filter/exclude_logs_from_node:
        logs:
          exclude:
            match_type: regexp
            resource_attributes:
              - key: k8s.node.name
                value: '^(nodeNameX)$'

      # Exclude spans from traces for services housed in containers named 'containerXName' or 'containerYName'
      filter/exclude_spans_from_traces_from_container:
        spans:
          exclude:
            match_type: regexp
            attributes:
              - key: k8s.container.name
                value: '^(containerXName|containerYName)$'

      # Exclude all telemetry data (metrics, logs, traces) from a namespace named 'namespaceX'
      filter/exclude_all_telemetry_data_from_namespace:
        logs:
          exclude:
            match_type: regexp
            resource_attributes:
              - key: k8s.namespace.name
                value: '^(namespaceX)$'
        metrics:
          exclude:
            match_type: regexp
            resource_attributes:
              - key: k8s.namespace.name
                value: '^(namespaceX)$'
        traces:
          span:
            - 'attributes["k8s.namespace.name"] != "namespaceX"'

      # Exclude metrics from a cluster named 'clusterX'
      filter/exclude_metrics_from_cluster:
        metrics:
          exclude:
            match_type: regexp
            resource_attributes:
              - key: k8s.cluster.name
                value: '^(clusterX)$'

プロセッサーを設定したら、パイプラインを設定します：

# Define the data processing pipelines for logs, metrics, and traces
service:
  pipelines:
    logs:
      processors:
        - memory_limiter
        - k8sattributes
        - filter/logs
        - batch
        - resourcedetection
        - resource
        - resource/logs
        - filter/exclude_logs_from_pod
        - filter/exclude_logs_from_node

OTTL条件を使用してテレメトリをドロップする

OpenTelemetry Transformation Language（OTTL）を使って、より詳細なフィルタリング条件を定義することができます。一致するテレメトリはドロップ（除外）されます。

OTTL では、各テレメトリタイプまたはコンテキストに独自のフィールドがあります。次の例は、使用可能なすべての OTTL コンテキストを表示しています。

processors:
  filter:
     traces:
       span:
         - 'attributes["attribute.label"] == "attribute_value"'
         - 'resource.attributes["host.name"] == "localhost"'
       # Checked only if `span` is not dropped
       spanevent:
         - 'attributes["label"] == true'
         - 'IsMatch(name, ".*http.*") == false'
        # If all span events are dropped, the span is dropped
       metrics:
         metric:
           - 'name == "metric.name" and attributes["label"] == "value"'
           - 'type == METRIC_DATA_TYPE_HISTOGRAM'
         # Checked only if `metric` is not dropped
         datapoint:
           - 'metric.type == METRIC_DATA_TYPE_SUMMARY'
           - 'resource.attributes["service.name"] == "my_service_name"'
          # If all datapoints are dropped, the metric is dropped
       logs:
         log_record:
           - 'IsMatch(body, ".*token.*") == true'
           - 'severity_number < SEVERITY_NUMBER_WARN'

OTTLの関数と構文の詳細については、こちらを参照してください：

設定

次の表は、フィルタープロセッサーのコンフィギュレーション・オプションを示しています：

トラブルシューティング

__ ___ ___ _ ______ _____________ _____ ________ ___ ___ ___ ____ __ ___ ____ ____ __ ______ _____________ ______ ___ ___ ___ ____ __ ___ _________ _____

_________ __ ______ _____________ _____ _________

_________ __ ___________ _________ ___ ____ _____ _____

  • ___ _ ________ ___ ___ _______ _______ _________ _______ __ ______ ________

  • ____ ___ ______ ______________ ____ _____ _____ _______ __ ___________ ____ __________ _________ ___ ______ _________ __________ __ _____ ___ ____ _______