cx-data-pipeline

データパイプラインスキル

Coralogix がデータを処理、エンリッチメント、変換する方法を設定する際に、このスキルを使用します。解析ルール（生ログから構造化フィールドを抽出）、エンリッチメント（ルックアップテーブルからコンテキストを追加）、Events2Metrics（ログ／スパンイベントからメトリクスを導出）、記録ルール（PromQL 式を事前計算）を扱います。

---

CLI コマンド

コマンド	サブコマンド	用途
cx parsing-rules	list、get、create、update、delete、bulk-delete、usage-limits	ログ解析ルールを管理します
cx enrichments	list、add、remove、overwrite、limit、settings	エンリッチメントルールを管理します
cx enrichments custom	list、get、create、update、delete、search	カスタムエンリッチメントテーブルを管理します
cx e2m	list、get、create、update、delete、labels-cardinality、limits	Events2Metrics の定義を管理します
cx recording-rules	list、get、create、update、delete	Prometheus の記録ルールグループを管理します

主なフラグ：

• すべての作成／更新操作では --from-file <path>（または標準入力の場合は -）を使用します
• すべてのコマンドで、構造化出力用の -o json とプロファイル選択用の -p <profile> を使用できます
• cx parsing-rules update と cx recording-rules update では、--from-file とルールグループ ID の両方が必要です
• cx enrichments custom search では、--id <table-id> と --query <text> が必要です
• cx parsing-rules bulk-delete では、--ids <id1> <id2> ... が必要です

---

JSON ペイロードの操作

これらのコマンドでは複雑な JSON 構造を使用します。形式エラーを避けるため、必ず既存のリソースをテンプレートとして使用してください。

# 1. Get an existing resource as a template
cx parsing-rules get <rule-group-id> -o json > template.json

# 2. Modify the template (change fields, remove the ID for create operations)

# 3. Create or update
cx parsing-rules create --from-file template.json
cx parsing-rules update --from-file template.json <rule-group-id>

このパターンは、4 つすべてのコマンドにおけるすべての作成／更新操作に適用されます。ペイロード形式のエラーは、試行が失敗する最大の原因であり、このパターンによって防止できます。

---

解析ルールのワークフロー

1. 既存のルールを一覧表示する

cx parsing-rules list -o json
cx parsing-rules list -o json | jq '[.[] | {id, name, enabled, rule_count: (.rules | length)}]'

2. テンプレートを取得する

cx parsing-rules get <existing-rule-group-id> -o json > rule-template.json

3. 新しいルールグループを作成する

新しいサービス用にテンプレートを編集し、次を実行します。

cx parsing-rules create --from-file rule-template.json

4. 解析を検証する

最近のログをクエリして、フィールドが抽出されていることを確認します（ログのクエリには cx-telemetry-querying を読み込みます）。

cx logs 'source logs | filter $d.subsystem == "my-service" | limit 10' -o json

5. 使用量の上限を確認する

cx parsing-rules usage-limits -o json

---

エンリッチメントのワークフロー

1. エンリッチメントルールを一覧表示する

cx enrichments list -o json
cx enrichments settings -o json
cx enrichments limit -o json

2. カスタムエンリッチメントテーブルを作成する（必要な場合）

cx enrichments custom list -o json
cx enrichments custom create --from-file table-definition.json

table-definition.json は v5 の JSON 形式を使用する必要があります（マルチパートの file=@... ではなく、ファイル内容を直接指定します）。

{
  "name": "IP Lookup",
  "description": "Maps IPs to locations",
  "file": {
    "textual": "ip,city\n1.2.3.4,London",
    "extension": "csv",
    "name": "lookup.csv",
    "size": 24
  }
}

更新する場合は、customEnrichmentId（数値）と同じフィールドを含めてください。

3. エンリッチメントルールを追加する

cx enrichments add --from-file enrichment-rules.json

enrichment-rules.json では requestEnrichments を使用する必要があります（一覧表示の出力にある enrichments ではありません）。各 enrichmentType は文字列ではなくオブジェクトです。

{
  "requestEnrichments": [
    {
      "fieldName": "sourceIPs",
      "enrichmentType": { "geoIp": { "withAsn": true } }
    }
  ]
}

その他のタイプ：{"aws": {"resourceType": "ec2"}}、{"suspiciousIp": {}}、{"customEnrichment": {"id": 1}}。

4. カスタムテーブルのデータを検索する

cx enrichments custom search --id <table-id> --query "search term"

5. エンリッチメント済みフィールドを検証する

ホットストレージ（FrequentSearch ティア）上のログをクエリし、エンリッチメント済みフィールドが表示されることを確認します。取り込みの遅延によって偽陰性が発生する可能性があるため、検証にはアーカイブをクエリしないでください。

cx logs 'source logs | filter $d.enriched_field != null | limit 5' -o json

---

Events2Metrics のワークフロー

E2M はログ／スパンイベントから Prometheus メトリクスを導出します。完全な JSON ワイヤー形式、列挙型、カーディナリティルールについては、references/e2m-schemas.md を参照してください。

E2M の計算方法（まずお読みください）

E2M は、イベントがリアルタイム取り込みパイプラインを通過する際に集約し、メトリクス系列（解像度は約 1 分）を生成します。処理は前向きのみです。メトリクスの生成は E2M の作成時点から始まり、バックフィルはありません。

取り込まれたデータはすべてパイプラインを通過します。TCO ポリシーによって各ストリームがティアに振り分けられ、そのティアによって利用可能な機能が決まります。

TCO ティア	ストレージ	E2M／アラート／ダッシュボード
High	Frequent Search（ホット、OpenSearch）	✅ 利用可能
Medium	S3 アーカイブ（ホットストレージではありません）	✅ 利用可能 — パイプラインで引き続き処理されます
Low	コンプライアンスのみ	❌ 集約機能は利用できません
Blocked	破棄	❌

基準となるのはティア／処理レベルであり、「Frequent Search とアーカイブのどちらか」ではありません（Medium はアーカイブですが、E2M は機能します）。「Frequent Search ではなくアーカイブを E2M の対象にする」ようユーザーに案内しないでください。これは誤りです。

1. メトリクスを設計する

logs2metrics と spans2metrics のどちらを使うか、ソースフィールドと集約方法、ラベルを選びます（カーディナリティに注意してください。references/e2m-schemas.md を参照）。E2M の対象をデータセットに絞るには、省略可能な dataSource フィールドに "<dataspace>/<dataset>" を設定します。この設定にはアカウント機能 e2m_dataset_source_enabled が必要です（有効でない場合、API は「dataSource is not enabled for this company」というエラーを返します）。標準のログ／スパンストリームを対象にする場合は、このフィールドを省略してください。

2. サイズを決める：制限とカーディナリティを確認する

cx e2m limits -o json              # account E2M count limit + used
cx e2m labels-cardinality -o json  # see caveat below

ラベルカーディナリティのエンドポイントはドラフトの予測機能です。提案したラベルとクエリを指定すると、過去 7 日間における日ごとの一意な組み合わせ数を返すため、作成前に設計のサイズを見積もれます。ただし、現在 cx e2m labels-cardinality は引数を受け取らないため、ドラフトを送信せず、空のリストを返します（CLI の機能不足により、現時点では予測できません）。この機能が連携されるまでは、UI で予測するか、一意なラベル値の積から組み合わせ数を手動で見積もり、permutationsLimit を設定してください。カーディナリティの高いフィールド（ID、生の URL、IP アドレスなど）をラベルに使用しないでください。この予測で参照されるのは Frequent Search（High ティア）のデータのみです。

3. 既存の定義からテンプレートを作成する

完全なペイロード（{"e2m": {...}}）を返すのは cx e2m get のみです。list は概要を出力します。.e2m を抽出し、読み取り専用フィールドを削除します。

cx e2m get <existing-e2m-id> -o json | jq '.e2m | del(.id, .permutations, .createTime, .updateTime, .metricName)' > e2m.json

4. E2M を作成する

cx e2m create --from-file e2m.json

5. メトリクスを確認する

系列が生成されていることを確認します（メトリクスのクエリについては cx-telemetry-querying を読み込んでください）。

cx metrics search --name "<targetBaseMetricName>"
cx metrics query "<target_metric_name>" --time now

トラブルシューティング：E2M がメトリクス系列を生成しない

1. ソースデータの TCO ティアを確認します — Low／コンプライアンスに振り分けられている場合（またはブロックされている場合）、E2M は実行できません。E2M を変更するのではなく、TCO を変更して対処してください（cx tco list／cx-cost-optimization）。
2. クエリがストリーミングデータに一致することを確認します — E2M の lucene フィルターをライブの cx logs／cx spans クエリとして実行し、最近の結果が返されることを確認します。cx logs はデフォルトで Frequent Search（High ティア）をクエリします。**Medium ティア（アーカイブ）**のソースの場合は --tier archive を追加してください。E2M は引き続き系列を生成しますが、デフォルトの Frequent Search クエリにはデータが表示されないためです。
3. 前向きのみであることを忘れないでください — E2M の作成前に取り込まれたデータについて、系列は生成されません。

コストの最適化：High ティアのログをメトリクスに変換する

集約／メトリクスビューが顧客にとって最も重要な場合は、High ティアのログをメトリクスに変換してから、生ログのティアをHigh から Medium に下げます。Medium でも E2M／アラート／ダッシュボードを利用でき、コストも抑えられます（S3 アーカイブで、ホットストレージは使用しません）。高価な Frequent Search の保持をやめつつ、詳細なメトリクスを低コストで維持できます。

1. 使用量の多い High ティアのソースを特定します：cx usage summary／cx tco list（cx-cost-optimization を参照）。
2. ダッシュボード／アラートに必要なフィールドを確認します（cx-telemetry-querying を参照）。
3. まず E2M を構築して動作を確認します（上記の手順を参照）。
4. その後で TCO ポリシーを変更し、生ログを High から Medium に移します。データは High または Medium に保持してください（どちらも E2M をサポートします）。メトリクスやアラートが引き続き必要な場合は、データを Low／コンプライアンスに移さないでください。

---

レコーディングルールのワークフロー

1. 既存のレコーディングルールを一覧表示する

cx recording-rules list -o json
cx recording-rules list -o json | jq '[.[] | {id, name, rules: [.rules[]?.record]}]'

2. テンプレートを取得する

cx recording-rules get <existing-id> -o json > recording-rule-template.json

3. レコーディングルールグループを作成する

cx recording-rules create --from-file recording-rule-group.json

4. PromQL で検証する

事前計算済みのメトリクスが利用可能であることを確認します（メトリクスのクエリには cx-telemetry-querying を読み込みます）。

cx metrics query "new_precomputed_metric" --time now

---

主な原則

• 必ず既存の設定からテンプレートを作成する - 作成する前に cx <command> get <id> -o json > template.json を実行します
• 作成後に検証する - ログ／メトリクスをクエリし、パイプラインの変更が反映されたことを確認します
• -o json を使用する - すべてのペイロードの確認と作成には JSON 出力を使用します
• 最初に上限を確認する - 上限に達しないよう、作成前に cx parsing-rules usage-limits と cx e2m limits を実行します
• 一括操作 - 個別に削除するのではなく、クリーンアップには cx parsing-rules bulk-delete --ids を使用します

---

追加リソース

参考ファイル

• references/e2m-schemas.md - Events2Metrics の JSON ワイヤ形式の全容：type／aggType の列挙値、logsQuery／spansQuery のフィルター、メトリクスのラベルとフィールド、TCO ティアのコンピューティングモデル、カーディナリティと順列のサイジング、注意事項

---

関連スキル

• cx-telemetry-querying - パイプラインを設定する前に利用可能なデータを調べ、ログ／メトリクスのクエリでパース結果、エンリッチされたフィールド、E2M メトリクスシリーズを検証します
• cx-cost-optimization - メトリクスへの変換に適した大量の High ティアソースを見つけ、E2M の検証後に生ログを High から Medium（TCO）へ移動します