Python agent FAQ - Application Real-Time Monitoring Service: Central de Documentação do Alibaba Cloud

Este FAQ responde às perguntas mais comuns sobre o agente Python.

A instalação falha ao usar aliyun-bootstrap -a install

A instalação do agente com o comando aliyun-bootstrap -a install pode gerar o seguinte erro:

Installation aborted due to download failure.

Essa falha geralmente ocorre por um dos dois motivos abaixo:

Um problema de rede impede que o agente acesse seu endpoint do OSS. Verifique a conexão de rede.

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]

O módulo SSL está ausente no interpretador Python.

python3 -m ssl

Se esse comando retornar um erro, significa que o módulo SSL não está disponível no seu interpretador Python. O script aliyun-bootstrap depende desse módulo para baixar as dependências; portanto, instale-o no seu ambiente Python.

Erro na inicialização: No module named 'aliyun'

Esse erro indica que o agente foi instalado em um local inacessível à aplicação durante a execução. Garanta que o interpretador Python no ambiente da aplicação localize as dependências do agente Python.

Execute o comando abaixo no ambiente da sua aplicação para verificar se o aliyun-bootstrap instalou o pacote do agente em um caminho pesquisável:

python3 -m site

Esse comando exibe os caminhos de busca que o interpretador Python utiliza para localizar pacotes. Caso as dependências do agente Python, conforme ilustrado na estrutura de diretórios a seguir, não apareçam em nenhum desses caminhos, o local de instalação está incorreto.

.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

Use o comando a seguir para especificar o local de instalação do pacote aliyun-bootstrap:

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

Substitua ${TARGET_PATH} pelo caminho correto do seu ambiente. Por exemplo, o caminho pode ser /root/demo/venv/lib/python3.12/site-packages.

Nenhum dado reportado por aplicações Flask

Não é possível usar o método aliyun-instrument para integrar uma aplicação Flask quando o modo de depuração está ativado. Nesse caso, adicione as instruções abaixo ao arquivo de entrada da aplicação Flask para importar manualmente o agente Python. Isso permite iniciar a aplicação sem adicionar o prefixo aliyun-instrument.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Falha ao iniciar aplicação Django

Caso sua aplicação Django não inicie e apresente um erro semelhante a AttributeError: module 'django.conf global_settings' has no attribute 'ROOT_URLCONF', defina a variável de ambiente DJANGO_SETTINGS_MODULE apontando para o módulo de configurações do seu projeto.

export DJANGO_SETTINGS_MODULE=instrumentation_example.settings

Nenhum dado reportado por aplicações Django

O recurso de recarregamento automático do Django, habilitado por padrão em comandos como python manage.py runserver 0.0.0.0:8080, pode impedir que o agente reporte dados. Para corrigir isso, adicione a opção --noreload e desative o recarregamento automático:

python manage.py runserver 0.0.0.0:8080 --noreload

Nenhum dado reportado por aplicações Uvicorn

O uso do servidor Uvicorn com recarregamento automático (parâmetro --reload) ou com múltiplos workers (parâmetro --workers) pode bloquear o envio de dados pelo agente. Para resolver essa questão, importe manualmente o agente Python adicionando a linha abaixo ao arquivo de entrada da sua aplicação. Não use o prefixo aliyun-instrument ao iniciar a aplicação.

from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize

Desinstalar o agente

Para desinstalar o agente Python, execute o seguinte comando:

aliyun-bootstrap -a uninstall

Instalar uma região e versão específicas

Para obter o melhor desempenho, talvez seja necessário instalar uma versão específica do agente a partir da região mais próxima. Siga estas etapas:

Defina a variável de ambiente ARMS_REGION_ID para especificar a região de onde o agente será baixado.

export ARMS_REGION_ID=cn-beijing

Para consultar a lista de regiões suportadas, veja Available regions.

Instale uma versão específica do agente Python com o comando abaixo. Se já houver outra versão do agente instalada, recomendamos desinstalá-la primeiro.

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

Se você instalou o agente Python usando o método não intrusivo descrito em Install the Python agent with the ack-onepilot component in Container Service for Kubernetes (ACK) and Container Compute Service (ACS), especifique a versão do agente adicionando o rótulo aliyun.com/agent-version. Para mais informações, consulte Control agent versions independently.

Para ver a lista completa das versões publicadas do agente Python, acesse Python agent release notes.

Especificar o diretório de logs

Certifique-se de que a versão do seu agente Python seja 1.6.0 ou superior. Em seguida, defina a variável de ambiente APSARA_APM_AGENT_WORKSPACE_DIR. O agente armazenará seus arquivos de log no diretório ${APSARA_APM_AGENT_WORKSPACE_DIR}/.apsara-apm/python/logs.

Por padrão, o agente determina o diretório de logs seguindo esta ordem de prioridade:

/home/admin/.opt/.apsara-apm/python/logs (diretório de volume do componente ack-onepilot)
~/.apsara-apm/python/logs (diretório home do usuário)
./.apsara-apm/python/logs (mesmo diretório do arquivo de entrada principal do Python)

Os nomes dos arquivos de log seguem o formato aliyun-python-agent-{PID}.log, onde {PID} representa o ID do processo (por exemplo, aliyun-python-agent-5921.log). Esse mesmo diretório também contém os arquivos de log de diagnóstico diagnose-{PID}.log.

Especificar o modo de reporte de rede

Se a versão do seu agente for 1.6.0 ou superior, defina a variável de ambiente PROFILER_NETWORK_STRATEGY para configurar o modo de reporte de rede:

internal: Força o reporte via rede interna.
public: Força o reporte via rede pública.
auto: Detecta automaticamente o modo de rede (comportamento padrão).

Uso invisível de tokens em streaming OpenAI

Para mais detalhes, consulte Streaming output. Por padrão, o protocolo OpenAI não retorna o uso de tokens em chamadas de streaming. Para receber essas informações, configure stream_options={"include_usage": true} e inclua os detalhes de uso de tokens no último bloco de dados.

Impedir a injeção do agente em processos filhos

Para evitar que o agente seja injetado em qualquer processo filho criado pela aplicação alvo, defina a variável de ambiente APSARA_APM_INSTRUMENTATION_CHILD_PROCESS como false.