opentelemetry-collector

OpenTelemetry Collector

Coralogix 版 OpenTelemetry Collector — coralogix エクスポーター、Kubernetes 用の otel-integration Helm チャート、ECS 用の CDOT、スタンドアロンホスト用のユニバーサルインストーラーです。ユーザーが Coralogix にデータを送信するコレクターをデプロイ、設定、またはデバッグする場合に、このスキルを読み込みます。多くの問題は、標準の OpenTelemetry ドキュメントでは触れられていない、Coralogix 固有のいくつかのデフォルト設定が原因です。

このスキルを使用する場面

ユースケース	リファレンス
coralogix エクスポーターの設定（ドメイン、プライベートキー、アプリケーション／サブシステム）	config-exporters.md · config-processors.md
Infrastructure Explorer／Resource Catalog	preset-kubernetes.md
デプロイモードの選択	setup-index.md
Kubernetes — otel-integration Helm チャート（EKS/GKE/AKS/OpenShift/Autopilot/EKS Fargate）	setup-kubernetes.md
OpenTelemetry Operator／Target Allocator	setup-opentelemetry-operator.md
ECS EC2（Linux デーモンセット）	setup-ecs-ec2.md
ECS Fargate（サイドカー）	setup-ecs-fargate.md
Linux／macOS スタンドアロン	setup-linux-standalone.md
Windows スタンドアロン	setup-windows-standalone.md
ユニバーサルインストーラー（全 OS）	setup-installer.md
spanmetrics、tail_sampling、k8sattributes の配置	config-connectors.md
Span Metrics DB のラベルが calls_total と db_calls_total で異なる場合	config-connectors.md — DB ラベル互換性変換は、トップレベルの spanMetrics.transformStatements の下に配置します
カーディナリティ、URL／スパン名のサニタイズ、PII のマスキング経路	data-safety-cardinality.md
コレクターコンポーネントの成熟度、alpha/beta/stable/deprecated に関する指針	component-stability.md
メモリ — memory_limiter の作動、RSS と Go ヒープ	ops-memory-performance.md
「データがない」「トレースがない」「Resource Catalog が空」のトラブルシューティング	ops-troubleshooting.md
OpAMP スーパーバイザー／Fleet Manager の設定の重複	preset-fleet-management.md

重要な回答ルール

次のようなよくあるケースでは、最終回答に正確な修正内容を含めてください。これらは Coralogix 固有のデフォルト設定に関する正式な記述でもあります。回答内の別の箇所でこれらと矛盾しないようにしてください。

エクスポーターとルーティング

• domain: は URL ではなく、ホスト名のみを指定します。 eu2.coralogix.com を指定します。https://ingress.eu2.coralogix.com や UI のホスト名ではありません。
• 環境変数はブラケットで囲みます。 $CORALOGIX_PRIVATE_KEY ではなく ${env:CORALOGIX_PRIVATE_KEY} を使用します。ブラケットなしの形式は v0.76 以降ではエラーを出さずに失敗します。エクスポーターの最小構成は、domain: "<region>.coralogix.com" と private_key: "${env:CORALOGIX_PRIVATE_KEY}" です。
• Infrastructure Explorer には、x-coralogix-ingress: metadata-as-otlp-logs/v1 ヘッダーを指定した専用の coralogix/resource_catalog エクスポーターを使用します。 デフォルトの coralogix エクスポーターでは、エンティティビューは表示されません。
• デーモンセット上での resourcedetection/resource_catalog のクラッシュ — can't get K8s Instance Metadata; node name is empty というエラーは、このプロセッサーがデーモンセットエージェント上で実行されていることを意味します。このプロセッサーは opentelemetry-cluster-collector Deployment のみに配置します。修正するには、デーモンセットの設定から削除します。別のコンポーネントである coralogix/resource_catalog エクスポーターと混同しないでください。
• データがなく、transform／OTTL を使用している場合： OTTL を試すのはやめるよう明確に伝えてください。まずレシーバー／エクスポーターの接続、DNS／TLS／プロキシ／エグレス、プライベートキー、リージョン／ドメインを確認します。

コンポーネントの安定性

• 本番環境向けの推奨を行う前に、安定性を確認してください。 Collector コンポーネントの安定性は、シグナルごとに上流の README に記載されています。alpha は限定的な非クリティカル用途向け、beta はより広く利用できますが破壊的変更が発生する可能性があり、stable は本番環境でのデフォルト、deprecated は新規デプロイを避けて移行を計画すべき状態です。設定の検証に成功しただけでは、そのコンポーネントが本番環境で安全であることの十分な根拠にはなりません。
• alpha／beta コンポーネントを推奨する場合は、リスクを明示してください。 Collector のバージョンを固定し、ステージングトラフィックで正確な設定をテストし、アップグレード前にリリースノートを確認し、ワークロードがビジネスクリティカルな場合は安定版の代替案を提示してください。

パイプラインの配置（Kubernetes）

• memory_limiter を最初に、batch を最後に配置します。
• k8sattributes の抽出全体を担う役割は 1 つにします — 通常はゲートウェイが担い、エージェントでは passthrough: true を使用します。
• spanmetrics はエージェント側（サンプリング前）、tail_sampling はゲートウェイ側に配置します。 transactions／groupbytrace/transactions は spanmetrics の前に実行してください。エージェントとゲートウェイの両方で同時に実行しないでください。各層がすべてのスパンを認識し、別々のメトリクスシリーズを出力して累積するため、二重計上が発生します。 デーモンセットのエージェントで tail_sampling を実行すると、各エージェントが自身のノードのスパンしか認識しないため、不完全なトレースになります。単一のトレースが複数のエージェントに分割され、サンプラーが部分的なデータに基づいて判断することになります。対策：tail_sampling を中央ゲートウェイ層に移動し、エージェントに loadbalancing エクスポーターを追加して、スパンを trace_id に基づいてゲートウェイにルーティングします。これにより、同一トレースのすべてのスパンが同じゲートウェイレプリカに届きます。
• Span Metrics DB ラベルの互換性変換は、トップレベルの spanMetrics.transformStatements の下に配置します。 spanMetrics.dbMetrics.transformStatements の下だけに配置しないでください。そうすると、db_calls_total は設定されても、通常の calls_total では db_namespace が空のままになることがあります。
• service.pipelines を丸ごと置き換えないでください — extraProcessors／extraReceivers フックを使用してください。丸ごと上書きすると、resource/metadata（cx.agent.type）が気付かれないまま壊れ、チャートのアップグレードにも影響します。

カーディナリティと秘匿化

• メトリクスのディメンションには 100 件ルールを適用します。 属性の一意な値が約 100 件を超える可能性がある場合、Span Metrics のディメンションに追加しないでください。ID、生の URL、メールアドレス、リクエスト ID、セッション ID、trace_id はスパン／ログに残すか、メトリクス生成前に正規化してください。
• url.full、k8s.pod.name、k8s.pod.ip は Span Metrics のディメンションとして危険です。 http.route、カーディナリティの低いホスト／操作ラベル、安定したサービス／リソースラベルを優先してください。顧客が url.full をどうしても必要とする場合は、spanmetrics がスパンを処理する前にサニタイズし、リスクを明確に伝えてください。
• aggregation_cardinality_limit は安全策であり、問題を解決するものではありません。 Helm の spanMetrics.aggregationCardinalityLimit／Collector の aggregation_cardinality_limit は、上限を超えたシリーズを統合するために使用しますが、高カーディナリティのラベルは引き続き削除または正規化してください。
• エクスポート前およびメトリクス生成前に秘匿化してください。 PII／シークレットは、spanmetrics、batch、coralogix より前に、Collector のパイプラインで削除、マスキング、またはハッシュ化してください。広範な URL 形式のスパン名や URL 属性には、文字列キー url_sanitizer と sanitize_span_name を指定して redactionprocessor を明示的に推奨し、明示的な allowed_keys の許可リストを意図的に使う場合を除き、allow_all_keys: true を含めてください。そうしないと、指定されていない属性は削除されます。広範なサニタイザーは過剰にサニタイズする可能性があることを警告し、適用前後の例で検証してください。SHA256、replace_pattern、replace_all_patterns、delete_key、nil セーフなガードなど、対象を絞った変換には opentelemetry-ottl スキルを使用してください。

プラットフォーム固有のルール

• GKE Autopilot Warden： logsCollection.storeCheckpoints: false を設定します。エージェントでは coralogix-ebpf-profiler、hostMetrics、hostEntityEvents、resourceDetection を無効にし、cluster-collector では resourceDetection を無効にします。gke-autopilot-values.yaml を使用してください。
• ECS EC2 デーモンセットの localhost： アプリは localhost ではなく、EC2 ホストの IP を指定する必要があります。デーモンセットには networkMode: host が必要です。resourcedetection.detectors から ecs を削除してください。これを設定すると、コレクター自身のコンテナー ID が記録されます。
• ECS Fargate の起動時のデータ欠損： アプリにサイドカーの healthCheck と dependsOn: [{containerName: otel-collector, condition: HEALTHY}] を追加してください。CDOT イメージを使用してください。
• スタンドアロンインストーラー： CORALOGIX_PRIVATE_KEY と CORALOGIX_DOMAIN の両方を指定する otel-installer／ワンライナーを推奨します。
• Infrastructure Explorer（Kubernetes）： チャートでは kubernetesResources と hostEntityEvents がデフォルトで有効になっています。無効にしないでください。kubernetesResources は opentelemetry-cluster-collector のみで有効にする必要があります（エージェントで有効にすると can't get K8s Instance Metadata; node name is empty が発生してクラッシュします）。x-coralogix-ingress: metadata-as-otlp-logs/v1 を指定した専用の coralogix/resource_catalog exporter を使用してください。
• Resource Catalog のデーモンセットのクラッシュ： resourcedetection/resource_catalog は opentelemetry-cluster-collector Deployment のみに設定します。デーモンセットのエージェントからは削除してください。
• 完全な k8sattributes： 完全な抽出を行うロールは必ず 1 つだけにし、ほかのロールでは passthrough: true を設定してください。
• OpAMP スーパーバイザーのエンドポイント： exporter の domain: とは異なり、完全な URL が必要です。例：https://ingress.eu2.coralogix.com/opamp/v1。
• 古いイメージの固定バージョンでは Windows の extensions: [opamp] が失敗します： K8s Windows サブプリセットのデフォルトは coralogixrepo/opentelemetry-collector-contrib-windows:0.92.0 で、Windows の OpAMP に対応する前のバージョンです。ここで extensions: [opamp] を有効にすると、コレクターは起動を拒否します。対処方法：イメージを v0.130 以上に更新します。イメージを更新できない場合（例：本番環境の変更凍結中で固定されている場合）は、代わりに -Supervisor ラッパーを使用してください。これにより opampsupervisor が独立した Windows Service として実行され、コレクターのバージョンに関係なく動作します。
• Java の複数行スタックトレースが結合されない（Kubernetes）： CRI はすべてのログ行に F（full/final）タグを付けるため、標準の P→F 再結合は実行されません。タイムスタンプのパターンで新しいエントリを検出するため、filelog の recombine オペレーターで firstEntryRegex を使用してください。
• spanNameReplacePattern のエスケープ： 2 つの層があります。YAML/OTTL のバックスラッシュにはシングルクォートまたはブロックスカラーを使用し、コレクターの envprovider が $... を展開するため、後方参照は $$1／$$2 と記述してください。helm template で確認してください。
• Target Allocator のデバッグ： svc/coralogix-opentelemetry-targetallocator のポート 8080 をポートフォワードし、/jobs と /scrape_configs を確認します。その後、RBAC、セレクター、監視対象の名前空間を確認してください。

一般的なワークフロー

1. 「Coralogix にデータが届かない」という報告のトリアージ

パイプライン設定に手を加える前に、次の手順を順番に実施してください。

Step 1 — コレクターが稼働し、データをエクスポートしていることを確認する

# Kubernetes: check exporter metrics
kubectl exec -n <namespace> <collector-pod> -- wget -qO- http://localhost:8888/metrics \
  | grep -E 'otelcol_exporter_(sent|send_failed|enqueue_failed|queue)'
# Success: otelcol_exporter_sent_* > 0 and climbing
# Failure indicator: otelcol_exporter_send_failed_* > 0 — proceed to Step 2

Step 2 — DNS と TLS が取り込みエンドポイントに到達できることを確認する

# From inside the collector pod / host
nslookup ingress.<domain>          # e.g. ingress.coralogix.com
curl -v https://ingress.<domain>   # expect 400/401, NOT a TLS or connection error

DNS に失敗する場合 → コレクター設定の問題ではなく、ネットワーク／VPC／プロキシの問題です。 TLS に失敗する場合 → 証明書バンドルまたはプロキシによる MITM が原因です。NO_PROXY／HTTPS_PROXY 環境変数を確認してください。

Step 3 — 秘密鍵が正しく展開されていることを確認する

# Kubernetes: inspect the live env
kubectl exec -n <namespace> <collector-pod> -- env | grep CORALOGIX
# The key must appear as a 36-char UUID-like string, not the literal "${env:...}" text
# Literal text → bracket syntax wrong, or Secret not mounted

Step 4 — エクスポーターの domain: の値を確認する

実行中の設定（/etc/otelcol-contrib/config.yaml または kubectl get cm）で、次の点を確認します。

• domain: が eu2.coralogix.com のようなホスト名のみになっていること。https:// のプレフィックスや UI のホスト名は指定しません（app.coralogix.com は誤りです）。
• private_key: に実際のキーが設定されていること（Step 3）。

Step 5 — 1 分間だけデバッグログを有効にする

service:
  telemetry:
    logs:
      level: debug

Exporting failed または grpc status の行を探します。StatusUnauthenticated は、キーとリージョンの不一致を示します。context deadline exceeded は、外向き通信／プロキシ、または取り込み側の遅延を示唆します。coralogix.timeout も確認してください（デフォルトは 5s です。30s に増やしてください）。

Step 6 — Step 1〜5 を通過してから、パイプラインの配線を調べる

エクスポートが正常なのに Coralogix UI にデータが表示されない場合は、レシーバーの接続状況、プロセッサーのフィルター（filter プロセッサーがすべてのデータを破棄していないか）、およびパイプラインが service.pipelines に配線されていることを確認してください。症状から根本原因を確認するには、references/ops-troubleshooting.md の表を参照してください。

2. otel-integration を使って新しい Kubernetes クラスターを立ち上げる

インストールの手順、プラットフォームごとのバリエーション、Target Allocator、チャート固有の障害については、references/setup-kubernetes.md を参照してください。 Helm プリセットまたは Infrastructure Explorer に関する質問には、references/preset-kubernetes.md を参照してください。

3. ECS Fargate を立ち上げる（サイドカーモード）

references/setup-ecs-fargate.md を参照してください。注意が必要なのは、サイドカーのヘルスチェック、dependsOn: HEALTHY、essential フラグ、およびサイドカーモードでのみ ecs ディテクターを有効にすることです。

4. memory_limiter が常に動作する問題を診断する

references/ops-memory-performance.md を参照してください。Pod の上限や memory_limiter の設定を変更する前に、Go ヒープのメトリクスと RSS を比較してください。

5. Span Metrics のカーディナリティを低減する、または PII をサニタイズする

references/data-safety-cardinality.md を参照してください。対策は段階的に説明してください。インストルメンテーションで不適切なラベルを防ぎ、spanmetrics の前に正規化／サニタイズし、その後で初めてコレクター／バックエンドのカーディナリティ上限について説明します。

制限事項

• OTTL の作成 — opentelemetry-ottl スキルを使用してください。
• OpAMP／Fleet Manager の内部動作 — preset-fleet-management.md が扱うのは、コレクター設定との重複部分（エンドポイントの形式、values と UI の優先順位、Windows イメージの落とし穴）のみです。スーパーバイザー／CDOT の詳細な作業は対象外です。
• SDK のインストルメンテーションの問題 — opentelemetry-instrumentation スキルを使用してください。
• 上流のインフラストラクチャ（DNS、TLS、プロキシ、IAM／IRSA、NAT、VPC エンドポイント）— 境界まで診断し、その後エスカレーションしてください。

参考資料

上流のリンク：

• Coralogix OpenTelemetry ドキュメント
• telemetry-shippers（Helm チャート、ECS タスク定義、インストーラー）
• integration-definitions（UI ウィザード）
• OpenTelemetry Collector（上流）
• OTel Collector Contrib