alibabacloud-emas-apm-remotelog

EMAS APM Remote Log (TLog) CLI Skill

Scenario Description

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

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.

Pre-check: Alibaba Cloud CLI plugin update required

aliyun configure set --auto-plugin-install true
aliyun plugin update

Install EMAS APM Plugin

aliyun plugin install --names aliyun-cli-emas-appmonitor
aliyun plugin list | grep emas-appmonitor  # Verify version >= 0.3.1

For detailed installation instructions, see references/cli-installation-guide.md

AI-Mode Lifecycle Management

[MUST] AI-Mode — AI-mode is required for Agent Skill execution. Run the following commands before any CLI invocation:
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-emas-apm-remotelog"
[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response for ANY reason, always disable AI-mode first.
aliyun configure ai-mode disable

Credential Verification

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)

NEVER ask the user to input AK/SK directly in the conversation or command line

NEVER use aliyun configure set with literal credential values

ONLY use aliyun configure list to check credential status
aliyun configure list
Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

Obtain credentials from Alibaba Cloud Console

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

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

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

# 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

Optional: Query single device details:

aliyun emas-appmonitor get-tlog-device-info \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --device-id <DeviceId>

Step 2: Preview Task Parameters (Dry-Run)

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.

aliyun emas-appmonitor create-tlog-task \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --ali-yun-name <OperatorName> \
  --days <Days> \
  --task-name <TaskName> \
  --source-type USER \
  --device-json '[{"appId":"<AppKey>@<OS>","appKey":"<AppKey>","deviceId":"<DeviceId>","os":"<OS>","osVersion":"<osVersion>","appVersion":"<appVersion>","userName":"<UserNick>","brand":"<brand>","deviceModel":"<deviceModel>","geo":"<geo>"}]' \
  --cli-dry-run

Step 3: Create Task (After Confirmation)

Remove --cli-dry-run after confirming parameters:

aliyun emas-appmonitor create-tlog-task \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --ali-yun-name <OperatorName> \
  --days <Days> \
  --task-name <TaskName> \
  --source-type USER \
  --device-json '[{"appId":"<AppKey>@<OS>","appKey":"<AppKey>","deviceId":"<DeviceId>","os":"<OS>","osVersion":"<osVersion>","appVersion":"<appVersion>","userName":"<UserNick>","brand":"<brand>","deviceModel":"<deviceModel>","geo":"<geo>"}]'

Note: On success, Model returns the taskId as a plain string (not a JSON object).

Step 4: Poll Task Status

Query overall task status:

aliyun emas-appmonitor get-tlog-task-info \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --task-id <TaskId>

Status	Meaning
`NORMAL`	Task in progress
`SUCCEEDED`	Task completed successfully
`FAILED`	Task failed
`SUSPENDED`	Task expired
`CANCELLED`	Task cancelled

[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).

Query per-device collection status:

aliyun emas-appmonitor get-tlog-task-collections \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --task-id <TaskId>

Collection Status	Meaning
`START`	Task created, device has not pulled
`PULL_REPLIED`	Device has task, token not applied
`TOKEN_APPLIED`	Token issued, waiting for upload
`FILE_SENDED`	File metadata saved, waiting for parsing
`FINISHED`	Logs are queryable
`FAIL_OVER`	Collection failed
`SUSPENDED`	Task expired
`CANCELLED`	Task cancelled

Step 5: Query Logs (When Device Status is FINISHED)

aliyun emas-appmonitor search-tlog \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --device-id <DeviceId> \
  --begin-date <BeginDate> \
  --end-date <EndDate> \
  --page-index 1 \
  --page-size 100 \
  --level-json '["debug","info","warning","error"]' \
  --keyword <Keyword>

Time Window Rules:

--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.

# Step 1: Check overall task status
aliyun emas-appmonitor get-tlog-task-info \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --task-id <TaskId>

# Step 2: Check per-device collection status
aliyun emas-appmonitor get-tlog-task-collections \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --task-id <TaskId>

# Step 3: For devices with FINISHED status, query logs
aliyun emas-appmonitor search-tlog \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --device-id <DeviceId> \
  --begin-date <BeginDate> \
  --end-date <EndDate>

Workflow 3: Query Actively Submitted Logs

For user-initiated log submissions (not manually triggered retrieval):

# Step 1: Query active submission records
aliyun emas-appmonitor get-tlog-collect-list \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --source-type POSITIVE \
  --page-index 1 \
  --page-size 20 \
  --device-id <DeviceId>

# Step 2: For records with FINISHED status, use deviceId + createTime window to query logs
aliyun emas-appmonitor search-tlog \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --device-id <DeviceId> \
  --begin-date <createTime - window> \
  --end-date <createTime + window>

Note: The taskId in active submission records is a system-generated association ID and CANNOT be queried via get-tlog-task-info.

Workflow 4: Direct Log Query by Device and Time

When you already know the device and time range:

aliyun emas-appmonitor search-tlog \
  --region cn-shanghai \
  --app-key <AppKey> \
  --os <OS> \
  --device-id <DeviceId> \
  --begin-date <BeginDate> \
  --end-date <EndDate> \
  --level-json '["error","warning"]' \
  --keyword <Keyword>

Success Verification

For each workflow step, verify success using the methods documented in references/verification-method.md:

Step	Verification Method
Plugin Installation	`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.

Reference Files

File	Description
references/cli-installation-guide.md	Aliyun CLI installation and configuration guide
references/ram-policies.md	RAM permission requirements for all APIs
references/related-commands.md	Complete CLI command reference
references/acceptance-criteria.md	Correct/incorrect usage patterns
references/verification-method.md	Step-by-step verification procedures

About this skill