メトリクストランスフォームプロセッサー

メトリクスの名前を変更し、ラベル・キーと値を追加、変更、または削除します。

Splunk Distribution of OpenTelemetry Collector では、メトリクストランスフォームプロセッサーを使用して以下のタスクを実行します：

  • メトリクスの名前を変更します。

  • ラベルのキーと値を追加、名前変更、削除します。

  • ラベルまたはラベル値全体にわたって、メトリクスをスケールおよび集約します。

プロセッサは、メトリクスのバッチ内での名前の変更と集約のみをサポートします。バッチ間の集約は行わないので、複数のノードやクライアントなど、複数のソースからのメトリクスの集約には使用しないでください。

サポートされるオペレーションの完全なリストについては、「利用可能な操作」を参照してください。

注: 属性プロセッサを活用して、アクションを通じてスパン、メトリクス、またはログの属性を削除、ハッシュ、または抽出します。ユースケースには、機密情報の難読化、新しいキーへの値のコピー、属性のバックフィルなどがあります。「属性プロセッサ」を参照してください。スパン全体、ログ、またはメトリクスを含めたり除外したりするには、フィルタープロセッサを使用します。「フィルタープロセッサ」を参照してください。

はじめに

以下の手順に従って、コンポーネントの設定とアクティベーションを行ってください：

  1. Splunk Distribution of the OpenTelemetry Collector をホストまたはコンテナプラットフォームにデプロイします：

  2. 次のセクションで説明するように、metricstransform プロセッサーを設定します。

  3. Collector を再起動します。

サンプル構成

リソースプロセッサーを有効にするには、設定ファイルの metricstransform セクションに processors を追加します。

例：

processors:
  metricstransform:

設定を完了するには、構成ファイルの service セクションの metrics パイプラインにプロセッサを含めます。例：

service:
  pipelines:
    metrics:
      processors: [metricstransform]

設定例

プロセッサを設定するには、メトリクスに適用する変換と操作のリストを指定する必要があります。以降の変換や操作は、前の変換や操作の結果を参照します。

processors:
  metricstransform:
  # transforms is a list of transformations with each element transforming a metric selected by metric name
    transforms:

        # SPECIFY WHICH METRIC(S) TO MATCH

        # include specifies the metric name used to determine which metric(s) to operate on
      - include: <metric_name>

        # match_type specifies whether the include name should be used as a strict match or regexp match, default = strict
        match_type: {strict, regexp}

        # experimental_match_labels specifies the label set against which the metric filter will work. If experimental_match_labels is specified, transforms will only be applied to those metrics which
        # have the provided metric label values. This works for both strict and regexp match_type. This is an experimental feature.
        experimental_match_labels: {<label1>: <label_value1>, <label2>: <label_value2>}

        # SPECIFY THE ACTION TO TAKE ON THE MATCHED METRIC(S)

        # action specifies if the operations (specified below) are performed on metrics in place (update), on an inserted clone (insert), or on a new combined metric (combine)
        action: {update, insert, combine}

        # SPECIFY HOW TO TRANSFORM THE METRIC GENERATED AS A RESULT OF APPLYING THE ABOVE ACTION

        # new_name specifies the updated name of the metric; if action is insert or combine, new_name is required
        new_name: <new_metric_name_inserted>

        # aggregation_type defines how combined data points will be aggregated; if action is combine, aggregation_type is required
        aggregation_type: {sum, mean, min, max}

        # submatch_case specifies the case that should be used when adding label values based on regexp submatches when performing a combine action; leave blank to use the submatch value as is
        submatch_case: {lower, upper}

        # operations contain a list of operations that will be performed on the resulting metric(s)
        operations:
            # action defines the type of operation that will be performed, see examples below for more details
          - action: {add_label, update_label, delete_label_value, toggle_scalar_data_type, experimental_scale_value, aggregate_labels, aggregate_label_values}
            # label specifies the label to operate on
            label: <label>
            # new_label specifies the updated name of the label; if action is add_label, new_label is required
            new_label: <new_label>
            # aggregated_values contains a list of label values that will be aggregated; if action is aggregate_label_values, aggregated_values is required
            aggregated_values: [values...]
            # new_value specifies the updated name of the label value; if action is add_label or aggregate_label_values, new_value is required
            new_value: <new_value>
            # label_value specifies the label value for which points should be deleted; if action is delete_label_value, label_value is required
            label_value: <label_value>
            # label_set contains a list of labels that will remain after aggregation; if action is aggregate_labels, label_set is required
            label_set: [labels...]
            # aggregation_type defines how data points will be aggregated; if action is aggregate_labels or aggregate_label_values, aggregation_type is required
            aggregation_type: {sum, mean, min, max}
            # experimental_scale specifies the scalar to apply to values
            experimental_scale: <scalar>
            # value_actions contain a list of operations that will be performed on the selected label
            value_actions:
                # value specifies the value to operate on
              - value: <current_label_value>
                # new_value specifies the updated value
                new_value: <new_label_value>

操作方法を理解し、いくつかの例を確認するには、「利用可能な操作」を参照してください。

利用可能な操作

プロセッサーは以下の操作を実行できます：

  • メトリクスの名前を変更します。たとえば、system.cpu.usage の名前を system.cpu.usage_time に変更します。

  • ラベルを追加します。たとえば、値 1 の新しいラベル identifier をすべてのポイントに追加できます。

  • ラベルキーの名前を変更します。たとえば、ラベル state の名前を cpu_state に変更します。

  • ラベルの値の名前を変更します。たとえば、ラベル state で、値 idle の名前を - に変更できます。

  • データポイントを削除します。たとえば、ラベル state の値が idle であるポイントをすべて削除します。

  • データタイプを切り替えます。たとえば、int データポイントを double データポイントに変更できます。

  • 値をスケーリングします。たとえば、秒からミリ秒に変換するには、値に 1000 を掛けます。

  • ラベルセット全体を集計します。たとえば、ラベル state だけを保持し、このラベルに同じ値を持つすべてのポイントを平均することができます。

  • ラベルの値を集計します。たとえば、state というラベルの場合、値が user または system であるポイントを used = user + system に合計することができます。

以下が該当します：

  • strict または regexp フィルターを使用して、1つまたは複数のメトリクスにのみ操作を適用できます。

  • action プロパティでは、以下が可能です：

    • メトリクスをインプレースで更新します ( update )。

    • メトリクスをコピーしてコピーしたメトリクス ( insert ) を更新します。

    • メトリクスを、新しく挿入したメトリクスに結合します。このメトリクスは、一致するメトリクスのセットからすべてのデータポイントを単一のメトリクスに結合することによって生成されます（ combine）。元の一致するメトリクスも削除されます。

  • メトリクスの名前を変更すると、regexp フィルターのキャプチャグループが展開されます。

  • ラベル値を追加または更新すると、{{version}} が Collector のインスタンスバージョン番号に置き換えられます。

例: 既存のメトリクスから新しいメトリクスを作成する

既存のメトリクスから新しいメトリクスを作成するには、この設定を適用する：

# create host.cpu.utilization from host.cpu.usage
include: host.cpu.usage
action: insert
new_name: host.cpu.utilization
operations:
  ...

例: ラベル値が一致する既存のメトリクスから新しいメトリクスを作成する

ラベル値が一致する既存のメトリクスから新しいメトリクスを作成するには、この設定を適用します:

# create host.cpu.utilization from host.cpu.usage where we have metric label "container=my_container"
include: host.cpu.usage
action: insert
new_name: host.cpu.utilization
match_type: strict
experimental_match_labels: {"container": "my_container"}
operations:
  ...

例: 正規表現を使って、ラベル値が一致する既存のメトリクスから新しいメトリクスを作成する

正規表現でラベル値が一致する既存のメトリクスから新しいメトリクスを作成するには、この設定を適用します:

# create host.cpu.utilization from host.cpu.usage where we have metric label pod with non-empty values
include: host.cpu.usage
action: insert
new_name: host.cpu.utilization
match_type: regexp
experimental_match_labels: {"pod": "(.|\\s)*\\S(.|\\s)*"}
operations:
  ...

例: メトリクス名の変更

メトリクスの名前を変更するには、この設定を適用する：

# rename system.cpu.usage to system.cpu.usage_time
include: system.cpu.usage
action: update
new_name: system.cpu.usage_time

例: 置換を使用して複数のメトリクスの名前を変更する

置換を使用して複数のメトリクスの名前を変更するには、この設定を適用します：

# rename all system.cpu metrics to system.processor.*.stat
# instead of regular $ use double dollar $$. Because $ is treated as a special character.
# wrap the group name/number with braces
include: ^system\.cpu\.(.*)$$
match_type: regexp
action: update
new_name: system.processor.$${1}.stat

例: ラベルの追加

ラベルを追加するには、この設定を適用します:

# for system.cpu.usage_time, add label `version` with value `opentelemetry collector vX.Y.Z` to all points
include: system.cpu.usage
action: update
operations:
  - action: add_label
    new_label: version
    new_value: opentelemetry collector {{version}}

例: 複数のメトリクスにラベルを追加する

複数のメトリクスにラベルを追加するには、この設定を適用します：

# for all system metrics, add label `version` with value `opentelemetry collector vX.Y.Z` to all points
include: ^system\.
match_type: regexp
action: update
operations:
  - action: add_label
    new_label: version
    new_value: opentelemetry collector {{version}}

例: ラベル名の変更

ラベルの名前を変更するには、この設定を適用します:

# for system.cpu.usage_time, rename the label state to cpu_state
include: system.cpu.usage
action: update
operations:
  - action: update_label
    label: state
    new_label: cpu_state

例: 複数のメトリクスのラベル名を変更する

複数のメトリクスのラベル名を変更するには、この設定を適用する：

# for all system.cpu metrics, rename the label state to cpu_state
include: ^system\.cpu\.
action: update
operations:
  - action: update_label
    label: state
    new_label: cpu_state

例: ラベル値の名前を変更する

ラベル値の名前を変更するには、この設定を適用します:

# rename the label value slab_reclaimable to sreclaimable, slab_unreclaimable to sunreclaimable
include: system.memory.usage
action: update
operations:
  - action: update_label
    label: state
    value_actions:
      - value: slab_reclaimable
        new_value: sreclaimable
      - value: slab_unreclaimable
        new_value: sunreclaimable

例: ラベル値による削除

ラベルの値で削除するには、この設定を適用します：

# deletes all data points with the label value 'idle' of the label 'state'
include: system.cpu.usage
action: update
operations:
  - action: delete_label_value
    label: state
    label_value: idle

例: データ型を切り替える

データ型を切り替えるには、この設定を適用します:

# toggle the datatype of cpu usage from int (the default) to double
include: system.cpu.usage
action: update
operations:
  - action: toggle_scalar_data_type

例: スケール値

値をスケーリングするには、この設定を適用します:

# experimental_scale CPU usage from seconds to milliseconds
include: system.cpu.usage
action: update
operations:
  - action: experimental_scale_value
    experimental_scale: 1000

例: ラベルを集計する

ラベルを集約するには、この設定を適用します:

# aggregate away all labels except `state` using summation
include: system.cpu.usage
action: update
operations:
  - action: aggregate_labels
    label_set: [ state ]
    aggregation_type: sum

例: ラベル値を集計する

ラベル値を集約するには、この設定を適用します:

# aggregate data points with state label value slab_reclaimable & slab_unreclaimable using summation into slab
include: system.memory.usage
action: update
operations:
  - action: aggregate_label_values
    label: state
    aggregated_values: [ slab_reclaimable, slab_unreclaimable ]
    new_value: slab
    aggregation_type: sum

例: メトリクスを組み合わせる

メトリクスを組み合わせるには、この設定を適用します：

# convert a set of metrics for each http_method into a single metric with an http_method label, i.e.
#
# Web Service (*)/Total Delete Requests     iis.requests{http_method=delete}
# Web Service (*)/Total Get Requests     >  iis.requests{http_method=get}
# Web Service (*)/Total Post Requests       iis.requests{http_method=post}
include: ^Web Service \(\*\)/Total (?P<http_method>.*) Requests$
match_type: regexp
action: combine
new_name: iis.requests
submatch_case: lower
operations:
  ...

例: メトリクスのグループ化

メトリクススをグループ化するには、この設定を適用する：

# Group metrics from one single ResourceMetrics and report them as multiple ResourceMetrics.
#
# ex: Consider pod and container metrics collected from Kubernetes. Both the metrics are recorded under under one ResourceMetric
# applying this transformation will result in two separate ResourceMetric packets with corresponding resource labels in the resource headers
#
# instead of regular $ use double dollar $$. Because $ is treated as a special character.

- include: ^k8s\.pod\.(.*)$$
  match_type: regexp
  action: group
  group_resource_labels: {"resouce.type": "k8s.pod", "source": "kubelet"}
- include: ^container\.(.*)$$
  match_type: regexp
  action: group
  group_resource_labels: {"resouce.type": "container", "source": "kubelet"}

設定

次の表は、metricstransform プロセッサーの構成オプションを示します：

同梱

https://raw.githubusercontent.com/splunk/collector-config-tools/main/cfg-metadata/processor/metricstransform.yaml

トラブルシューティング

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

_________ __ ______ _____________ _____ _________

_________ __ ___________ _________ ___ ____ _____ _____

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

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