分散トレース：OpenTelemetry

分散トレース： OpenTelemetry

1）なぜOTelとそれが与えるもの

• リクエストパス（ゲートウェイ→サービス→DB/キャッシュ/キュー）のエンドツーエンドの可視性。
• 高速RCA/デバッグの劣化とリリース（カナリア/ブルーグリーン）。
• SLOおよび自動ロールバック（データに基づく運用ソリューション）との連携).
• Vendor-agnostic： 1つのAPMにバインディングすることなく、バックエンドにエクスポートします。

参照原理：標準化、サンプルスマート、デフォルトで安全、すべての関連付け。

2）基本： コンテキスト、スパン、属性

トレース-コールツリー/グラフ；スパン-操作（RPC、 SQL、キュー呼び出し）。
Span Kind： 'SERVER'、 'CLIENT'、 'PRODUCER'、 'CONSUMER'、 'INTERNAL'。
W3Cトレースのコンテキスト：'traceparent'、 'tracestate'ヘッダー；コンテキストはサービス間で実行されます。
属性-キー値（低cardinality！）、イベント-タイムスタンプ、ステータス-エラーコード/説明。
リンク-リンクは厳密な階層の外に広がります（非同期/ファンアウト/ファンインに重要です）。

• HTTP： 'HTTP {METHOD}'（属性として'GET/withdraw'）
• DB： 'DB SELECT'/'DB INSERT'
• キュー：'QUEUE publish topic=X'/'QUEUE consume topic=X'

3）セマンティック規則（semconv）

• HTTP/GRPC： 'http。メソッド'、'http。ルート'、'http。status_code'、 'url。「フル」
• DB： 'db。system=postgresql'、'db。statement '（safe squeeze！のみ）、'db。名前'。
• メッセージング：'メッセージング。system=kafka'、'messaging。operation=receive'、'messaging。デスティネーション'。
• Cloud/K8s/Host： 'cloud。region'、'k8s。ポッド。名前'、'コンテナ。ID。
• リソース属性（必須）：'service。名前'、'サービス。バージョン'、'deployment。「environment」

SDK/Collectorリソースの'schemaUrl'でスキーマの安定性を指定します。

4）見本抽出： 頭部、適応性がある尾

ヘッドベース（SDKで）：事前に決定、安い；高いQPSのためによいが「興味深い」トラックを逃すかもしれない。
テールベース（コレクター内）：トラックの完了後に決定します。ステータス、レイテンシ、属性によるルールを許可します。
Adaptive/Dynamic： p95エラー/成長のサンプルシェアを上げます。

生産レベルのレシピ：ヘッド1-5％グローバル+「重要」のテール選択：'status=ERROR'、 'latency> p95'、 「money routes」、 PSP/KYCエラー。

5）相関： メトリクス、ログ、トレイル

例：メトリックヒストグラムで'trace_id'を持つラベル（トラックにクイックジャンプ）。
ログ：'trace_id'/'span_id'を追加し、ログからトレースに切り替えます。
SpanMetrics（プロセッサ）は、SLO/アラートのREDメトリック（'request、 errors、 duration'）トレースから集約されます。

6）導入アーキテクチャ

各ノードのエージェント（DaemonSet）は、アプリケーション（OTLP）から収集し、転送します。
ゲートウェイ（Cluster/Region）-ルーティング/サンプリング/エンリッチメントパイプラインを備えたCentral Collector（多くのレプリカ）。
OTLP： gRPC '4317'、 HTTP '4318'；TLS/mTLSを有効にします。

「エージェント+ゲートウェイ」の長所：分離、バッファリング、ローカルバックプレッシャー、簡素化されたネットワーク。

7） OpenTelemetry Collector-基本テンプレート（ゲートウェイ）

yaml receivers:
otlp:
protocols:
grpc: { endpoint: 0. 0. 0. 0:4317 }
http: { endpoint: 0. 0. 0. 0:4318 }

processors:
memory_limiter: { check_interval: 5s, limit_percentage: 75 }
batch: { timeout: 2s, send_batch_size: 8192 }
attributes:
actions:
- key: deployment. environment action: upsert value: prod resource:
attributes:
- key: service. namespace action: upsert value: core tail_sampling:
decision_wait: 5s policies:
- name: errors type: status_code status_code: { status_codes: [ERROR] }
- name: slow_traces type: latency latency: { threshold_ms: 800 }
- name: important_routes type: string_attribute string_attribute:
key: http. route values: ["/withdraw", "/deposit"]
- name: baseline_prob type: probabilistic probabilistic: { sampling_percentage: 5 }

exporters:
otlp/apm:
endpoint: apm-backend:4317 tls: { insecure: true }
prometheus:
endpoint: 0. 0. 0. 0:9464

extensions:
health_check: {}
pprof: { endpoint: 0. 0. 0. 0:1777 }
zpages: { endpoint: 0. 0. 0. 0:55679 }

service:
extensions: [health_check, pprof, zpages]
pipelines:
traces:  { receivers: [otlp], processors: [memory_limiter,attributes,resource,batch,tail_sampling], exporters: [otlp/apm] }
metrics: { receivers: [otlp], processors: [batch], exporters: [prometheus] }
logs:   { receivers: [otlp], processors: [batch], exporters: [] }

8） SpanMetricsとRED for SLO

yaml processors:
spanmetrics:
metrics_exporter: prometheus histogram:
explicit:
buckets: [50ms,100ms,200ms,400ms,800ms,1600ms,3200ms]
service:
pipelines:
traces: { receivers: [otlp], processors: [spanmetrics,batch,tail_sampling], exporters: [otlp/apm] }
metrics: { receivers: [otlp], processors: [batch], exporters: [prometheus] }

SLO/アラートには'traces_spanmetrics_calls {service、 route、 code}'と'duration_bucket'があります。

9） K8s： Collectorの展開（DaemonSet+展開）

yaml apiVersion: apps/v1 kind: DaemonSet metadata: { name: otel-agent, namespace: observability }
spec:
template:
spec:
containers:
- name: otelcol image: otel/opentelemetry-collector:latest args: ["--config=/conf/agent. yaml"]
ports:
- { containerPort: 4317, name: otlp-grpc }
- { containerPort: 4318, name: otlp-http }

ゲートウェイ（展開）-いくつかのレプリカ、Service ClusterIP/Ingress、 CPU/QPSによるHPA。

10）セキュリティとプライバシー

TLS/mTLS между SDK→エージェント→ゲートウェイ→バックエンド。
ゲートウェイ入力の認証（Basic/OAuth/Headers）；起源を制限します。
PIIリビジョン：filter/mask属性（'user。電子メール'、'カード。'）コレクタープロセッサで。
制限：SDKでは、イベントサイズ/属性数（カーディナリティ保護）を制限します。
バックエンド+個々のプロジェクト/テナント名前空間のRBAC。

yaml processors:
attributes/redact:
actions:
- key: user. email action: delete
- key: payment. card action: delete

11）計装： クイックスタート

ノード。js： js

js import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes as R } from "@opentelemetry/semantic-conventions";

const sdk = new NodeSDK({
traceExporter: new OTLPTraceExporter({ url: "http://otel-agent. observability:4317" }),
resource: new Resource({
[R.SERVICE_NAME]: "payments-api",
[R.SERVICE_VERSION]: "1. 14. 2",
[R.DEPLOYMENT_ENVIRONMENT]: "prod"
}),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk. start();

Java（春）

java
// Gradle: io. opentelemetry. instrumentation:opentelemetry-spring-boot-starter
// application. yml otel:
service:
name: orders-api exporter:
otlp:
endpoint: http://otel-agent. observability:4317 traces:
sampler: parentbased_traceidratio sampler-arg: 0. 05

Python （FastAPI）

python from opentelemetry import trace from opentelemetry. sdk. resources import Resource from opentelemetry. exporter. otlp. proto. grpc. trace_exporter import OTLPSpanExporter from opentelemetry. sdk. trace import TracerProvider from opentelemetry. sdk. trace. export import BatchSpanProcessor

provider = TracerProvider(resource=Resource. create({"service. name":"fraud-scoring","deployment. environment":"prod"}))
provider. add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-agent. observability:4317", insecure=True)))
trace. set_tracer_provider(provider)

Go

go exp, _:= otlptracegrpc. New(ctx, otlptracegrpc. WithEndpoint("otel-agent. observability:4317"), otlptracegrpc. WithInsecure())
res:= resource. NewWithAttributes(semconv. SchemaURL, semconv. ServiceNameKey. String("gateway"), semconv. DeploymentEnvironmentKey. String("prod"))
tp:= sdktrace. NewTracerProvider(sdktrace. WithBatcher(exp), sdktrace. WithResource(res), sdktrace. WithSampler(sdktrace. ParentBased(sdktrace. TraceIDRatioBased(0. 05))))
otel. SetTracerProvider(tp)

12）非同期： キュー、バス、cron

PRODUCER/CONSUMER「リンク」を通じたコミュニケーション（メッセージには独自のライフサイクルがあります）。
コンテキストをメッセージヘッダー（'traceparent'/'baggage'）に伝播します。
バッチ消費時には、メッセージごとにスパンを作成するか、'messaging属性で集計します。バッチだ。サイズ'。
cron/jobsの場合：実行する新しいトレース+プライマリイベントへのリンク（もしあれば）。

13）手荷物とターゲティング

最小限の安定したキー（'tenant_id'、 'region'、 'vip_tier'）を手荷物に保管します。PIIを禁止します。
ゲートウェイ/ゲートウェイロガーをプッシュして、その後のセグメント別のメトリックの集計を行います。

14）リリースとSLOゲートとの統合

カナリアステップ→ルート/サブセグメントの"traces_spanmetrics _'をチェックします。
劣化中（5xx/p95）-自動停止およびロールバック（Argo Rollouts AnalysisTemplate+PromQL）。
メトリックからのインスタンスは、リリース間隔の「悪い」トラックに直結します。

15）限界とパフォーマンス

'OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT'、 'OTEL_SPAN_EVENT_COUNT_LIMIT'、 'OTEL_ATTRIBUTE_VALUE_LENGTH IMIT''。
確率/頻度によるサンプル/スタックトレースの例外。
SDKおよびコレクターのバッチプロセッサ；バーストが発生したときにトラックを失うことを避けるためにキューを保ちます。

16）相互運用性と移行

プロパゲータ：W3Cを使用します。二重伝播B3/X-Ray読書を支えて下さい。
輸出：OTLP→APM （Jaeger/Tempo/Elastic/X線、等）。
semconvの安定したバージョン-'schemaUrl'を修正し、アップグレードを計画します。

17）アンチパターン

属性の高いカーディナリティ（ラベル、動的キーの'user_id'）。
trace_id→相関なしのログ。
アプリケーションから直接インターネットAPMにエクスポート（ゲートウェイなし、TLS/mTLSなし）。
「のみ」を収集する100％売上高は高価で無意味です。
'dbにユーザーデータを含むSQLクエリをダンプします。ステートメント'。
一貫性のないサービス/バージョン名-メトリックは「crumbling」です。

18）実装チェックリスト（0-45日）

0-10日

2-3の重要なサービスでSDK/自動計装を有効にします。
TLSでAgent （DaemonSet）+Gateway （Deployment）、 OTLP 4317/4318を構成します。
サービスを追加します。名前'、'サービス。バージョン'、'deployment。環境はどこにでもあります。

11-25日

エラー/レイテンシ/」お金」ルートによるテールサンプリング。
SpanMetrics→Prometheus、 ExemplarsとRED/SLOダッシュボードを含む。
API ゲートウェイ/NGINX/メッシュを介してW3Cを伝播します。ログを関連付けます。

26-45日

カバーキュー/DB/キャッシュ；非同期のためのリンク。
CollectorのPII版ポリシー;SDKの属性制限。
リリースと自動ロールバックのSLOゲートを統合します。

19）成熟度の指標

トレース≥ 95％（サンプリングヘッド/テールを含む）の受信リクエストカバレッジ。
Exemplarsのメトリクスのシェア≥ 80％です。
RCA時間「メートルからトレース」≤ 2分（p50）。
0属性/イベント（スキャナ）のPIIリーク。
すべてのサービスにサービスがあります。name/version/environmentとconsistent semantics。

20）付録： 有用な断片

nginx proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;
proxy_set_header baggage   $http_baggage;

histogram_quantile(0. 95, sum(rate(traces_spanmetrics_duration_bucket{route="/withdraw"}[5m])) by (le))

ポリシー： PII属性の禁止（擬似リンタ）

yaml forbid_attributes:
- user. email
- payment. card
- personal.

21）結論

OpenTelemetryは、オブザビリティを標準化された管理可能な回路に変えます。統一されたセマンティクス、安全な伝播、スマートサンプリング、およびメトリックとログとの強い相関です。エージェント+ゲートウェイを構築し、テールサンプリング、スパンメトリクス、Examplarsを追加し、PIIとカーディナリティを監視します。トレースは、デバッグだけでなく、SRE/リリースソリューションの自動化のためのツールとなり、リリースごとにMTTRとリスクを削減します。