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

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

É preciso enviar os dados das implantações de API de produção, mas não das APIs em implantações de desenvolvimento ou 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. Cada instalação do Edge para nuvem privada pode usar esse utilitário para recuperar e informar dados de tráfego à Apigee.

Obrigatório: entre em contato com o suporte da Apigee antes de fazer upload de dados

Antes de fazer upload de dados para a Apigee, entre em contato com o suporte da Apigee Edge para concluir o processo de integração.

Instalar o apigee-analytics-collector

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

Como 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 ao servidor de gerenciamento.

Requisitos de acesso à Internet

Instale o utilitário apigee-analytics-collector em uma máquina com acesso à Internet externo. 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 da borda no servidor de gerenciamento da borda e acesso à Internet externa, use a API de gerenciamento da borda para salvar os dados de tráfego localmente. Em seguida, transfira os dados para uma máquina com acesso à Internet para fazer 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 a Apigee para mais informações.

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 total ao sudo. Para acesso total ao sudo, isso significa que o usuário tem acesso ao sudo para realizar as mesmas operações que o root.

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

Como executar o 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 apigee-analytics-collector como um usuário não raiz. Esse usuário precisa ter acesso sudo completo ao usuário "apigee".

Para configurar um usuário para ter acesso sudo completo 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, teste 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 a Apigee:

  • apigee_mgmt_api_uri: o URL de base da API Edge no 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 DNS para a API Edge, o URL estará no formato:

    http://ms_DNS/v1

    Se você ativar o TLS na API de gerenciamento da borda, 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 do Edge /stats. Geralmente, 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 ao suporte da Apigee Edge 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 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 apigee_analytics_client_id e apigee_analytics_secret.

Os resultados vão aparecer no seguinte formato:

[
  {
    "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 as opções de linha de comando para controlar as ações do comando. Use as seguintes opções para especificar as organizações e os ambientes que serão incluídos nos dados gerados:

  • -i, --include_orgs comma-separated list of items
  • -x, --exclude_orgs comma-separated list of items
  • -n, --include_envs comma-separated list of items
  • -e, --exclude_envs comma-separated list of items

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 para examiná-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 novamente sem a opção -S para enviar os dados à Apigee.

Um motivo para usar a opção -S é que você pode 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 de API, desenvolvedores, apps ou proxies de API. O exemplo abaixo usa as opções -D e -S para exibir 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 receber uma saída detalhada 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 Descrição
-h, --help

Informações de uso de saída

-D, --dimension dimension

A dimensão de tráfego a ser coletada. Os valores válidos são:

  • apiproducts
  • apiproxy (padrão)
  • apps
  • devs
-d, --days days

O número de dias anteriores de dados a serem coletados, começando na data atual. O padrão é 3.

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

-m, --apigee_mgmt_api_uri apigee_mgmt_api_uri

URL para a API Management do Edge.

-u, --apigee_mgmt_api_email apigee_mgmt_api_email

O endereço de e-mail de uma conta com acesso às APIs do Edge /stats. Normalmente, é 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.

-p, --apigee_mgmt_api_password apigee_mgmt_api_password

A senha associada à conta de e-mail da API Management do Edge especificada por -u.

-i, --include_orgs items

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

-x, --exclude_orgs items

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

-n, --include_envs items

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

-e, --exclude_envs items

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

-o, --output path

O caminho e o nome do arquivo para salvar a saída.

-s, --time_range_start time_range_start

Período para iniciar a consulta de estatísticas de tráfego, no formato: "MM/DD/YYYY HH:MM".

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 as 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. O valor padrão é hour. As unidades de tempo válidas são:

  • second
  • minute
  • hour (padrão)
  • day
  • week

Se você definir -t como week e -d como 365, a Apigee vai retornar uma grande quantidade de dados, agrupados em 52 entradas separadas (uma para cada semana).

-S, --standard_output

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

-c, --apigee_analytics_client_id apigee_analytics_client_id

Seu ID para fazer upload de dados para a Apigee. Envie um tíquete ao suporte da Apigee Edge para receber.

-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 Edge para receber.

-R, --include_curl_commands

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

-v, --verbose

Mostra uma saída detalhada.

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 pode fazer upload de dados diretamente para a Apigee.

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

Use o seguinte comando curl para coletar dados de tráfego de uma organização e um 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/apiproxy?select=sum(message_count)&timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM&timeUnit=hour"

Esse comando usa a API Get API message count do Edge. Nesse comando:

  • apigee_mgmt_api_email:apigee_mgmt_api_password especifica o endereço de e-mail de uma conta com acesso às APIs /stats do Edge.
  • 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.
  • apiproxy é a dimensão que agrupa as métricas por proxies de API.
  • MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM&timeUnit=hour especifica o período dividido em unidades de tempo das métricas a serem coletadas. Observe que o comando curl usa o código hexadecimal %20 para espaços no período.

Por exemplo, para coletar contagens de mensagens de proxy de API hora a hora em um período de 24 horas, use a seguinte chamada de API.

curl -X GET -u apigee_mgmt_api_email:apigee_mgmt_api_password \
"http://192.168.56.103:8080/v1/organizations/myOrg/environments/prod/stats/apiproxy?select=sum(message_count)&timeRange=01%2F01%2F2018%2000%3A00~01%2F02%2F2018%2000%3A00&timeUnit=hour"

Observe que timeRange contém caracteres codificados em URL.

Você verá uma resposta no formato:

{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values": [
                {
                  "timestamp": 1514847600000,
                  "value": "35.0"
                },
                {
                  "timestamp": 1514844000000,
                  "value": "19.0"
                },
                {
                  "timestamp": 1514840400000,
                  "value": "58.0"
                },
                {
                  "timestamp": 1514836800000,
                  "value": "28.0"
                },
                {
                  "timestamp": 1514833200000,
                  "value": "29.0"
                },
                {
                  "timestamp": 1514829600000,
                  "value": "33.0"
                },
                {
                  "timestamp": 1514826000000,
                  "value": "26.0"
                },
                {
                  "timestamp": 1514822400000,
                  "value": "57.0"
                },
                {
                  "timestamp": 1514818800000,
                  "value": "41.0"
                },
                {
                  "timestamp": 1514815200000,
                  "value": "27.0"
                },
                {
                  "timestamp": 1514811600000,
                  "value": "47.0"
                },
                {
                  "timestamp": 1514808000000,
                  "value": "66.0"
                },
                {
                  "timestamp": 1514804400000,
                  "value": "50.0"
                },
                {
                  "timestamp": 1514800800000,
                  "value": "41.0"
                },
                {
                  "timestamp": 1514797200000,
                  "value": "49.0"
                },
                {
                  "timestamp": 1514793600000,
                  "value": "35.0"
                },
                {
                  "timestamp": 1514790000000,
                  "value": "89.0"
                },
                {
                  "timestamp": 1514786400000,
                  "value": "42.0"
                },
                {
                  "timestamp": 1514782800000,
                  "value": "47.0"
                },
                {
                  "timestamp": 1514779200000,
                  "value": "21.0"
                },
                {
                  "timestamp": 1514775600000,
                  "value": "27.0"
                },
                {
                  "timestamp": 1514772000000,
                  "value": "20.0"
                },
                {
                  "timestamp": 1514768400000,
                  "value": "12.0"
                },
                {
                  "timestamp": 1514764800000,
                  "value": "7.0"
                }
              ]
            }
          ],
          "name" : "proxy1"
      } ],
    "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 para a 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 especifique as credenciais para fazer upload de dados para a Apigee que você recebeu da Apigee.
  • org_name especifica o nome da organização.
  • "environments"... contém os resultados do comando curl que você usou para coletar as estatísticas acima.