Appstats para Python 2

O SDK para Python 2 inclui a biblioteca do Appstats usada para criar o perfil do desempenho da Chamada de procedimento remoto (RPC, na sigla em inglês) do seu aplicativo. Uma RPC do App Engine é uma chamada de rede de ida e volta entre seu aplicativo e uma App Engine Service API. Por exemplo, todas estas chamadas da API são chamadas RPC:

Chamadas do Datastore, como ndb.get_multi(), ndb.put_multi() ou ndb.gql().
Chamadas do Memcache, como memcache.get() ou memcache.get_multi().
Chamadas de busca de URL, como urlfetch.fetch().
Chamadas de E-mail, como mail.send().

Otimizar ou depurar um aplicativo escalonável pode ser um desafio porque vários problemas podem causar baixo desempenho ou custos inesperados. Esses problemas são muito difíceis de depurar com as fontes de informações comuns, como registros ou estatísticas de tempo de solicitação. A maioria das solicitações de aplicativos passa a maior parte do tempo esperando que as chamadas de rede sejam concluídas como parte do processo de atender a solicitação.

Para manter seu aplicativo rápido, você precisa saber disto:

Seu aplicativo está fazendo chamadas RPC desnecessárias?
Ele armazena dados em cache em vez de fazer chamadas RPC repetidas para conseguir os mesmos dados?
Seu aplicativo funcionará melhor se várias solicitações forem executadas em paralelo em vez de em série?

A biblioteca do Appstats ajuda você a responder essas perguntas e verificar se o aplicativo está usando chamadas RPC da maneira mais eficiente ao permitir que você defina perfis de suas chamadas RPC. O Appstats permite rastrear todas as chamadas RPC de determinada solicitação e relata o tempo e o custo de cada chamada.

A otimização do uso da RPC do aplicativo também pode reduzir a fatura. Consulte Como gerenciar recursos do app.

Assistir a uma demonstração em vídeo.

Configuração

Para começar a usar o Appstats, não é necessário fazer o download nem a instalação dele. A única exigência é configurar seu aplicativo, reimplantá-lo e acessar o console do Appstats de acordo com a descrição contida nas etapas abaixo. A biblioteca do Appstats cuida do restante.

1. Instalar o gravador de eventos

Para registrar estatísticas sobre solicitações da Web, cada gerenciador de solicitações do aplicativo precisa invocar o Appstats. Dependendo da biblioteca usada pelo aplicativo, escolha uma das seguintes opções:

Gerenciadores de solicitações WSGI

Para usar o Appstats com gerenciadores de solicitações WSGI, inclusive bibliotecas WSGI, como webapp2, encapsule o aplicativo WSGI com o middleware de appstats. A maneira mais simples de fazer isso é definir um middleware WSGI para envolver cada aplicativo WSGI usando appengine_config.py.

Se ele ainda não existir, crie um arquivo chamado appengine_config.py no diretório raiz do aplicativo. Adicione a seguinte função ao arquivo:
```
def webapp_add_wsgi_middleware(app):
    from google.appengine.ext.appstats import recording
    app = recording.appstats_wsgi_middleware(app)
    return app
```
Para invocar o aplicativo WSGI, o ambiente de execução importará esse arquivo e chamará a função webapp_add_wsgi_middleware, se encontrada.

Consulte Configuração opcional abaixo para mais informações sobre appengine_config.py.
Framework do Django

Para instalar o middleware do Appstats em um aplicativo Django, edite seu arquivo settings.py e adicione a seguinte linha para ser o primeiro item em MIDDLEWARE_CLASSES:
```
    MIDDLEWARE_CLASSES = (
  'google.appengine.ext.appstats.recording.AppStatsDjangoMiddleware',

  # ...
)
```
É necessário que o middleware do Appstats seja o primeiro item. Dessa maneira, o criador de perfil pode incluir outro middleware nas estatísticas.

O middleware do Django chama o Appstats para registrar eventos, conforme apropriado. Você não precisa alterar nenhum outro código de aplicativo.

2. Definir o caminho do console

O console do Appstats é acessado por meio de um URL para seu aplicativo em um navegador da Web. Defina o caminho do URL de duas maneiras:

URL padrão

Para mapear o Appstats até o diretório padrão (/_ah/stats/), adicione o builtin appstats ao seu arquivo app.yaml:
```
runtime: python27
api_version: 1
threadsafe: yes

builtins:
- appstats: on

handlers:
- url: .*
  script: main.app
```
URL personalizado

Se você precisar mapear o Appstats para um diretório diferente do padrão, use a diretiva url em app.yaml:
```
  - url: /stats.*
  script: google.appengine.ext.appstats.ui.app
  
```

3. Configuração opcional

Você pode configurar o comportamento do Appstats adicionando conteúdo ao arquivo appengine_config.py no diretório raiz do aplicativo. Para obter um exemplo completo das opções de configuração, consulte o arquivo google/appengine/ext/appstats/sample_appengine_config.py no SDK.

Algumas informações sobre appengine_config.py:

Se os manipuladores de solicitação modificarem sys.path, você deverá fazer as mesmas modificações ao sys.path em appengine_config.py, para que a interface da web do Appstats possa ver todos os arquivos.

Como exibir o custo

O AppStats pode acompanhar o custo da RPC e o tempo. Se o aplicativo é rápido o suficiente, mas é mais caro do que o esperado, procure operações que custem mais do você espera. Para ativar o rastreamento de custos, defina appstats_CALC_RPC_COSTS = True no seu arquivo appengine_config.py.

4. Testar o Appstats pelo servidor de desenvolvimento

Teste a configuração do Appstats com o servidor de desenvolvimento. Se tiver configurado o caminho do console para usar o URL padrão acima, você poderá acessar o console em http://localhost:8080/_ah/stats/.

5. Implantar

Quando você estiver satisfeito com a configuração do Appstats, implante o aplicativo. Se você configurou o caminho do console para usar o URL padrão acima, acesse o console em http://your_app_id.appspot.com/_ah/stats.

Um tour pelo console do Appstats

O console do Appstats fornece informações gerais sobre chamadas RPC feitas, caminhos de URL solicitados, histórico de solicitações recentes e detalhes de solicitações individuais:

A tabela RPC Stats mostra estatísticas para cada tipo de RPC feita pelo aplicativo. Clique em um botão com o sinal de adição para expandir a entrada e exibir um detalhamento por solicitação de caminho da RPC:
A tabela Path Stats mostra as estatísticas de cada solicitação de caminho enviada ao aplicativo. Clique em um botão com o sinal de adição para expandir a entrada e exibir um detalhamento das solicitações de caminho por RPC.

Se você ativou o recurso de rastreamento de custos da API, isso também exibirá os custos.
A tabela Request History mostra os dados relativos às solicitações individuais. Clicar em um botão de adição expande a entrada para exibir um detalhamento por RPC. Clicar em um link de solicitação mostra um cronograma para a solicitação, incluindo o tempo RPC individual:
O gráfico Timeline de RPC mostra quando as chamadas RPC específicas foram feitas e quanto tempo as solicitações levaram para serem processadas. A barra Total de RPC mostra o tempo total gasto aguardando chamadas RPC, e a barra Total geral mostra o tempo total gasto no processamento da solicitação. Como você pode ver na linha do tempo abaixo, a maior parte do tempo foi gasto em chamadas RPC. Frequentemente, esse é o caso. As outras guias mostram informações adicionais sobre a solicitação. Entender o impacto das chamadas de RPC no tempo de resposta do seu aplicativo é inestimável ao analisar o desempenho.

O Interactive Playground permite que desenvolvedores insiram um código do Python arbitrário em um formulário da Web e o executem dentro do ambiente do app.

Depois de navegar até Appstats, clique no link do Interactive Playground. Um formulário com uma única área de texto será exibido. Insira qualquer código arbitrário do Python à sua escolha na área de texto e envie o formulário para executá-lo. Todos os resultados impressos na saída padrão são exibidos ao lado da área de texto, e uma análise da Linha do tempo das chamadas de RPC geradas pelo código é exibida.

O Interactive Playground pode ser ativado ou desativado. No SDK, ele é ativado por padrão. Na produção, ele é desativado por padrão. Para ativá-lo, adicione a seguinte linha ao arquivo appengine_config.py:
```
<pre suppresswarning="yes" class="prettyprint">
appstats_SHELL_OK = True
</pre>
```
Aviso: o Interactive Playground tem o mesmo acesso ao ambiente e aos serviços do aplicativo que um arquivo .py dentro do próprio aplicativo. Tome cuidado, porque isso significa que gravações no armazenamento de dados serão executadas de fato.

Como funciona

O Appstats usa hooks da API para se adicionar à estrutura de chamada de procedimento remoto localizada nas APIs de serviço do App Engine. Ele grava estatísticas de todas as chamadas à API feitas durante o gerenciador de solicitações e armazena os dados em memcache, usando um namespace __appstats__. O Appstats retém estatísticas das 1.000 solicitações mais recentes. Os dados incluem registros de resumo, cada um com cerca de 200 bytes, e registros de detalhes, que podem ter até 100 KB cada. Controle o valor de detalhes armazenados em registros detalhados. Consulte Configuração opcional e o arquivo de configuração de exemplo.

Os ganchos de API adicionam sobrecarga aos gerenciadores de solicitações. O Appstats adiciona uma mensagem aos registros no nível "info" para relatar o volume de recursos consumidos pela própria biblioteca do Appstats. A linha do registro é semelhante a esta:

<pre suppresswarning="yes" class="prettyprint">
INFO 2009-08-25 12:04:07,277 recording.py:290] Saved; key: __appstats__:046800, part: 160 bytes, full: 25278 bytes, overhead: 0.019 + 0.018; link: http://your_app_id.[REGION_ID].r.appspot.com/stats/detail?time=1234567890123
</pre>

Esta linha informa a chave do cache de memória que foi atualizada, o tamanho dos registros de resumo (part) e registros de detalhe (full) e o tempo (em segundos) gasto para gravar essas informações. A linha do registro inclui o link para a interface administrativa do Appstats que exibe os dados desse evento.