Como fazer o upload de dados de tráfego da API para a Apigee: versão Beta

Edge para nuvem privada v. 4.17.09

Todos os clientes do Edge para nuvem privada precisam enviar estatísticas do Apigee sobre o tráfego de proxy da API. A Apigee recomenda que os clientes façam upload dessas informações uma vez por dia, possivelmente criando um trabalho cron.

Você precisa enviar os dados para implantações de API de produção, mas não para implantações de desenvolvimento ou de teste. Na maioria das instalações do Edge, você define organizações ou ambientes específicos para suas APIs de produção. Os dados enviados são apenas para essas organizações e ambientes de produção.

Para ajudar no upload desses dados, a Apigee fornece a versão Beta do utilitário de linha de comando apigee-analytics-collector. Esse utilitário envia o relatório de volume de chamadas de API de volta para a Apigee. Todas as instalações do Edge para nuvem privada podem usar esse utilitário para recuperar e informar dados de tráfego para a Apigee.

Como acessar os dados enviados pelo apigee-analytics-collector

Depois de fazer upload dos dados com o utilitário apigee-analytics-collector, será possível visualizá-los no Apigee 360.

Para conferir os dados, faça login no Apigee 360 e selecione a opção Usage. A página Usage mostra um gráfico de uso e uma tabela de dados de uso para cada uma das suas organizações do Edge.

Como instalar o apigee-analytics-collector

O utilitário apigee-analytics-collector é um RPM que você instala usando o utilitário apigee-service.

Onde instalar

O nó em que você instala o utilitário apigee-analytics-collector pode ser qualquer nó que possa acessar a API de gerenciamento do Edge no servidor de gerenciamento do Edge. É possível instalá-lo diretamente no servidor de gerenciamento, em outro nó da instalação do Edge ou em um nó separado, desde que esse nó possa fazer solicitações de API para o servidor de gerenciamento.

Requisitos de acesso à Internet

Instale o utilitário apigee-analytics-collector em uma máquina com acesso externo à Internet. Em seguida, o utilitário apigee-analytics-collector pode fazer upload de dados diretamente para a Apigee.

Se não houver um nó com acesso à API de gerenciamento de borda no servidor de gerenciamento de borda e com acesso externo à Internet, use a API de gerenciamento de borda para salvar os dados de tráfego localmente. Em seguida, transfira os dados para uma máquina com acesso à Internet para fazer o upload para a Apigee. Nesse cenário, não é necessário usar o utilitário apigee-analytics-collector. Consulte Como fazer upload manual de dados para o Apigee abaixo para saber mais.

Instalação

Use o comando a seguir para instalar o utilitário apigee-analytics-collector. Como você está instalando um arquivo RPM, esse comando precisa ser executado pelo usuário raiz ou por um usuário que tenha acesso sudo total. Para acesso sudo total, isso significa que o usuário tem acesso sudo para realizar as mesmas operações que o root.

> /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector install

Como executar apigee-analytics-collector

Nesta seção, descrevemos como executar o utilitário apigee-analytics-collector.

Como configurar um usuário para executar o apigee-analytics-collector

Execute o apigee-analytics-collector como um usuário não raiz. Esse usuário precisa ter acesso total de sudo ao usuário "apigee".

Para configurar um usuário com acesso sudo total ao usuário "apigee", use o comando "visudo" para editar o arquivo sudoers e adicionar:

analyticsUser        ALL=(apigee)      NOPASSWD: ALL

em que analyticsUser é o nome de usuário da pessoa que executa o utilitário apigee-analytics-collector.

Depois de instalar o utilitário apigee-analytics-collector e configurar o usuário, é possível testar o utilitário executando o comando de ajuda para o utilitário apigee-analytics-collector:

> /opt/apigee/apigee-service/bin/ apigee-service apigee-analytics-collector export traffic --help

Informações necessárias para executar o apigee-analytics-collector

Você precisa das seguintes informações para executar o comando apigee-analytics-collector e encaminhar dados para o Apigee:

  • apigee_mgmt_api_uri: o URL base da API Edge no seu servidor de gerenciamento. Esse URL geralmente tem o seguinte formato:
    http://ms_IP:8080/v1

    Em que ms_IP é o endereço IP ou o servidor de gerenciamento e 8080 é a porta usada pela API Edge. Se você criou uma entrada de DNS para a API Edge, o URL está no formato:
    http://ms_DNS/v1

    Se você ativar o TLS na API de gerenciamento do Edge, ele estará no formato:
    https://ms_IP:8080/v1
    https://ms_DNS/v1
  • apigee_mgmt_api_email: o endereço de e-mail de uma conta com acesso às APIs /stats do Edge. Muitas vezes, esse será o e-mail do administrador do sistema do Edge ou o e-mail do administrador da organização para suas organizações de produção.
  • apigee_mgmt_api_password: a senha do Edge para a conta especificada por apigee_mgmt_api_email.
  • apigee_analytics_client_id e apigee_analytics_secret: suas credenciais para fazer upload de dados para a Apigee. Envie um tíquete para o suporte da Apigee para receber apigee_analytics_client_id e apigee_analytics_secret.

Exemplos de comandos

Veja abaixo um exemplo de comando para recuperar dados de tráfego de todas as organizações e ambientes na instalação do Edge e fazer o upload desses dados para a Apigee. Observe como você usa apigee-service para executar o comando apigee-analytics-collector:

>  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

Observe que o comando contém todas as informações necessárias, como seu apigee_analytics_client_id e apigee_analytics_secret.

Você vai encontrar os resultados no formulário:

[
  {
    "org": "myOrg",
    "env": "prod",
    "time_range_start": "08/27/2016 00:00",
    "time_range_end": "08/30/2016 00:00",
    "response": [
      {
        "store_org_env_metrics_hourly_v4": 1
      }
    ]
  },
  {
    "org": "VALIDATE",
    "env": "test",
    "time_range_start": "08/27/2016 00:00",
    "time_range_end": "08/30/2016 00:00",
    "response": [
      {
        "store_org_env_metrics_hourly_v4": 1
      }
    ]
  }
]

Use opções de linha de comando para controlar as ações do comando. Use as opções a seguir para especificar as organizações e os ambientes a serem incluídos nos dados gerados:

  • -i, --include_orgs <comma-separated list of items>
  • -x, --exclude_orgs <lista de itens separados por vírgulas>
  • -n, --include_envs <lista de itens separados por vírgulas>
  • -e, --exclude_envs <lista de itens separados por vírgulas>

Por exemplo, para especificar apenas as organizações e os ambientes de produção, use as opções -i (ou --include_orgs) e -n (ou --include_envs):

>  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

Neste exemplo, você só coleta dados do ambiente de produção de myOrg.

Para despejar os dados em uma tela e analisá-los antes de enviá-los à Apigee, use a opção -S:

>  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod -S \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

A opção -S omite o upload de dados para a Apigee. Em seguida, execute o comando sem a opção -S para enviar os dados à Apigee.

Um motivo para usar a opção -S é que você possa exibir diferentes tipos de dados localmente. A Apigee exige apenas que você faça upload dos dados de tráfego da API, mas a opção -D permite exibir dados sobre produtos, desenvolvedores, apps ou proxies de API da API. O exemplo abaixo usa as opções -D e -S para mostrar dados do desenvolvedor localmente:

>  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod -S -D devs \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

Inclua a opção -v para ter um resultado detalhado e a opção -R para ver os comandos curl gerados por apigee-analytics-collector:

 >  /opt/apigee/apigee-service/bin/apigee-service apigee-analytics-collector export traffic -i myOrg -n prod -S -R -v \
--apigee_mgmt_api_uri http://192.168.56.103:8080/v1 \
--apigee_mgmt_api_email $ae_username \
--apigee_mgmt_api_password $ae_password \
--apigee_analytics_client_id $apigee_analytics_client_id \
--apigee_analytics_secret $apigee_analytics_secret

A próxima seção contém uma lista completa de opções de linha de comando.

Parâmetros de comando

A tabela a seguir lista o conjunto completo de opções para o utilitário apigee-analytics-collector:

Comando

Uso

-h, --help

Gerar informações de uso

-D, --dimension <dimension>

A dimensão de tráfego a ser coletada. Dimensões válidas: apiproducts, devs, apps, apiproxy (padrão)

-d, --days <days>

O número de dias anteriores, a partir da data atual, de dados a serem coletados. O padrão é 3.

Se você especificar -d, não especifique também -s e -z para definir um intervalo de tempo.

-m, --apigee_mgmt_api_uri <apigee_mgmt_api_uri>

URL para a API Edge Management.

-u, --apigee_mgmt_api_email <apigee_mgmt_api_email>

O endereço de e-mail de uma conta com acesso às APIs /stats do Edge. Geralmente, esse é o e-mail do administrador do sistema do Edge ou do administrador da organização de produção.

-p, --apigee_mgmt_api_password <apigee_mgmt_api_password>

Senha associada à conta de e-mail da API Edge Management especificada por -u.

-i, --include_orgs <items>

Lista separada por vírgulas de organizações a serem incluídas na saída.

-x, --exclude_orgs <itens>

Lista separada por vírgulas de organizações a serem excluídas da saída.

-n, --include_envs <items>

Lista separada por vírgulas de ambientes a serem incluídos na saída.

-e, --exclude_envs <items>

Lista separada por vírgulas de ambientes para incluir na saída.

-o, --output <path>

Caminho e nome do arquivo para salvar a saída.

-s, --time_range_start <time_range_start>

Intervalo de tempo para começar a consultar as estatísticas de tráfego, no formato: "03/01/2016 00:00".

Se você especificar -d, não especifique também -s e -z para definir um período.

-z, --time_range_end <time_range_end>

Fim do período para consultar estatísticas de tráfego, no formato: "04/01/2016 24:00".

Se você especificar -d, não especifique também -s e -z para definir um período.

-t, --time_unit <time_unit>

Unidade de tempo para dados de tráfego. Semana padrão. Unidades padrão por hora. Unidades de tempo válidas: segundo, minuto, hora, dia, semana.

-S, --standard_output

Gravar a saída no terminal (stdout), em vez de fazer upload para a Apigee.

-c, --apigee_analytics_client_id <apigee_analytics_client_id>

Seu ID para fazer upload de dados para a Apigee. Para receber, envie um tíquete com o suporte da Apigee.

-r, --apigee_analytics_secret <apigee_analytics_secret>

Sua chave secreta para fazer upload de dados para a Apigee. Envie um tíquete ao suporte da Apigee para receber.

-R, --include_curl_commands

Inclua os comandos cURL gerados na saída para depuração.

-v, --verbose

Mostra uma saída detalhada.

Como fazer upload manual de dados para a Apigee

A Apigee recomenda que você instale o utilitário apigee-analytics-collector em uma máquina com acesso externo à Internet. Em seguida, o utilitário apigee-analytics-collector poderá fazer o upload dos dados diretamente na Apigee.

No entanto, se a máquina não tiver acesso externo à Internet, use a API Edge Management para coletar dados de tráfego e, em seguida, use comandos cURL para fazer upload desses dados na Apigee de uma máquina com acesso à Internet. Repita esse processo para cada organização e ambiente de produção na sua instalação do Edge.

Use o comando cURL a seguir para coletar dados de tráfego de uma organização e ambiente específicos em um intervalo de tempo especificado:

curl -X GET -u apigee_mgmt_api_email:apigee_mgmt_api_password \
"http://<ms_IP>:8080/v1/organizations/{org_name}/environments/{env_name}/stats/?select=sum(message_count)&timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM"

Esse comando usa a API Edge Get para contagem de mensagens. Nesse comando:

  • apigee_mgmt_api_email:apigee_mgmt_api_password especifica o endereço de e-mail de uma conta com acesso às APIs Edge /stats.
  • <ms_IP> é o endereço IP ou o nome DNS do servidor de gerenciamento do Edge.
  • {org_name} e {env_name} especificam a organização e o ambiente.
  • MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM especifica o período das estatísticas a serem coletadas. O comando cURL usa o código hexadecimal %20 para os espaços no período.

Por exemplo, para coletar estatísticas de um período de 24 horas, use o seguinte comando:

curl -X GET -u apigee_mgmt_api_email:apigee_mgmt_api_password \
"http://192.168.56.103:8080/v1/organizations/myOrg/environments/prod/stats/?select=sum(message_count)&timeRange=08/29/2016%2000:00~08/30/2016%2000:00"

Você verá uma resposta no formato:

{
  "environments" : [ {
    "metrics" : [ {
      "name" : "sum(message_count)",
      "values" : [ "42.0" ]
    } ],
    "name" : "prod"
  } ],
  "metaData" : {
    "errors" : [ ],
    "notices" : [ "query served by:53dab80c-e811-4ba6-a3e7-b96f53433baa", "source pg:6b7bab33-e732-405c-a5dd-4782647ce096", "Table used: myorg.prod.agg_api" ]
  }
}

Para fazer upload desses dados no Apigee de uma máquina com acesso à Internet, use o seguinte comando cURL:

curl -X POST -H 'Content-Type:application/json' \
-u apigee_analytics_client_id:apigee_analytics_secret \
https://nucleus-api-prod.apigee.com/v1/apigee-analytics-cli-api/traffic/orgs/{org_name}/apis -d '{"environments"...}'

em que:

  • apigee_analytics_client_id:apigee_analytics_secret especifica suas credenciais para fazer upload de dados para a Apigee que você recebeu do suporte da Apigee.
  • {org_name} especifica a organização.
  • {"environments"...} contém os resultados do comando cURL que você usou para coletar as estatísticas acima.