Consultas en SQL de muestra para Trace

Versión preliminar

Este producto o esta función se encuentra sujeto a las "Condiciones de la oferta de la fase previa a la DG" en la sección Condiciones del servicio generales de las Condiciones específicas del servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Este documento contiene consultas de muestra que son específicas para consultar datos de seguimiento almacenados en tu Google Cloud proyecto.

Compatibilidad con el lenguaje SQL

Las consultas que se usan en la página Análisis de registros admiten funciones de GoogleSQL con algunas excepciones.

Los siguientes comandos de SQL no son compatibles con las consultas de SQL que se emiten a través de la página Análisis de registros:

• Comandos DDL y DML
• Funciones de JavaScript definidas por el usuario
• Funciones de BigQuery ML
• Variables de SQL

Lo siguiente solo se admite cuando consultas un conjunto de datos vinculado a través de las páginas BigQuery Studio y Looker Studio o con la herramienta de línea de comandos de bq:

• Funciones de JavaScript definidas por el usuario
• Funciones de BigQuery ML
• Variables de SQL

Prácticas recomendadas

Para establecer el período de tu consulta, te recomendamos que uses el selector de período. Por ejemplo, para ver los datos de la semana pasada, selecciona Últimos 7 días en el selector de período. También puedes usar el selector de período para especificar una hora de inicio y finalización, especificar una hora para ver los datos y cambiar las zonas horarias.

Si incluyes un campo start_time en la cláusula WHERE, no se usa la configuración del selector de período. En el siguiente ejemplo, se filtran los datos con la función TIMESTAMP_SUB, que te permite especificar un intervalo de retroceso desde la hora actual:

WHERE
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)

Para obtener más información sobre cómo filtrar por hora, consulta Funciones de hora y Funciones de marca de tiempo.

Antes de comenzar

Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. Para obtener los permisos que necesitas para cargar la página Análisis de registros, escribir, ejecutar y guardar consultas privadas sobre tus datos de seguimiento, pídele a tu administrador que te otorgue los siguientes roles de IAM:

   • Usuario con acceso a vistas de observabilidad (roles/observability.viewAccessor) en las vistas de observabilidad que deseas consultar. Este rol admite condiciones de IAM, que te permiten restringir el otorgamiento a una vista específica. Si no adjuntas una condición al otorgamiento del rol, la principal puede acceder a todas las vistas de observabilidad.
   • Usuario de estadísticas de observabilidad (roles/observability.analyticsUser) en tu proyecto. Este rol contiene los permisos necesarios para guardar y ejecutar consultas privadas, y para ejecutar consultas compartidas.
   • Visor de registros (roles/logging.viewer) en tu proyecto.

   Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

   También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Cómo usar las consultas en esta página

1. En la Google Cloud consola de, ve a la página Análisis de registros:

   Ir a Análisis de registros

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

2. En el panel Consulta, haz clic en  SQL y, luego, copia y pega una consulta en el panel de consulta en SQL.

   A continuación, se muestra el formato de la causa FROM para consultar la vista _AllSpans:

   FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
   

   La cláusula FROM contiene los siguientes campos:

   • PROJECT_ID: Es el identificador del proyecto.
   • LOCATION: Es la ubicación del bucket de observabilidad.
   • _Trace es el nombre del bucket de observabilidad.
   • Spans es el nombre del conjunto de datos.
   • _AllSpans es el nombre de la vista.
   Nota: Los delimitadores de la ruta de acceso son caracteres de punto (.). Si un elemento de ruta de acceso como el Google Cloud proyecto contiene un carácter de punto, entonces asegúrate de que cada campo de ruta de acceso esté envuelto en comillas invertidas simples, (`).

Para usar las consultas que se muestran en este documento en la página BigQuery Studio o para usar la herramienta de línea de comandos de bq, edita la cláusula FROM y, luego, ingresa la ruta de acceso al conjunto de datos vinculado. Por ejemplo, para consultar la _AllSpans vista en el conjunto de datos vinculado llamado my_linked_dataset que se encuentra en el proyecto myproject, la ruta de acceso es `myproject.my_linked_dataset._AllSpans`.

Casos de uso habituales

En esta sección, se enumeran varios casos de uso habituales que pueden ayudarte a crear tus consultas personalizadas.

Mostrar todos los datos de seguimiento

Para consultar la vista _AllSpans, ejecuta la siguiente consulta:

-- Display all data.
SELECT *
FROM `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
-- Limit to 10 entries.
LIMIT 10

Mostrar información común del intervalo

Para mostrar información común del intervalo, como la hora de inicio y la duración, ejecuta la siguiente consulta:

SELECT
  start_time,
  -- Set the value of service name based on the first non-null value in the list.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,
  name AS span_name,
  duration_nano,
  status.code AS status,
  trace_id,
  span_id
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
LIMIT 10

Para obtener más información, consulta Expresiones condicionales.

Mostrar los percentiles 50 y 99 de la latencia del intervalo

Para mostrar los percentiles 50 y 99 de la latencia de cada servicio de RPC, ejecuta la siguiente consulta:

SELECT
  -- Compute 50th and 99th percentiles for each service
  STRING(attributes['rpc.service']) || '/' || STRING(attributes['rpc.method']) AS rpc_service_method,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS duration_nano_p50,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS duration_nano_p99
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans whose kind field has a value of 2 (SPAN_KIND_SERVER).
  kind = 2
GROUP BY rpc_service_method

Para obtener más información sobre la enumeración, consulta la documentación de OpenTelemetry: SpanKind.

Para ver los resultados de forma gráfica, puedes crear un gráfico con la dimensión establecida en rpc_service_method. Puedes agregar dos medidas, una para el promedio del valor duration_nano_p50 y la otra para el promedio del campo duration_nano_p99.

Filtrar entradas de seguimiento

Para aplicar un filtro a tu consulta, agrega una cláusula WHERE. La sintaxis que usas en esta cláusula depende del tipo de datos del campo. En esta sección, se proporcionan varios ejemplos para diferentes tipos de datos.

Filtrar por tipos de datos de cadena

El campo name se almacena como String.

• Para analizar solo los intervalos en los que se especifica name, usa la siguiente cláusula:

  -- Matches spans that have a name field.
  WHERE name IS NOT NULL
  

• Para analizar solo los intervalos en los que name tiene el valor "POST", usa la siguiente cláusula:

  -- Matches spans whose name is POST.
  WHERE STRPOS(name, "POST") > 0
  

• Para analizar solo los intervalos en los que name contiene el valor "POST", usa el LIKE operador junto con comodines:

  -- Matches spans whose name contains POST.
  WHERE name LIKE "%POST%"
  

Filtrar por tipos de datos de números enteros

El campo kind es un número entero que puede tomar valores entre cero y cinco:

• Para analizar solo los intervalos en los que se especifica kind, usa la siguiente cláusula:

  -- Matches spans that have field named kind.
  WHERE kind IS NOT NULL
  

• Para analizar los intervalos cuyo valor kind es uno o dos, usa la siguiente cláusula:

  -- Matches spans whose kind value is 1 or 2.
  WHERE kind IN (1, 2)
  

Filtrar por tipos de datos de RECORD

Algunos campos del esquema de seguimiento tienen un tipo de datos de RECORD. Estos campos pueden almacenar una o más estructuras de datos, o bien almacenar entradas repetidas de la misma estructura de datos.

Filtrar por estado o código de estado

El campo status es un ejemplo de un campo cuyo tipo de datos es RECORD. Este campo almacena una estructura de datos, con miembros etiquetados como code y message.

• Para analizar solo los intervalos cuando el campo status.code tiene un valor de 1, agrega la siguiente cláusula:

  -- Matches spans that have a status.code field that has a value of 1.
  WHERE status.code = 1
  

  El campo status.code se almacena como un número entero.

• Para analizar los intervalos en los que el campo status no es EMPTY, agrega la siguiente cláusula:

  -- Matches spans that have status field. When the status field exists, it
  -- must contain a subfield named code.
  -- Don't compare status to NULL, because this field has a data type of RECORD.
  WHERE status.code IS NOT NULL
  

Filtrar por eventos o vínculos

Los campos events y links se almacenan con un tipo de datos de RECORD, pero son campos repetidos.

• Para hacer coincidir los intervalos que tienen al menos un evento, usa la siguiente cláusula:

  -- Matches spans that have at least one event. Don't compare events to NULL.
  -- The events field has data type of RECORD and contains a repeated fields.
  WHERE ARRAY_LENGTH(events) > 0
  

• Para hacer coincidir los intervalos que tienen un evento cuyo campo name tiene el valor de message, usa la siguiente cláusula:

  WHERE
    -- Exists is true when any event in the array has a name field with the
    -- value of message.
    EXISTS(
      SELECT 1
      FROM UNNEST(events) AS ev
      WHERE ev.name = 'message'
    )
  

Filtrar por tipos de datos JSON

El campo attributes es del tipo JSON. Cada atributo individual es un par clave-valor.

• Para analizar solo los intervalos en los que se especifica attributes, usa la siguiente cláusula:

  -- Matches spans where at least one attribute is specified.
  WHERE attributes IS NOT NULL
  

• Para analizar solo los intervalos en los que la clave de atributo llamada component tiene un valor de "proxy", usa la siguiente cláusula:

  -- Matches spans that have an attribute named component with a value of proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') = 'proxy'
  

  También puedes usar una sentencia LIKE junto con comodines para realizar una prueba de contenido:

  -- Matches spans that have an attribute named component whose value contains proxy.
  WHERE attributes IS NOT NULL
        AND JSON_VALUE(attributes, '$.component') LIKE '%proxy%'
  

Agrupar y agregar datos de seguimiento

En esta sección, se muestra cómo puedes agrupar y agregar intervalos. Si no especificas una agrupación, pero sí una agregación, se imprime un resultado porque SQL trata todas las entradas que satisfacen la cláusula WHERE como un grupo.

Cada expresión SELECT debe incluirse en los campos de grupo o agregarse.

Agrupar intervalos por hora de inicio

Para agrupar datos por hora de inicio, usa la función TIMESTAMP_TRUNC, que trunca una marca de tiempo a una granularidad especificada como HOUR:

SELECT
  -- Truncate the start time to the hour. Count the number of spans per group.
  TIMESTAMP_TRUNC(start_time, HOUR) AS hour,
  status.code AS code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE
  -- Matches spans shows start time is within the previous 12 hours.
  start_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 12 HOUR)
GROUP BY
  -- Group by hour and status code.
  hour, code
ORDER BY hour DESC

Para obtener más información, consulta la TIMESTAMP_TRUNC documentación y las funciones de fecha y hora.

Nota: Si incluyes un campo start_time en la cláusula WHERE, no se usa la configuración del selector de período.

Contar intervalos por código de estado

Para mostrar el recuento de intervalos con un código de estado específico, ejecuta la siguiente consulta:

SELECT
  -- Count the number of spans for each status code.
  status.code,
  COUNT(*) AS count
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
WHERE status.code IS NOT NULL
GROUP BY status.code

Si reemplazas status.code por kind, la consulta anterior informa la cantidad de intervalos para cada valor de la enumeración kind. Del mismo modo, si reemplazas status.code por name, los resultados de la consulta muestran la cantidad de entradas para cada nombre de intervalo.

Calcular la duración promedio de todos los intervalos

Para mostrar la duración promedio, después de agrupar los datos de intervalo por nombre de intervalo, ejecuta la siguiente consulta:

SELECT
  -- Group by name, and then compute the average duration for each group.
  name,
  AVG(duration_nano) AS nanosecs,
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY name
ORDER BY nanosecs DESC

Calcular la duración promedio y los percentiles por nombre de servicio

La siguiente consulta calcula el recuento de intervalos y varias estadísticas para cada servicio:

SELECT
  -- Set the service name by the first non-null value.
  COALESCE(
    JSON_VALUE(resource.attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."service.name"'),
    JSON_VALUE(attributes, '$."g.co/gae/app/module"')) AS service_name,

  -- Count the number spans for each service name. Also compute statistics.
  COUNT(*) AS span_count,
  AVG(duration_nano) AS avg_duration_nano,
  MIN(duration_nano) AS min_duration_nano,
  MAX(duration_nano) AS max_duration_nano,

  -- Calculate percentiles for duration
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(50)] AS p50_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(95)] AS p95_duration_nano,
  APPROX_QUANTILES(duration_nano, 100)[OFFSET(99)] AS p99_duration_nano,

  -- Count the number of unique trace IDs. Also, collect up to 5 unique
  -- span names and status codes.
  COUNT(DISTINCT trace_id) AS distinct_trace_count,
  ARRAY_AGG(DISTINCT name IGNORE NULLS LIMIT 5) AS sample_span_names,
  ARRAY_AGG(DISTINCT status.code IGNORE NULLS LIMIT 5) AS sample_status_codes
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans`
GROUP BY service_name
ORDER BY span_count DESC

Búsqueda entre columnas

En esta sección, se describen dos enfoques que puedes usar para buscar varias columnas de la vista que estás consultando:

• Búsquedas basadas en tokens: Especificas la ubicación de búsqueda, una consulta de búsqueda y, luego, usas la SEARCH función. Debido a que la función SEARCH tiene reglas específicas sobre cómo se buscan los datos, te recomendamos que leas la documentación de SEARCH.

• Búsquedas basadas en substrings: Proporcionas la ubicación de búsqueda, un literal de cadena, y, luego, usas la función CONTAINS_SUBSTR. El sistema realiza una prueba que no distingue mayúsculas de minúsculas para determinar si el literal de cadena existe en una expresión. La función CONTAINS_SUBSTR muestra TRUE cuando existe el literal de cadena y FALSE en caso contrario. El valor de búsqueda debe ser un literal STRING, pero no el literal NULL.

Consultar varias vistas

Las declaraciones de consulta analizan una o más tablas o expresiones y muestran las filas de resultados calculados. Por ejemplo, puedes usar declaraciones de consulta para combinar los resultados de las sentencias SELECT en diferentes tablas o conjuntos de datos de varias maneras y, luego, seleccionar las columnas de los datos combinados.

Para unir vistas, se aplican las siguientes restricciones:

1. Las ubicaciones de las vistas satisfacen una de las siguientes condiciones:

   • Todas las vistas tienen la misma ubicación.
   • Todas las vistas están en la ubicación global o us.

2. Cuando los recursos de almacenamiento usan claves de encriptación administradas por el cliente (CMEK), se debe cumplir una de las siguientes condiciones:

   • Los recursos de almacenamiento que usan CMEK usan la misma clave de Cloud KMS.
   • Los recursos de almacenamiento que usan CMEK tienen un ancestro común, y ese ancestro especifica una clave de Cloud KMS predeterminada que se encuentra en la misma ubicación que los recursos de almacenamiento.

   Cuando uno o más recursos de almacenamiento usan CMEK, el sistema encripta los datos temporales generados por la unión con la clave de Cloud KMS común o la clave de Cloud KMS predeterminada del ancestro.

Por ejemplo, supongamos que tienes dos vistas que residen en la misma ubicación. Luego, puedes unir estas vistas cuando se cumpla alguna de las siguientes condiciones:

• Los recursos de almacenamiento no usan CMEK.
• Un recurso de almacenamiento usa CMEK y el otro no.
• Ambos recursos de almacenamiento usan CMEK y la misma clave de Cloud KMS.

• Ambos recursos de almacenamiento usan CMEK, pero usan claves diferentes. Sin embargo, los recursos comparten un ancestro que especifica una clave de Cloud KMS predeterminada que se encuentra en la misma ubicación que los recursos de almacenamiento.

  Por ejemplo, supongamos que la jerarquía de recursos para un bucket de registros y un bucket de observabilidad incluye la misma organización. Puedes unir vistas en esos buckets cuando, para esa organización, hayas configurado los parámetros de configuración de recursos predeterminados para Cloud Logging y para buckets de observabilidad con la misma clave de Cloud KMS predeterminada para la ubicación de almacenamiento.

Unir datos de seguimiento y de registro con el ID de seguimiento

La siguiente consulta une datos de registro y de seguimiento con los IDs de intervalo y de seguimiento:

SELECT
  T.trace_id,
  T.span_id,
  T.name,
  T.start_time,
  T.duration_nano,
  L.log_name,
  L.severity,
  L.json_payload
FROM
  `PROJECT_ID.LOCATION._Trace.Spans._AllSpans` AS T
JOIN
  `PROJECT_ID.LOCATION._Default._AllLogs` AS L
ON
  -- Join log and trace data by both the span ID and trace ID.
  -- Don't join only on span ID, this field isn't globally unique.
  T.span_id = L.span_id
  -- A regular expression is required because the storage format of the trace ID
  -- differs between a log view and a trace view.
  AND T.trace_id = REGEXP_EXTRACT(L.trace, r'/([^/]+)$')
WHERE T.duration_nano > 1000000
LIMIT 10

La respuesta de la consulta muestra el ID de seguimiento y el ID de intervalo, lo que te permite consultarlos de forma individual para recopilar más información. Además, los resultados muestran la gravedad de la entrada de registro y la carga útil de JSON.

¿Qué sigue?

• Guarda y comparte una consulta de SQL.
• Visualiza consulta en SQL en gráficos.
• Consulta un conjunto de datos vinculado en BigQuery.

Para obtener documentación de referencia de SQL o más ejemplos, consulta los siguientes documentos:

• Funciones, operadores y condicionales.
• Search functions.
• Sintaxis de las consultas.
• Consultas de SQL de muestra para Cloud Logging.