Trackio documentation
環境変数
環境変数
Trackio は、Hugging Face Spaces へのデプロイやデータの永続化など、動作のさまざまな側面を設定するために環境変数を使用します。このガイドでは、主な環境変数とその使用方法について説明します。
コア環境変数
TRACKIO_DIR
Trackioデータの保存に使用するカスタムディレクトリを指定します。デフォルトでは、Trackioはデータを~/.cache/huggingface/trackio/に保存します。
export TRACKIO_DIR="/path/to/trackio/data"注: この環境変数は、Trackio が永続ストレージを有効にした Space で実行されていない限り適用されます。Trackio が永続ストレージを有効にした Space で実行されている場合(PERSISTANT_STORAGE_ENABLED 環境変数で検出されます)、Trackio のデータは /data/trackio に保存されます。
TRACKIO_SERVER_URL
セルフホストされた Trackio サーバーのベース URL（http:// または https://）。クエリ文字列に write_token を含めることもできます（trackio.show() の full_url のように）。また、URL をそのままにして TRACKIO_WRITE_TOKEN を設定することもできます。設定すると、trackio.init() はメトリクスをそのサーバーに送信します。trackio.init() に server_url= を渡すことと同等です。
優先順位: TRACKIO_SPACE_ID も設定されている場合（またはコードで space_id が渡されている場合）、Hugging Face Space が使用され、TRACKIO_SERVER_URL は無視されます。space_id と server_url の両方が渡される場合も同じルールで、space_id が優先されます。
サーバーのセルフホスティングを参照してください。
export TRACKIO_SERVER_URL="http://127.0.0.1:7860"
export TRACKIO_WRITE_TOKEN="YOUR_TOKEN"TRACKIO_WRITE_TOKEN
セルフホストされた Trackio サーバーのダッシュボード書き込みトークン（書き込みアクセス URL の write_token クエリパラメータと同じ値です）。Trackio サーバーで設定された場合、この値が起動時にランダムなトークンを生成する代わりに、サーバーの書き込みトークンとして使用されます。Trackio クライアントで設定された場合、TRACKIO_SERVER_URL または server_url がクエリパラメータを含まないベース URL である場合に使用します。クライアントは各リクエストでこのトークンを送信します（X-Trackio-Write-Token ヘッダーとしてなど）。これにより、Hugging Face Spaces 上で実行していない場合でも、メトリクスの取り込みとアップロードが認証されます。
TRACKIO_FRONTEND_DIR
Trackio用のカスタム静的フロントエンドディレクトリへのパス。ディレクトリにはindex.htmlが含まれている必要があります。
設定されている場合、frontend_dir / --frontend 引数が明示的に渡されない限り、Trackio は trackio.show() および trackio.sync() や trackio.freeze() などのデプロイフローにそのフロントエンドを使用します。
export TRACKIO_FRONTEND_DIR="/path/to/my-trackio-frontend"設定されたディレクトリが無効な場合、Trackio はそれを無視し、組み込みのフロントエンド選択ロジックにフォールバックします。自動的なスターターテンプレートのコピー動作は、明示的な frontend_dir / --frontend 引数が存在しないディレクトリまたは空のディレクトリを指している場合にのみ適用されます。
TRACKIO_LOGO_LIGHT_URL と TRACKIO_LOGO_DARK_URL
Trackio ダッシュボードで表示されるロゴを、ライトテーマおよびダークテーマ用にカスタマイズします。カスタムロゴの URL を指定できます。両方の環境変数を指定する必要があります。指定されていない変数については、Trackio のデフォルトが使用されます。
export TRACKIO_LOGO_LIGHT_URL="https://example.com/logo-light.png"
export TRACKIO_LOGO_DARK_URL="https://example.com/logo-dark.png"注: リモートの Trackio Spaces については、これらの環境変数は
trackio.init(space_id=...)によって Space が最初に作成されたときにのみ適用されます。既存の Space のロゴを変更するには、Hugging Face の Space 設定で Space 変数を直接更新してください。
TRACKIO_PLOT_ORDER
Trackio ダッシュボードのプロットおよびメトリックグループの順序を制御します。値には、希望する順序を指定するメトリックパターンをカンマ区切りで指定します。グループは保持されます。例えば、train/loss を最初に指定した場合、他の train/* メトリックはすべて train グループ内で一緒に表示され、そのグループ内では train/loss が最初に表示されます。
パターンがどのメトリクスにも一致しない場合、エラーを引き起こすことなく単に無視されます。
export TRACKIO_PLOT_ORDER="train/loss,val/loss"
**Pattern Matching:**
- **Exact matches**: `train/loss` matches exactly `train/loss`
- **Group wildcards**: `train/*` matches all metrics starting with `train/`
- **Partial wildcards**: `*gpu*` matches any metric containing "gpu"
**Behavior:**
- Metrics are grouped first (e.g., all `train/*` metrics stay together)
- Within each group, metrics are ordered according to the specified patterns
- Groups appear in the order of their first matching pattern
- Unspecified metrics appear in alphabetical order after specified ones
> **Note:** For remote Trackio Spaces, this environment variable is only applied when the Space is first created via `trackio.init(space_id=...)`. To change the plot order on an existing Space, update the `TRACKIO_PLOT_ORDER` Space variable directly in the Hugging Face Space settings.
### `TRACKIO_THEME`
Sets the theme for the Trackio dashboard. Can be a built-in Gradio theme name or a theme from the Hugging Face Hub.
```bash
# Built-in themes
export TRACKIO_THEME="soft"
export TRACKIO_THEME="citrus"
export TRACKIO_THEME="monochrome"
# Themes from the Hub
export TRACKIO_THEME="gstaff/xkcd"
export TRACKIO_THEME="ParityError/Anime"注: リモートの Trackio Spaces については、この環境変数は
trackio.init(space_id=...)を介して Space が最初に作成されたときにのみ適用されます。既存の Space のテーマを変更するには、Hugging Face の Space 設定でTRACKIO_THEMESpace 変数を直接更新してください。
TRACKIO_COLOR_PALETTE
Trackio ダッシュボードのプロットラインに使用されるカラーパレットをカスタマイズします。値は、カンマ区切りの16進カラーコードのリストである必要があります。複数のランのプロットを描画する際、これらの色が循環して使用されます。
export TRACKIO_COLOR_PALETTE="#FF0000,#00FF00,#0000FF,#FFFF00,#FF00FF,#00FFFF"デフォルトのパレット: #A8769B, #E89957, #3B82F6, #10B981, #EF4444, #8B5CF6, #14B8A6, #F59E0B, #EC4899, #06B6D4
TRACKIO_TABLE_TRUNCATE_LENGTH
テーブルセルに表示される文字列値の最大長を制御します。セルの値がこの長さを超えると、省略表示され、展開可能な要素によって全文を表示できるようになります。デフォルト値は250文字です。
export TRACKIO_TABLE_TRUNCATE_LENGTH="500"TRACKIO_STORAGE_MODE
Trackio がローカルにデータを永続化する際の動作を制御します。許可される値: auto (デフォルト)、sqlite、jsonl。
sqlite: トレーニングプロセスがプロジェクトの SQLite データベースに直接書き込みます（従来の動作）。jsonl: 学習プロセスは、TRACKIO_DIR/inbox/に追記専用の JSONL フラグメントを、プロセスごとに1ファイルとして書き込みます。ダッシュボードサーバー（trackio show）はこれらを SQLite にインポートします。これにより、SQLite の同時書き込みを完全に回避できるため、SQLite のロックや mmap のセマンティクスが信頼できないネットワークファイルシステム（NFS、Lustre、FSx、GPFS、WekaFS、CephFS など）でも Trackio は安全に動作します。auto:TRACKIO_DIRがネットワークファイルシステム上にあると検出された場合（Linux のみ）に自動的にjsonlを選択し、それ以外の場合はsqliteを選択します。
export TRACKIO_STORAGE_MODE="jsonl"TRACKIO_INBOX_POLL_INTERVAL
ダッシュボードサーバーとTrackio Spacesが、ローカルのインボックスディレクトリおよびHugging Face Bucketのインボックスからインポートする新しいJSONLフラグメントを確認する頻度（秒）です。デフォルト値は15で、5未満の値は5にクランプされます。
export TRACKIO_INBOX_POLL_INTERVAL="30"TRACKIO_SQLITE_*（高度な設定）
TrackioがSQLite接続に設定するPRAGMAsをオーバーライドします。これらは主に特殊なファイルシステムで有用です。無効な値は無視されます。
TRACKIO_SQLITE_JOURNAL_MODE:wal、delete、truncate、persist、memory、offのいずれか。ローカルではwal、Spaces ではdeleteがデフォルトです。TRACKIO_SQLITE_MMAP_SIZE: メモリマップ I/O のサイズ（バイト単位）。ネットワークファイルシステム上で SIGBUS クラッシュの直接的な原因となるメモリマップ読み取りは、Trackio のワークロードではほとんどメリットがないため、デフォルトではどこでも0（無効）です。TRACKIO_SQLITE_SYNCHRONOUS:off、normal、full、extraのいずれか。デフォルトはnormalです。TRACKIO_SQLITE_LOCKING_MODE:normalまたはexclusiveのいずれか。Spacesではデフォルトでexclusive、それ以外ではnormalです。TRACKIO_SQLITE_TEMP_STORE:default、file、memoryのいずれか。デフォルトはmemoryです。
推奨されるクラスタ設定: ホームディレクトリまたはキャッシュディレクトリが共有ファイルシステム (/fsx、Lustre、NFS、GPFS、WekaFS など) にある場合、TRACKIO_DIR をノードローカルのディスク (例: /tmp または $SLURM_TMPDIR) に設定するか、ネットワークファイルシステムを検出し JSONL フラグメントロギングに切り替える TRACKIO_STORAGE_MODE=auto に依存してください。共有ファイルシステム上に直接 SQLite を書き込む必要がある場合は、以下を設定してください:
export TRACKIO_SQLITE_JOURNAL_MODE="delete"
export TRACKIO_SQLITE_MMAP_SIZE="0"TRACKIO_WEBHOOK_URL
アラート用のグローバル Webhook URL を設定します。設定すると、trackio.alert() のすべての呼び出しで、アラートペイロードがこの URL に POST されます。Slack および Discord の Webhook URL はネイティブでサポートされており、ペイロードは自動的にフォーマットされます。webhook_url パラメータを介して、アラートごとまたはランごとに上書きできます。
export TRACKIO_WEBHOOK_URL="https://hooks.slack.com/services/T.../B.../xxx"詳細については、アラートガイドを参照してください。
TRACKIO_WEBHOOK_MIN_LEVEL
Webhookに送信されるべき最小の警告レベルを設定します。このレベル未満の警告は、ターミナルに出力され、データベースに保存され、ダッシュボードに表示されますが、Webhookの宛先には送信されません。
許可される値: info、warn、error。
export TRACKIO_WEBHOOK_MIN_LEVEL="warn"warn を使用すると、WARN と ERROR のアラートのみが Webhook URL に送信されます。
TRACKIO_CAPTURE_CONSOLE
1またはtrueに設定すると、Trackio は実行中に stdout および stderr に書き込まれたすべての内容をキャプチャし、ダッシュボードの実行ページに表示します。trackio.init()にcapture_console=Trueを渡すことと同等です。明示的にcapture_console引数を指定した場合、その値が優先されます。
export TRACKIO_CAPTURE_CONSOLE=1詳細については、コンソール出力と起動コマンドのキャプチャを参照してください。
TRACKIO_HANDLE_SIGTERM
1またはtrueに設定すると、trackio.init()はSIGTERMハンドラーをインストールし、シグナルを通常の終了に変換します。これにより、Slurmの時間制限、docker stop、またはKubernetesのエビクションによってプロセスが停止された場合、実行が完了し、最後のメトリクスとコンソール出力が保存されます。終了コードは143のままです。ハンドラーはメインスレッドからのみインストールされ、かつ他のSIGTERMハンドラーが設定されていない場合のみ有効になります。デフォルトでは無効です。これは、SIGTERMに対するプロセス全体の応答方法を変更するためです。例えば、プロセスは終了前に非デーモンスレッドを待機し、既存のハンドラーをチェーンするフレームワーク（PyTorch LightningのSlurm自動リキューなど）は、シグナルを無視する代わりに終了します。
export TRACKIO_HANDLE_SIGTERM=1TRACKIO_BUCKET_ID
Hugging Face Space で実行する際に Trackio データを永続化するために使用される Hugging Face Bucket の ID（例: username/bucketname）です。通常、trackio.init(space_id=...) または trackio.sync(...) を介して Space が作成される際に、Space 上で自動的に設定されます。明示的な bucket_id が指定されない限り、Space ID から Bucket が自動生成されます。
export TRACKIO_BUCKET_ID="username/my-trackio-bucket"TRACKIO_DATASET_ID（非推奨）
非推奨: Trackio データを Hugging Face Dataset（
dataset_id/TRACKIO_DATASET_ID）に永続化することは非推奨となり、将来の Trackio バージョンで削除されます。代わりに Hugging Face Bucket（bucket_id/TRACKIO_BUCKET_ID）を使用してください。
Trackio Space がバックグラウンドのコミットスケジューラを介してデータを同期する Hugging Face Dataset の ID（例: username/datasetname）です。Space に設定されている場合、Trackio は非推奨の警告を出力し、当面は Dataset への同期を続行します。
export TRACKIO_DATASET_ID="username/my-trackio-dataset"HF_TOKEN
Hugging Face の認証トークンです。Hugging Face 上で Spaces と Buckets を作成するには必要です。ローカルマシンから Spaces にデプロイする場合は、ローカルで設定してください。Trackio ダッシュボードをデプロイするネームスペースに対して write 権限が必要です。
export HF_TOKEN="hf_xxxxxxxxxxxxx"Gradio 環境変数
TrackioはGradioの上に構築されているため、Gradioで使用される環境変数を使ってTrackioの動作を制御できます。以下にいくつかの例を示します。
GRADIO_SERVER_PORT
Tradio ダッシュボードを起動するポートを指定します。デフォルトは7860です。
export GRADIO_SERVER_PORT=8000GRADIO_SERVER_NAME
Trackio ダッシュボードサーバーのホスト名を定義します。すべての IP アドレスからダッシュボードにアクセスできるようにするには、これを"0.0.0.0"に設定します。
export GRADIO_SERVER_NAME="0.0.0.0"GRADIO_MCP_SERVER
Trackio における MCP（Model Context Protocol）サーバー機能の有効化を制御します。有効にすると、Trackio ダッシュボードが MCP サーバーとして設定され、特定の機能が MCP ツールとして公開されます。これにより、LLM がこれらのツールを利用できるようになります（例：記録されたメトリクスの読み取り）。
export GRADIO_MCP_SERVER="True"Gradioで使用される環境変数のより包括的なリストについては、こちらを参照してください。
Update on GitHub