CLI_GUIDE.md•9.77 kB
# WhaTap MXQL CLI 사용 가이드
WhaTap 모니터링 데이터를 MXQL로 조회할 수 있는 명령줄 인터페이스입니다.
## 🚀 설치
```bash
# 프로젝트 빌드
npm install
npm run build
# bin 실행 권한 부여
chmod +x bin/whatap-mxql
# (선택) 전역 설치
npm link
```
## 📋 명령어
### 1. 로그인
WhaTap 서비스에 로그인합니다.
**💡 TIP**: 로그인 없이 다른 명령어를 실행하면 **자동으로 로그인 프롬프트**가 표시됩니다!
```bash
# 대화형 로그인
whatap-mxql login
# 옵션으로 로그인
whatap-mxql login \
-e your@email.com \
-p your-password \
-u https://service.whatap.io
# 또는 로그인 없이 바로 명령어 실행
# → 자동으로 로그인 유도
whatap-mxql projects
```
**옵션:**
- `-e, --email <email>` - WhaTap 계정 이메일
- `-p, --password <password>` - WhaTap 계정 비밀번호
- `-u, --url <url>` - WhaTap 서비스 URL
**세션 저장 위치:**
- 기본: `~/.whatap-mxql/session.enc`
- 환경변수로 변경: `WHATAP_SESSION_DIR=/custom/path`
### 2. 프로젝트 목록
접근 가능한 모든 프로젝트를 조회합니다.
```bash
# 테이블 형식 (기본)
whatap-mxql projects
# JSON 형식
whatap-mxql projects -f json
# CSV 형식
whatap-mxql projects -f csv
# 타입 필터링
whatap-mxql projects --filter MOBILE
whatap-mxql projects --filter BROWSER
```
**옵션:**
- `-f, --format <format>` - 출력 형식 (table|json|csv)
- `--filter <type>` - 프로젝트 타입 필터 (BROWSER|MOBILE|APM 등)
**출력 예시:**
```
✓ Found 12 project(s)
┌──────────────┬─────────────────────────┬─────────┬────────────┐
│ Project Code │ Project Name │ Type │ Status │
├──────────────┼─────────────────────────┼─────────┼────────────┤
│ 27506 │ Browser Monitoring Demo │ BROWSER │ subscribe │
│ 44482 │ mobile test project │ MOBILE │ subscribe │
└──────────────┴─────────────────────────┴─────────┴────────────┘
```
### 3. MXQL 쿼리 실행
프로젝트에서 MXQL 쿼리를 실행합니다.
```bash
# 직접 쿼리 입력
whatap-mxql query 27506 "CATEGORY app_counter"
# 파일에서 쿼리 읽기
whatap-mxql query 27506 -f query.mxql
# 시간 범위 지정
whatap-mxql query 27506 "CATEGORY app_counter" -r 24h
whatap-mxql query 27506 "CATEGORY app_counter" -r 7d
# 명시적 시작/종료 시간
whatap-mxql query 27506 "CATEGORY app_counter" \
-s 2025-01-01T00:00:00Z \
-e 2025-01-02T00:00:00Z
# 결과 제한 및 포맷
whatap-mxql query 27506 "CATEGORY app_counter" -l 50 -o json
whatap-mxql query 27506 "CATEGORY app_counter" -o csv --no-header
```
**인자:**
- `<pcode>` - 프로젝트 코드 (필수)
- `[mxql]` - MXQL 쿼리 문자열 (또는 `-f` 사용)
**옵션:**
- `-f, --file <path>` - 파일에서 MXQL 쿼리 읽기
- `-s, --start <time>` - 시작 시간 (ISO 문자열 또는 타임스탬프)
- `-e, --end <time>` - 종료 시간 (ISO 문자열 또는 타임스탬프)
- `-r, --range <range>` - 시간 범위 프리셋 (1h|6h|24h|7d|30d) [기본: 1h]
- `-l, --limit <number>` - 결과 행 제한 [기본: 100]
- `-o, --output <format>` - 출력 형식 (table|json|csv) [기본: table]
- `--no-header` - 헤더 행 제외
**출력 예시:**
```
✓ Query executed successfully
────────────────────────────────────────────────────────────
Query Summary:
Rows: 2
Execution Time: 849ms
Query: HEADER { "pname$":"#"...
────────────────────────────────────────────────────────────
[
{
"_id_": "27506_",
"pname": "Browser Monitoring Demo",
"pcode": 27506,
"sessionCount": 108.04790419161677,
"_rows_": 167
}
]
```
### 4. 대화형 모드
REPL 스타일의 대화형 모드를 시작합니다.
```bash
# 대화형 모드 시작
whatap-mxql interactive
# 기본 프로젝트 지정
whatap-mxql interactive -p 27506
```
**대화형 명령어:**
```
> help # 도움말 표시
> projects # 프로젝트 목록
> use 27506 # 프로젝트 선택
> query <mxql> # MXQL 실행
> CATEGORY app_counter # 직접 MXQL 입력 (프로젝트 선택 시)
> exit # 종료
```
**사용 예시:**
```
WhaTap MXQL Interactive Mode
Type "help" for available commands, "exit" to quit
✓ Loaded 12 projects
> use 27506
✓ Selected project: Browser Monitoring Demo (27506)
[27506]> CATEGORY app_counter
ℹ Executing...
✓ Query executed
────────────────────────────────────────────────────────────
Query Summary:
Rows: 0
Execution Time: 271ms
────────────────────────────────────────────────────────────
[27506]> exit
ℹ Goodbye!
```
### 5. 로그아웃
저장된 세션을 삭제합니다.
```bash
whatap-mxql logout
```
## 📚 MXQL 쿼리 예제
### 간단한 카테고리 조회
```mxql
CATEGORY app_counter
```
### 복잡한 파이프라인 쿼리
```mxql
HEADER { "pname$":"#","$":"#","logbits$":"#","sessionCount$":"#","oid$":"#" }
OIDSET { oid:$oid, okind:$okind, onode:$onode }
CATEGORY {"rum_session_count":6h, "rum_session_count{m5}":3d, "rum_session_count{h1}":unlimit }
TAGLOAD { backward: true }
INJECT default
UPDATE { key: ["logbits","sessionCount"], value: $TIME_MERGE_PLACE }
SELECT ["pcode","pname","","logbits","sessionCount","oid"]
CREATE { key: _id_, expr: "pcode+'_'+oid" }
GROUP { timeunit: 5s, pk:_id_ }
FIRST-ONLY { key: _id_ }
UPDATE { key: ["logbits","sessionCount"], value: $OBJECT_MERGE_PLACE }
INJECT default
```
### 파일에서 쿼리 실행
```bash
# query.mxql 파일 생성
cat > query.mxql << 'EOF'
CATEGORY app_counter
SELECT ["pcode", "pname", "oid"]
EOF
# 실행
whatap-mxql query 27506 -f query.mxql -r 24h -o json
```
## 🎨 출력 형식
### Table (기본)
```
┌──────────┬─────────────────┬──────┐
│ pcode │ pname │ oid │
├──────────┼─────────────────┼──────┤
│ 27506 │ Project Name │ 123 │
└──────────┴─────────────────┴──────┘
```
### JSON
```json
[
{
"pcode": 27506,
"pname": "Project Name",
"oid": 123
}
]
```
### CSV
```csv
pcode,pname,oid
27506,Project Name,123
```
## ⚙️ 환경 변수
- `WHATAP_SESSION_DIR` - 세션 저장 디렉토리 (기본: `~/.whatap-mxql`)
## 🔧 문제 해결
### 로그인 실패
```
✗ Login failed: Request failed with status code 401
Hint: Please check your email and password
```
→ 이메일과 비밀번호를 확인하세요.
### 네트워크 오류
```
✗ Login failed: ENOTFOUND service.whatap.io
Hint: Please check your network connection and service URL
```
→ 네트워크 연결과 서비스 URL을 확인하세요.
### 세션 없음
```
✗ Not logged in. Please login first using: whatap-mxql login
```
→ `whatap-mxql login` 명령어로 먼저 로그인하세요.
### 데이터 없음
```
⚠ No data returned
Possible reasons:
• No data in the specified time range
• Project has no monitoring data
• Query returned empty result
```
→ 시간 범위를 조정하거나 다른 쿼리를 시도하세요.
## 📖 추가 도움말
```bash
# 전체 도움말
whatap-mxql --help
# 명령어별 도움말
whatap-mxql login --help
whatap-mxql projects --help
whatap-mxql query --help
whatap-mxql interactive --help
```
## 🎯 일반적인 워크플로우
```bash
# 1. 로그인
whatap-mxql login
# 2. 프로젝트 확인
whatap-mxql projects
# 3. 쿼리 실행
whatap-mxql query 27506 "CATEGORY app_counter" -r 24h -o json
# 4. 대화형 모드로 여러 쿼리 실행
whatap-mxql interactive -p 27506
# 5. 작업 완료 후 로그아웃
whatap-mxql logout
```
## 🚀 고급 사용법
### 파이프라인과 함께 사용
```bash
# JSON 출력을 jq로 파싱
whatap-mxql projects -f json | jq '.[] | select(.productType=="MOBILE")'
# CSV로 파일 저장
whatap-mxql query 27506 "CATEGORY app_counter" -o csv > data.csv
# 여러 프로젝트에서 쿼리 실행
for pcode in 27506 44482 44898; do
whatap-mxql query $pcode "CATEGORY app_counter" -r 7d -o json > "data_${pcode}.json"
done
```
### 스크립트에서 사용
```bash
#!/bin/bash
# 로그인 (환경변수 사용)
whatap-mxql login \
-e "${WHATAP_EMAIL}" \
-p "${WHATAP_PASSWORD}" \
-u "${WHATAP_URL}"
# 모든 MOBILE 프로젝트 조회
whatap-mxql projects --filter MOBILE -f json > mobile_projects.json
# 각 프로젝트에서 데이터 수집
cat mobile_projects.json | jq -r '.[].projectCode' | while read pcode; do
echo "Querying project $pcode..."
whatap-mxql query $pcode "CATEGORY app_counter" -r 24h -o json > "data_${pcode}.json"
done
# 로그아웃
whatap-mxql logout
```
---
**문의 및 이슈:** [GitHub Issues](https://github.com/whatap/whatap-mxql-cli/issues)