Acerca de los informes

Para recuperar los datos de costos y uso con la API de App Optimize, primero debes crear un informe. Este recurso actúa como una definición persistente de los datos que deseas analizar, y especifica parámetros como el alcance, las dimensiones, el período y los filtros.

Después de crear un informe, la API genera los datos solicitados de forma asíncrona. Luego, usa el nombre del recurso del informe para recuperar el conjunto de datos resultante.

Por lo tanto, el flujo de trabajo es el siguiente:

  1. Creas un informe en el que especificas tus criterios.
  2. El sistema procesa esta solicitud de forma asíncrona.
  3. Cuando se completa la operación, lees los datos resultantes.

En este documento, se detallan la estructura y los parámetros configurables de los informes de la API de App Optimize, incluidas las dimensiones, las métricas y las opciones de filtrado disponibles, y se explica el formato de los datos que se devuelven.

Para obtener información sobre las limitaciones de costos y uso, consulta Cómo comprender los datos.

Define un informe

Para crear un informe, debes definir un recurso Report con los siguientes parámetros de configuración, que se describen en las siguientes subsecciones:

Parámetro Tipo Descripción
scopes Arreglo Es el proyecto o la aplicación de App Hub que se analizará. Debes proporcionar exactamente un elemento de alcance.
dimensions Arreglo Son los atributos por los que se recuperan y agrupan los datos, incluidos los agrupamientos basados en el tiempo.
metrics Arreglo Son las mediciones específicas que se devolverán.
filter String Es una expresión de Common Expression Language (CEL) para reducir los datos, incluidos los períodos.

Permisos

El campo scopes define el conjunto de recursos que analizará la API de App Optimize. Aunque el campo es un array, debes especificar exactamente un elemento, que puede ser un proyecto o una aplicación de App Hub:

  • project: Es una cadena que representa un proyecto de Google Cloud . Debe tener el siguiente formato:

    projects/PROJECT_ID

    Reemplaza PROJECT_ID por el ID de tu proyecto de Google Cloud . Por ejemplo, projects/my-project-1.

  • application: Es una cadena que representa el nombre completo del recurso de una aplicación del App Hub. Debe tener el siguiente formato:

    projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto host del Centro de aplicaciones.
    • LOCATION: Es la región de la aplicación de App Hub, como us-central1.
    • APPLICATION_ID: Es el ID de la aplicación de App Hub.

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

A continuación, se muestran ejemplos de arrays scopes en JSON para una solicitud de creación de informes, en los que se muestra un solo elemento de alcance:

  • Delimitación del alcance por proyecto:

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

  • Alcance por aplicación:

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

Dimensiones

Las dimensiones determinan qué datos se devuelven y cómo se agrupan. Por ejemplo, si seleccionas project y product_display_name, el resultado contendrá una fila para cada combinación única de valores de nombre del proyecto y nombre del producto que se encuentren en los datos.

A continuación, se incluye una tabla de las dimensiones admitidas:

Dimensión Tipo Descripción Valor de ejemplo
project STRING ID del proyecto Google Cloud projects/my-project
application STRING Es la aplicación de App Hub. projects/my-project/locations/us-central1/applications/my-app
service_or_workload STRING Es el servicio o la carga de trabajo de App Hub. projects/my-project/locations/us-central1/applications/my-app/services/my-service
resource STRING Es el nombre completo del recurso. //compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1
resource_type STRING Es el tipo de recurso de la API. compute.googleapis.com/Instance
location STRING Es la Google Cloud región o multirregión. us-east1
sku STRING Es el ID del SKU de facturación. 4496-8C0D-228F
product_display_name STRING Es el nombre del producto Google Cloud . Compute Engine
month STRING El año y el mes. 2024-01
day STRING El año, el mes y el día. 2024-01-10
hour STRING Año, mes, día y hora. 2024-01-10T00

La dimensión location representa la Google Cloud región o multirregión a la que se atribuyen los costos y el uso. La forma en que se informa esta ubicación depende de la configuración de ubicación de los recursos incluidos en el alcance del informe:

  • En el caso de los recursos implementados en una zona específica, como us-central1-a, los costos y el uso se agregan y se atribuyen a la región principal. En este ejemplo, la dimensión location mostraría us-central1.
  • En el caso de los recursos implementados en una región, como us-central1, la dimensión location refleja esa región específica.
  • En el caso de los recursos implementados o configurados para una región múltiple, como us, la dimensión location refleja esa región múltiple.

Dimensiones de tiempo

Para agregar los resultados por período, incluye al menos una dimensión de tiempo, como month, day o hour, en la lista dimensions. Ten en cuenta lo siguiente:

  • Todas las dimensiones de tiempo usan la hora del Pacífico y respetan el horario de verano (DST).
  • Los formatos siguen la norma ISO 8601.
  • Si el período del filter no se alinea perfectamente con la granularidad de la dimensión de tiempo seleccionada, el período se expande para abarcar los períodos completos. Por ejemplo, si filtras los datos para incluir parte de un día con dimension: ["month"], se incluirán los datos de todo el mes.

Métricas

Las métricas son los valores cuantitativos que deseas medir para cada grupo definido por tus dimensiones. Las métricas admitidas son las siguientes:

Métrica Tipo Descripción
cost RECORD Es el costo monetario en la moneda solicitada.
cpu_mean_utilization FLOAT64 Uso promedio de CPU (de 0.0 a 1.0).
cpu_p95_utilization FLOAT64 Uso de CPU del percentil 95 (de 0.0 a 1.0).
cpu_usage_core_seconds INT64 Es el trabajo total de la CPU realizado.
cpu_allocation_core_seconds INT64 Es la capacidad total de CPU aprovisionada.
memory_mean_utilization FLOAT64 Es el uso promedio de memoria (de 0.0 a 1.0).
memory_p95_utilization FLOAT64 Uso de memoria del percentil 95 (de 0.0 a 1.0).
memory_usage_byte_seconds INT64 Memoria total usada con el tiempo.
memory_allocation_byte_seconds INT64 Es la memoria total aprovisionada con el tiempo.

Combinaciones válidas

No todas las dimensiones se pueden combinar con todas las métricas de la API de App Optimize. En la siguiente tabla, se muestran ejemplos de conjuntos de dimensiones válidos y las métricas que puedes usar con ellos. La API mostrará un error si se solicita una combinación no válida. Consulta ese error para conocer las combinaciones válidas.

Dimensiones Admite la métrica cost Admite la 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 y sku
product_display_name, project
product_display_name, resource_type
product_display_name, resource
product_display_name
project

Filtros

Usa el campo filter para acotar los datos con una cadena de CEL. Puedes crear tus expresiones de filtro con cualquiera de los campos que se indican en la tabla Dimensiones.

El filtrado debe cumplir con estas restricciones:

  • Todos los predicados de campos de cadena deben usar coincidencias exactas de cadenas. Por ejemplo, location == 'us-east1'.
  • Los predicados múltiples que hacen referencia al mismo campo de cadena deben unirse con el operador lógico OR, ||. Por ejemplo, location == 'us-east1' || location == 'us-west1'
  • Todos los demás predicados deben unirse con el operador lógico AND, &&.
  • Un predicado en una dimensión temporal, como day, que especifica la hora de inicio debe usar la comparación mayor o igual que, >=.
  • Un predicado en una dimensión temporal que especifica la hora de finalización debe usar la comparación menor que, <.

Intervalo de tiempo

Si filter omite las dimensiones de tiempo (month, day, hour), el informe se establece de forma predeterminada en un período de siete días que finaliza a la medianoche anterior (hora del Pacífico), respetando el horario de verano. El período máximo es de 90 días antes de la fecha actual, y la hora de inicio debe estar dentro del período de 90 días.

Por ejemplo, si la hora del Pacífico actual es 2026-01-05T12:00:00, el rango predeterminado es de 2025-12-29T00:00:00 a 2026-01-05T00:00:00, hora del Pacífico. La hora de inicio más temprana del intervalo es 2025-10-07T00:00:00.

Las métricas de Cloud Run solo están disponibles durante seis semanas antes de la fecha actual.

Filtros de ejemplo

A continuación, se incluyen algunos ejemplos de cómo puedes estructurar tus cadenas de filtro de CEL:

  • Para filtrar los datos del informe para un tipo de recurso específico, usa el operador == en la dimensión resource_type:

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

  • Para incluir solo los datos de una sola ubicación, aplica un filtro en la dimensión location:

    location == 'us-east1'

  • Para incluir datos de una lista específica de ubicaciones, usa el operador || para combinar condiciones en la dimensión location:

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

  • Para obtener datos dentro de un período específico con una granularidad por hora, puedes filtrar por la dimensión hour. Este ejemplo incluye datos desde el inicio del 2024-01-01 hasta el 2024-02-01, sin incluir este último día:

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

  • Para filtrar por días completos, usa la dimensión day. Ten en cuenta que los límites de los días se interpretan en la hora del Pacífico, por lo que especificar el desplazamiento es una práctica recomendada. Este ejemplo incluye todos los datos del 15 y el 16 de marzo de 2024:

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

  • Del mismo modo, puedes filtrar por meses calendario con la dimensión month, teniendo en cuenta el horario del Pacífico para los límites exactos. En este ejemplo, se incluyen todos los datos de octubre y noviembre de 2025:

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

  • Para obtener datos de las últimas 72 horas, usa las funciones now() y duration() en la dimensión hour:

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

  • Para obtener datos de los últimos siete días, puedes usar duration() con la dimensión hour:

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

  • Para filtrar por un mes calendario específico, como el anterior, es necesario calcular las marcas de tiempo de inicio y finalización en el código de la aplicación. Luego, insertas esas marcas de tiempo calculadas en la expresión CEL. Conceptualmente, podría verse así, con un filtro en la dimensión day:

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

    Reemplaza lo siguiente:

    • START_OF_LAST_MONTH: Es la cadena de marca de tiempo ISO 8601 que representa el comienzo del mes anterior en la zona horaria del Pacífico, como 2025-12-01T00:00:00-08:00.
    • START_OF_THIS_MONTH: Es la cadena de marca de tiempo ISO 8601 que representa el comienzo del mes actual en la zona horaria del Pacífico, como 2026-01-01T00:00:00-08:00.

    Debes calcular estas cadenas de marcas de tiempo exactas en el código de tu aplicación, teniendo en cuenta la fecha actual, la zona horaria (hora del Pacífico) y las transiciones del horario de verano.

  • Puedes combinar filtros de cadena y de tiempo con el operador &&. En este ejemplo, se filtran dos ubicaciones dentro de un período específico de dos meses:

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

  • Este es un ejemplo más complejo que combina resource_type, project y un rango de tiempo basado en 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')

Estructura de los datos del informe

Cuando lees un informe correctamente, el servicio devuelve los datos como columns y rows.

Columnas

El array columns describe el esquema de los datos, en el orden en que aparece cada campo en rows. Cada objeto del array columns tiene un name, un type y, a veces, un columns anidado si el tipo es RECORD.

  • Las dimensiones que solicitaste aparecen como campos con el tipo STRING.
  • Las métricas que solicitaste aparecen como campos con tipos como INT64, FLOAT64 o RECORD para tipos complejos como cost.

Por ejemplo, con la API de REST, si solicitas dimensions: ["application", "product_display_name"] y metrics: ["cost", "cpu_mean_utilization"], la API de App Optimize genera en la respuesta un array columns como el siguiente:

"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"
  }
]

Filas

El campo rows contiene los datos reales. Cada fila es un array de valores que representa un solo registro. El orden de los valores dentro de cada array interno corresponde directamente al orden de los campos definidos en el array columns.

Continuando con el ejemplo en el que se solicitaron application, product_display_name, cost y cpu_mean_utilization desde la API de REST, una sola fila en el array rows generado podría verse de la siguiente manera:

"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
  ]
]

En la siguiente tabla, se visualiza cómo se asignan los valores dentro de un array de una sola fila al esquema definido en el array columns, utilizando el índice del valor en el array de la fila:

Índice dentro de la fila Columna correspondiente Tipo Valor de ejemplo
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 de la lista rows es un array en el que el orden de los valores coincide con el orden de las definiciones de campo en el array columns. Por lo tanto, el valor en el índice n de cualquier array de filas determinado corresponde a la columna definida en el índice n del array columns.

Cómo interpretar las métricas de costos

Cuando un informe incluye la métrica cost, el valor se devuelve como un RECORD que contiene los siguientes campos, según el tipo estándar google.type.Money:

Campo Tipo Descripción
currency_code STRING Es el código de moneda de tres letras según la norma ISO 4217, como "USD".
units INT64 La unidad entera del importe.
nanos INT64 Son las unidades de nano (10-9) de la cantidad. Debe ser un valor entre -999,999,999 y +999,999,999, inclusive.

Para obtener el valor monetario completo, combina los campos units y nanos. El campo nanos representa la parte fraccionaria del valor de la moneda. Por ejemplo:

  • Si currency_code es "USD", units es 106 y nanos es 321590000: El valor es 106 + (321,590,000 / 1,000,000,000) = 106.32159 USD.

  • Si currency_code es "EUR", units es 5 y nanos es 750000000, el valor es 5 + (750,000,000 / 1,000,000,000) = 5.75 EUR.

Por lo general, usarías una biblioteca de formato de moneda estándar para mostrar este valor en un formato fácil de usar, incluido el símbolo de moneda adecuado.

Para obtener más información sobre los datos que devuelve la API y comprender sus limitaciones, consulta Comprende los datos.

Vencimiento del informe

Cada informe se borra automáticamente del servicio de la API de App Optimize 24 horas después de su creación. Después de este tiempo, no se podrá recuperar el informe ni sus datos a través de la API. Para verificar la hora de vencimiento programada de un informe, obtén sus metadatos y consulta el campo expireTime.

¿Qué sigue?