gcp-logs

GCP 日志查询技能

适用场景

• 调查 relayer、validator 或 scraper 的行为
• 调试消息处理问题
• 分析运维事故
• 在 Agent 日志中查找特定错误或模式

前提条件

• 已安装并完成身份验证的 gcloud CLI
• 拥有 abacus-labs-dev GCP 项目的访问权限

基础查询模板

Relayer（Omniscient）

gcloud logging read 'resource.type="k8s_container" AND resource.labels.project_id="abacus-labs-dev" AND resource.labels.location="us-east1-c" AND resource.labels.cluster_name="hyperlane-mainnet" AND resource.labels.namespace_name="mainnet3" AND labels.k8s-pod/app_kubernetes_io/component="relayer" AND labels.k8s-pod/app_kubernetes_io/instance="omniscient-relayer" AND labels.k8s-pod/app_kubernetes_io/name="hyperlane-agent"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

Validator

gcloud logging read 'resource.type="k8s_container" AND resource.labels.project_id="abacus-labs-dev" AND resource.labels.location="us-east1-c" AND resource.labels.cluster_name="hyperlane-mainnet" AND resource.labels.namespace_name="mainnet3" AND labels.k8s-pod/app_kubernetes_io/component="validator" AND labels.k8s-pod/app_kubernetes_io/name="hyperlane-agent"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

Scraper

gcloud logging read 'resource.type="k8s_container" AND resource.labels.project_id="abacus-labs-dev" AND resource.labels.location="us-east1-c" AND resource.labels.cluster_name="hyperlane-mainnet" AND resource.labels.namespace_name="mainnet3" AND labels.k8s-pod/app_kubernetes_io/component="scraper3" AND labels.k8s-pod/app_kubernetes_io/instance="omniscient-scraper" AND labels.k8s-pod/app_kubernetes_io/name="hyperlane-agent"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

噪声过滤

添加以下过滤条件，减少那些会占用上下文却没有价值的嘈杂日志行：

-jsonPayload.fields.message="Found log(s) in index range"
-jsonPayload.fields.message="Dispatching get_public_key"
NOT "Instantiated AWS signer"
-jsonPayload.fields.message="Ingesting leaf"
-jsonPayload.fields.message="Message already marked as processed in DB"
-jsonPayload.fields.message="Message destined for self, skipping"
-jsonPayload.fields.message="Message has already been delivered, marking as submitted."
-jsonPayload.fields.message="Popped OpQueue operations"
-jsonPayload.fields.message="Validator returned latest index"
-jsonPayload.fields.message="Found signed checkpoint"
-jsonPayload.fields.return="Ok(None)"
-jsonPayload.fields.message="Fast forwarded current sequence"
-jsonPayload.fields.message="Cursor can't make progress, sleeping"
-jsonPayload.fields.message="fallback_request"
-jsonPayload.fields.message="No message found in DB for leaf index"
-jsonPayload.fields.message="Processor working on message"
-jsonPayload.fields.message="Message destined for unknown domain, skipping"

渐进式查询策略（提高 Token 效率）

步骤 1：先仅获取 message 字段

为尽量减少上下文消耗，先仅获取 message 字段：

gcloud logging read '[BASE_QUERY] AND "[search_term]"' --project=abacus-labs-dev --limit=30 --format='json(jsonPayload.fields.message,timestamp)' --freshness=1d

这样可以快速了解概况，而无需获取完整日志负载。

步骤 2：获取特定条目的完整上下文

找到有价值的日志条目后，获取完整详情：

gcloud logging read '[BASE_QUERY] AND "[specific_identifier]"' --project=abacus-labs-dev --limit=20 --format=json --freshness=1d

步骤 3：提取特定字段

需要特定详情时，使用 jq 或 grep 提取：

gcloud logging read '[QUERY]' --format=json | jq '.[].jsonPayload.fields.error'

常见查询模式

按消息 ID 搜索

gcloud logging read '[BASE_QUERY] AND "0x[MESSAGE_ID]"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

搜索错误/警告

gcloud logging read '[BASE_QUERY] AND severity>="WARNING"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

按链/域搜索

gcloud logging read '[BASE_QUERY] AND jsonPayload.spans.domain:"[chain_name]"' --project=abacus-labs-dev --limit=50 --format=json --freshness=1d

搜索卡住的消息（重试次数较多）

gcloud logging read '[BASE_QUERY] AND jsonPayload.fields.num_retries>=5' --project=abacus-labs-dev --limit=30 --format=json --freshness=1d

搜索 Gas 估算错误

gcloud logging read '[BASE_QUERY] AND "eth_estimateGas"' --project=abacus-labs-dev --limit=30 --format=json --freshness=1d

按应用上下文搜索

gcloud logging read '[BASE_QUERY] AND jsonPayload.fields.app_context:"[APP_CONTEXT]"' --project=abacus-labs-dev --limit=30 --format=json --freshness=1d

时间范围选项

• --freshness=1h - 最近 1 小时
• --freshness=1d - 最近 1 天
• --freshness=7d - 最近 1 周
• 或在过滤条件中使用明确的时间戳：timestamp>="2026-01-27T00:00:00Z"

输出格式选项

• --format=json - 完整 JSON（冗长，占用较多上下文）
• --format='json(jsonPayload.fields.message,timestamp)' - 仅输出特定字段（更高效）
• --format='value(jsonPayload.fields.message)' - 仅输出值，不包含结构

需要关注的关键日志字段

字段	说明
jsonPayload.fields.message	主要日志消息
jsonPayload.fields.error	错误详情
jsonPayload.spans[].domain	涉及的链
jsonPayload.fields.num_retries	重试次数
jsonPayload.fields.operations	待处理消息详情
jsonPayload.span.id	span 上下文中的消息 ID

环境差异

环境	命名空间	集群
mainnet3	mainnet3	hyperlane-mainnet
testnet4	testnet4	hyperlane-mainnet

提示

1. 始终从具体条件开始 - 先搜索确切的消息 ID 或错误模式
2. 使用噪声过滤器 - 基础日志噪声很大；务必进行过滤
3. 限制结果数量 - 使用 --limit，避免上下文过载
4. 逐步扩展详情 - 先仅获取 message 字段，再按需扩展
5. 限定查询时间范围 - 使用 --freshness 或时间戳过滤条件
6. 通过管道传递给 grep/jq - 在本地对大量结果进行后处理