Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

查詢及查看記錄

在 Google Distributed Cloud (GDC) 實體隔離方案中，收集記錄後，您可以使用記錄查詢功能，檢查專案工作負載的作業和稽核事件。您可以使用記錄查詢語言 (LogQL) 運算式，在 Grafana 記錄面板中篩選、視覺化及匯出記錄串流。如要執行程式輔助工作流程，請按照標準 API 存取方法，透過 HTTP 或 gRPC 查詢貴組織的 Log Query API。

事前準備

如要查詢及視覺化記錄，您必須具備必要權限。

要求 IAM 組織角色

請與 IAM 機構組織管理員聯絡，要求下列角色：

組織 Grafana 檢視者 (organization-grafana-viewer)：在 Grafana 監控執行個體的資訊主頁上，以視覺化方式呈現組織相關可觀測的資料。
記錄查詢者 (log-query-api-querier-pa)：存取 Log Query API，查詢 platform-obs 專案中的平台記錄。

要求 IAM 專案角色

請與 IAM 專案管理員聯絡，要求下列角色：

專案 Grafana 檢視者 (project-grafana-viewer)：在專案命名空間中，透過 Grafana 監控執行個體的資訊主頁，以視覺化方式呈現專案相關可觀測的資料。
記錄查詢者 (log-query-api-querier)：存取 Log Query API，查詢專案命名空間中的應用程式記錄。

下表摘要列出 PA 和 AO 角色對 Role 的要求：

角色	物件	叢集	角色	命名空間	群組/使用者
PA	`grafana`	管理 API 伺服器	`project-grafana-viewer`	`platform-obs`	群組
PA	`log-query-api`	管理 API 伺服器	`log-query-api-querier-pa`	`platform-obs`	群組
PA	`grafana`	管理 API 伺服器	`project-grafana-viewer`	`platform-obs`	使用者
PA	`log-query-api`	管理 API 伺服器	`log-query-api-querier-pa`	`platform-obs`	使用者
AO	`grafana`	管理 API 伺服器	`project-grafana-viewer`	`PROJECT_NAMESPACE`	群組
AO	`log-query-api`	管理 API 伺服器	`log-query-api-querier`	`PROJECT_NAMESPACE`	群組
AO	`grafana`	管理 API 伺服器	`project-grafana-viewer`	`PROJECT_NAMESPACE`	使用者
AO	`log-query-api`	管理 API 伺服器	`log-query-api-querier`	`PROJECT_NAMESPACE`	使用者

選取下列其中一項設定，將 Grafana 存取權授予 Management API 伺服器上的使用者群組 (Config 1) 或個別使用者 (Config 2)。針對每項設定，您可以執行 kubectl 指令直接建立 RoleBinding，也可以將 RoleBinding YAML 資訊清單儲存至指定的基礎架構即程式碼 (IaC) 檔案路徑，透過 GitOps 套用：

設定 1

這項設定會授予使用者群組權限，允許他們存取 Management API 伺服器上的 PA 和 AO Grafana。完成這項設定後，請參閱本文件的「Grafana 資訊主頁」一節，瞭解如何在 Grafana 查看記錄。

kubectl 指令

執行下列指令，直接建立 RoleBinding：

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

範例：

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

IaC 檔案路徑

或者，如要使用 IaC 管理 RoleBinding，請在下列路徑建立 YAML 檔案：
```
/infrastructure/zonal/zones/ZONE/org-admin/rolebindings/GROUP_NAME/YAML_FILE
```

YAML 檔案

將下列 RoleBinding 資訊清單儲存至 IaC 檔案路徑中的 YAML 檔案：

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

設定 2

這項設定會授予使用者權限，允許他們存取 Management API 伺服器上的 PA 和 AO Grafana。完成這項設定後，請參閱本文的「Grafana 資訊主頁」一節，瞭解如何在 Grafana 查看記錄。

kubectl 指令

執行下列指令，直接建立 RoleBinding：

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

範例：

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

IaC 檔案路徑

或者，如要使用 IaC 管理 RoleBinding，請在下列路徑建立 YAML 檔案：
```
/infrastructure/zonal/zones/ZONE/org-admin/rolebindings/EMAIL_ADDRESS/YAML_FILE
```

YAML 檔案

將下列 RoleBinding 資訊清單儲存至 IaC 檔案路徑中的 YAML 檔案：

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

更改下列內容：

KUBECONFIG：特定叢集的 kubeconfig 檔案路徑，其中包含套用這個 RoleBinding 的 NAMESPACE。
KUBECONFIG_PATH：範例指令中 kubeconfig 檔案的路徑。
RULE_NAME：命名空間中這個 RoleBinding 資源的專屬名稱，例如 pa-project-grafana-viewer。
NAMESPACE：建立及套用這個 RoleBinding 的 Kubernetes 命名空間。請查看上表中的「Namespace」欄。
EMAIL_ADDRESS：獲派角色的使用者 ID，例如 application-operator@example.com。
ROLE：Role 的名稱，其中包含要授予使用者的權限。請查看上表中的可用角色。
GROUP_NAME：PA 使用者所屬 Group 的名稱，例如 pa-group。
ZONE：可用區名稱。
YAML_FILE：RoleBinding 資源的 YAML 檔案名稱。

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

查詢及篩選記錄

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

Grafana 記錄面板

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

找出 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」。
按一下「View all in Grafana Loki」(在 Grafana Loki 中查看全部)。

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

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

在圖 1 中，「Audit logs」(稽核記錄) 選項會顯示介面，讓您從 Grafana 建構查詢來擷取稽核記錄。

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

選取記錄的日期範圍

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

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

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

Log Query API

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

找出 Log Query API 端點

Log Query 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：列出專案的特定標籤值。
logs：列出特定專案的記錄。

詳情請參閱「API 說明文件」。

傳送查詢

使用 HTTP 或 gRPC 用戶端，將查詢傳送至記錄查詢 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 替換為要查詢記錄的 Log Query 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：要查詢記錄的標籤值。
請參閱 API 說明文件，瞭解建構 logs_filter 查詢的所有選項。

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