Python agent FAQ - Application Real-Time Monitoring Service - Centro de documentación de Alibaba Cloud

Esta sección de preguntas frecuentes responde a las dudas más comunes sobre el agente de Python.

La instalación falla al usar aliyun-bootstrap -a install

Al instalar el agente con el comando aliyun-bootstrap -a install, puede presentarse el siguiente error:

Installation aborted due to download failure.

Este fallo suele deberse a una de las siguientes dos causas:

Un problema de red impide que el agente se conecte a su endpoint de OSS. Compruebe la conexión de red.

Starting Aliyun Python Agent installation...
agent download url: https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz
Checking network connectivity...
Downloading agent from https://arms-apm-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com/aliyun-python-agent/aliyun-python-agent.tar.gz...
Downloading: 100%|████████████████████████████████████████████████████████████| 1.00M/1.00M [00:00<00:00, 6.21MB/s]
Extracting wheels from archive...
Extracting files: 100%|███████████████████████████████████████████████████████| 27/27 [00:00<00:00, 2151.05file/s]
Found 27 wheel files
Installing 27 packages...
Installing packages:   0%|                                                   | 0/27 [00:00<?, ?pkg/s]
Installing packages:   0%|                                                   | 0/27 [00:00<?, ?pkg/s]

Falta el módulo SSL en su intérprete de Python.

python3 -m ssl

Si este comando devuelve un error, significa que falta el módulo SSL en su intérprete de Python. El script aliyun-bootstrap requiere este módulo para descargar las dependencias, por lo que debe instalarlo en su entorno de Python.

Error de inicio: No module named 'aliyun'

Este error indica que el agente se instaló en una ubicación que su aplicación no encuentra durante la ejecución. Debe asegurarse de que el intérprete de Python en el entorno de su aplicación pueda localizar las dependencias del agente de Python.

Ejecute el siguiente comando en el entorno de su aplicación para comprobar si aliyun-bootstrap instaló el paquete del agente en una ruta accesible:

python3 -m site

Este comando muestra las rutas de búsqueda que utiliza el intérprete de Python para encontrar paquetes. Si las dependencias del agente de Python, como se muestra en la estructura de directorios de ejemplo a continuación, no se encuentran en ninguna de estas rutas, la ubicación de instalación es incorrecta.

.venv
  bin
  lib
    python3.12
      site-packages  library root
        _distutils_hack
        aliyun
          instrumentation
          opentelemetry
          sdk
          semconv
            __init__.py
        aliyun_instrumentation_dashscope-1.0.0.dist-info
        aliyun_instrumentation_dify-1.1.0.dist-info
        aliyun_instrumentation_langchain-1.1.0.dist-info
        aliyun_instrumentation_llama_index-1.0.3.dev0.dist-info
        aliyun_instrumentation_openai-1.0.1.dist-info
        aliyun_instrumentation_vllm-0.1.0.dist-info
        aliyun_opentelemetry_exporter_otlp_proto_common-1.25.0.dist-info
        aliyun_opentelemetry_exporter_otlp_proto_grpc-1.25.0.dist-info
        aliyun_opentelemetry_exporter_otlp_proto_http-1.25.0.dist-info
        aliyun_opentelemetry_instrumentation-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_aiohttp_client-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_asgi-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_django-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_fastapi-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_flask-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_httpx-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_logging-0.46b0.dev0.dist-info
        aliyun_opentelemetry_instrumentation_redis-0.46b0.dev0.dist-info

Utilice el siguiente comando para especificar la ubicación de instalación del paquete aliyun-bootstrap:

aliyun-bootstrap -a install -t ${TARGET_PATH}

Reemplace ${TARGET_PATH} con la ruta correcta para su entorno. Por ejemplo, la ruta podría ser /root/demo/venv/lib/python3.12/site-packages.

No se reportan datos desde aplicaciones Flask

No es posible utilizar el método aliyun-instrument para integrar una aplicación Flask cuando el modo de depuración está habilitado. En su lugar, debe agregar las siguientes instrucciones al archivo de entrada de la aplicación Flask para importar manualmente el agente de Python. Esto le permite iniciar la aplicación sin necesidad de añadir el prefijo aliyun-instrument.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Fallo al iniciar la aplicación Django

Si su aplicación Django no inicia y muestra un error similar a AttributeError: module 'django.conf global_settings' has no attribute 'ROOT_URLCONF', establezca la variable de entorno DJANGO_SETTINGS_MODULE apuntando al módulo de configuración de su proyecto.

export DJANGO_SETTINGS_MODULE=instrumentation_example.settings

No se reportan datos desde aplicaciones Django

La función de recarga en caliente de Django, habilitada de forma predeterminada con comandos como python manage.py runserver 0.0.0.0:8080, puede impedir que el agente reporte datos. Para solucionar esto, agregue la opción --noreload para deshabilitar la recarga en caliente:

python manage.py runserver 0.0.0.0:8080 --noreload

No se reportan datos desde aplicaciones Uvicorn

El uso de un servidor Uvicorn con recarga en caliente (parámetro --reload) o con múltiples workers (parámetro --workers) puede impedir que el agente reporte datos. Para resolverlo, importe manualmente el agente de Python añadiendo la siguiente línea al archivo de entrada de su aplicación. No utilice el prefijo aliyun-instrument al iniciar la aplicación.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Desinstalar el agente

Para desinstalar el agente de Python, ejecute el siguiente comando:

aliyun-bootstrap -a uninstall

Instalar una región y versión específicas

Para obtener un rendimiento óptimo, es posible que necesite instalar una versión específica del agente desde la región más cercana. Siga estos pasos:

Establezca la variable de entorno ARMS_REGION_ID para especificar la región desde la cual se obtendrá el agente.

export ARMS_REGION_ID=cn-beijing

Para consultar la lista de regiones compatibles, véase Available regions.

Instale una versión específica del agente de Python con el siguiente comando. Si ya tiene instalada otra versión del agente, se recomienda desinstalarla primero.

# Replace ${version} with the target version number
aliyun-bootstrap -a install -v ${version}

Si instaló el agente de Python mediante el método no intrusivo descrito en Install the Python agent with the ack-onepilot component in Container Service for Kubernetes (ACK) and Container Compute Service (ACS), puede especificar la versión del agente agregando la etiqueta aliyun.com/agent-version. Para más información, consulte Control agent versions independently.

Para ver la lista completa de versiones publicadas del agente de Python, consulte Python agent release notes.

Especificar el directorio de registros

Asegúrese de que la versión de su agente de Python sea 1.6.0 o posterior. Luego, configure la variable de entorno APSARA_APM_AGENT_WORKSPACE_DIR. El agente almacenará sus archivos de registro en el directorio ${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs.

De forma predeterminada, el agente determina el directorio de registros siguiendo este orden de prioridad:

/home/admin/.opt/.apsara-apm/python/logs (Directorio de volumen del componente ack-onepilot)
~/.apsara-apm/python/logs (Directorio principal del usuario)
./.apsara-apm/python/logs (Mismo directorio que el archivo de entrada principal de Python)

Los nombres de los archivos de registro siguen el formato aliyun-python-agent-{PID}.log, donde {PID} es el identificador del proceso (por ejemplo, aliyun-python-agent-5921.log). En el mismo directorio también se encuentran los archivos de registro de diagnóstico diagnose-{PID}.log.

Especificar el modo de reporte de red

Si la versión de su agente es 1.6.0 o posterior, puede configurar la variable de entorno PROFILER_NETWORK_STRATEGY para especificar el modo de reporte de red:

internal: Fuerza el reporte por red interna.
public: Fuerza el reporte por red pública.
auto: Detecta automáticamente el modo de red (comportamiento predeterminado).

Uso invisible de tokens en streaming de OpenAI

Para más información, consulte Streaming output. De forma predeterminada, el protocolo de OpenAI no devuelve el uso de tokens en las llamadas de streaming. Para recibir esta información, establezca stream_options={"include_usage": true} e incluya así los detalles de uso de tokens en el último fragmento de datos.

Evitar la inyección del agente en procesos secundarios

Para evitar que el agente se inyecte en cualquier proceso secundario creado por la aplicación objetivo, establezca la variable de entorno APSARA_APM_INSTRUMENTATION_CHILD_PROCESS en false.