クライアントトークンは、ブラウザやモバイルアプリケーションなどのフロントエンドからトレースを投稿するための専用トークンです。
クライアントトークンとは
Mackerelでトレースを投稿するには通常APIキーを使用しますが、フロントエンドやモバイルアプリケーションにAPIキーを埋め込むとエンドユーザーに露出するリスクがあります。APIキーはトレース投稿以外にも多くの操作が可能なため、露出した場合の影響が大きくなります。
フロントエンドやモバイルアプリケーションからトレースを投稿する際のセキュリティリスクを軽減するために、クライアントトークンが提供されています。クライアントトークンはスコープがトレース投稿のみに限定されているため、エンドユーザー向けのアプリケーションのコードに安全に埋め込むことができます。
APIキーとの違い
| クライアントトークン | APIキー | |
|---|---|---|
| スコープ | トレース投稿のみ | 全API操作（Read/Write権限に応じて） |
| 認証ヘッダー | X-Mackerel-Client-Token |
Mackerel-Api-Key |
| 用途 | フロントエンド（ブラウザ、モバイル） | サーバーサイド |
| 個別のレートリミット設定 | 可能（トークンごと） | 不可 |
クライアントトークンの作成
クライアントトークンはダッシュボードのクライアントトークンタブから作成できます。作成にはオーナーまたは管理者の権限が必要です。
トークン作成時に以下の項目を設定できます。
- 名前: トークンの識別用の名前
- メモ: トークンに関する補足情報
- トレース投稿のレートリミット（スパン/分）: トークンごとのレートリミット（未設定時はオーガニゼーションのデフォルトレートリミットが適用されます）
作成されたトークンは64文字の英数字文字列です。
クライアントトークンの削除
不要になったクライアントトークンはダッシュボードから削除できます。トークンを削除すると、そのトークンを使用したトレースの投稿は即座に拒否されるようになります。
トークンの削除時には、オーガニゼーションのオーナーと管理者にメール通知が送信されます。
レートリミット
クライアントトークンにはトークンごとのトレース投稿のレートリミット（スパン/分）を設定できます。フロントエンドからは不特定多数のユーザーによる大量のトレースが投稿される可能性があるため、適切なレートリミットの設定を推奨します。
レートリミットは以下の順序で評価されます。
- トークンごとのレートリミット（
トレース投稿のレートリミットで設定した値） - オーガニゼーション全体のレートリミット
いずれかのレートリミットを超過した場合、それ以降のスパンは受信拒否され、送信側には429エラーが返ります。
トークンごとのレートリミットが未設定の場合は、オーガニゼーション全体のレートリミットのみが適用されます。
サンプリングの推奨
フロントエンドからのトレースはユーザー数に比例して大量に発生するため、適切なサンプリングの設定を強く推奨します。
OpenTelemetry SDKでは標準的にサンプリング機能が提供されています。例えば、TraceIdRatioBasedSampler を使用すると、トレースの一定割合のみを送信するように設定できます。
import { TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base'; const provider = new WebTracerProvider({ sampler: new TraceIdRatioBasedSampler(0.1), // 10%のトレースのみ記録 });
利用方法
クライアントトークンを使用してブラウザからトレースを投稿する具体的な方法は、以下のページを参照してください。
