This skill enables remote log retrieval (TLog) operations for mobile applications managed by Alibaba Cloud EMAS APM (Application Performance Monitoring). It provides a complete workflow to:
Resolve target devices by device ID, user nickname, user ID, or custom ID
Create remote log retrieval tasks to trigger log collection from end-user devices
Track task progress including overall task status and per-device collection status
Query log details by device and time window with level and keyword filtering
Query actively submitted logs for user-initiated log uploads
Architecture: EMAS Console + Mobile App (with TLog SDK) + EMAS APM Service + Alibaba Cloud CLI (emas-appmonitor plugin)
Key Components:
Device Side: Mobile apps integrated with EMAS TLog SDK (Android/iOS)
Server Side: EMAS APM backend service for task dispatch and log storage
Client Side: Alibaba Cloud CLI with aliyun-cli-emas-appmonitor plugin for API operations
Installation
Pre-check: Alibaba Cloud CLI >= 3.3.3 required
bash
aliyun version
# If not installed or version too low (script served by Alibaba Cloud official CDN over HTTPS):
curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh | bash
aliyun version
Security note — the one-liner above pipes a remote script directly into bash. The script is hosted on Alibaba Cloud's official CDN (aliyuncli.alicdn.com) and served over HTTPS, so transit is authenticated. However, if your environment requires inspecting installer scripts before execution (security-hardened CI, regulated workloads, multi-tenant hosts), use the safer two-step flow in references/cli-installation-guide.md — download → inspect → execute. Do not run this command with elevated privileges (e.g. as root); the installer does not require it.
Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
Return and re-run after aliyun configure list shows a valid profile
Data Safety: Do not save real AccessKeys in command-line parameters, scripts, or logs. Authentication is fully delegated to CLI profiles.
RAM Policy
Required Permissions: See references/ram-policies.md for the complete list of RAM permissions required by each API.
Quick Reference:
Permission
API
apm:GetTlogDeviceList
Query available devices
apm:GetTlogDeviceInfo
Get device details
apm:CreateTlogTask
Create log retrieval task
apm:GetTlogTaskInfo
Query task status
apm:GetTlogTaskCollections
Query device collection status
apm:SearchTlog
Query log details
apm:GetTlogCollectList
Query active submission records
System Policies: AliyunEMASFullAccess or AliyunEMASReadOnlyAccess
[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:
Read references/ram-policies.md to get the full list of permissions required by this SKILL
Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
Pause and wait until the user confirms that the required permissions have been granted
Parameters Requiring User Confirmation
IMPORTANT: Parameter Confirmation — Before executing any command or API call,
ALL user-customizable parameters (e.g., AppKey, OS type, device identifiers,
task names, time windows, etc.) MUST be confirmed with the user. Do NOT assume or use
default values without explicit user approval.
[MUST] RegionId is fixed — EMAS APM service is ONLY available in cn-shanghai.
Always pass --region cn-shanghai regardless of the credential's default region
(e.g., even if aliyun configure list shows cn-hangzhou). Do NOT ask the user
to confirm RegionId, and do NOT try other regions on failure.
Parameter
Required
Description
Example
RegionId
Yes (fixed)
EMAS APM service region — must be cn-shanghai (only supported region)
cn-shanghai
AppKey
Yes
Application key from EMAS console
123456789
OS
Yes
Mobile OS type: android or iphoneos
android
UserNick
Conditional
User nickname for device lookup
testuser01
DeviceId
Conditional
Device unique ID (UTDID)
Z1234567890ABCDEF
Keyword
Conditional
User ID or custom ID for lookup
user_12345
TaskName
Yes (create task)
Name for the log retrieval task
task-2024-01-15-user01
Days
Yes (create task)
Number of days of log history to retrieve
1
OperatorName
Yes (create task)
Operator name (AliYunName)
admin
DeviceJson
Yes (create task)
Device metadata JSON array
See workflow
BeginDate
Yes (query logs)
Start time in Unix milliseconds (13 digits)
1700000000000
EndDate
Yes (query logs)
End time in Unix milliseconds (13 digits)
1700086400000
TaskId
Conditional
Task ID returned from create operation
tlog_task_xxxxx
PageIndex
No
Page number for paginated results
1
PageSize
No
Number of results per page
10
LevelJson
No (query logs)
Log level filter as JSON array
["error","warning"]
Keyword
No (query logs)
Log content search keyword
NullPointerException
SourceType
Yes (collect list)
Source type: USER or POSITIVE
POSITIVE
Core Workflow
IMPORTANT: Parameter Confirmation — Before executing any command or API call,
ALL user-customizable parameters MUST be confirmed with the user. Do NOT assume or use
default values without explicit user approval.
Workflow 1: Known User — Create Retrieval Task and Query Logs
Use when you know a user's identity and need to retrieve their device logs.
Step 1: Resolve Device by Identity
bash
# By user nickname (fuzzy/prefix match)
aliyun emas-appmonitor get-tlog-device-list \
--region cn-shanghai \
--app-key <AppKey> \
--os <OS> \
--user-nick <UserNick> \
--page-index 1 \
--page-size 10
# By user ID or custom ID (exact match)
aliyun emas-appmonitor get-tlog-device-list \
--region cn-shanghai \
--app-key <AppKey> \
--os <OS> \
--keyword <UserId> \
--page-index 1 \
--page-size 10
# By device ID (exact match)
aliyun emas-appmonitor get-tlog-device-list \
--region cn-shanghai \
--app-key <AppKey> \
--os <OS> \
--utdid <DeviceId> \
--page-index 1 \
--page-size 10
IMPORTANT: create-tlog-task will create a real task and trigger device-side log collection.
You MUST use --cli-dry-run first to preview the request body and confirm parameters.
[MUST] Defensive existence check — get-tlog-task-info may return
Success: true with an empty placeholder model even when the taskId
does not exist (no TaskNotFound error). The placeholder looks like:
status=NORMAL, dayNum=0, progress="0/0/0/0", collectionNums=0,
and a fresh createTime equal to "now". Do NOT trust Model.status
alone. Confirm the task is real by ALL of:
Model.dayNum > 0 (real tasks always have a configured day window)
Model.taskName / Model.author non-empty
Model.createTime is older than the request time (real tasks are not created at query time)
If the placeholder pattern is detected, treat it as task does not exist: surface this clearly to the user, and do NOT proceed to get-tlog-task-collections or search-tlog. The most common cause is a malformed or truncated taskId (e.g. a hyphen in the taskId mistakenly parsed as a CLI flag delimiter — always pass taskId quoted).
--begin-date: Use task.createTime - days * 86400000 to cover the full retrieval range
--end-date: Use at least task.modifyTime (task completion time) or current time; do NOT use task.createTime as this will miss logs generated after the task was created
All times are Unix milliseconds (13 digits)
Workflow 2: Known TaskId — Query Task Progress and Logs
Use when you already have a taskId and need to check progress and retrieve logs.
aliyun plugin list | grep emas-appmonitor shows version >= 0.3.1
Credentials
aliyun configure list shows valid profile
Device Resolution
Response Success: true, non-empty device list
Task Creation (Dry-Run)
Request body preview matches intended parameters
Task Creation (Actual)
Model returns a valid taskId string
Task Status
Status is one of: NORMAL, SUCCEEDED, FAILED, SUSPENDED, CANCELLED
Device Collection
At least one device reaches FINISHED status
Log Query
Response Success: true, log entries returned
Active Submission
Records returned with valid status and timestamps
Best Practices
Always dry-run first: Before creating a task, always use --cli-dry-run to preview and confirm request parameters.
Use correct time windows: For search-tlog, calculate --begin-date as createTime - days * 86400000 and --end-date as at least modifyTime or current time.
Poll with appropriate intervals: Task collection may take minutes. Poll get-tlog-task-info every 30-60 seconds.
Handle task IDs correctly: Task IDs from create-tlog-task are plain strings. Active submission record taskIds are system-generated and cannot be queried with get-tlog-task-info.
Use pagination: For large result sets, use --page-index and --page-size to paginate through results.
Filter logs efficiently: Use --level-json and --keyword to narrow down log results.
Security first: Never embed credentials in scripts or command history. Rely on CLI profiles or environment variables.
Check permissions: If API calls fail with permission errors, refer to references/ram-policies.md and use the ram-permission-diagnose skill.
