Trackio documentation
환경 변수
환경 변수
Trackio는 환경 변수를 사용하여 동작의 다양한 측면, 특히 Hugging Face Spaces 배포 및 데이터 영속성을 구성합니다. 이 가이드에서는 주요 환경 변수와 그 사용법을 다룹니다.
핵심 환경 변수
TRACKIO_DIR
Trackio 데이터를 저장할 사용자 지정 디렉터리를 지정합니다. 기본적으로 Trackio는 데이터를 ~/.cache/huggingface/trackio/에 저장합니다.
export TRACKIO_DIR="/path/to/trackio/data"Note: Trackio가 영속적 저장소가 활성화된 Space에서 실행되지 않는 한 이 환경 변수가 적용됩니다. Trackio가 영속적 저장소가 활성화된 Space에서 실행되는 경우(PERSISTANT_STORAGE_ENABLED 환경 변수로 감지됨)에는 Trackio 데이터가 /data/trackio에 저장됩니다.
TRACKIO_SERVER_URL
자체 호스팅된 Trackio 서버의 Base 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 서버의 대시보드 write token입니다(write-access URL의 write_token 쿼리 파라미터와 동일한 값). Trackio 서버에 설정된 경우, 이 값은 시작 시 무작위 토큰을 생성하는 대신 서버의 write token으로 사용됩니다. Trackio 클라이언트에 설정된 경우, TRACKIO_SERVER_URL 또는 server_url이 쿼리 파라미터가 없는 기본 URL일 때 이 값을 사용합니다. 클라이언트는 각 요청 시 이 토큰을 전송하여(예: X-Trackio-Write-Token 헤더로) Hugging Face Spaces에서 실행하지 않을 때에도 지표 수집 및 업로드가 인증되도록 합니다.
TRACKIO_FRONTEND_DIR
Trackio용 사용자 지정 정적 프론트엔드 디렉터리의 경로입니다. 해당 디렉터리에는 index.html 파일이 포함되어야 합니다.
설정된 경우, Trackio는 frontend_dir / --frontend 인수가 명시적으로 전달되지 않는 한 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/에 프로세스당 하나의 파일로 append-only JSONL 조각을 기록합니다. 대시보드 서버(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가 로컬 inbox 디렉터리와 Hugging Face Bucket inbox에서 가져올 새 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: 바이트 단위의 memory-mapped I/O 크기. Trackio의 워크로드에서 memory-mapped 읽기는 네트워크 파일 시스템에서 SIGBUS 크래시의 직접적인 원인이 되며 이점이 거의 없으므로 모든 환경에서 기본값은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
알림용 전역 웹훅 URL을 설정합니다. 설정된 경우, trackio.alert()의 모든 호출에서 알림 페이로드를 해당 URL로 POST합니다. Slack 및 Discord 웹훅 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 알림만 웹훅 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 응답 방식을 변경하기 때문에 기본적으로 비활성화되어 있습니다. 예를 들어, 프로세스는 종료하기 전에 non-daemon 스레드를 대기하며, 기존 핸들러를 체인하는 프레임워크(예: PyTorch Lightning의 Slurm auto-requeue)는 시그널을 무시하는 대신 종료됩니다.
export TRACKIO_HANDLE_SIGTERM=1TRACKIO_BUCKET_ID
Hugging Face Space에서 Trackio 데이터를 영속화하는 데 사용되는 Hugging Face Bucket의 ID(예: username/bucketname)입니다. trackio.init(space_id=...) 또는 trackio.sync(...)를 통해 Space가 생성될 때 일반적으로 자동으로 설정됩니다. 명시적인 bucket_id가 제공되지 않는 한 Space ID에서 버킷이 자동으로 생성됩니다.
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는 비추천(deprecation) 경고를 출력하고 당분간 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 서버로 설정되며, 특정 함수가 LLM(예: 기록된 메트릭 읽기)에서 사용할 수 있는 MCP 도구로 노출됩니다.
export GRADIO_MCP_SERVER="True"Gradio에서 사용하는 환경 변수의 더 포괄적인 목록을 확인하세요.
Update on GitHub