Cloud Monitor:Diagnose Python applications with the Live-Debug Agent Skill

Install the CLI

If the CLI is not installed, see Install Alibaba Cloud CLI and select the installation method for your operating system (Linux, macOS, or Windows).

After installation, verify that the CLI is available:

aliyun version

Configure access credentials

aliyun configure

Enter the AccessKey ID, AccessKey secret, and default region as prompted. Use a RAM user and grant CMS ServiceTask and read/write/query permissions on the target Simple Log Service project. For more information, see Configure and manage identity credentials.

Install CMS CLI (aliyuncms2) and verify availability

CMS ServiceTask capabilities are provided by the aliyuncms2 plugin binary. Obtain aliyuncms2 and place it in the ~/.aliyun/ directory (or PATH). You can then call it through aliyun cms2, and credentials are reused from the aliyun configure configuration.

# Verify CMS ServiceTask capabilities
aliyun cms2 apm service-task --help

# Verify SLS query availability
aliyun sls --help

If cms2 is not available, confirm that the aliyuncms2 binary is in ~/.aliyun/ (or PATH) and has execute permissions:

ls -l ~/.aliyun/aliyuncms2
chmod +x ~/.aliyun/aliyuncms2
aliyun cms2 apm service-task --help

If the issue persists, upgrade Alibaba Cloud CLI and try again:

aliyun upgrade -y

Dynamic log (LOG)

Example statement:

Use the /alibabacloud-livedebug Skill to add a dynamic log at the exit of OrderService.create_order in app.service.order, print order_id, amount, return value, and latency. Keep it for 30 minutes.

Reference configuration:taskType = live_debug_log_probe

{
  "probeType": "LOG",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "LOG",
    "template": "create_order id={order_id} amount={amount} ret={@return} cost={@duration}ms"
  },
  "ttl": "30m",
  "captureCount": 100
}

Line-level with condition:

Add a log at line 42 of app/service/order.py. Only output the order ID and amount when amount >= 1000.

Reference configuration:taskType = live_debug_log_probe

{
  "probeType": "LOG",
  "language": "python",
  "target": {
    "sourceFile": "app/service/order.py",
    "location": "line:42",
    "instanceIds": ["*"]
  },
  "trigger": {
    "condition": "amount >= 1000"
  },
  "action": {
    "type": "LOG",
    "template": "big order id={order_id} amount={amount}"
  },
  "ttl": "30m"
}

Method snapshot (SNAPSHOT)

Example statement:

Use the /alibabacloud-livedebug Skill to take a snapshot at the exit of OrderService.create_order. Capture input parameters, local variables, return value, and call stack. Capture up to 20 times.

Reference configuration:taskType = live_debug_snapshot_probe

{
  "probeType": "SNAPSHOT",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SNAPSHOT",
    "capture": ["ARGS", "LOCALS", "RETURN", "STACK"],
    "captureConfig": {
      "maxDepth": 3,
      "maxCollectionSize": 100,
      "maxStringLength": 1024
    }
  },
  "ttl": "30m",
  "captureCount": 20
}

Conditional filtering with custom fields:

Take a snapshot at the exit of create_order. Trigger only when the return value is empty or the amount is greater than 10000. Focus on order_id, amount * count, self.user_id, and the return value.

Reference configuration:taskType = live_debug_snapshot_probe

{
  "probeType": "SNAPSHOT",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "trigger": {
    "condition": "@return is None or amount > 10000"
  },
  "action": {
    "type": "SNAPSHOT",
    "capture": ["ARGS"],
    "captureExpressions": [
      "order_id",
      "amount * count",
      "self.user_id",
      "@return"
    ]
  },
  "ttl": "30m",
  "captureCount": 50
}

Exception capture:

Capture a snapshot when PaymentService.process_payment throws an exception. Include input parameters, exception information, and call stack. Keep it for 2 hours.

Reference configuration:taskType = live_debug_snapshot_probe

{
  "probeType": "SNAPSHOT",
  "language": "python",
  "target": {
    "typeName": "app.service.payment",
    "methodName": "PaymentService.process_payment",
    "location": "exception",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SNAPSHOT",
    "capture": ["ARGS", "EXCEPTION", "STACK", "LOCALS"]
  },
  "ttl": "2h",
  "captureCount": 100
}

Dynamic metric (METRIC)

Example statement:

Use the /alibabacloud-livedebug Skill to add an amount histogram metric to create_order. Include a tag indicating whether the user is a VIP. Keep it for 1 hour.

Reference configuration:taskType = live_debug_metric_probe

{
  "probeType": "METRIC",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "METRIC",
    "metricName": "livedebug.order.amount",
    "metricType": "HISTOGRAM",
    "valueExpression": "amount",
    "tags": {
      "is_vip": "str(user_id == 'vip')"
    }
  },
  "ttl": "1h"
}

Dynamic span (SPAN)

Example statement:

Use the /alibabacloud-livedebug Skill to temporarily add a span on OrderService.create_order named dyn.create_order. Include the order ID and amount as span attributes.

Reference configuration:taskType = live_debug_span_probe

{
  "probeType": "SPAN",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "enter",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SPAN",
    "spanName": "dyn.create_order",
    "spanTags": {
      "order.id": "str(order_id)",
      "order.amount": "str(amount)"
    }
  },
  "ttl": "1h"
}

Span tagging (SPAN_TAG)

Example statement:

At the exit of create_order, use the /alibabacloud-livedebug Skill to tag the current span with order.id and order.result (use the return value). Do not create a new span.

Reference configuration:taskType = live_debug_span_tag_probe

{
  "probeType": "SPAN_TAG",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SPAN_TAG",
    "tags": [
      {"key": "order.id", "value": "str(order_id)"},
      {"key": "order.result", "value": "str(@return)"}
    ]
  },
  "ttl": "1h"
}

The agent reports that cms2 or aliyun command is unavailable

Cause: Alibaba Cloud CLI is not installed, the version is too old, or the aliyuncms2 plugin binary is not ready.

Solution:

aliyun version
aliyun upgrade -y
ls -l ~/.aliyun/aliyuncms2   # Confirm the CMS CLI plugin binary exists and is executable
aliyun cms2 apm service-task --help
aliyun sls --help

Make sure that you have run aliyun configure to configure the AccessKey pair.

Task created successfully but no capture results appear

Troubleshoot in the following order:

1. Ask the Agent to check the Task Status first and confirm whether the agent was installed successfully.

2. Verify that typeName and methodName match the runtime module name and __qualname__. Check whether the main module should be __main__.

3. Confirm that you have triggered a request that reaches the target function. Check whether the filter condition is too strict.

4. Confirm that regionId in .arms-info matches the region of slsProject.

5. Increase the query time window and try again.

You can also tell the Agent: "No data was captured. Help me check whether the status and target location are correct."

SLS reports ProjectNotExist

Cause: The region used for the query does not match the region of the Simple Log Service project.

Solution: Enter the correct regionId in .arms-info and make sure that the Agent has exported LIVE_DEBUG_REGION_ID. Do not rely solely on the CLI default region.

How to confirm that agents are cleaned up

Show me what Live-Debug agents are still attached to the current service. If there are any, delete all of them.

Can Python applications perform thread, memory, or decompilation diagnostics?

No. These are Command capabilities that are supported only for Java/JVM applications. For Python applications, use log, snapshot, metric, or span diagnostics instead.