Crear y gestionar ámbitos de seguimiento

En este documento se describe cómo puede crear y gestionar un ámbito de traza, lo que permite que la página Explorador de trazas encuentre los intervalos de traza que quiera ver o analizar. Si solo quieres ver y analizar los intervalos que se originan en tu Google Cloud proyecto, no tienes que configurar ningún ámbito de traza. Sin embargo, si los datos de la traza se almacenan en varios proyectos, como puede ocurrir cuando se usa una arquitectura de microservicios, debe realizar algunas actividades de configuración para ver todos los intervalos de un solo proyecto. Google Cloud

En este documento no se describe cómo ver tus trazas y spans. Para obtener información sobre este tema, consulta Buscar y explorar trazas.

Esta función solo se admite en proyectos de Google Cloud . En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.

Acerca de los permisos de trazas

Los ámbitos de traza son recursos persistentes a nivel de proyecto que enumeran un conjunto de proyectos. Google Cloud Puedes configurar la página Explorador de trazas para buscar por ámbito de traza, lo que significa que la página busca los proyectos que se incluyen en el ámbito seleccionado. Los roles de Gestión de Identidades y Accesos (IAM) que tengas en los proyectos buscados y el ajuste del periodo determinan qué datos se obtienen del almacenamiento y se muestran.

Cuando creas un Google Cloud proyecto, se crea un ámbito de traza llamado _Default. Este ámbito solo incluye el proyecto Google Cloud . No puedes añadir proyectos a este ámbito ni eliminarlo.

Puedes crear ámbitos de traza, así como modificar y eliminar los que crees. Quieres crear un ámbito de seguimiento cuando tienes un servicio que escribe datos de intervalo en varios proyectos de Google Cloud .

A menos que abras la página Explorador de rastreo con una URL que incluya un ámbito de rastreo o un ID de rastreo y de intervalo, la página Explorador de rastreo buscará datos de rastreo en los proyectos que se incluyan en el ámbito de rastreo predeterminado.Google Cloud Cuando creas un proyecto, el ámbito de traza llamado _Default se define como el ámbito de traza predeterminado. Sin embargo, puede seleccionar otro ámbito de seguimiento para usarlo como ámbito de seguimiento predeterminado.

Aplicaciones y ámbitos de rastreo de App Hub

Es posible que tus aplicaciones de App Hub escriban datos de traza en varios proyectos. Para obtener una vista agregada de estos datos, crea un ámbito de traza, configúralo para que muestre todos los proyectos que almacenan tus datos de traza y, a continuación, configúralo como ámbito de traza predeterminado. Cuando completes estos pasos, la página Explorador de trazas mostrará automáticamente los datos escritos por tu aplicación, aunque estén almacenados en proyectos diferentes.

Crea el ámbito de seguimiento personalizado en el proyecto desde el que verás tus datos de registro. Este proyecto es el proyecto host de tu centro de aplicaciones o el proyecto de gestión de tu carpeta habilitada para aplicaciones. Por ejemplo, si el nombre visible de la carpeta es My Folder, el nombre visible del proyecto de gestión es My Folder-mp.

Antes de empezar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. 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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. 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

    8.

  8. Para obtener los permisos que necesitas para crear y ver ámbitos de traza, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Editor de ámbitos de observabilidad (roles/observability.scopesEditor) en tu proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

    También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

    El rol Editor de ámbitos de observabilidad incluye permisos privados que te permiten crear y ver ámbitos de traza. Estos permisos no se pueden incluir en roles de IAM personalizados.

  9. Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST

    Para usar las muestras de la API REST de esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la CLI de gcloud.

      Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando: 

      gcloud init

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

    Para obtener más información, consulta el artículo Autenticarse para usar REST de la documentación sobre autenticación de Google Cloud .

    Mostrar ámbitos de traza

    Consola

    Para enumerar los ámbitos de seguimiento, haz lo siguiente:

    1. En la Google Cloud consola, ve a la página  Configuración:

      Ve a Configuración.

      Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

    2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.

    3. Selecciona la pestaña Ámbitos de traza.

      En la tabla se muestran los ámbitos de seguimiento. Cuando hayas seleccionado un Google Cloud proyecto, se mostrará una entrada con el icono "Predeterminado", , que indica que es el ámbito de seguimiento predeterminado. La página Explorador de trazas busca datos de trazas en los proyectos que se incluyen en el ámbito de trazas predeterminado cuando se abre la página.

    gcloud

    No es compatible.

    REST

    Para mostrar todos los ámbitos de traza de un Google Cloud proyecto, usa el comando projects.locations.traceScopes.list. Debe especificar un parámetro de ruta.

    El parámetro de ruta de este endpoint tiene la siguiente sintaxis:

    projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

    Los campos de la expresión anterior tienen el siguiente significado:

    • PROJECT_ID: identificador del proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
    • LOCATION_ID debe establecerse en global.

    La respuesta es una matriz de objetos TraceScope. Cada objeto incluye un nombre y una lista de recursos.

    Para obtener información sobre un ámbito de seguimiento específico, usa el comando projects.locations.traceScopes.get.

    Crear un ámbito de rastreo

    Los intervalos que se muestran en la página Explorador de trazas dependen de los proyectos buscados, de tus roles de gestión de identidades y accesos en esos proyectos, del periodo y de los filtros que apliques.

    Puedes crear 100 ámbitos de traza por proyecto. Un ámbito de traza puede incluir un total de 20 proyectos.

    Consola

    Para crear un ámbito de traza, haz lo siguiente:

    1. En la Google Cloud consola, ve a la página  Configuración:

      Ve a Configuración.

      Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

    2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
    3. Selecciona la pestaña Ámbitos de traza y, a continuación, haz clic en Crear ámbito de traza.

    4. Haz clic en Añadir proyectos y completa el cuadro de diálogo.

      Si no sabes qué proyectos incluir en un ámbito, puedes usar la página antigua Explorador de trazas para identificarlos. Para obtener más información, consulta la sección Migrar a ámbitos de seguimiento de este documento.

    5. En la sección Nombre del ámbito de la traza, introduce el nombre y la descripción que quieras que se muestren en la pestaña Ámbitos de la traza.

      El nombre de un ámbito de traza no se puede modificar y debe ser único en el proyecto.

    6. Haz clic en Crear ámbito de traza.

    gcloud

    No es compatible.

    REST

    Para crear un ámbito de seguimiento, usa el comando projects.locations.traceScopes.create. Debe especificar un parámetro de ruta y proporcionar un objeto TraceScope. La respuesta es un objeto TraceScope.

    El parámetro de ruta de este endpoint tiene la siguiente sintaxis:

    projects/PROJECT_ID/locations/LOCATION_ID/traceScopes

    Los campos de la expresión anterior tienen el siguiente significado:

    • PROJECT_ID: identificador del proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
    • LOCATION_ID debe establecerse en global.

    Migrar a ámbitos de traza

    En la página Explorador de trazas, debe especificar los Google Cloud proyectos en los que buscar datos de trazas, lo que supone un cambio en el comportamiento respecto a la página Explorador de trazas anterior. La página antigua Explorador de trazas busca en todos los proyectos de una organización. Debido a estas diferencias, es posible que la página Explorador de trazas no muestre los intervalos que sí muestra la página Explorador de trazas antigua.

    Puedes usar la sección del panel Detalles del rastreo de la página antigua Explorador de rastreo para compilar una lista deGoogle Cloud proyectos que almacenan tus datos de rastreo:

    1. Ve a la página antigua Explorador de trazas:

      Ir a Explorador de Trace antiguo

    2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.

    3. Selecciona una traza.

      Puedes probar lo siguiente:

      • Ver un rastreo introduciendo su ID en el campo ID de rastreo.
      • Añadir filtros.

    4. En el panel Detalles del rastreo, selecciona el rastreo y, a continuación, ve a la pestaña Proyectos.

      En esta pestaña se muestran los proyectos que almacenan los intervalos de la traza.

    5. Para crear un ámbito de rastreo que contenga los proyectos de la lista, vaya a la barra de herramientas de la pestaña Proyectos y seleccione Crear ámbito con estos proyectos. A continuación, complete el cuadro de diálogo.

    6. Repite los pasos anteriores hasta que hayas creado una lista de proyectos.

    Una vez que hayas compilado una lista de proyectos, crea un ámbito de traza. También puedes definirlo como el ámbito de seguimiento predeterminado.

    Modificar o eliminar un ámbito de seguimiento

    No puedes eliminar ni modificar el ámbito de seguimiento llamado _Default. Puedes modificar o eliminar todos los demás ámbitos de traza.

    Consola

    Para modificar o eliminar un ámbito de seguimiento, haz lo siguiente:

    1. En la Google Cloud consola, ve a la página  Configuración:

      Ve a Configuración.

      Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

    2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
    3. Selecciona la pestaña Ámbitos de traza.

    4. Busca el ámbito de la traza que quieras modificar o eliminar, haz clic en  Más y, a continuación, haz una de las siguientes acciones:

      • Para modificarlo, selecciona Editar ámbito y, a continuación, completa el cuadro de diálogo.
      • Para eliminarlo, selecciona Eliminar ámbito y, a continuación, completa el cuadro de diálogo.

    gcloud

    No es compatible.

    REST

    Modificar un ámbito

    Para modificar el ámbito de un rastreo, usa el comando projects.locations.traceScopes.patch. Debe especificar un parámetro de ruta, parámetros de consulta y proporcionar un objeto TraceScope. Los parámetros de consulta identifican los campos que se han modificado. La respuesta es un objeto TraceScope.

    El parámetro de ruta de este endpoint tiene la siguiente sintaxis:

    projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

    Los campos de la expresión anterior tienen el siguiente significado:

    • PROJECT_ID: identificador del proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
    • LOCATION_ID debe establecerse en global.
    • TRACE_SCOPE_NAME: nombre de un ámbito de traza. Por ejemplo, my-trace-scope.

    Eliminar un ámbito

    Para eliminar un ámbito de seguimiento, usa el comando projects.locations.traceScopes.delete. Debe especificar un parámetro de ruta.

    El parámetro de ruta de este endpoint tiene la siguiente sintaxis:

    projects/PROJECT_ID/locations/LOCATION_ID/traceScopes/TRACE_SCOPE_NAME

    Los campos de la expresión anterior tienen el siguiente significado:

    • PROJECT_ID: identificador del proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
    • LOCATION_ID debe establecerse en global.
    • TRACE_SCOPE_NAME: nombre de un ámbito de traza. Por ejemplo, my-trace-scope.

    Configurar el ámbito de la traza predeterminado

    Cuando se abre la página Explorador de trazas, se buscan datos de trazas en los proyectos que se muestran en el ámbito de trazas predeterminado. Si no se puede acceder a ese ámbito de seguimiento, se buscarán datos de seguimiento en tu proyecto.

    Cuando se crean proyectos, se crea el ámbito de traza _Default y se designa como ámbito de traza predeterminado. Sin embargo, puedes crear tu propio ámbito de traza y designarlo como ámbito de traza predeterminado.

    Consola

    Para definir el ámbito de la traza predeterminado, haz lo siguiente:

    1. En la Google Cloud consola, ve a la página  Configuración:

      Ve a Configuración.

      Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

    2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.

    3. Selecciona la pestaña Ámbitos de traza.

      En la pestaña se muestran los ámbitos de seguimiento y se incluye un botón para crear un ámbito de seguimiento personalizado. El ámbito de la traza que se muestra con el icono "Predeterminado", , es el ámbito de la traza predeterminado actual.

    4. Para cambiar el ámbito de la traza predeterminado, busca el ámbito de la traza que quieras designar como predeterminado, haz clic en  Más y, a continuación, selecciona Definir como predeterminado.

      El ámbito de la traza que has seleccionado se muestra con un icono "Predeterminado", .

    gcloud

    No es compatible.

    REST

    Para obtener y definir el ámbito de registro predeterminado o el ámbito de seguimiento predeterminado mediante una llamada a la API, configura el ámbito de observabilidad. En el ámbito de observabilidad se muestran el ámbito de registro predeterminado y el ámbito de traza predeterminado:

    • Para obtener el ámbito de observabilidad predeterminado de un proyecto, envía una solicitud al punto de conexión projects.locations.scopes.get. Debe especificar un parámetro de ruta. La respuesta es un objeto Scope que muestra el ámbito de registro predeterminado y el ámbito de seguimiento predeterminado.

    • Para actualizar el ámbito de observabilidad predeterminado de un proyecto, envía una solicitud al endpoint projects.locations.scopes.patch. Debe especificar un parámetro de ruta, parámetros de consulta y un objeto Scope. Los parámetros de consulta identifican qué campos se han modificado. La respuesta es un objeto Scope.

    El parámetro de ruta de ambos endpoints tiene el siguiente formato:

    projects/PROJECT_ID/locations/LOCATION/scopes/OBSERVABILITY_SCOPE_ID

    Los campos de la expresión anterior tienen el siguiente significado:

    • PROJECT_ID: identificador del proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
    • LOCATION: el campo de ubicación debe tener el valor global.
    • OBSERVABILITY_SCOPE_ID: nombre de un objeto Scope. Este campo debe tener el valor _Default. El objeto Scope con el nombre _Default, que se crea automáticamente, almacena información sobre el ámbito de registro predeterminado y el ámbito de seguimiento predeterminado.

    Para enviar un comando a un endpoint de la API, puedes usar Explorador de APIs, que te permite enviar un comando desde una página de referencia. Por ejemplo, para obtener el ámbito predeterminado actual, puedes hacer lo siguiente:

    1. Haz clic en projects.locations.scopes.get.

    2. En el widget Prueba este método, introduce lo siguiente en el campo name (nombre): 

      projects/PROJECT_ID/locations/global/scopes/_Default

      Antes de copiar el campo anterior, sustituye PROJECT_ID por el nombre de tu proyecto.

    3. Selecciona Ejecutar.

    4. En el cuadro de diálogo de autorización, completa los pasos necesarios.

      La respuesta es similar a la siguiente:

      {
"name": "projects/my-project/locations/global/scopes/_Default",
"logScope": "logging.googleapis.com/projects/my-project/locations/global/logScopes/_Default"
"traceScope": "projects/my-project/locations/global/traceScopes/_Default"
}

    Límites de los ámbitos de los rastreos

    Límites de los ámbitos de los rastreos Valor
    Número máximo de ámbitos de traza por proyecto 100
    Número máximo de proyectos por ámbito de traza 20

    Siguientes pasos