本頁面由 Cloud Translation API 翻譯而成。

查詢及查看記錄

本頁面提供詳細操作說明，說明如何使用 Grafana 使用者介面和記錄查詢 API 查詢及顯示記錄，進而深入瞭解服務事件和活動。

從 Google Distributed Cloud (GDC) 氣隙環境中部署的工作負載和服務收集記錄後，即可開始分析。如要分析記錄，您可以在資訊豐富的 Grafana 面板上顯示及篩選記錄，也可以透過 HTTP 或 gRPC 呼叫，以程式輔助方式直接從 Log Query API 存取記錄。

您可以透過下列其中一種方式存取記錄：

Grafana 面板：透過 Grafana 執行個體的「記錄」面板，深入瞭解專案的活動記錄。您可以在這個面板中查詢及找出特定記錄，取得符合需求的詳細資料可觀測性。Grafana 提供簡單易用的介面，可供您篩選及分析工作負載資料、建立自訂資訊主頁和面板，全面呈現資料。
記錄查詢 API：如要透過程式存取，請直接從專案的記錄查詢 API 查詢記錄。記錄查詢 API 是非 Kubernetes API，支援 HTTP 和 gRPC，並向您公開自己的端點。請按照標準 API 存取方法，僅在 Distributed Cloud 的特定機構內存取這個 API。

事前準備

如要取得在 Grafana 使用者介面查詢及顯示記錄的權限，請要求機構 IAM 管理員或專案 IAM 管理員授予您預先定義的機構 Grafana 檢視者或專案 Grafana 檢視者角色。視您需要的存取層級和權限而定，您可能需要取得機構或專案的 Grafana 角色。

或者，如要取得透過 Log Query API 查詢記錄所需的權限，請要求專案 IAM 管理員在專案命名空間中授予您 Log Query API 查詢者角色。

如要進一步瞭解這些角色，請參閱「準備 IAM 權限」。

查詢及篩選記錄

選取下列其中一種方法，從專案工作負載中建構查詢及篩選記錄：

Grafana 記錄面板

本節說明如何使用 Grafana 的「記錄」面板存取記錄。

找出 Grafana 端點

以下網址是專案 Grafana 執行個體的端點：

  https://GDC_URL/PROJECT_NAMESPACE/grafana

更改下列內容：

GDC_URL：您在 GDC 中的機構網址。
PROJECT_NAMESPACE：您的專案命名空間。

舉例來說，org-1 機構中 platform-obs 專案的 Grafana 端點為 https://org-1/platform-obs/grafana。

在 Grafana 使用者介面中查看記錄

在 Grafana 使用者介面中查詢記錄：

在 GDC 控制台中選取專案。
在導覽選單中，依序選取「Operations」>「Logging」。
按一下「在 Grafana Loki 中查看所有記錄」。

新頁面會開啟 Grafana 端點，並顯示使用者介面。
在使用者介面中，按一下導覽選單中的「探索」，開啟「探索」頁面。
在「探索」列的選單中，根據您的宇宙類型選取資料來源，以擷取記錄：
- 單一可用區宇宙：選取下列其中一個資料來源，顯示宇宙單一可用區的記錄資料：
  - 作業記錄：顯示作業記錄。
  - 稽核記錄：顯示稽核記錄。
- 多區域宇宙：Grafana 可以連線至不同區域，並顯示跨區域資料。選取下列任一資料來源，即可顯示宇宙中任何區域的記錄資料，不論您登入的區域為何：
  - 作業記錄 ZONE_NAME：顯示特定區域的作業記錄。
  - 稽核記錄 ZONE_NAME：顯示特定區域的稽核記錄。
  此外，如要在單一資訊主頁中顯示跨區域資料，並在查詢中新增多個區域，請選取「混合」做為資料來源。
  
  注意： 只有平台管理員才能查看稽核記錄，即使他們無法建立或設定稽核記錄目標也一樣。應用程式營運人員只能存取作業記錄。
在「記錄」面板中，使用 LogQL (記錄查詢語言) 運算式輸入查詢，即可搜尋記錄。你可以透過下列任一方式完成這個步驟：
- 使用互動式查詢建立工具介面。然後按一下「執行查詢」。
- 直接在文字欄位中輸入查詢內容，然後按下 Shift+Enter 鍵執行查詢。
頁面會顯示與查詢相符的記錄。查詢記錄後，您可以匯出記錄。按一下「匯出」，即可下載純文字或 CSV 格式的記錄。您也可以選取記錄的時間範圍。

圖 1. 可從 Grafana 使用者介面查詢稽核記錄的選單選項。

如圖 1 所示，「稽核記錄」選項會顯示介面，讓您從 Grafana 建立查詢，以擷取稽核記錄。

如需查詢不同記錄的標籤和值範例，請參閱查詢和標籤範例。

選取記錄檔的時間範圍

如要查詢特定時間範圍內的記錄，請按照下列步驟操作：

按一下 Grafana 中的「時間選擇器」選單。
在選單中執行下列任一操作：
- 選取相對時間範圍選項，例如「過去 30 分鐘」。
- 如要設定自訂絕對時間範圍，請從日曆選擇特定日期和時間，然後按一下「套用時間範圍」。
(選用) 按一下「變更時間設定」，即可透過時間範圍控制項變更「時區」和「會計年度」設定。

時間設定會儲存在個別資訊主頁中。如要進一步瞭解如何查詢特定時間範圍內的資料，請參閱 https://grafana.com/docs/loki/latest/reference/api/#query-loki-over-a-range-of-time。

記錄查詢 API

本節說明如何使用 Log Query API 存取記錄。

找出 Log Query API 端點

記錄查詢 API 提供下列兩個端點，可查詢稽核和作業記錄：

稽核記錄端點：
```
audit-log-query-api.ORG_DOMAIN
```
注意： 只有平台管理員可以查看稽核記錄，即使他們無法建立或設定稽核記錄目標也一樣。應用程式作業人員只能存取作業記錄。
作業記錄端點：
```
operational-log-query-api.ORG_DOMAIN
```

將 ORG_DOMAIN 替換為機構的網域名稱。您可以使用 gdcloud config list 指令查看這項屬性。網域名稱必須遵循 org-name.zone.google.gdch.com 語法。舉例來說，在測試環境中，名為 org-1 的機構位於 zone1 區域，網域類似 org-1.zone1.google.gdch.test。

Log Query API 提供下列三種端點選項：

labels：列出專案的所有標籤。
labels/labels/LABEL/values：列出專案的特定標籤值。
記錄：列出特定專案的記錄。

詳情請參閱 API 說明文件。

傳送查詢

使用 HTTP 或 gRPC 用戶端，將查詢傳送至 Log Query API 端點。

HTTP

按照操作說明使用 HTTP 用戶端直接存取 API。您可以依賴 kubectl 管理驗證，也可以自行處理驗證。

使用 curl、wget 等 HTTP 用戶端，或您建立及管理的 HTTP 用戶端，查詢 Log Query API。下列範例使用 curl 工具查詢 API，您也可以對 wget 指令使用類似格式：

驗證 cURL 要求：
1. 下載並安裝 gdcloud CLI。
2. 設定 gdcloud core/organization_console_url 屬性：
```
gdcloud config set core/organization_console_url https://GDC_URL
```
  將 GDC_URL 替換為 GDC 中機構的網址。
3. 使用已設定的識別資訊提供者登入：
```
gdcloud auth login
```
4. 使用使用者名稱和密碼進行驗證並登入。
5. 將指定帳戶的身分權杖匯出至環境變數：
```
export TOKEN="$($HOME/gdcloud auth print-identity-token --audiences=https://LOG_QUERY_API_ENDPOINT)"
```
  將 LOG_QUERY_API_ENDPOINT 替換為要查詢記錄的記錄查詢 API 端點，以及要連線的網域。因此，audiences 標記的值可以是 https://operational-log-query-api.org-1.zone1.google.gdch.test。
  
  登入成功後，您可以使用 gdcloud auth print-identity-token 指令，透過 cURL 要求中的授權標頭。詳情請參閱 gdcloud auth print-identity-token。
如要列出專案的所有標籤，請傳送下列查詢：
```
curl -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels \
-H "Content-Type: application/json" -v
```
更改下列內容：
- LOG_QUERY_API_ENDPOINT：您要從中查詢記錄的記錄查詢 API 端點。
- PROJECT_NAMESPACE：您的專案命名空間。
如要列出專案的特定標籤值，請傳送下列查詢：
```
curl -H "Authorization: Bearer ${TOKEN}" \
https://LOG_QUERY_API_ENDPOINT/v1/projects/PROJECT_NAMESPACE/labels/labels/LABEL/values \
-H "Content-Type: application/json" -v
```
更改下列內容：
- LOG_QUERY_API_ENDPOINT：您要從中查詢記錄的記錄查詢 API 端點。
- PROJECT_NAMESPACE：您的專案命名空間。
- LABEL：要查詢值的特定標籤。
如要查詢特定專案的記錄，請建構 logs_filter 查詢，並將其納入要求主體：
```
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
```
更改下列內容：
- LOG_QUERY_API_ENDPOINT：您要從中查詢記錄的記錄查詢 API 端點。
- PROJECT_NAMESPACE：您的專案命名空間。
- LABEL：您要查詢記錄的特定標籤。
- LABEL_VALUE：要查詢記錄的標籤值。
如要查看建構 logs_filter 查詢的所有選項，請參閱 API 說明文件。

gRPC

gRPC 廣泛支援各種程式設計語言，與 HTTP 用戶端相比，通訊方法更有效率。

如要使用 gRPC 查詢記錄，必須符合下列先決條件：

根據 Google 提供的通訊協定緩衝區，建立自己的用戶端程式庫。
在用戶端實作驗證。
實作重試機制。

如要瞭解通訊協定緩衝區，請參閱 API 說明文件。

以下範例說明如何使用未經驗證的 gRPC 用戶端，從 Go 程式查詢記錄。這個範例假設您已建立 golang 套件，其中包含 Bazel 建構檔案，可匯入程式碼依附元件：

將下列程式碼儲存至名為 client.go 的 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
}

執行 Go 程式：
```
go run PATH_TO_API/client.go -server=LOG_QUERY_API_ENDPOINT:443
```
更改下列內容：
- PATH_TO_API：API 檔案的路徑。
- LOG_QUERY_API_ENDPOINT：您要從中查詢記錄的記錄查詢 API 端點。
如未指定伺服器旗標，預設要求會傳送至 localhost。

查詢和標籤範例

以下列舉幾個可用於查詢記錄的預設標籤：

cluster：叢集名稱。
namespace：您的專案命名空間。
node：節點名稱。
pod：Pod 名稱。
container：容器名稱。

下列程式碼範例顯示如何使用標籤和值查詢不同記錄：

選取伺服器記錄：

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

選取叢集稽核記錄：

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