Gestiona tareas dinámicas de sondeo de código para aplicaciones en Python mediante la API ServiceTaskController de Cloud Monitor (CMS), versión 2024-03-30. Se admiten cinco tipos de sondeo (LOG, SNAPSHOT, METRIC, SPAN y SPAN_TAG). Los resultados de captura se almacenan en Simple Log Service (SLS).
Requisitos previos
CLI de Alibaba Cloud: los comandos
cms2yslsque se usan en este tema requieren la CLI (interfaz de línea de comandos) de Alibaba Cloud.ID del espacio de trabajo: el identificador del espacio de trabajo de Application Real-Time Monitoring Service (ARMS), por ejemplo,
default-cms-xxx-cn-hangzhou.ID del servicio: el identificador de la aplicación o del servicio, como
ggxw4lnjuz@f2fd3a6265a254a052afb.Proyecto de SLS: el proyecto de SLS correspondiente a la aplicación, por ejemplo,
proj-xtrace-...-cn-hangzhou.Región: especifique el parámetro
--regionde forma explícita tanto en los comandos de CMS como en los de SLS. Así evitará depender de la región predeterminada de la CLI.
Este tema abarca únicamente las aplicaciones en Python (tareas de sondeo).
Operaciones de la API
|
Operación |
Método HTTP |
Ruta |
Comando de la CLI |
|
Crear una tarea |
|
|
|
|
Listar tareas |
|
|
|
|
Consultar una tarea |
|
|
|
|
Eliminar una tarea |
|
|
|
|
Consultar resultados de captura |
|
(No es una operación de CMS) |
|
Parámetros de ruta
|
Parámetro |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
El ID del espacio de trabajo de ARMS, por ejemplo, |
|
|
string |
Sí |
El ID de la aplicación o del servicio, como |
|
|
string |
Sí (Get/Delete) |
El ID de la tarea que devuelve la operación de creación. |
Parámetros comunes de la CLI
|
Parámetro |
Descripción |
Valor predeterminado |
|
|
La región. Especifique este parámetro de forma explícita en los comandos de CMS y de SLS para no depender de la región predeterminada de la CLI. |
La región predeterminada en la configuración de la CLI de Alibaba Cloud |
|
|
El endpoint de CMS. Anula el endpoint que se deriva de la región. |
|
|
|
Muestra JSON con sangría. El modo predeterminado |
|
CreateServiceTask
Crea una tarea de sondeo de Live-Debug.
Solicitud
POST /serviceTask/{workspace}/{serviceId}/task
Content-Type: application/json
Parámetros del cuerpo
|
Parámetro |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
El tipo de tarea ( |
|
|
string |
Sí |
La dirección IP de la instancia de destino. Establezca este parámetro en |
|
|
string (texto JSON) |
Sí |
Un objeto de configuración plano para un solo sondeo. El servidor lo almacena como una cadena. El parámetro |
Ejemplo de la CLI
aliyun cms2 apm service-task create \
--workspace <workspace> --service-id <serviceId> \
--type <taskType> --ip '<targetIp>' \
--task-config '<taskConfigJson>' \
--region <regionId> -o json
Para coincidir con todas las instancias, establezca
--ipen*.Pase un objeto JSON sin procesar a
--task-config. No es necesario escapar el JSON de forma manual.
Respuesta
{
"success": true,
"data": {
"requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"taskId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
}
}
|
Campo |
Descripción |
|
|
El ID de la solicitud. |
|
|
El ID de la tarea. Utilice este valor para las consultas de SLS y para las operaciones Get y Delete. |
Ejemplo de cuerpo HTTP (después de la serialización de la CLI)
{
"type": "live_debug_log_probe",
"ip": "*",
"taskConfig": "{\"probeType\":\"LOG\",\"language\":\"python\",\"target\":{\"typeName\":\"app.service.order\",\"methodName\":\"OrderService.create_order\",\"location\":\"exit\",\"instanceIds\":[\"*\"]},\"action\":{\"type\":\"LOG\",\"template\":\"id={order_id}\"},\"ttl\":\"30m\",\"captureCount\":100}"
}
En el cuerpo HTTP, taskConfig es una cadena JSON escapada. Cuando pase el parámetro mediante --task-config en la CLI, utilice el objeto JSON sin escapar. La CLI se encarga de la serialización.
ListServiceTask
Lista las tareas de sondeo de Live-Debug.
Solicitud
GET /serviceTask/{workspace}/{serviceId}/tasks?type={taskType}&maxResults={n}
Parámetros de consulta
|
Parámetro |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
El tipo de tarea para filtrar por coincidencia exacta, por ejemplo, |
|
|
int |
No |
El número máximo de entradas que se devuelven. Valor predeterminado: |
Campos de respuesta
La CLI muestra una matriz data.serviceTasks[]. Cada elemento contiene a continuación los siguientes campos:
|
Campo |
Descripción |
|
|
El ID de la tarea. |
|
|
El tipo de tarea. |
|
|
El ID del servicio. |
|
|
La dirección IP especificada durante la creación, o bien |
|
|
La hora en la que se creó la tarea. |
|
|
La hora de la última actualización de la tarea. |
|
|
La configuración de la tarea (objeto plano del sondeo). |
Ejemplo de la CLI
aliyun cms2 apm service-task list \
--workspace <workspace> --service-id <serviceId> \
--type <taskType> --max-results 100 \
--region <regionId> -o json
GetServiceTask
Consulta los detalles de una única tarea de sondeo de Live-Debug.
Solicitud
GET /serviceTask/{workspace}/{serviceId}/task/{taskId}?type={taskType}
Parámetros de consulta
|
Parámetro |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
El tipo de tarea. Debe coincidir con el tipo real de la tarea. |
Respuesta
La CLI muestra un objeto data.serviceTask. Los campos son los mismos que los de un elemento individual en la respuesta de List.
Ejemplo de la CLI
aliyun cms2 apm service-task get \
--workspace <workspace> --service-id <serviceId> \
--task-id <taskId> --type <taskType> \
--region <regionId> -o json
DeleteServiceTask
Elimina una tarea de sondeo de Live-Debug. Tras la eliminación, el servidor quita la tarea y sincroniza el cambio con el servidor de configuración. El sondeo correspondiente en el agente queda inactivo.
Para desactivar un sondeo desplegado, elimine la tarea correspondiente.
Solicitud
DELETE /serviceTask/{workspace}/{serviceId}/task/{taskId}?type={taskType}
Parámetros de consulta
|
Parámetro |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
El tipo de tarea. Debe coincidir con el tipo real de la tarea. |
Ejemplo de la CLI
aliyun cms2 apm service-task delete \
--workspace <workspace> --service-id <serviceId> \
--task-id <taskId> --type <taskType> \
--region <regionId> -o json
Ejemplo de eliminación por lotes
Para eliminar todas las tareas de sondeo de un servicio, liste y elimine las tareas de cada uno de los cinco tipos de sondeo:
WS=<workspace>; SVC=<serviceId>; REGION=<regionId>
for t in live_debug_log_probe live_debug_snapshot_probe \
live_debug_metric_probe live_debug_span_probe live_debug_span_tag_probe; do
aliyun cms2 apm service-task list \
--workspace "$WS" --service-id "$SVC" --type "$t" --region "$REGION" -o json |
python3 -c 'import sys,json; [print(t["taskId"]) for t in (json.load(sys.stdin)["data"].get("serviceTasks") or [])]' |
while read -r id; do
aliyun cms2 apm service-task delete \
--workspace "$WS" --service-id "$SVC" \
--task-id "$id" --type "$t" --region "$REGION" -o json
done
done
Consulta de resultados de captura (SLS)
El estado y los resultados de captura se escriben en Simple Log Service (SLS). La operación Get de CMS no los devuelve.
Ejemplo de la CLI
Consulte los datos de los últimos 10 minutos. Reemplace <taskId> con el ID de tarea que devolvió la operación de creación.
FROM=$(( $(date +%s) - 600 )); TO=$(date +%s)
# Task status (installation status, funnel metrics)
aliyun sls get-logs-v2 --region <regionId> --accept-encoding gzip \
--project <slsProject> --logstore logstore-apm-logs \
--from "$FROM" --to "$TO" \
--query "* and \"<taskId>\" | SELECT content FROM log WHERE json_extract_scalar(attributes, '\$[\"livedebug.report_type\"]') = 'status'"
# Capture results (actual captured data)
aliyun sls get-logs-v2 --region <regionId> --accept-encoding gzip \
--project <slsProject> --logstore logstore-apm-logs \
--from "$FROM" --to "$TO" \
--query "* and \"<taskId>\" | SELECT content FROM log WHERE json_extract_scalar(attributes, '\$[\"livedebug.report_type\"]') != 'status'"
Parámetros de consulta
|
Parámetro |
Obligatorio |
Descripción |
|
|
Sí |
El proyecto de SLS de la aplicación, por ejemplo, |
|
|
Sí |
El nombre del logstore. Valor predeterminado: |
|
|
Sí |
El intervalo de tiempo de la consulta en marcas de tiempo Unix (segundos). |
|
|
Sí |
La región del proyecto de SLS. Debe coincidir con la región del proyecto. Especifique este parámetro de forma explícita. |
Tipos de consulta
|
Tipo de consulta |
Condición de filtro |
Descripción |
|
Estado de la tarea |
|
Estado de instalación y métricas de embudo. |
|
Resultados de captura |
|
Datos capturados reales. |
Los proyectos de SLS están aislados por región. Un parámetro region incorrecto provoca el error ProjectNotExist.
Enumeración de tipos de tarea
A continuación se muestran los cinco tipos de sondeo compatibles con aplicaciones en Python. La convención de nomenclatura es live_debug_ + semántica del sondeo en minúsculas + _probe.
|
|
Tipo de sondeo |
Descripción |
|
|
LOG |
Genera registros dinámicos en el punto de destino. |
|
|
SNAPSHOT |
Captura instantáneas de métodos y serializa el grafo de objetos. |
|
|
METRIC |
Emite métricas personalizadas en el punto de destino. |
|
|
SPAN |
Crea un span de OpenTelemetry para la ejecución de la función. |
|
|
SPAN_TAG |
Agrega atributos al span activo actual. |
Estructura taskConfig del sondeo
El objeto plano que se pasa a --task-config:
{
"probeType": "LOG|SNAPSHOT|METRIC|SPAN|SPAN_TAG",
"language": "python",
"target": { },
"action": { },
"trigger": { },
"rateLimit": { },
"ttl": "1h",
"captureCount": 100,
"enabled": true
}
Campos de nivel superior
|
Campo |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
El tipo de sondeo. Valores válidos: |
|
|
string |
Sí |
El lenguaje. Establezca este parámetro en |
|
|
object |
Sí |
Ubica el método o la línea de destino. |
|
|
object |
Sí |
La acción del sondeo. La estructura varía según |
|
|
object |
No |
La condición de activación. |
|
|
object |
No |
La configuración de limitación de velocidad. |
|
|
string |
Como mínimo uno entre |
El tiempo de vida. Formatos compatibles: |
|
|
int |
Como mínimo uno entre |
El número máximo de capturas. La tarea finaliza cuando se alcanza primero |
|
|
boolean |
No |
Por lo general es |
target: ubicación del destino
|
Campo |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Recomendado para sondeos a nivel de función |
El nombre del módulo (clave de |
|
|
string |
Recomendado para sondeos a nivel de función |
El valor |
|
|
string |
No (recomendado para sondeos a nivel de línea) |
El nombre del archivo fuente o el sufijo de la ruta. |
|
|
string |
No |
El punto de hook. Valores válidos: |
|
|
string[] |
Muy recomendado |
La lista de ID de instancia donde el sondeo surte efecto. Coloque este parámetro dentro de |
|
|
string[] |
No |
La lista de direcciones IP donde el sondeo surte efecto. Se combina con |
Los sondeos a nivel de línea pueden basarse principalmente en sourceFile + location:"line:N".
trigger: condición de activación (opcional)
|
Campo |
Tipo |
Valor predeterminado |
Descripción |
|
|
string |
- |
El sondeo captura datos solo cuando esta expresión se evalúa como verdadera. |
|
|
string |
- |
Filtro de llamante (de uso poco frecuente en Python). |
Ejemplos de condiciones: amount > 10000 o @return is None or amount > 10000
Reglas de las expresiones:
Utilice directamente nombres de parámetros, variables locales o variables globales a nivel de módulo.
En las ubicaciones
exitoexception, use@return,@duration(milisegundos) o@exception.No utilice OGNL,
args[0],returnValuenidurationMs.Si la condición hace referencia a
@returno a@exception, el campolocationdel sondeo debe serexitoexception.
rateLimit: limitación de velocidad (opcional)
|
Campo |
Tipo |
Valor predeterminado |
Descripción |
|
|
int |
Varía según el tipo de sondeo (véase más adelante) |
El máximo de ejecuciones por segundo (token bucket). |
|
|
double |
1.0 |
La probabilidad aleatoria de paso (de 0 a 1). |
|
|
int |
100 |
El tiempo de espera de una captura individual, en milisegundos. |
Límites de velocidad predeterminados: los sondeos LOG, METRIC, SPAN y SPAN_TAG permiten aproximadamente 5,000 ejecuciones por segundo. Los sondeos SNAPSHOT permiten cerca de 1 ejecución por segundo. Los sondeos a nivel de línea tienen un límite global de protección adicional de unas 100 ejecuciones por segundo.
Acción del sondeo por tipo
LOG (taskType: live_debug_log_probe)
Genera registros dinámicos en el punto de destino sin serializar el grafo de objetos.
Campos de action
|
Campo |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
Establézcalo en |
|
|
string |
Sí |
La plantilla de registro. Utilice la sintaxis |
Los sondeos LOG solo procesan la plantilla e ignoran la dimensión capture. Para capturar parámetros, valores de retorno o trazas de pila, utilice un sondeo SNAPSHOT.
Ejemplo
{
"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
}
SNAPSHOT (taskType: live_debug_snapshot_probe)
Captura instantáneas de métodos y serializa el grafo de objetos.
Campos de action
|
Campo |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
Establézcalo en |
|
|
string[] |
Sí |
Las dimensiones de captura. Si no se proporciona o se establece en |
|
|
string[] |
No |
Expresiones adicionales que se van a evaluar. |
|
|
object |
No |
Límites de serialización del grafo de objetos. |
Valores de enumeración de capture
|
Valor |
Descripción |
|
|
Serializa los argumentos del método. |
|
|
Serializa el valor de retorno. |
|
|
Serializa la instancia actual. |
|
|
Registra el resumen de la excepción. |
|
|
Captura las variables locales (requiere información de depuración). |
|
|
Captura la pila de llamadas (opcional; debe incluirse de forma explícita). |
|
|
Agrega las subllamadas dentro del cuerpo del método. |
captureConfig
|
Campo |
Valor predeterminado |
Descripción |
|
|
3 |
La profundidad máxima de serialización de objetos. |
|
|
100 |
El número máximo de elementos en colecciones o matrices. |
|
|
1024 |
La longitud máxima de las cadenas. |
|
|
50 |
El número máximo de campos por objeto. |
|
|
65536 |
El tamaño máximo de una instantánea individual, en bytes. |
|
|
50 |
La profundidad máxima de la pila de llamadas. |
|
|
|
Expresiones regulares para ocultar nombres de campos. |
captureExpressions
La sintaxis es la misma que la de trigger.condition y las plantillas LOG (eval limitado). Los resultados se escriben en context.evaluatedExpressions. Cada elemento tiene a continuación el siguiente formato:
{"name": "order_id", "type": "...", "value": "...", "notCapturedReason": null}
Si la evaluación falla, value se establece en null y notCapturedReason registra el motivo. Esto no afecta a las demás dimensiones. captureExpressions y capture son independientes entre sí.
Ejemplo
{
"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"],
"captureConfig": {
"maxDepth": 3,
"maxCollectionSize": 100,
"maxStringLength": 1024
}
},
"ttl": "30m",
"captureCount": 50
}
METRIC (taskType: live_debug_metric_probe)
Emite métricas personalizadas en el punto de destino.
Campos de action
|
Campo |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
Establézcalo en |
|
|
string |
Sí |
El nombre de la métrica, por ejemplo, |
|
|
string |
Sí |
El tipo de métrica. Valores válidos: |
|
|
string |
Sí |
Una expresión de Python que se evalúa como el valor de la métrica. |
|
|
object |
No |
Un mapa de etiquetas. Los valores son cadenas con expresiones de Python. |
Ejemplo
{
"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"
}
SPAN (taskType: live_debug_span_probe)
Crea un span de OpenTelemetry para la ejecución de la función de destino. Marca el span como ERROR y registra un evento de excepción si ocurre alguna. Solo funciona a nivel de función.
Campos de action
|
Campo |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
Establézcalo en |
|
|
string |
Sí |
El nombre del span. |
|
|
object |
No |
Un mapa de atributos. Los valores son cadenas con expresiones de Python. |
Ejemplo
{
"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_TAG (taskType: live_debug_span_tag_probe)
Agrega atributos al span activo actual. Si no existe ningún span activo, se omite de forma silenciosa.
Campos de action
|
Campo |
Tipo |
Obligatorio |
Descripción |
|
|
string |
Sí |
Establézcalo en |
|
|
array |
Sí |
Una matriz de etiquetas. Cada elemento tiene el formato |
Ejemplo
{
"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"
}
Errores y solución de problemas
|
Síntoma |
Posible causa |
Solución |
|
|
La región de SLS es incorrecta. |
Especifique la región correcta con |
|
List devuelve resultados vacíos, pero la tarea existe |
El parámetro |
Liste las tareas utilizando el tipo exacto. |
|
Crear una tarea con |
Este parámetro no afecta a las tareas ya desplegadas. |
Utilice |
|
El sondeo no captura datos |
|
Establezca |
|
La creación del SPAN falla o no es válida |
Se utilizó |
Cambie a |
|
Excepción de TTL |
Se usó la unidad |
Utilice |
Ejemplo completo de flujo de trabajo (sondeo LOG)
# 0. Environment variables
REGION=cn-hangzhou
SLS_PROJECT=proj-xtrace-xxxxxxxxxxxxxxxxxxxxxx-cn-hangzhou
WORKSPACE=default-cms-xxxxxxxxxxxxxxxxxx-cn-hangzhou
SERVICE_ID='ggxw4lnjuz@f2fd3a6265a254a052afb'
# 1. Create a task
RESP=$(aliyun cms2 apm service-task create \
--workspace "$WORKSPACE" --service-id "$SERVICE_ID" \
--type live_debug_log_probe --ip '*' \
--task-config '{"probeType":"LOG","language":"python","target":{"typeName":"app.service.order","methodName":"OrderService.create_order","location":"exit","instanceIds":["*"]},"action":{"type":"LOG","template":"id={order_id} ret={@return}"},"ttl":"30m","captureCount":50}' \
--region "$REGION" -o json)
echo "$RESP"
TASK_ID=$(echo "$RESP" | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["taskId"])')
# 2. Verify the task
aliyun cms2 apm service-task get \
--workspace "$WORKSPACE" --service-id "$SERVICE_ID" \
--task-id "$TASK_ID" --type live_debug_log_probe \
--region "$REGION" -o json
# 3. Generate traffic to the instrumented endpoint and query results (last 10 minutes)
FROM=$(( $(date +%s) - 600 )); TO=$(date +%s)
aliyun sls get-logs-v2 --region "$REGION" --accept-encoding gzip \
--project "$SLS_PROJECT" --logstore logstore-apm-logs \
--from "$FROM" --to "$TO" \
--query "* and \"$TASK_ID\" | SELECT content FROM log WHERE json_extract_scalar(attributes, '\$[\"livedebug.report_type\"]') != 'status'"
# 5. Delete the task
aliyun cms2 apm service-task delete \
--workspace "$WORKSPACE" --service-id "$SERVICE_ID" \
--task-id "$TASK_ID" --type live_debug_log_probe \
--region "$REGION" -o json