Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Consulta y visualización de registros

En esta página, se proporcionan instrucciones detalladas para consultar y visualizar tus registros con la interfaz de usuario de Grafana y la API de Log Query para obtener estadísticas sobre los eventos y la actividad de tu servicio.

Después de recopilar registros de tus cargas de trabajo y servicios implementados en Google Distributed Cloud (GDC) aislado, puedes comenzar a analizarlos. Para analizar los registros, puedes visualizarlos y filtrarlos en paneles informativos de Grafana, o bien acceder a ellos directamente desde la API de Log Query con llamadas HTTP o gRPC para obtener acceso programático.

Puedes acceder a tus registros con uno de los siguientes dos métodos:

Paneles de Grafana: Obtén estadísticas sobre el registro de actividad de tu proyecto a través del panel de registro de tu instancia de Grafana. Este panel te permite consultar y detectar registros específicos, lo que proporciona una observabilidad de datos detallada adaptada a tus necesidades. Grafana proporciona una interfaz fácil de usar para filtrar y analizar los datos de tu carga de trabajo, y crear paneles personalizados para una visualización integral.
API de Log Query: Para obtener acceso programático, consulta los registros directamente desde la API de Log Query de tu proyecto. La API de Log Query es una API que no es de Kubernetes y que admite HTTP y gRPC, lo que te expone sus propios extremos. Accede a esta API solo dentro de una organización específica en Distributed Cloud siguiendo los métodos de acceso a la API estándar.

Antes de comenzar

Para consultar y visualizar registros, debes tener los permisos necesarios.

Solicita roles de organización de IAM

Comunícate con el administrador de IAM de tu organización para solicitar los siguientes roles:

Visualizador de Grafana de la organización (organization-grafana-viewer): Visualiza los datos observables relacionados con la organización en los paneles de la instancia de supervisión de Grafana.
Log Querier (log-query-api-querier-pa): Accede a la API de Log Query para consultar los registros de la plataforma en el proyecto platform-obs.

Solicita roles de IAM para el proyecto

Comunícate con el administrador de IAM de tu proyecto para solicitar los siguientes roles:

Visualizador de Grafana del proyecto (project-grafana-viewer): Visualiza los datos observables relacionados con el proyecto en los paneles de la instancia de supervisión de Grafana en el espacio de nombres del proyecto.
Log Querier (log-query-api-querier): Accede a la API de Log Query para consultar los registros de aplicaciones en el espacio de nombres del proyecto.

En la siguiente tabla, se resumen los requisitos de Role para los arquetipos de PA y AO:

Personificación	Objeto	Clúster	Rol	Espacio de nombres	Grupo/usuario
PA	`grafana`	servidor de la API de administración	`project-grafana-viewer`	`platform-obs`	Grupo
PA	`log-query-api`	servidor de la API de administración	`log-query-api-querier-pa`	`platform-obs`	Grupo
PA	`grafana`	Servidor de la API de administración	`project-grafana-viewer`	`platform-obs`	Usuario
PA	`log-query-api`	Servidor de la API de administración	`log-query-api-querier-pa`	`platform-obs`	Usuario
AO	`grafana`	servidor de la API de administración	`project-grafana-viewer`	`PROJECT_NAMESPACE`	Grupo
AO	`log-query-api`	servidor de la API de administración	`log-query-api-querier`	`PROJECT_NAMESPACE`	Grupo
AO	`grafana`	servidor de la API de administración	`project-grafana-viewer`	`PROJECT_NAMESPACE`	Usuario
AO	`log-query-api`	servidor de la API de administración	`log-query-api-querier`	`PROJECT_NAMESPACE`	Usuario

Selecciona una de las siguientes configuraciones para otorgar acceso a Grafana a un grupo de usuarios (Config 1) o a un usuario individual (Config 2) en el servidor de la API de administración. Para cada configuración, puedes ejecutar el comando kubectl para crear el RoleBinding directamente o guardar el manifiesto YAML de RoleBinding en la ruta de acceso del archivo de infraestructura como código (IaC) especificada para aplicarlo a través de GitOps:

Config. 1

Esta configuración otorga permisos a un grupo de usuarios para acceder a Grafana de PA y AO en el servidor de la API de administración. Después de establecer esta configuración, consulta la sección Paneles de Grafana de este documento para ver los registros en Grafana.

Comando de kubectl

Ejecuta el siguiente comando para crear el RoleBinding directamente:

kubectl --kubeconfig KUBECONFIG create rolebinding RULE_NAME -n platform-obs --group=GROUP_NAME --role=project-grafana-viewer

Ejemplo:

kubectl --kubeconfig KUBECONFIG_PATH create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obs

Ruta de acceso del archivo de IaC

Como alternativa, para administrar el RoleBinding con IaC, crea el archivo YAML en la siguiente ruta de acceso:
```
/infrastructure/zonal/zones/ZONE/org-admin/rolebindings/GROUP_NAME/YAML_FILE
```

Archivo YAML

Guarda el siguiente manifiesto RoleBinding en el archivo YAML en la ruta de acceso del archivo de IaC:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: Group
  name: GROUP_NAME
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

Config. 2

Esta configuración otorga permisos a un usuario para acceder a PA y AO Grafana en el servidor de la API de administración. Después de configurar este parámetro, consulta la sección Paneles de Grafana de este documento para ver los registros en Grafana.

Comando kubectl

Ejecuta el siguiente comando para crear el RoleBinding directamente:

kubectl --kubeconfig KUBECONFIG create rolebinding RULE_NAME -n platform-obs --user=EMAIL_ADDRESS --role=project-grafana-viewer

Ejemplo:

kubectl --kubeconfig KUBECONFIG_PATH create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=my-email@example.com --namespace=platform-obs

Ruta de acceso del archivo de IaC

Como alternativa, para administrar el RoleBinding con IaC, crea el archivo YAML en la siguiente ruta de acceso:
```
/infrastructure/zonal/zones/ZONE/org-admin/rolebindings/EMAIL_ADDRESS/YAML_FILE
```

Archivo YAML

Guarda el siguiente manifiesto RoleBinding en el archivo YAML en la ruta de acceso del archivo de IaC:

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: RULE_NAME
  namespace: platform-obs
subjects:
- kind: User
  name: EMAIL_ADDRESS
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: project-grafana-viewer
  apiGroup: rbac.authorization.k8s.io

Reemplaza lo siguiente:

KUBECONFIG: Es la ruta de acceso al archivo kubeconfig del clúster específico que contiene el NAMESPACE en el que se aplica este RoleBinding.
KUBECONFIG_PATH: Es la ruta de acceso al archivo kubeconfig en los comandos de ejemplo.
RULE_NAME: Es el nombre único de este recurso RoleBinding dentro del espacio de nombres, como pa-project-grafana-viewer.
NAMESPACE: Es el espacio de nombres de Kubernetes en el que se crea y aplica este RoleBinding. Busca la columna Namespace en la tabla anterior.
EMAIL_ADDRESS: Es el identificador del usuario al que se le otorga el rol, como application-operator@example.com.
ROLE: Es el nombre del Role que contiene los permisos que deseas otorgar al usuario. Busca los roles disponibles en la tabla anterior.
GROUP_NAME: Es el nombre del Group al que pertenece el usuario de PA, como pa-group.
ZONE: el nombre de la zona
YAML_FILE: Es el nombre del archivo YAML para el recurso RoleBinding.

Para obtener más información sobre estos roles, consulta Prepara los permisos de IAM.

Consulta y filtra tus registros

Selecciona uno de los siguientes métodos para compilar consultas y filtrar registros de las cargas de trabajo de tu proyecto:

Panel de registros de Grafana

En esta sección, se describe cómo acceder a tus registros con el panel de registros en Grafana.

Identifica tu extremo de Grafana

La siguiente URL es el extremo de la instancia de Grafana de tu proyecto:

  https://GDC_URL/PROJECT_NAMESPACE/grafana

Reemplaza lo siguiente:

GDC_URL: Es la URL de tu organización en GDC.
PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.

Por ejemplo, el extremo de Grafana para el proyecto platform-obs en la organización org-1 es https://org-1/platform-obs/grafana.

Visualiza registros en la interfaz de usuario de Grafana

Consulta los registros en la interfaz de usuario de Grafana:

En la consola de GDC, selecciona tu proyecto.
En el menú de navegación, selecciona Operaciones > Logging.
Haz clic en Ver todo en Grafana Loki.

Se abrirá una página nueva con tu extremo de Grafana y se mostrará la interfaz de usuario.
En la interfaz de usuario, haz clic en Explorar Explorar en el menú de navegación para abrir la página Explorar.
En el menú de la barra Explorar, selecciona una fuente de datos para recuperar los registros, según el tipo de universo:
- Universos de una sola zona: Selecciona una de las siguientes fuentes de datos para mostrar los datos de registro de la única zona de tu universo:
  - Registros operativos: Muestra los registros operativos.
  - Registros de auditoría: Muestra los registros de auditoría.
- Universos multizona: Grafana puede conectarse a diferentes zonas y mostrar datos entre zonas. Selecciona una de las siguientes fuentes de datos para mostrar los datos de registros de cualquier zona de tu universo, independientemente de la zona en la que hayas accedido:
  - Registros operativos ZONE_NAME: Muestra los registros operativos de una zona en particular.
  - Registros de auditoría ZONE_NAME: Muestra los registros de auditoría de una zona en particular.
  Además, para tener visualizaciones de datos entre zonas en un solo panel y agregar varias zonas a tu consulta, selecciona Mixta como fuente de datos.
  
  Nota: Los registros de auditoría solo están disponibles para los administradores de la plataforma, incluso si no pueden crear ni configurar destinos de registro de auditoría. Los operadores de aplicaciones solo pueden acceder a los registros operativos.
Ingresa una consulta para buscar registros en el panel de registros con expresiones de LogQL (lenguaje de consulta de registros). Puedes realizar este paso de una de las siguientes maneras:
- Usa la interfaz interactiva del compilador de consultas. Luego, haz clic en Ejecutar consulta.
- Ingresa tu consulta directamente en el campo de texto y presiona Mayúsculas + Intro para ejecutarla.
En la página, se muestran los registros que coinciden con tu consulta. Después de consultar los registros, puedes exportarlos. Haz clic en Exportar para descargar los registros en formato de texto sin formato o CSV. También puedes seleccionar un período para tus registros.

Figura 1. Opción de menú para consultar los registros de auditoría desde la interfaz de usuario de Grafana.

En la figura 1, la opción Registros de auditoría muestra la interfaz que te permite compilar consultas desde Grafana para recuperar registros de auditoría.

Para ver ejemplos de etiquetas y valores para consultar diferentes registros, consulta Consultas y etiquetas de ejemplo.

Selecciona un intervalo de tiempo para tus registros

Para consultar registros en un período, sigue estos pasos:

Haz clic en el menú Selector de tiempo en Grafana.
En el menú, realiza una de las siguientes acciones:
- Selecciona opciones de intervalo de tiempo relativo, por ejemplo, los últimos 30 minutos.
- Establece períodos absolutos personalizados eligiendo fechas y horas específicas del calendario y haciendo clic en Aplicar período.
De manera opcional, haz clic en Cambiar la configuración de tiempo para cambiar la configuración de Zona horaria y Año fiscal desde los controles de período.

La configuración de hora se guarda por panel. Para obtener más información sobre las consultas en un intervalo de tiempo, consulta https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time.

API de Log Query

En esta sección, se describe cómo acceder a tus registros con la API de Log Query.

Identifica el extremo de API de Log Query

La API de Log Query expone los siguientes dos extremos para consultar los registros de auditoría y operativos:

Extremo del registro de auditoría:
```
audit-log-query-api.ORG_DOMAIN
```
Nota: Los registros de auditoría solo están disponibles para los administradores de la plataforma, incluso si no pueden crear ni configurar destinos de registro de auditoría. Los operadores de aplicaciones solo pueden acceder a los registros operativos.
Extremo de registro operativo:
```
operational-log-query-api.ORG_DOMAIN
```

Reemplaza ORG_DOMAIN por el nombre de dominio de la organización. Puedes ver esta propiedad con el comando gdcloud config list. El nombre de dominio debe seguir la sintaxis org-name.zone.google.gdch.com. Por ejemplo, una organización llamada org-1, en la zona zone1 y en un entorno de prueba tiene un dominio como org-1.zone1.google.gdch.test.

La API de Log Query tiene las siguientes tres opciones de extremos:

labels: Enumera todas las etiquetas de un proyecto.
labels/labels/LABEL/values: Enumera valores de etiquetas específicos para un proyecto.
logs: Enumera los registros de un proyecto específico.

Para obtener más información, consulta la documentación de la API.

Envía una consulta

Envía una consulta al endpoint de API de Log Query con clientes HTTP o gRPC.

HTTP

Sigue las instrucciones para acceder directamente a la API con un cliente HTTP. Puedes confiar en kubectl para administrar la autenticación o controlarla por tu cuenta.

Consulta la API de Log Query con clientes HTTP como curl, wget o un cliente HTTP que crees y administres. En el siguiente ejemplo, se usa la herramienta curl para consultar la API, y puedes usar un formato similar para los comandos de wget:

Autentica la solicitud cURL:
1. Descarga e instala la CLI de gdcloud.
2. Configura la propiedad core/organization_console_url de gdcloud:
```
gdcloud config set core/organization_console_url https://GDC_URL
```
  Reemplaza GDC_URL por la URL de una organización en GDC.
3. Accede con el proveedor de identidad configurado:
```
gdcloud auth login
```
4. Usa tu usuario y contraseña para autenticarte y acceder.
5. Exporta el token de identidad de la cuenta especificada a una variable de entorno:
```
export TOKEN="$($HOME/gdcloud auth print-identity-token --audiences=https://LOG_QUERY_API_ENDPOINT)"
```
  Reemplaza LOG_QUERY_API_ENDPOINT por el extremo de la API de Log Query desde el que deseas consultar los registros y el dominio al que quieres conectarte. Por lo tanto, el valor de la marca audiences puede ser, por ejemplo, https://operational-log-query-api.org-1.zone1.google.gdch.test.
  
  Cuando el acceso se realice correctamente, podrás usar el encabezado de autorización en tu solicitud de cURL con el comando gdcloud auth print-identity-token. Para obtener más información, consulta gdcloud auth print-identity-token.
Si quieres enumerar todas las etiquetas de un proyecto, envía la siguiente consulta:
```
curl -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels \
-H "Content-Type: application/json" -v
```
Reemplaza lo siguiente:
- LOG_QUERY_API_ENDPOINT: Es el endpoint de API de Log Query desde el que deseas consultar los registros.
- PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.
Si deseas enumerar valores de etiqueta específicos para un proyecto, envía la siguiente consulta:
```
curl -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels/labels/LABEL/values \
-H "Content-Type: application/json" -v
```
Reemplaza lo siguiente:
- LOG_QUERY_API_ENDPOINT: Es el endpoint de API de Log Query desde el que deseas consultar los registros.
- PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.
- LABEL: Es la etiqueta específica de la que deseas consultar su valor.
Si deseas consultar los registros de un proyecto específico, crea una consulta logs_filter y agrégala al cuerpo de la solicitud:
```
curl -X GET -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/logs \
-H "Content-Type: application/json" -d \
'{"logs_filter": {"labels_equal": {"LABEL": "LABEL_VALUE"}}}' -v
```
Reemplaza lo siguiente:
- LOG_QUERY_API_ENDPOINT: Es el endpoint de API de Log Query desde el que deseas consultar los registros.
- PROJECT_NAMESPACE: Es el espacio de nombres de tu proyecto.
- LABEL: Es la etiqueta específica para la que deseas consultar los registros.
- LABEL_VALUE: Es el valor de la etiqueta para el que deseas consultar los registros.
Consulta la documentación de la API para ver todas las opciones de construcción de una consulta de logs_filter.

gRPC

gRPC es ampliamente compatible con varios lenguajes de programación y proporciona un método de comunicación más eficiente en comparación con los clientes HTTP.

Para consultar registros con gRPC, debes cumplir con los siguientes requisitos previos:

Crea tu propia biblioteca cliente basada en los búferes de protocolo que proporciona Google.
Implementa la autenticación en el cliente.
Implementa reintentos.

Para obtener información sobre los búferes de protocolo, consulta la documentación de la API.

En el siguiente ejemplo, se muestra cómo consultar registros desde un programa en Go con un cliente de gRPC no autenticado. En el ejemplo, se supone que creaste un paquete de golang que incluye un archivo de compilación de Bazel para importar dependencias de código:

Guarda el siguiente código en un programa de Go llamado client.go:

package main
import (
        "context"
        "crypto/tls"
        "flag"
        "fmt"
        "google.golang.org/grpc/credentials"
        "google.golang.org/grpc/metadata"
        pb "<import path to generated log query api protos>/pkg/apis/public/logging/v1/proto"
        "google.golang.org/grpc"
)

var serverAddr = flag.String("server", "localhost:8080", "server address")

func main() {
        flag.Parse()
        tc := credentials.NewTLS(&tls.Config{InsecureSkipVerify: true})
        conn, err := grpc.Dial(*serverAddr, grpc.WithTransportCredentials(tc))

        if err != nil {
                panic(error.Error(fmt.Errorf("create client connection failed: %v", err)))
        }
        defer conn.Close()

        c := pb.NewLogsClient(conn)
        md := metadata.Pairs("clienttest", "test")
        ctx := metadata.NewOutgoingContext(context.Background(), md)

        err = listLabels(ctx, c, "project-foo")
        if err != nil {
                panic(error.Error(err))
        }

        if err := listLabelValues(ctx, c, "project-foo", "resource-bar"); err != nil {
                panic(error.Error(err))
        }

        if err := listLogs(ctx, c, "project-foo", &pb.ListLogsFilter{
                LabelsEqual:    map[string]string{"resource-bar": "resource-bar-value"},
                OrderAscending: true,
        }); err != nil {
                panic(error.Error(err))
        }
}

// List all labels for a project.

func listLabels(ctx context.Context, c pb.LogsClient, project string) error {
        lbr := &pb.ListLabelsRequest{
                Parent:   project,
                PageSize: 1000, // PageSize can be configured to limit the number of responses per page.
        }
        resp, err := c.ListLabels(ctx, lbr)
        if err != nil {
                return fmt.Errorf("list labels: %v", err)
        }
        fmt.Printf("%v", resp)
        return nil
}

// List specific label values for a project.

func listLabelValues(ctx context.Context, c pb.LogsClient, project string, label string) error {
        lbr := &pb.ListLabelValuesRequest{
                Parent:   project,
                Label:    label,
                PageSize: 1000, // PageSize can be configured to limit the number of responses per page.
        }
        resp, err := c.ListLabelValues(ctx, lbr)
        if err != nil {
                return fmt.Errorf("list label values: %v", err)
        }
        fmt.Printf("%v", resp)
        return nil
}

// List logs for a specific project.

func listLogs(ctx context.Context, c pb.LogsClient, project string, lf *pb.ListLogsFilter) error {
        lbr := &pb.ListLogsRequest{
                Parent:     project,
                LogsFilter: lf,
                PageSize:   5, // PageSize can be configured to limit the number of responses per page.
        }
        resp, err := c.ListLogs(ctx, lbr)
        if err != nil {
                return fmt.Errorf("list logs: %v", err)
        }
        fmt.Printf("logs: %v", resp)
        return nil
}

Ejecuta el programa en Go:
```
go run PATH_TO_API/client.go -server=LOG_QUERY_API_ENDPOINT:443
```
Reemplaza lo siguiente:
- PATH_TO_API: Es la ruta de acceso al archivo de la API.
- LOG_QUERY_API_ENDPOINT: Es el endpoint de API de Log Query desde donde deseas consultar los registros.
Si no se especifica la marca del servidor, la solicitud predeterminada llega a localhost.

Ejemplos de búsquedas y etiquetas

Estas son algunas de las etiquetas predeterminadas que puedes usar para consultar registros:

cluster: el nombre del clúster
namespace: Es el espacio de nombres de tu proyecto.
node: Es el nombre del nodo.
pod: Es el nombre del Pod.
container: Es el nombre del contenedor.

En las siguientes muestras de código, se muestra el uso de etiquetas y valores para consultar diferentes registros:

Selecciona los registros del servidor:

{cluster="admin", namespace="kube-system", resources="k8s_container", container="kube-apiserver"}

Selecciona los registros de auditoría del clúster:
```
{cluster="admin", resources="k8s_audit"}
```