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:

1. Resolve target devices by device ID, user nickname, user ID, or custom ID
2. Create remote log retrieval tasks to trigger log collection from end-user devices
3. Track task progress including overall task status and per-device collection status
4. Query log details by device and time window with level and keyword filtering
5. 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.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
3. 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:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. 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.

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  \
  --os  \
  --user-nick  \
  --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  \
  --os  \
  --keyword  \
  --page-index 1 \
  --page-size 10

# By device ID (exact match)
aliyun emas-appmonitor get-tlog-device-list \
  --region cn-shanghai \
  --app-key  \
  --os  \
  --utdid  \
  --page-index 1 \
  --page-size 10

Optional: Query single device details:

aliyun emas-appmonitor get-tlog-device-info \
  --region cn-shanghai \
  --app-key  \
  --os  \
  --device-id 

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  \
  --os  \
  --ali-yun-name  \
  --days  \
  --task-name  \
  --source-type USER \
  --device-json '[{"appId":"@","appKey":"","deviceId":"","os":"","osVersion":"","appVersion":"","userName":"","brand":"","deviceModel":"","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  \
  --os  \
  --ali-yun-name  \
  --days  \
  --task-name  \
  --source-type USER \
  --device-json '[{"appId":"@","appKey":"","deviceId":"","os":"","osVersion":"","appVersion":"","userName":"","brand":"","deviceModel":"","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  \
  --os  \
  --task-id 

[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  \
  --os  \
  --task-id 

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

aliyun emas-appmonitor search-tlog \
  --region cn-shanghai \
  --app-key  \
  --os  \
  --device-id  \
  --begin-date  \
  --end-date  \
  --page-index 1 \
  --page-size 100 \
  --level-json '["debug","info","warning","error"]' \
  --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  \
  --os  \
  --task-id 

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

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

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  \
  --os  \
  --source-type POSITIVE \
  --page-index 1 \
  --page-size 20 \
  --device-id 

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

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  \
  --os  \
  --device-id  \
  --begin-date  \
  --end-date  \
  --level-json '["error","warning"]' \
  --keyword 

Success Verification

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

Best Practices

1. Always dry-run first: Before creating a task, always use --cli-dry-run to preview and confirm request parameters.
2. Use correct time windows: For search-tlog, calculate --begin-date as createTime - days * 86400000 and --end-date as at least modifyTime or current time.
3. Poll with appropriate intervals: Task collection may take minutes. Poll get-tlog-task-info every 30-60 seconds.
4. 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.
5. Use pagination: For large result sets, use --page-index and --page-size to paginate through results.
6. Filter logs efficiently: Use --level-json and --keyword to narrow down log results.
7. Security first: Never embed credentials in scripts or command history. Rely on CLI profiles or environment variables.
8. Check permissions: If API calls fail with permission errors, refer to references/ram-policies.md and use the ram-permission-diagnose skill.

Reference Files

Related Documentation

• Alibaba Cloud CLI Documentation
• CLI Credential Configuration
• EMAS Mobile Monitoring Product
• CreateTlogTask API
• GetTlogDeviceList API
• GetTlogDeviceInfo API
• GetTlogCollectList API
• SearchTlog API
• GetTlogTaskCollections API
• GetTlogTaskInfo API