Sobre os relatórios

Pré-lançamento

Este produto está sujeito aos "Termos de ofertas pré-GA" na seção "Termos gerais de serviço" dos Termos específicos de serviço. Os produtos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para recuperar dados de custo e utilização com a API App Optimize, primeiro crie um relatório. Esse recurso atua como uma definição persistente dos dados que você quer analisar, especificando parâmetros como escopo, dimensões, período e filtros.

Depois de criar um relatório, a API gera os dados solicitados de forma assíncrona. Em seguida, use o nome do recurso do relatório para buscar o conjunto de dados resultante.

O fluxo de trabalho é o seguinte:

1. Você cria um relatório especificando seus critérios.
2. O sistema processa essa solicitação de forma assíncrona.
3. Quando a operação for concluída, leia os dados resultantes.

Este documento detalha a estrutura e os parâmetros configuráveis dos relatórios da API App Optimize, incluindo dimensões, métricas e opções de filtragem disponíveis, e explica o formato dos dados retornados.

Para informações sobre limitações de custo e utilização, consulte Entender os dados.

Definir um relatório

Para criar um relatório, defina um recurso Report com os seguintes parâmetros de configuração, que são descritos nas próximas subseções:

Parâmetro	Tipo	Descrição
scopes	Matriz	O projeto ou aplicativo do App Hub a ser analisado. É necessário fornecer exatamente um elemento de escopo.
dimensions	Matriz	Os atributos para recuperar e agrupar os dados, incluindo agrupamentos com base no tempo.
metrics	Matriz	As medições específicas a serem retornadas.
filter	String	Uma expressão da Common Expression Language (CEL) para restringir os dados, incluindo intervalos de tempo.

Escopos

O campo scopes define o conjunto de recursos que a API App Optimize vai analisar. Embora o campo seja uma matriz, você precisa especificar exatamente um elemento, que pode ser um projeto ou um aplicativo do App Hub:

• project: uma string que representa um Google Cloud project. Ele precisa ser formatado como:

  projects/PROJECT_ID
  

  Substitua PROJECT_ID pelo ID do seu projeto do Google Cloud . Por exemplo, projects/my-project-1.

• application: uma string que representa o nome completo do recurso de um aplicativo do App Hub. Ele precisa estar no formato:

  projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID
  

  Substitua:

  • PROJECT_ID: o ID do projeto host do App Hub.
  • LOCATION: a região do aplicativo do App Hub, como us-central1.
  • APPLICATION_ID: o ID do aplicativo do App Hub.

  Por exemplo, projects/my-host-proj/locations/us-central1/applications/my-app

Confira exemplos de matrizes scopes em JSON para uma solicitação de criação de relatório, mostrando um único elemento de escopo:

• Escopo por projeto:

  "scopes": [
    {
      "project": "projects/my-project-1"
    }
  ]
  

• Escopo por aplicativo:

  "scopes": [
    {
      "application": "projects/my-host-proj/locations/us-central1/applications/my-app"
    }
  ]
  

Dimensões

As dimensões determinam quais dados são retornados e como eles são agrupados. Por exemplo, se você selecionar project e product_display_name, a saída vai conter uma linha para cada combinação exclusiva de valores de nome do projeto e do produto encontrada nos dados.

Confira uma tabela de dimensões compatíveis:

Dimensão	Tipo	Descrição	Valor de exemplo
project	STRING	O ID do projeto Google Cloud .	projects/my-project
application	STRING	O aplicativo do App Hub.	projects/my-project/locations/us-central1/applications/my-app
service_or_workload	STRING	O serviço ou a carga de trabalho do App Hub.	projects/my-project/locations/us-central1/applications/my-app/services/my-service
resource	STRING	O nome completo do recurso.	//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1
resource_type	STRING	O tipo de recurso da API.	compute.googleapis.com/Instance
location	STRING	A região ou multirregião Google Cloud .	us-east1
sku	STRING	O ID da SKU de faturamento.	4496-8C0D-228F
product_display_name	STRING	O nome do produto Google Cloud .	Compute Engine
month	STRING	O ano e o mês.	2024-01
day	STRING	O ano, o mês e o dia.	2024-01-10
hour	STRING	O ano, o mês, o dia e a hora.	2024-01-10T00

A dimensão location representa a Google Cloud região ou multirregião a que os custos e o uso são atribuídos. A forma como esse local é informado depende das configurações de localização dos recursos no escopo do relatório:

• Para recursos implantados em uma zona específica, como us-central1-a, os custos e o uso são agregados e atribuídos à região principal. Neste exemplo, a dimensão location mostraria us-central1.
• Para recursos implantados em uma região, como us-central1, a dimensão location reflete essa região específica.
• Para recursos implantados ou configurados para uma multirregião, como us, a dimensão location reflete essa multirregião.

Dimensões de tempo

Para agregar resultados por tempo, inclua pelo menos uma dimensão de tempo, como month, day ou hour, na lista dimensions. Não esqueça:

• Todas as dimensões de tempo usam o horário do Pacífico e respeitam o horário de verão (DST).
• Os formatos seguem o ISO 8601.
• Se o período no filter não se alinhar perfeitamente com a granularidade da dimensão de tempo selecionada, ele será expandido para abranger os períodos completos. Por exemplo, filtrar parte de um dia com dimension: ["month"] vai incluir dados de todo o mês.

Métricas

As métricas são os valores quantitativos que você quer medir para cada grupo definido pelas dimensões. As métricas compatíveis são:

Métrica	Tipo	Descrição
cost	RECORD	O custo monetário na moeda solicitada.
cpu_mean_utilization	FLOAT64	Uso médio da CPU (0,0 a 1,0).
cpu_p95_utilization	FLOAT64	Uso da CPU do 95º percentil (0,0 a 1,0).
cpu_usage_core_seconds	INT64	Trabalho total da CPU realizado.
cpu_allocation_core_seconds	INT64	Capacidade total de CPU provisionada.
memory_mean_utilization	FLOAT64	Uso médio da memória (0,0 a 1,0).
memory_p95_utilization	FLOAT64	Uso da memória do 95º percentil (0,0 a 1,0).
memory_usage_byte_seconds	INT64	Memória total usada ao longo do tempo.
memory_allocation_byte_seconds	INT64	É a memória total provisionada ao longo do tempo.

Combinações válidas

Nem todas as dimensões podem ser combinadas com todas as métricas na API App Optimize. A tabela a seguir mostra exemplos de conjuntos de dimensões válidos e as métricas que podem ser usadas com eles. A API vai retornar um erro se uma combinação inválida for solicitada. Consulte esse erro para ver as combinações válidas.

Dimensões	Suporte à métrica cost	Suporte à métrica cpu_mean_utilization
application, product_display_name
application
location, product_display_name, project, resource, resource_type, sku
location, product_display_name, project, resource, resource_type
location, product_display_name, project, service_or_workload
location, product_display_name, project, sku
product_display_name, project
product_display_name, resource_type
product_display_name, resource
product_display_name
project

Filtros

Use o campo filter para restringir os dados usando uma string CEL. É possível criar expressões de filtro usando qualquer um dos campos listados na tabela Dimensões.

A filtragem precisa obedecer a estas restrições:

• Todos os predicados de campo de string precisam usar correspondências exatas de string. Por exemplo, location == 'us-east1'
• Vários predicados que se referem ao mesmo campo de string precisam ser unidos usando o operador lógico OR, ||. Por exemplo, location == 'us-east1' || location == 'us-west1'.
• Todos os outros predicados precisam ser unidos usando o operador lógico AND, &&.
• Um predicado em uma dimensão de tempo, como day, que especifica o horário de início precisa usar a comparação maior ou igual a, >=.
• Um predicado em uma dimensão de tempo que especifica o horário de término precisa usar a comparação "menor que", <.

Intervalo de tempo

Se o filter omitir dimensões de tempo (month, day, hour), o relatório vai usar um período de sete dias que termina na meia-noite anterior do Horário do Pacífico, respeitando o horário de verão. O período máximo é de 90 dias antes da data atual, e o horário de início precisa estar dentro da janela de 90 dias.

Por exemplo, se o horário atual do Pacífico for 2026-01-05T12:00:00, o intervalo padrão será 2025-12-29T00:00:00 a 2026-01-05T00:00:00 no Horário do Pacífico. O horário de início mais próximo para o período é 2025-10-07T00:00:00.

As métricas do Cloud Run só estão disponíveis por seis semanas antes da data atual.

Exemplos de filtros

Confira alguns exemplos de como você pode estruturar suas strings de filtro da CEL:

• Para filtrar os dados do relatório por um tipo de recurso específico, use o operador == na dimensão resource_type:

  resource_type == 'compute.googleapis.com/Instance'
  

• Para incluir apenas dados de um único local, filtre pela dimensão location:

  location == 'us-east1'
  

• Para incluir dados de uma lista específica de locais, use o operador || para combinar condições na dimensão location:

  location == 'us-east1' || location == 'us-west1'
  

• Para receber dados em um período específico usando granularidade por hora, filtre pela dimensão hour. Este exemplo inclui dados do início de 2024-01-01 até 2024-02-01, mas não inclui essa data:

  hour >= timestamp('2024-01-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
  

• Para filtrar dias inteiros, use a dimensão day. Os limites de dia são interpretados no horário do Pacífico. Por isso, especificar o ajuste é uma prática recomendada. Este exemplo inclui todos os dados de 15 e 16 de março de 2024:

  day >= timestamp('2024-03-15T00:00:00-07:00') && day < timestamp('2024-03-17T00:00:00-07:00')
  

• Da mesma forma, é possível filtrar por meses do calendário usando a dimensão month, sempre considerando o horário do Pacífico para os limites exatos. Este exemplo inclui todos os dados de outubro e novembro de 2025:

  month >= timestamp('2025-10-01T00:00:00-07:00') && month < timestamp('2025-12-01T00:00:00-08:00')
  

• Para receber dados das últimas 72 horas, use as funções now() e duration() na dimensão hour:

  hour >= now() - duration('72h')
  

• Para acessar dados dos últimos sete dias, use duration() com a dimensão hour:

  hour >= now() - duration('168h')
  

• Para filtrar um mês específico do calendário, como o anterior, é necessário calcular os carimbos de data/hora de início e fim no código do aplicativo. Em seguida, insira esses carimbos de data/hora calculados na expressão CEL. Conceitualmente, ela pode ter esta aparência, filtrando na dimensão day:

  day >= timestamp('START_OF_LAST_MONTH') && day < timestamp('START_OF_THIS_MONTH')
  

  Substitua:

  • START_OF_LAST_MONTH: a string de carimbo de data/hora ISO 8601 que representa o início do mês anterior no fuso horário do Pacífico, como 2025-12-01T00:00:00-08:00.
  • START_OF_THIS_MONTH: a string de carimbo de data/hora ISO 8601 que representa o início do mês atual no fuso horário do Pacífico, como 2026-01-01T00:00:00-08:00.

  Você precisa calcular essas strings de carimbo de data/hora exatas no código do aplicativo, considerando a data atual, o fuso horário (horário do Pacífico) e as transições do horário de verão.

• É possível combinar filtros de string e de tempo usando o operador &&. Este exemplo filtra dois locais em um período específico de dois meses:

  (location == 'us-east1' || location == 'us-west1') && hour >= timestamp('2023-12-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
  

• Confira um exemplo mais complexo que combina resource_type, project e um período com base em day:

  resource_type == 'compute.googleapis.com/Instance' && project == 'projects/my-project' && day >= timestamp('2025-01-01T00:00:00-08:00') && day < timestamp('2025-02-01T00:00:00-08:00')
  

Estrutura de dados do relatório

Quando você lê um relatório, o serviço retorna os dados como columns e rows.

Colunas

A matriz columns descreve o esquema dos dados, na ordem em que cada campo aparece no rows. Cada objeto na matriz columns tem um name, type e, às vezes, columns aninhado se o tipo for RECORD.

• As dimensões solicitadas aparecem como campos do tipo STRING.
• As métricas solicitadas aparecem como campos com tipos como INT64, FLOAT64 ou RECORD para tipos complexos como cost.

Por exemplo, com a API REST, se você solicitar dimensions: ["application", "product_display_name"] e metrics: ["cost", "cpu_mean_utilization"], a API App Optimize vai gerar uma matriz columns como esta:

"columns": [
  {
    "name": "application",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "product_display_name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "cost",
    "type": "RECORD",
    "mode": "NULLABLE",
    "columns": [
      {
        "name": "currency_code",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "units",
        "type": "INT64",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "cpu_mean_utilization",
    "type": "FLOAT64",
    "mode": "NULLABLE"
  }
]

Linhas

O campo rows contém os dados reais. Cada linha é uma matriz de valores que representa um único registro. A ordem dos valores em cada matriz interna corresponde diretamente à ordem dos campos definidos na matriz columns.

Continuando o exemplo em que application, product_display_name, cost e cpu_mean_utilization foram solicitados da API REST, uma única linha na matriz rows gerada pode ser assim:

"rows": [
  [
    "//apphub.googleapis.com/projects/my-proj/locations/us-central1/applications/my-app",
    "Compute Engine",
    {
      "currency_code": "USD",
      "units": "12",
      "nanos": 750000000
    },
    0.65
  ],
  [
    "//apphub.googleapis.com/projects/my-proj/locations/us-east1/applications/another-app",
    "Cloud Storage",
    {
      "currency_code": "USD",
      "units": "5",
      "nanos": 200000000
    },
    0.15
  ]
]

A tabela a seguir mostra como os valores em uma matriz de linha única são mapeados para o esquema definido na matriz columns, usando o índice do valor na matriz de linha:

Índice na linha	Coluna correspondente	Tipo	Valor de exemplo
0	application	STRING	"//apphub.googleapis.com/.../applications/my-app"
1	product_display_name	STRING	"Cloud Storage"
2	cost	RECORD	{ "currency_code": "USD", "units": "10", ... }
3	cpu_mean_utilization	FLOAT64	0.65

Cada elemento na lista rows é uma matriz em que a ordem dos valores corresponde à ordem das definições de campo na matriz columns. Assim, o valor no índice n em qualquer matriz de linha corresponde à coluna definida no índice n na matriz columns.

Como interpretar métricas de custo

Quando um relatório inclui a métrica cost, o valor é retornado como um RECORD que contém os seguintes campos, com base no tipo padrão google.type.Money:

Campo	Tipo	Descrição
currency_code	STRING	O código de moeda ISO 4217 de três letras, como "USD".
units	INT64	As unidades inteiras do montante.
nanos	INT64	As unidades nano (10^-9) do valor. Precisa estar entre -999.999.999 e +999.999.999 (inclusive).

Para receber o valor monetário total, combine os campos units e nanos. O campo nanos representa a parte fracionária do valor da moeda. Exemplo:

• Se currency_code for "USD", units será 106 e nanos será 321590000: O valor é 106 + (321.590.000 / 1.000.000.000) = 106,32159 USD.

• Se currency_code for "EUR", units for 5 e nanos for 750000000: O valor será 5 + (750.000.000 / 1.000.000.000) = 5,75 EUR.

Normalmente, você usaria uma biblioteca de formatação de moeda padrão para mostrar esse valor em um formato fácil de usar, incluindo o símbolo de moeda adequado.

Para mais informações sobre os dados retornados pela API e entender as limitações dela, consulte Entender os dados.

Expiração do relatório

Cada relatório é excluído automaticamente do serviço da API App Optimize 24 horas após a criação. Depois disso, não será possível recuperar o relatório e os dados dele pela API. Para verificar a hora de expiração programada de um relatório, extraia os metadados e confira o campo expireTime.

A seguir

• Criar um relatório
• Listar relatórios
• Receber os metadados de um relatório
• Ler os dados de um relatório
• Excluir um relatório