Consultar y ver registros

La consulta de registros en Google Distributed Cloud (GDC) aislado te permite inspeccionar los eventos operativos y de auditoría de las cargas de trabajo de tu proyecto después de recoger los registros. Puedes filtrar, visualizar y exportar flujos de registros en el panel de registros de Grafana con expresiones de Log Query Language (LogQL). En el caso de los flujos de trabajo programáticos, consulta la API Log Query de tu organización a través de HTTP o gRPC siguiendo los métodos de acceso estándar de la API.

Antes de empezar

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

Solicitar roles de organización de gestión de identidades y accesos

Ponte en contacto con el admin. de la org. de gestión de identidades y accesos para solicitar los siguientes roles:

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

Solicitar roles de proyecto de gestión de identidades y accesos

Ponte en contacto con el administrador de proyectos de gestión de identidades y accesos para solicitar los siguientes roles:

  • Lector de Grafana del proyecto (project-grafana-viewer): visualiza datos observables relacionados con el proyecto en los paneles de control de la instancia de supervisión de Grafana en el espacio de nombres del proyecto.
  • Consultor de registros (log-query-api-querier): accede a la API 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 perfiles de PA y AO:

Perfil ficticio Objeto Clúster Rol Espacio de nombres Grupo o usuario
PA grafana servidor de la API de gestión project-grafana-viewer platform-obs Grupo
PA log-query-api servidor de la API de gestión log-query-api-querier-pa platform-obs Grupo
PA grafana servidor de la API de gestión project-grafana-viewer platform-obs Usuario
PA log-query-api servidor de la API de gestión log-query-api-querier-pa platform-obs Usuario
AO grafana servidor de la API de gestión project-grafana-viewer PROJECT_NAMESPACE Grupo
AO log-query-api servidor de la API de gestión log-query-api-querier PROJECT_NAMESPACE Grupo
AO grafana servidor de la API de gestión project-grafana-viewer PROJECT_NAMESPACE Usuario
AO log-query-api servidor de la API de gestión log-query-api-querier PROJECT_NAMESPACE Usuario

Selecciona una de las siguientes configuraciones para conceder acceso de Grafana a un grupo de usuarios (Config 1) o a un usuario concreto (Config 2) en el servidor de la API de gestió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 archivo de infraestructura como código (IaC) especificada para aplicarlo mediante GitOps:

Configuración 1

Esta configuración concede permisos a un grupo de usuarios para acceder a PA y AO Grafana en el servidor de la API de gestión. Después de configurar esta opción, consulta la sección Paneles de control 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 --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 archivo de IaC

    También puedes gestionar el RoleBinding usando IaC. Para ello, crea el archivo YAML en la siguiente ruta:

    /infrastructure/zonal/zones/ZONE/org-admin/rolebindings/GROUP_NAME/YAML_FILE
    
  • Archivo YAML

    Guarda el siguiente manifiesto de RoleBinding en el archivo YAML de la ruta 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
    

Configuración 2

Esta configuración concede permisos a un usuario para acceder a Grafana de PA y AO en el servidor de la API de gestión. Después de configurar esta opción, consulta la sección Paneles de control 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 archivo de IaC

    También puedes gestionar el RoleBinding usando IaC. Para ello, crea el archivo YAML en la siguiente ruta:

    /infrastructure/zonal/zones/ZONE/org-admin/rolebindings/EMAIL_ADDRESS/YAML_FILE
    
  • Archivo YAML

    Guarda el siguiente manifiesto de RoleBinding en el archivo YAML de la ruta 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
    

Haz los cambios siguientes:

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

Para obtener más información sobre estos roles, consulta Preparar permisos de gestión de identidades y accesos.

Consultar y filtrar registros

Selecciona uno de los siguientes métodos para crear 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 mediante el panel de registros de Grafana.

Identificar tu endpoint de Grafana

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

  https://GDC_URL/PROJECT_NAMESPACE/grafana

Haz los cambios siguientes:

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

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

Ver registros en la interfaz de usuario de Grafana

Registros de consultas en la interfaz de usuario de Grafana:

  1. En la consola de GDC, selecciona tu proyecto.
  2. En el menú de navegación, selecciona Operations (Operaciones) > Logging (Registro).
  3. Haz clic en Ver todo en Grafana Loki.

    Se abrirá una nueva página con tu endpoint de Grafana y se mostrará la interfaz de usuario.

  4. En la interfaz de usuario, haz clic en Explorar Explorar en el menú de navegación para abrir la página Explorar.

  5. En el menú de la barra Explorar, selecciona una fuente de datos para obtener 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 zona única 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 de varias zonas. Selecciona una de las siguientes fuentes de datos para mostrar los datos de registro de cualquier zona de tu universo, independientemente de la zona en la que hayas iniciado sesión:

      • Registros operativos ZONE_NAME: muestra los registros operativos de una zona concreta.
      • Registros de auditoría ZONE_NAME: muestra los registros de auditoría de una zona concreta.

      Además, para tener visualizaciones de datos de varias zonas en un solo panel de control y añadir varias zonas a tu consulta, selecciona Mixto como fuente de datos.

  6. Introduce una consulta para buscar registros en el panel Registro mediante expresiones de LogQL (Log Query Language). Puedes hacerlo de cualquiera de las siguientes formas:

    • Usa la interfaz interactiva de la herramienta para crear consultas. A continuación, haz clic en Ejecutar consulta.
    • Introduce tu consulta directamente en el campo de texto y pulsa Mayús+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 intervalo de tiempo para tus registros.

    La opción Registros de auditoría está seleccionada en la página Explorar para obtener registros de auditoría.

    Imagen 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 crear consultas desde Grafana para obtener registros de auditoría.

    Para ver ejemplos de etiquetas y valores para consultar diferentes registros, consulta Ejemplos de consultas y etiquetas.

Seleccionar un periodo para los registros

Para consultar registros de un periodo, sigue estos pasos:

  1. Haz clic en el menú Selector de tiempo de Grafana.

  2. En el menú, realiza una de las siguientes acciones:

    • Selecciona opciones de periodo relativas, como los últimos 30 minutos.
    • Define intervalos de tiempo absolutos personalizados eligiendo fechas y horas específicas en el calendario y haciendo clic en Aplicar intervalo de tiempo.
  3. Si quieres, haz clic en Cambiar configuración de tiempo para modificar los ajustes Zona horaria y Año fiscal de los controles de periodo.

    La configuración de tiempo se guarda en cada panel de control. 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 Log Query

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

Identificar el endpoint de API de consulta de registros

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

  • Endpoint del registro de auditoría:

    audit-log-query-api.ORG_DOMAIN
    
  • Endpoint de registro operativo:

    operational-log-query-api.ORG_DOMAIN
    

Sustituye 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 la prueba(s) tiene un dominio como org-1.zone1.google.gdch.test.

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

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

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

Enviar una consulta

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

HTTP

Sigue las instrucciones para acceder directamente a la API con un cliente HTTP. Puedes confiar en kubectl para gestionar la autenticación o hacerlo tú.

Envía una consulta a la API Log Query usando clientes HTTP como curl, wget o un cliente HTTP que crees y gestiones. En el siguiente ejemplo se usa la herramienta curl para consultar la API. Puedes usar un formato similar para los comandos de wget:

  1. Autentica la solicitud de cURL:

    1. Descarga e instala la CLI gdcloud.
    2. Configura la propiedad core/organization_console_url de gdcloud:

      gdcloud config set core/organization_console_url https://GDC_URL
      

      Sustituye GDC_URL por la URL de una organización de GDC.

    3. Inicia sesión con el proveedor de identidades configurado:

      gdcloud auth login
      
    4. Usa tu usuario y contraseña para autenticarte e iniciar sesión.

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

      Sustituye LOG_QUERY_API_ENDPOINT por el endpoint de API Log Query desde el que quieras consultar los registros y el dominio al que quieras 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 inicio de sesión se haya completado correctamente, podrás usar el encabezado de autorización en tu solicitud de cURL mediante el comando gdcloud auth print-identity-token. Para obtener más información, consulta gdcloud auth print-identity-token.

  2. Si quieres ver 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
    

    Haz los cambios siguientes:

    • LOG_QUERY_API_ENDPOINT: el endpoint de API de Log Query desde el que quieres consultar los registros.
    • PROJECT_NAMESPACE: el espacio de nombres de tu proyecto.
  3. Si quieres mostrar valores de etiqueta específicos de 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
    

    Haz los cambios siguientes:

    • LOG_QUERY_API_ENDPOINT: el endpoint de API de Log Query desde el que quieres consultar los registros.
    • PROJECT_NAMESPACE: el espacio de nombres de tu proyecto.
    • LABEL: la etiqueta específica cuyo valor quieres consultar.
  4. Si quieres consultar los registros de un proyecto específico, crea una consulta de logs_filter e inclúyela en el 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
    

    Haz los cambios siguientes:

    • LOG_QUERY_API_ENDPOINT: el endpoint de API de Log Query desde el que quieres consultar los registros.
    • PROJECT_NAMESPACE: el espacio de nombres de tu proyecto.
    • LABEL: la etiqueta específica de la que quieres consultar los registros.
    • LABEL_VALUE: el valor de la etiqueta para la que quieres consultar los registros.

    Consulta la documentación sobre la API para ver todas las opciones para crear una consulta de logs_filter.

gRPC

gRPC es compatible con muchos lenguajes de programación y ofrece un método de comunicación más eficiente que los clientes HTTP.

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

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

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

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

  1. 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
    }
    
  2. Ejecuta el programa Go:

    go run PATH_TO_API/client.go -server=LOG_QUERY_API_ENDPOINT:443
    

    Haz los cambios siguientes:

    • PATH_TO_API: la ruta al archivo de la API.
    • LOG_QUERY_API_ENDPOINT: el endpoint de API de Log Query desde el que quieres consultar los registros.

    Si no se especifica la marca del servidor, la solicitud predeterminada se envía a localhost.

Consultas y etiquetas de ejemplo

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

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

En los siguientes códigos de ejemplo 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"}
    
  • Seleccionar registros de auditoría de clústeres:

    {cluster="admin", resources="k8s_audit"}