Galileo Observability

Name: Galileo Observability
Rating: 3.5 (1 reviews)
Author: nyasukun

By nyasukun 👁 40 views ▲ 0 votes

Native Galileo observability plugin for OpenClaw

GitHub

Install

npm install
npm

README

# openclaw-galileo-observability

[OpenClaw](https://github.com/openclaw/openclaw) の agent 実行を
[Galileo](https://docs.galileo.ai/sdk-api/overview) へ直接送る Observability Plugin です。

OpenClaw の typed lifecycle hook を OpenTelemetry GenAI span に変換し、Galileo 公式 TypeScript SDK の span enrichment と公式 OTLP protobuf exporter を組み合わせて export します。
一回の user turn を一つの trace とし、LLM と tool を root Agent span の child として記録します。

```text
invoke_agent OpenClaw Agent
├── chat {model}
├── execute_tool {tool_name}
└── chat {model}
```

主な性質:

- OpenClaw の結果を変更しない fail-open observer
- `runId`、`callId`、`toolCallId` による並行相関
- Galileo 公式認証、routing、OTLP exporter
- OpenClaw session の HMAC 仮名化
- 同じ会話の複数 turn をまとめる Galileo native Session
- prompt、response、tool payload を既定で取得しない privacy 設定
- secret、reasoning、巨大 payload の送信前 redaction
- private `TracerProvider` と trace 単位の head sampling
- bounded state、TTL cleanup、bounded shutdown

Galileo SDK 2.2.0 の exporter は OpenTelemetry 0.221 の非同期 header factory と互換性問題があるため、SDK の `GalileoSpanProcessor` は属性 enrichment に使い、送信は同じ endpoint/header を設定した公開 `OTLPTraceExporter` へ bridge しています。
private field の参照や SDK への monkey patch は行いません。

## 対応範囲

- OpenClaw `>=2026.7.1`
- Galileo TypeScript SDK `>=2.2.0 <3`
- Node.js は OpenClaw 本体の対応 version に準拠

OpenTelemetry GenAI Semantic Conventions と OpenClaw Plugin hooks は更新が続いています。
dependency 更新時は unit test と wire-level E2E を再実行してください。

## Install

開発 checkout から:

```bash
npm install
npm run check
npm pack
openclaw plugins install npm-pack:/absolute/path/to/openclaw-galileo-observability-0.1.0.tgz --force
```

有効化後は Gateway を再起動し、live runtime を確認します。

```bash
openclaw gateway restart
openclaw plugins inspect openclaw-galileo-observability --runtime --json
```

plain `plugins list` / `plugins inspect` は cold config の確認であり、現在の Gateway が同じ Plugin を import 済みである証明にはなりません。

## Configuration

### Galileo

OpenClaw process の環境に次を設定します。

```dotenv
GALILEO_API_KEY=...
GALILEO_PROJECT=openclaw
GALILEO_LOG_STREAM=production

# custom deployment の場合
# GALILEO_CONSOLE_URL=https://console.example.com
# GALILEO_API_URL=https://api.example.com

# productionではAPI key rotationとconversation IDを分離するため推奨
# OPENCLAW_GALILEO_PSEUDONYM_SECRET=...
```

API key、routing、endpoint、pseudonym secret は OpenClaw Plugin config へ保存せず、環境変数または process の secret injection で供給してください。

### OpenClaw

外部 Plugin が会話 hook を受け取るため、`allowConversationAccess` を明示します。
content を Galileo へ送るかどうかは、これとは別の `captureContent` で制御します。

```json5
{
  plugins: {
    entries: {
      "openclaw-galileo-observability": {
        enabled: true,
        hooks: {
          allowConversationAccess: true,
        },
        config: {
          enabled: true,
          captureContent: false,
          captureConversationHistory: false,
          hashUserIds: true,
          sampleRate: 1.0,
          nativeSessionsEnabled: true,
          environment: "production",
        },
      },
    },
  },
}
```

`plugins.allow` を使っている場合は `openclaw-galileo-observability` も allow list に追加してください。

### Behavior environment overrides

| Plugin config                | 環境変数                                        |           既定値 |
| ---------------------------- | ----------------------------------------------- | ---------------: |
| `enabled`                    | `OPENCLAW_GALILEO_ENABLED`                      |           `true` |
| `captureContent`             | `OPENCLAW_GALILEO_CAPTURE_CONTENT`              |          `false` |
| `captureConversationHistory` | `OPENCLAW_GALILEO_CAPTURE_CONVERSATION_HISTORY` |          `false` |
| `hashUserIds`                | `OPENCLAW_GALILEO_HASH_USER_IDS`                |           `true` |
| `sampleRate`                 | `OPENCLAW_GALILEO_SAMPLE_RATE`                  |            `1.0` |
| `maxContentChars`            | `OPENCLAW_GALILEO_MAX_CONTENT_CHARS`            |          `12000` |
| `maxCollectionItems`         | `OPENCLAW_GALILEO_MAX_COLLECTION_ITEMS`         |            `100` |
| `maxActiveRuns`              | `OPENCLAW_GALILEO_MAX_ACTIVE_RUNS`              |            `512` |
| `turnTtlMs`                  | `OPENCLAW_GALILEO_TURN_TTL_MS`                  |         `900000` |
| `flushTimeoutMs`             | `OPENCLAW_GALILEO_FLUSH_TIMEOUT_MS`             |          `10000` |
| `nativeSessionsEnabled`      | `OPENCLAW_GALILEO_NATIVE_SESSIONS_ENABLED`      |           `true` |
| `nativeSessionTimeoutMs`     | `OPENCLAW_GALILEO_NATIVE_SESSION_TIMEOUT_MS`    |           `5000` |
| `serviceName`                | `OPENCLAW_GALILEO_SERVICE_NAME`                 | `openclaw-agent` |
| `environment`                | `OPENCLAW_GALILEO_ENVIRONMENT`                  |    `development` |

空の環境変数は未指定として扱います。
不正値または必須 Galileo credential の不足時は observability だけが disabled になり、OpenClaw 本体は動作を続けます。

## Privacy

実 content は既定で送信しません。
capture を明示的に有効化しても、次は常に redaction されます。

- Authorization、Cookie、API key、password、token、secret
- JWT、cloud access key、private key
- reasoning、analysis、thinking、signature
- base64 data URI
- 上限を超える collection と文字列

raw OpenClaw session ID は送信しません。
`openclaw:<HMAC-SHA256>` を `gen_ai.conversation.id` と Galileo native Session の external ID に使います。

## Reliability boundary

Direct Plugin が保証するのは process 内での local acceptance と best-effort flush までです。
`forceFlush()` は Galileo での永続化を証明する ack ではありません。

次が必要な場合は、永続 queue/WAL を持つ OpenTelemetry Collector profile を検討してください。

- process crash 後の復元
- at-least-once delivery
- `Retry-After` を含む独自 retry policy
- OTLP partial success の厳密な計測
- tail sampling

## Development

```bash
npm install
npm run format:check
npm run lint
npm run typecheck
npm run test
npm run test:e2e
npm run build
npm run pack:check
```

## Documents

- [技術調査](docs/RESEARCH.md)
- [要件定義](docs/REQUIREMENTS.md)
- [技術設計](docs/DESIGN.md)

## License

Apache-2.0

tools